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/master/readme.md#-security) of the project readme on GitHub.
 13
 14
 15 <ul>
 16     <li><a href="#initial-security-setup">Initial Security Setup</a></li>
 17     <li><a href="#mfa">Multi-Factor Authentication</a></li>
 18     <li><a href="#securing-images">Securing Images</a></li>
 19     <li><a href="#attachments">Attachments</a></li>
 20     <li><a href="#user-passwords">User Passwords</a></li>
 21     <li><a href="#javascript-in-page-content">JavaScript in Page Content</a></li>
 22     <li><a href="#web-crawler-control">Web Crawler Control</a></li>
 23     <li><a href="#secure-cookies">Secure Cookies</a></li>
 24     <li><a href="#iframe-control">Host IFrame Control</a></li>
 25     <li><a href="#failed-access-logging">Failed Access Logging</a></li>
 26     <li><a href="#server-side-requests">Untrusted Server Side Requests</a></li>
 27 </ul>
 28
 29 ---
 30
 31 <a name="initial-security-setup"></a>
 32
 33 ### Initial Security Setup
 34
 35 1. Ensure you change the password and email address for the initial `admin@admin.com` user.
 36 2. Ensure only the `public` folder is being served by your webserver. Serving files above this folder
 37 opens up a lot of code that does not need to be public. Triple check this if you have installed
 38 BookStack within the commonly used `/var/www` folder.
 39 3. Ensure the database user you've used for BookStack has limited permissions for only accessing
 40 the database used for BookStack data.
 41 4. Check that you've set the `APP_URL` option in your `.env` file so that system generated URLs cannot be manipulated.
 42 5. Within BookStack, go through the settings to ensure registration and public access settings are as you expect.
 43 6. Review the user roles in the settings area.
 44 7. Read the below to further understand the security for images & attachments.
 45
 46 ---
 47
 48 <a name="mfa"></a>
 49
 50 ### Multi-Factor Authentication
 51
 52 Any user can enable multi-factor authentication (MFA) on their account. Upon login they would then need to use an extra proof of identity
 53 to gain access. BookStack currently supports the following mechanisms:
 54
 55 - TOTP (Time-based One-Time Passwords)
 56   - Labelled as "Mobile App" (Google/Microsoft Authenticator etc...).
 57   - Uses a SHA1 algorithm internally (Greater algorithms have poor cross-app compatibility).
 58 - Backup Codes
 59   - These are a list of 16 one-time-use codes.
 60   - Users will be warned once they have less than 5 codes remaining.
 61
 62 Secrets and values for these options are stored encrypted within the database.
 63
 64 Where required, MFA can be forced upon users via their roles. This can be found via
 65 a "Requires Multi-Factor Authentication" checkbox seen when editing a role.
 66 If a user does not already have an MFA method configured, they will be forced to set one up
 67 upon next login.
 68
 69 ---
 70
 71 <a name="securing-images"></a>
 72
 73 ### Securing Images
 74
 75 By default, Images are stored in a way which is publicly accessible. This is done on purpose to ensure decent performance while using BookStack. Below are a couple of options to increasing image security:
 76
 77 #### Image Authentication
 78
 79 You can choose to store images behind authentication so only logged-in users can view images. This solution is currently still in testing you could experience performance issues. This option will only work if you have the  'Allow Public Viewing' setting disabled.
 80
 81 ***Back-up your BookStack instance before migrating to this option***
 82
 83 To use this option simply set `STORAGE_TYPE=local_secure` in your `.env` file. Uploaded images will be stored within the `storage/uploads/images` folder.
 84
 85 If you are migrating to this option with existing images you will need to move all content in the folder `public/uploads/images` to `storage/uploads/images`. Do not simply copy and leave content in the `public/uploads/images` as those images will still be publicly accessible. After doing this migration you may have to clean-up and re-upload any 'App Icon' images, found in settings, since these need to remain publicly accessible.
 86
 87 #### Complex Urls
 88
 89 In the settings area of BookStack you can find the option 'Enable higher security image uploads?'. Enabling this will add a 16 character
 90 random string to the name of image files to prevent easy guessing of URLs. This increases security without potential performance concerns.
 91
 92 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:
 93
 94 **NGINX**
 95
 96 ```nginx
 97 # By default indexes are disabled on Nginx but if you have them enabled
 98 # add this to your BookStack server block
 99 location /uploads {
 100        autoindex off;
 101 }
 102 ```
 103
 104 **Apache**
 105
 106 ```apache
 107 # Add this to your Apache BookStack virtual host if Indexes are enabled.
 108 # If .htaccess file are enabled then the below should already be active.
 109 <Location "/uploads">
 110     Options -Indexes
 111 </Location>
 112 ```
 113
 114 ---
 115
 116 <a name="attachments"></a>
 117
 118 ### Attachments
 119
 120 Attachments, if not using Amazon S3, are stored in the `storage/uploads` directory.
 121 By default, unlike images, these are stored behind the application authentication layer so access
 122 depends on permissions you have set up at a role level and page level.
 123
 124 If you are using Amazon S3 for file storage then access will depend on your S3 permission
 125 settings. Unlike images, BookStack will not automatically attempt to make uploaded attachments
 126 publically accessible.
 127
 128 ---
 129
 130 <a name="user-passwords"></a>
 131
 132 ### User Passwords
 133
 134 User passwords, if not using an alternative authentication method, are stored in the database.
 135 These are hashed using the standard Laravel hashing methods which use the Bcrypt hashing algorithm.
 136
 137 ---
 138
 139 <a name="javascript-in-page-content"></a>
 140
 141 ### JavaScript in Page Content
 142
 143 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 it's own JavaScript escaping.
 144
 145 ---
 146
 147 <a name="web-crawler-control"></a>
 148
 149 ### Web Crawler Control
 150
 151 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.
 152
 153 ---
 154
 155 <a name="secure-cookies"></a>
 156
 157 ### Secure Cookies
 158
 159 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.
 160
 161 ---
 162
 163 <a name="iframe-control"></a>
 164
 165 ### Host Iframe Control
 166
 167 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:
 168
 169 ```bash
 170 # Adding a single host
 171 ALLOWED_IFRAME_HOSTS="https://example.com"
 172
 173 # Mulitple hosts can be separated with a space
 174 ALLOWED_IFRAME_HOSTS="https://a.example.com https://b.example.com"
 175 ```
 176
 177 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
 178 a user session can persist within the iframe.
 179
 180 ---
 181
 182 <a name="failed-access-logging"></a>
 183
 184 ### Failed Access Logging
 185
 186 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.
 187
 188 To enable this you simply need to define the `LOG_FAILED_LOGIN_MESSAGE` option in your `.env` file like so:
 189
 190 ```bash
 191 LOG_FAILED_LOGIN_MESSAGE="Failed login for %u"
 192 ```
 193
 194 The optional "%u" element of the message will be replaced with the username or email provided in the login attempt
 195 when the message is logged. By default messages will be logged via the php `error_log` function which, in most
 196 cases, will log to your webserver error log files.
 197
 198 ---
 199
 200 <a name="server-side-requests"></a>
 201
 202 ### Untrusted Server Side Requests
 203
 204 Some features, such as the PDF exporting, have the option to make http calls to external user-defined locations to do things
 205 such as load images or styles. This is disabled by default but can be enabled if desired. This is required for using
 206 WKHTMLtoPDF as your PDF export renderer.
 207
 208 To enable untrusted server side requests, you need to define the `ALLOW_UNTRUSTED_SERVER_FETCHING` option in your `.env` file like so:
 209
 210 ```bash
 211 ALLOW_UNTRUSTED_SERVER_FETCHING=true
 212 ```