BookStack Code Mirror - website/blob - content/docs/admin/security.md

   1 +++
   2 title = "Security"
   3 description = "BookStack security concerns and considerations"
   4 date = "2017-01-01"
   5 type = "admin-doc"
   6 +++
   7
   8 Since BookStack can hold important information for users you should be aware of any potential security concerns.
   9 Read through the below to ensure you have secured your BookStack instance. Note, The below only
  10 relates to BookStack itself. The security of the server BookStack is hosted on is not instructed below but should be taken into account.
  11
  12 If you'd like to be notified of new potential security concerns you can sign-up to the [BookStack security mailing list](https://updates.bookstackapp.com/signup/bookstack-security-updates). For reporting security vulnerabilities, please see the ["Security" section](https://github.com/BookStackApp/BookStack/blob/development/readme.md#-security) of the project readme on GitHub.
  13
  14
  15 {{<toc>}}
  16
  17 ---
  18
  19 ### Initial Security Setup
  20
  21 1. Ensure you change the password and email address for the initial `[email protected]` user.
  22 2. Ensure only the `public` folder is being served by your webserver. Serving files above this folder
  23 opens up a lot of code that does not need to be public. Triple check this if you have installed
  24 BookStack within the commonly used `/var/www` folder.
  25 3. Ensure the database user you've used for BookStack has limited permissions for only accessing
  26 the database used for BookStack data.
  27 4. Check that you've set the `APP_URL` option in your `.env` file so that system generated URLs cannot be manipulated.
  28 5. Within BookStack, go through the settings to ensure registration and public access settings are as you expect.
  29 6. Review the user roles in the settings area.
  30 7. Read the below to further understand the security for specific functionality and features.
  31
  32 ---
  33
  34 ### Multi-Factor Authentication
  35
  36 Any user can enable multi-factor authentication (MFA) on their account. Upon login they would then need to use an extra proof of identity
  37 to gain access. BookStack currently supports the following mechanisms:
  38
  39 - TOTP (Time-based One-Time Passwords)
  40   - Labelled as "Mobile App" (Google/Microsoft Authenticator etc...).
  41   - Uses a SHA1 algorithm internally (Greater algorithms have poor cross-app compatibility).
  42 - Backup Codes
  43   - These are a list of 16 one-time-use codes.
  44   - Users will be warned once they have less than 5 codes remaining.
  45
  46 Secrets and values for these options are stored encrypted within the database.
  47
  48 Where required, MFA can be forced upon users via their roles. This can be found via
  49 a "Requires Multi-Factor Authentication" checkbox seen when editing a role.
  50 If a user does not already have an MFA method configured, they will be forced to set one up
  51 upon next login.
  52
  53 ---
  54
  55 ### Securing Images
  56
  57 By default, Images are stored in a way which is publicly accessible which ensures performance while using BookStack.
  58 Listed below are a few options for increasing image security.
  59
  60 #### Alternative Storage Options
  61
  62 Review our [file upload storage options](/docs/admin/upload-config/#storage-options) documentation for image storage options that add addition access or permission control
  63 to image requests.
  64
  65 #### Complex Urls
  66
  67 In the settings area of BookStack you can find the option 'Enable higher security image uploads?'. Enabling this will add a 16 character
  68 random string to the name of image files to prevent easy guessing of URLs. This increases security without potential performance concerns.
  69
  70 #### Prevent Directory Indexes
  71
  72 It's important to ensure you disable 'directory indexes' to prevent unknown users from being able to navigate their way through your images. Here's the configuration for NGINX & Apache if your server allows directory indexes:
  73
  74 **NGINX**
  75
  76 ```nginx
  77 # By default indexes are disabled on Nginx but if you have them enabled
  78 # add this to your BookStack server block
  79 location /uploads {
  80        autoindex off;
  81 }
  82 ```
  83
  84 **Apache**
  85
  86 ```apache
  87 # Add this to your Apache BookStack virtual host if Indexes are enabled.
  88 # If .htaccess file are enabled then the below should already be active.
  89 <Location "/uploads">
  90     Options -Indexes
  91 </Location>
  92 ```
  93
  94 You can test that indexes are disabled by attempting to navigate to
  95 `<your_bookstack_url>/uploads/images` in the browser after having uploaded at least one image.
  96 You should not see a list of files but instead a BookStack "Not Found" page.
  97
  98 ---
  99
 100 ### Attachments
 101
 102 Attachments, if not using Amazon S3, are stored in the `storage/uploads` directory.
 103 By default, unlike images, these are stored behind the application authentication layer so access
 104 depends on permissions you have set up at a role level and page level.
 105
 106 If you are using Amazon S3 for file storage then access will depend on your S3 permission
 107 settings. Unlike images, BookStack will not automatically attempt to make uploaded attachments
 108 publicly accessible.
 109
 110 ---
 111
 112 ### Filesystem Permissions
 113
 114 It's usually a good idea to limit the file and folder access privileges for the user/group used to run the application PHP, which is typically the user/group for PHP or the running web-server processes. Limiting permissions can help avoid a range of potential vulnerability exploits.
 115
 116 Details on required [filesystem permissions can be found here](/docs/admin/filesystem-permissions/).
 117
 118 ---
 119
 120 ### User Passwords
 121
 122 User passwords, if not using an alternative authentication method, are stored in the database.
 123 These are hashed using the standard Laravel hashing methods which use the Bcrypt hashing algorithm.
 124
 125 ---
 126
 127 ### JavaScript in Page Content
 128
 129 By default, JavaScript tags within page content is escaped when rendered. This can be turned off by setting `ALLOW_CONTENT_SCRIPTS=true` in your `.env` file. Note that even if you disable this escaping the WYSIWYG editor may still perform its own JavaScript escaping. This option will also alter the [CSP rules](#content-security-policy-csp) set by BookStack.
 130
 131 ***This option disables some fundamental cross-site-scripting protections. Only use this option on secure instances, where only very trusted users can edit content***
 132
 133 ---
 134
 135 ### Web Crawler Control
 136
 137 The rules found in the `/robots.txt` file are automatically controlled via the "Allow public viewing?" setting. This can be overridden by setting `ALLOW_ROBOTS=false` or `ALLOW_ROBOTS=true` in your `.env` file. If you'd like to customise the rules this can be done via theme overrides.
 138
 139 ---
 140
 141 ### Secure Cookies
 142
 143 BookStack uses cookies to track sessions, remember logins and for XSRF protection. When using HTTPS you may want to ensure that cookies are only sent back to the browser if the connection is over HTTPS. If you have set a https `APP_URL` option in your `.env` this will enabled automatically but it can also be forced on by setting `SESSION_SECURE_COOKIE=true` in your `.env` file.
 144
 145 ---
 146
 147 ### Host Iframe Control
 148
 149 By default BookStack will only allow itself to be embedded within iframes on the same domain as you're hosting on. This is done through a [CSP: frame-ancestors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors) header. You can add additional trusted hosts by setting a `ALLOWED_IFRAME_HOSTS` option in your `.env` file like the example below:
 150
 151 ```bash
 152 # Adding a single host
 153 ALLOWED_IFRAME_HOSTS="https://example.com"
 154
 155 # Multiple hosts can be separated with a space
 156 ALLOWED_IFRAME_HOSTS="https://a.example.com https://b.example.com"
 157 ```
 158
 159 Note: when this option is used, all cookies will served with `SameSite=None` [(info)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite#None) set so that
 160 a user session can persist within the iframe.
 161
 162 ---
 163
 164 <a name="iframe-src-control"></a>
 165
 166 ### Iframe Source Control
 167
 168 By default BookStack will only allow certain other hosts to be used as `src` values for embedded iframe/frame content within the application. This is done through a [CSP: frame-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src) header. You can configure the list of trusted sources by setting a `ALLOWED_IFRAME_SOURCES` option in your `.env` file like the examples below:
 169
 170 ```bash
 171 # Adding a single host
 172 ALLOWED_IFRAME_SOURCES="https://example.com"
 173
 174 # Multiple hosts can be separated with a space
 175 ALLOWED_IFRAME_SOURCES="https://a.example.com https://b.example.com"
 176
 177 # Allow all sources
 178 # This opens vulnerability risk and should only be done in secure & trusted environments.
 179 ALLOWED_IFRAME_SOURCES="*"
 180 ```
 181
 182 By default this option is configured as follows:
 183
 184 ```bash
 185 ALLOWED_IFRAME_SOURCES="https://*.draw.io https://*.youtube.com https://*.youtube-nocookie.com https://*.vimeo.com"
 186 ```
 187
 188 Note: The source of 'self' will always be automatically added to this CSP rule. In addition, the host used for the diagrams.net integration (If enabled) will be automatically appended to the lists of hosts.
 189
 190 ---
 191
 192 ### Failed Access Logging
 193
 194 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.
 195
 196 To enable this you simply need to define the `LOG_FAILED_LOGIN_MESSAGE` option in your `.env` file like so:
 197
 198 ```bash
 199 LOG_FAILED_LOGIN_MESSAGE="Failed login for %u"
 200 ```
 201
 202 The optional "%u" element of the message will be replaced with the username or email provided in the login attempt
 203 when the message is logged. By default messages will be logged via the php `error_log` function which, in most
 204 cases, will log to your webserver error log files.
 205
 206 ---
 207
 208 ### Untrusted Server Side Requests
 209
 210 Some features, such as the PDF exporting, have the option to make http calls to external user-defined locations to do things
 211 such as load images or styles. This is disabled by default but can be enabled if desired. This is required for using
 212 WKHTMLtoPDF as your PDF export renderer.
 213 This should only be enabled in BookStack environments where BookStack users and viewers are fully trusted.
 214
 215 To enable untrusted server side requests, you need to define the `ALLOW_UNTRUSTED_SERVER_FETCHING` option in your `.env` file like so:
 216
 217 ```bash
 218 ALLOW_UNTRUSTED_SERVER_FETCHING=true
 219 ```
 220
 221 Note that this is not connected to the `ALLOWED_SSR_HOSTS` setting at all.
 222 `ALLOW_UNTRUSTED_SERVER_FETCHING` is used for typically "untrusted" scenarios/functionality
 223 whereas `ALLOWED_SSR_HOSTS` is used for typically "trusted" user scenarios/functionality
 224 (where admin-level permissions are required).
 225
 226 ---
 227
 228 ### Server Side Request Allow List
 229
 230 There is some functionality in BookStack, like webhooks for example, that is typically only
 231 accessible by trusted (admin-level) users.
 232 In some cases, those admin users may not be trusted to the level where they can freely make server
 233 side requests. In such scenarios, you can define a `ALLOWED_SSR_HOSTS` option in your `.env` file
 234 to limit the hosts that can be called for such typically trusted functionality:
 235
 236 ```bash
 237 # Allow all hosts (Default)
 238 ALLOWED_SSR_HOSTS="*"
 239
 240 # Allow a single host
 241 ALLOWED_SSR_HOSTS="https://example.com"
 242
 243 # Allow multiple hosts via space-separated entries
 244 ALLOWED_SSR_HOSTS="https://example.com https://example.org"
 245
 246 # Use '*' as wildcards and/or define required paths
 247 ALLOWED_SSR_HOSTS="https://*.example.com https://example.org/bookstack/"
 248 ```
 249
 250 Values will be compared prefix-matched, case-insensitive, against called SSR urls.
 251
 252 Note that this is not connected to the `ALLOW_UNTRUSTED_SERVER_FETCHING` setting at all.
 253 `ALLOW_UNTRUSTED_SERVER_FETCHING` is used for typically "untrusted" scenarios/functionality
 254 whereas `ALLOWED_SSR_HOSTS` is used for typically "trusted" user scenarios/functionality
 255 (where admin-level permissions are required).
 256
 257 ---
 258
 259 ### Content Security Policy (CSP)
 260
 261 BookStack serves responses with a CSP header to increase protection again malicious content.
 262 This is especially important in a system such as BookStack where users can create a variety of HTML content,
 263 especially so if you allow untrusted users to create content in your instance.
 264 The CSP rules set by BookStack are as follows:
 265
 266 - `frame-ancestors 'self'`
 267   - Restricts what websites can embed BookStack pages via iframes.
 268   - See the "[Host Iframe Control](#iframe-control)" section above for details on expanding this rule to other hosts.
 269 - `frame-source 'self' https://*.diagrams.net https://*.draw.io https://*.youtube.com https://*.youtube-nocookie.com https://*.vimeo.com https://embed.diagrams.net`
 270   - Restricts what sources are allowed to load for frames/iframes.
 271   - Can be configured via a `ALLOWED_IFRAME_SOURCES` .env option.
 272   - May be different depending on other configuration set.
 273 - `script-src http: https: 'nonce-abc123' 'strict-dynamic'`
 274   - Restricts what scripts can be ran on a BookStack-served page.
 275   - Will not be set if the `ALLOW_CONTENT_SCRIPTS` .env option is active.
 276   - The nonce value used is randomly generated upon each request. It is automatically applied to any "Custom HTML Head Content" scripts.
 277 - `object-src 'self'`
 278   - Restricts which embeddable content can be loaded onto a BookStack-served page.
 279   - Will not be set if the `ALLOW_CONTENT_SCRIPTS` .env option is active.
 280 - `base-uri 'self'`
 281   - Restricts what `<base>` tags can be added to a BookStack-served page.
 282
 283 If needed you should be able to set additional CSP headers via your webserver.
 284 If there's a clash with an existing BookStack CSP header then browsers will generally favour the most restrictive policy.
 285
 286 ---
 287
 288 ### MySQL SSL Connection
 289
 290 If your BookStack database is not on the same host as your web server, you may want to ensure the connection is encrypted using SSL between these systems.
 291 Assuming SSL is configured correctly on your MySQL server, you can enable this by defining the `MYSQL_ATTR_SSL_CA` option in your `.env` file like so:
 292
 293 ```bash
 294 # Path to Certificate Authority (CA) certificate file for your MySQL instance.
 295 # When this option is used host name identity verification will be performed
 296 # which checks the hostname, used by the client, against names within the
 297 # certificate itself (Common Name or Subject Alternative Name).
 298 MYSQL_ATTR_SSL_CA="/path/to/ca.pem"
 299 ```
 300
 301 ---
 302
 303 ### Using BookStack Content Externally
 304
 305 In some scenarios you may use BookStack user-provided content externally (Accessed via the database or API). Such content is not guaranteed to be safe so keep security in mind when dealing with such content. In some cases, the system will apply some filtering to content in an attempt to prevent certain vulnerabilities, but this is not assured to be a bullet-proof defence.
 306
 307 Within its own interfaces, unless disabled, BookStack makes use of Content Security Policy (CSP) rules to heavily negate cross-site scripting vulnerabilities from user content. If displaying user content externally, it's advised you also use defences such as CSP or other techniques such as disabling of JavaScript entirely.