Merge pull request #9736 from open-sausages/pulls/4/docs-protected-folder

DOCS Recommend moving .protected out of webroot

docs/en/00_Getting_Started/00_Server_Requirements.md

@@ -68,7 +68,7 @@ dynamically generated whitelist based on the `File.allowed_extensions` setting
 This whitelist uses the same defaults configured through file upload
 through SilverStripe, so is considered a second line of defence.
 
-### Secure Assets
+### Secure Assets {#secure-assets}
 
 Files can be kept in draft stage,
 and access restricted to certain user groups.
@@ -80,6 +80,32 @@ are routed to PHP by default when using Apache, through `public/assets/.htaccess
 If you are using another webserver, please follow our guides to ensure a secure setup.
 See [Developer Guides: File Security](/developer_guides/files/file_security) for details.
 
+For additional security, we recommend moving the `.protected/` folder out of `public/assets/`.
+This removes the possibility of a misconfigured webserver accidentally exposing
+these files under URL paths, and forces read access via PHP.
+
+This can be configured via [.env](/getting_started/environment_management) variable,
+relative to the `index.php` location.
+
+```
+SS_PROTECTED_ASSETS_PATH="../.protected/"
+```
+
+The resulting folder structure will look as follows:
+
+```
+.protected/
+  <hash>/my-protected-file.txt
+public/
+  index.php
+  assets/
+    my-public-file.txt
+vendor/
+app/
+```
+
+Don't forget to include this additional folder in any syncing and backup processes!
+
 
 ### Web Worker Concurrency
 

docs/en/00_Getting_Started/04_Directory_Structure.md

@@ -17,6 +17,7 @@ Directory            | Description
 ---------            | -----------
 `public/`            | Webserver public webroot
 `public/assets/`     | Images and other files uploaded via the SilverStripe CMS. You can also place your own content inside it, and link to it from within the content area of the CMS.
+`public/assets/.protected/` | Default location for [protected assets](/developer_guides/files/file_security)
 `public/_resources/` | Exposed public files added from modules. Folders within this parent will match that of the source root location (this can be altered by configuration). 
 `vendor/`            | SilverStripe modules and other supporting libraries (the framework is in `vendor/silverstripe/framework`)
 `themes/`            | Standard theme installation location

docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md

@@ -509,26 +509,36 @@ standard PHP way. See [casting](/developer_guides/model/data_types_and_casting).
 
 ## Filesystem
 
-### Don't script-execution in /assets
+### Don't allow script-execution in /assets
 
 Please refer to the article on [file security](/developer_guides/files/file_security)
 for instructions on how to secure the assets folder against malicious script execution.
 
-### Don't allow access to YAML files
+### Don't run Silverstripe in the webroot
 
-YAML files are often used to store sensitive or semi-sensitive data for use by 
-SilverStripe, such as configuration files. We block access to any files
-with a `.yml` or `.yaml` extension through the default web server rewriting rules.
-If you need users to access files with this extension,
-you can bypass the rules for a specific directory.
-Here's an example for a `.htaccess` file used by the Apache web server:
+Silverstripe routes all execution through a [public/ subfolder](/getting_started/directory_structure))
+by default. This enables you to keep application code and configuration outside of webserver routing.
+But since this was introduced after the 4.0, there's a fallback `.htaccess` file in place
+which allows you to set the webroot to the project root. Don't rely on this, since it increases your security surface.
 
 ```
-<Files ~ "\.ya?ml$">
-    Require all granted
-</Files>
+.htaccess <- fallback, shouldn't be used
+public/ <- this should be your webroot
+  .htaccess
+  index.php
+app/
+  _config/
+    secrets.yml <- this isn't routed if public/ is your webroot
 ```
 
+### Don't place protected files in the webroot
+
+Protected files are stored in `public/assets/.protected` by default
+(assuming you're using the [public/ subfolder](/getting_started/directory_structure)).
+While default configuration is in place to avoid the webserver serving these files,
+we recommend moving them out of the webroot altogether -
+see [Server Requirements: Secure Assets](/getting_started/server_requirements#secure-assets).
+
 ### User uploaded files
 
 Certain file types are by default excluded from user upload. html, xhtml, htm, and xml files may have embedded,

docs/en/02_Developer_Guides/14_Files/03_File_Security.md

@@ -439,20 +439,30 @@ SilverStripe\ORM\DataObject:
   AssetControl: null
 ```
 
-### Configuring: Web server settings
+## Webserver Configuration
+
+### Protected files location
+
+Protected files are stored in `public/assets/.protected` by default
+(assuming you're using the [public/ subfolder](/getting_started/directory_structure)).
+While default configuration is in place to avoid the webserver serving these files,
+we recommend moving them out of the webroot altogether -
+see [Server Requirements: Secure Assets](/getting_started/server_requirements#secure-assets).
+
+### Config templates
 
 If the default server configuration is not appropriate for your specific environment, then you can
-further customise the .htaccess or web.config by editing one or more of the below:
+further customise the `.htaccess` or `web.config` by editing one or more of the below:
 
 * `PublicAssetAdapter_HTAccess.ss`: Template for public permissions on the Apache server.
 * `PublicAssetAdapter_WebConfig.ss`: Template for public permissions on the IIS server.
 * `ProtectedAssetAdapter_HTAccess.ss`: Template for the protected store on the Apache server (should deny all requests).
 * `ProtectedAssetAdapter_WebConfig.ss`: Template for the protected store on the IIS server (should deny all requests).
 
-Each of these files will be regenerated on ?flush, so it is important to ensure that these files are
+Each of these files will be regenerated on `?flush`, so it is important to ensure that these files are
 overridden at the template level, not via manually generated configuration files.
 
-#### Configuring Web Server: Apache server
+#### Apache
 
 In order to ensure that public files are served correctly, you should check that your `assets/.htaccess`
 bypasses PHP requests for files that do exist. The default template
@@ -486,7 +496,7 @@ For instance your server configuration should look similar to the below:
 The `php_admin_flag` will protect against uploaded `.htaccess` files accidentally re-enabling script
 execution within the assets directory.
 
-#### Configuring Web Server: Windows IIS 7.5+
+#### Windows IIS 7.5+
 
 Configuring via IIS requires the Rewrite extension to be installed and configured properly.
 Any rules declared for the assets folder should be able to dynamically serve up existing files,
@@ -508,7 +518,7 @@ The default rule for IIS is as below (only partial configuration displayed):
 You will need to make sure that the `allowOverride` property of your root web.config is not set
 to false, to allow these to take effect.
 
-#### Configuring Web Server: Other server types
+#### Other server types
 
 If using a server configuration which must be configured outside of the web or asset root, you
 will need to make sure you manually configure these rules.

docs/en/02_Developer_Guides/14_Files/04_File_Storage.md

@@ -122,7 +122,8 @@ It leaves out the `.protected/` folder, and leaves that to SilverStripe's integr
 `http://www.example.com/assets/my-protected-folder/b63923d8d4/my-protected-file.jpg`.
 
 For more information on how protected files are stored see the [file security](/developer_guides/files/file_security)
-section.
+section. We recommend moving this folder outside of the webroot,
+see [Server Requirements: Secure Assets](/getting_started/server_requirements#secure-assets).
 
 ## Versioned file paths