diff --git a/docs/en/00_Getting_Started/00_Server_Requirements.md b/docs/en/00_Getting_Started/00_Server_Requirements.md index ac138db09..ee2ca91ac 100644 --- a/docs/en/00_Getting_Started/00_Server_Requirements.md +++ b/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/ + /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 diff --git a/docs/en/00_Getting_Started/04_Directory_Structure.md b/docs/en/00_Getting_Started/04_Directory_Structure.md index a7733de76..a44501a5b 100644 --- a/docs/en/00_Getting_Started/04_Directory_Structure.md +++ b/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 diff --git a/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md b/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md index f6a9dd010..8e291e968 100644 --- a/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md +++ b/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. ``` - - Require all granted - +.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, diff --git a/docs/en/02_Developer_Guides/14_Files/03_File_Security.md b/docs/en/02_Developer_Guides/14_Files/03_File_Security.md index b64fafe19..354162cd1 100644 --- a/docs/en/02_Developer_Guides/14_Files/03_File_Security.md +++ b/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. diff --git a/docs/en/02_Developer_Guides/14_Files/04_File_Storage.md b/docs/en/02_Developer_Guides/14_Files/04_File_Storage.md index 16c14a79a..4e219546f 100644 --- a/docs/en/02_Developer_Guides/14_Files/04_File_Storage.md +++ b/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