bookstack/website
Fork 4
Code Issues 5 Pull requests Activity

Finished off 21-08 content

Browse source
This commit is contained in:
Dan Brown 2021-08-31 22:00:33 +01:00
commit 9dfe5eeb78
Signed by: danb
GPG key ID: 46D9F943C24A2EF9
4 changed files with 81 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

30
content/blog/bookstack-release-v21-08.md
View file

@ -2,7 +2,7 @@
categories = ["Releases"]
tags = ["Releases"]
title = "BookStack Release v21.08"
date = 2021-08-30T21:05:23Z
date = 2021-08-31T21:05:23Z
author = "Dan Brown"
image = "/images/blog-cover-images/lighthouse-dimitry_b.jpg"
slug = "bookstack-release-v21-08"
@ -22,26 +22,27 @@ number of other nice features. Within this post we'll dive into some of the bigg
This uses the `APP_KEY` value in your `.env` file. Ensure you have this stored safely since it would be required if you ever
restore/migrate your instance to another system.
- **Security/Exports** - During this release cycle it was highlighted that server-side request forgery could be achieved via the
PDF export system. This would need to be a very targeted attack, due to the blind nature of the vulnerability, and the use of this is limited due to how responses are handled.
In this release we've added permissions that allow disabling of exports per role. You may want to limit exports to only those roles which you trust.
- **Security/Authentication** - A slight change was made in relation to how email addresses are confirmed. Email confirmations are now checked at point-of-login rather
than being checked on every request. If you allowed sign-up with email confirmation or email domain restrictions, It's advised you [invalidate existing user sessions](/link/to/invalidate) upon upgrade.
PDF export system. External fetching in the default PDF renderer has been disabled by default. The WKHTMLtoPDF renderer will now
not be used if active. Either of these changes can be overridden by setting `ALLOW_UNTRUSTED_SERVER_FETCHING=true` in your `.env` file.
This should only be used were only trusted users can create and export content. To support this we've added permissions that allow disabling of exports per role.
- **Security/Authentication** - A slight change was made in relation to how email addresses are confirmed. Email confirmations are now primarily checked at point-of-login rather
than being checked on every request. Enabling email confirmation, or email domain restrictions, may no longer take action on unconfirmed users right away in the future.
### Multi-Factor Authentication
Multi-factor authentication (MFA) can now be enabled for user accounts in BookStack.
Two different methods MFA are available in this inital release of the feature:
Two different MFA methods are available in this initial release of the feature:
1. TOTP, Labelled as "Mobile App" (Google/Microsoft Authenticator etc...)
2. Backup Codes (A list of single-use codes)
MFA can be enabled by any user accounts in the system. It can be enforced at a per-role level
via a new "Required Multi-Factor Authentication" checkbox found when editing a role:
via a new "Requires Multi-Factor Authentication" checkbox found when editing a role:
![View of MFA required checkbox on role edit page](/images/2021/08/mfa-role-permission.png)
When enforced, users will be forced to setup at least one MFA method upon next login.
When required, users will be forced to setup at least one MFA method upon next login.
For those with at least one method configured, the system will require an MFA method to be used
upon login:
@ -75,13 +76,13 @@ priority.
A new "Export content" role permission has been added to BookStack. This will be given to
all roles by default upon upgrade. This new permission allows admins to control who can
see and use the "Export" option that's available via the API and on any page, chapter and book.
see and use the "Export" option that's available via the API or on any page, chapter or book.
### "Skip to content" Link
A new accessibility feature was added in v21.05.3, providing a "Skip to main content" link on the
first element of focus on the page. This link is not visible by default but will appear when focused
upon, typically by hitting tab when landing on the page.
upon, typically by hitting tab after landing on a page.
![View of the Skip to content link](/images/2021/08/skip-to-content-link.png)
@ -104,13 +105,13 @@ been uploaded via the UI. This is not yet available for markdown content.
Within BookStack v21.05.2 we added the ability to open/reference attachments without
forcing the file to be downloaded. This can be useful for files that your browser may support
like images and pdfs, where they would then open in their own tab instead of being downloaded.
like images and PDFs, where they could then open in their own tab instead of being downloaded.
![Preview of a non-download attachment link](/images/2021/08/non-download-attachment-link.png)
This feature is fairly hidden. You can either Ctrl/Cmd+Click the attachment link or add `?open=true`
to the end of any current attachment link. I'd like to build this option into the interface at some
point to make this easier to find & use where desired.
point to make it easier to find & use where desired.
### Translations
@ -153,6 +154,7 @@ since the initial v21.05 release:
- Kuzma Simonov (ovmach) - *Russian*
- Vojtěch Krystek (acantophis) - *Czech*
- Blaade - *French*
- Siamak Guodarzi (siamakgoudarzi88) - *Persian*
### Full List of Changes
@ -168,7 +170,7 @@ since the initial v21.05 release:
* Added some core opengraph tags to content. Thanks to [@james-geiger](https://github.com/BookStackApp/BookStack/pull/2393). ([#2393](https://github.com/BookStackApp/BookStack/pull/2393), [#2348](https://github.com/BookStackApp/BookStack/issues/2348))
* Updated blade views to be more consistent and follow a documented convention. ([#2805](https://github.com/BookStackApp/BookStack/issues/2805))
* Fixed markdown blockquotes not rendering correctly in preview. ([#2858](https://github.com/BookStackApp/BookStack/issues/2858), [#2837](https://github.com/BookStackApp/BookStack/issues/2837))
* Fixed issue on API where page update removes HTML. ([#2856](https://github.com/BookStackApp/BookStack/issues/2856))
* Fixed issue on API where page updates can remove HTML. ([#2856](https://github.com/BookStackApp/BookStack/issues/2856))
* Fixed inconsistency in list display and nesting. ([#2854](https://github.com/BookStackApp/BookStack/issues/2854))
* Standardised styling of the codebase. ([#2820](https://github.com/BookStackApp/BookStack/pull/2820))
@ -187,7 +189,7 @@ since the initial v21.05 release:
* Improved audit log user select list stability. ([#2863](https://github.com/BookStackApp/BookStack/issues/2863))
* Fixed incorrect styling of favourites sidebar when using a non-default homepage option. ([#2783](https://github.com/BookStackApp/BookStack/issues/2783))
* Fixed issue where empty HTML comments could cause errors. ([#2804](https://github.com/BookStackApp/BookStack/issues/2804))
* Extracted not found text into it's own view for easier overriding ([58117bc](https://github.com/BookStackApp/BookStack/commit/58117bcf2d91b72620de3e34b0daa705da519f5e))
* Extracted not found text into it's own view for easier overridding ([58117bc](https://github.com/BookStackApp/BookStack/commit/58117bcf2d91b72620de3e34b0daa705da519f5e))
* Fixed issue where translations system may attempt to load from the root directory when a theme was not in use. ([#2836](https://github.com/BookStackApp/BookStack/issues/2836))
* Fixed issue where user profile pages item "View All" links used ids hence did not link to proper searches. ([#2857](https://github.com/BookStackApp/BookStack/issues/2857))

8
content/docs/admin/pdf-rendering.md
View file

@ -19,3 +19,11 @@ WKHTMLTOPDF=/home/user/bins/wkhtmltopdf
```
If neither of those exist Dompdf will be used instead.
**Note:** as of BookStack v21.08 you'll need to also enable untrusted server fetching in your `.env` file like below.
This change was made for security since, in many cases, wkhtmltopdf will perform fetches to external URLs which may be defined by users.
You should only enable the below option in environments where only trusted users can export content.
```bash
ALLOW_UNTRUSTED_SERVER_FETCHING=true
```

45
content/docs/admin/security.md
View file

@ -14,6 +14,7 @@ If you'd like to be notified of new potential security concerns you can sign-up
<ul>
<li><a href="#initial-security-setup">Initial Security Setup</a></li>
<li><a href="#mfa">Multi-Factor Authentication</a></li>
<li><a href="#securing-images">Securing Images</a></li>
<li><a href="#attachments">Attachments</a></li>
<li><a href="#user-passwords">User Passwords</a></li>
@ -22,6 +23,7 @@ If you'd like to be notified of new potential security concerns you can sign-up
<li><a href="#secure-cookies">Secure Cookies</a></li>
<li><a href="#iframe-control">Host IFrame Control</a></li>
<li><a href="#failed-access-logging">Failed Access Logging</a></li>
<li><a href="#server-side-requests">Untrusted Server Side Requests</a></li>
</ul>
---
@ -43,6 +45,29 @@ the database used for BookStack data.
---
<a name="mfa"></a>
### Multi-Factor Authentication
Any user can enable multi-factor authentication (MFA) on their account. Upon login they would then need to use an extra proof of identity
to gain access. BookStack currently supports the following mechanisms:
- TOTP (Time-based One-Time Passwords)
- Labelled as "Mobile App" (Google/Microsoft Authenticator etc...).
- Uses a SHA1 algorithm internally (Greater algorithms have poor cross-app compatibility).
- Backup Codes
- These are a list of 16 one-time-use codes.
- Users will be warned once they have less than 5 codes remaining.
Secrets and values for these options are stored encrypted within the database.
Where required, MFA can be forced upon users via their roles. This can be found via
a "Requires Multi-Factor Authentication" checkbox seen when editing a role.
If a user does not already have an MFA method configured, they will be forced to set one up
upon next login.
---
<a name="securing-images"></a>
### Securing Images
@ -160,7 +185,7 @@ a user session can persist within the iframe.
An option is available to log failed login events to a log file which is useful to identify users having trouble logging in, track malicious login attempts or to use with tools such as Fail2Ban. This works with login attempts using the default email & password login mechanism or attempts via LDAP login. Failed attempts are **not logged** for "one-click" social or SAML2 options.
To enable this you simple need to define the `LOG_FAILED_LOGIN_MESSAGE` option in your `.env` file like so:
To enable this you simply need to define the `LOG_FAILED_LOGIN_MESSAGE` option in your `.env` file like so:
```bash
LOG_FAILED_LOGIN_MESSAGE="Failed login for %u"
@ -168,4 +193,20 @@ LOG_FAILED_LOGIN_MESSAGE="Failed login for %u"
The optional "%u" element of the message will be replaced with the username or email provided in the login attempt
when the message is logged. By default messages will be logged via the php `error_log` function which, in most
cases, will log to your webserver error log files.
cases, will log to your webserver error log files.
---
<a name="server-side-requests"></a>
### Untrusted Server Side Requests
Some features, such as the PDF exporting, have the option to make http calls to external user-defined locations to do things
such as load images or styles. This is disabled by default but can be enabled if desired. This is required for using
WKHTMLtoPDF as your PDF export renderer.
To enable untrusted server side requests, you need to define the `ALLOW_UNTRUSTED_SERVER_FETCHING` option in your `.env` file like so:
```bash
ALLOW_UNTRUSTED_SERVER_FETCHING=true
```

14
content/docs/admin/updates.md
View file

@ -34,6 +34,20 @@ Check the below list for the version you are updating to for any additional inst
The below lists things you may need to be aware of when upgrading to a newer version of BookStack.
#### Updating to v21.08 or higher
**Config & Administration** - The introduction of multi-factor authentication brings the first use of encryption in the platform.
This uses the `APP_KEY` value in your `.env` file. Ensure you have this stored safely since it would be required if you ever
restore/migrate your instance to another system.
**Security/Exports** - During this release cycle it was highlighted that server-side request forgery could be achieved via the
PDF export system. External fetching in the default PDF renderer has been disabled by default. The WKHTMLtoPDF renderer will now
not be used if active. Either of these changes can be overridden by setting `ALLOW_UNTRUSTED_SERVER_FETCHING=true` in your `.env` file.
This should only be used were only trusted users can create and export content. To support this we've added permissions that allow disabling of exports per role.
**Security/Authentication** - A slight change was made in relation to how email addresses are confirmed. Email confirmations are now primarily checked at point-of-login rather
than being checked on every request. Enabling email confirmation, or email domain restrictions, may no longer take action on unconfirmed users right away in the future.
#### Updating to v21.04 or higher