DOC Create dedicated article about limiting allowed file types (#9505)

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

@@ -8,7 +8,7 @@ icon: lock
 
 ## Overview
 
-File security is an important concept, and is as essential as managing any other piece of data that exists 
+File security is an important concept, and is as essential as managing any other piece of data that exists
 in your system. As pages and dataobjects can be either versioned, or restricted to view by authenticated
 members, it is necessary at times to apply similar logic to any files which are attached to these objects
 in the same way.
@@ -24,7 +24,7 @@ Versioning stage:
  * "Published file": A published file (can be protected by further access restrictions).
    Files are often published indirectly as part
    of the objects who own them (see [File Ownership](file_management#ownership)).
- 
+
 Access restrictions:
 
  * "Unprotected file" (default): A file without access restrictions.
@@ -49,7 +49,7 @@ The permission model defines the following actions:
 There's a few rules guiding their access, in descending order of priority:
 
  * Published and unprotected files can be downloaded by anyone knowing the URL.
-   They bypass any SilverStripe permission checks (served directly by the webserver). 
+   They bypass any SilverStripe permission checks (served directly by the webserver).
  * Access can be restricted by custom `can*()` method implementations on `File`
    (through [extensions](/developer_guides/extending/extensions)).
    This logic can overrule any further restrictions below.
@@ -66,15 +66,15 @@ There's a few rules guiding their access, in descending order of priority:
  * Protected files need an "access grant" for the current session
    in order to download the file (see [User access control](#user-access-control)).
    While you can technically allow viewing or editing a file without granting
-   access to download it, those aspects are usually bundled together by the file viewing logic. 
+   access to download it, those aspects are usually bundled together by the file viewing logic.
 
 Access to create or delete files generally aligns with the edit access described above.
 
 Note that even if the permissions above allow access,
-you need to have access to a mechanism to view or edit file information. 
+you need to have access to a mechanism to view or edit file information.
 Most commonly this is through the "Access to Files section" permission.
 Custom implementations (e.g. APIs or custom file viewers) can have
-further restrictions in your project. 
+further restrictions in your project.
 
 [warning]
 When implenting your own `canView()` logic through [extensions](/developer_guides/extending/extensions),
@@ -128,7 +128,7 @@ control access to embedded assets at a template level.
 Users who are able to guess the value of $URL will not be able to access those urls without being
 authorised by this code.
 
-In order to ensure protected assets are not leaked publicly, but are properly whitelisted for 
+In order to ensure protected assets are not leaked publicly, but are properly whitelisted for
 authorised users, the following should be considered:
 
 Caching mechanisms which prevent `$URL` being invoked for the user's request (such as `$URL` within a
@@ -138,12 +138,12 @@ file via PHP for the current user instead, by using the following code to grant
 ```php
 use SilverStripe\CMS\Controllers\ContentController;
 
-class PageController extends ContentController 
+class PageController extends ContentController
 {
-    public function init() 
+    public function init()
     {
         parent::init();
-        
+
         // Whitelist the protected files on this page for the current user
         $file = $this->File();
         if($file->canView()) {
@@ -171,12 +171,12 @@ the `revokeFile` method.
 ```php
 use SilverStripe\CMS\Controllers\ContentController;
 
-class PageController extends ContentController 
+class PageController extends ContentController
 {
-    public function init() 
+    public function init()
     {
         parent::init();
-        
+
         // Whitelist the protected files on this page for the current user
         $file = $this->File();
         if($file->canView()) {
@@ -232,7 +232,7 @@ either. This provides a consistent method for interacting with files.
 
 In day to day operation, moving assets to or between either of these stores does not normally
 alter these asset urls, as the routing mechanism will infer file access requirements dynamically.
-This allows you to prepare predictable file urls on a draft site, which will not change once 
+This allows you to prepare predictable file urls on a draft site, which will not change once
 the page is published, but will be protected in the mean time.
 
 For instance, consider two files `OldCompanyLogo.gif` in the public store, and `NewCompanyLogo.gif`
@@ -318,25 +318,6 @@ to put protected files into `/sites/myapp/protected` with the below `.env` setti
 SS_PROTECTED_ASSETS_PATH="/sites/myapp/protected"
 ```
 
-### Configuring: File types {#file-types}
-
-In addition to configuring file locations, it's also important to ensure that you have allowed the
-appropriate file extensions for your instance. This can be done by setting the `File.allowed_extensions`
-config.
-
-```yaml
-SilverStripe\Assets\File: 
-  allowed_extensions: 
-    - 7zip 
-    - xzip
-```
-
-[warning]
-Any file not included in this config, or in the default list of extensions, will be blocked from
-any requests to the assets directory. Invalid files will be blocked regardless of whether they
-exist or not, and will not invoke any PHP processes.
-[/warning]
-
 ### Configuring: Protected file headers {#protected_file_headers}
 
 In certain situations, it's necessary to customise HTTP headers required either by
@@ -356,7 +337,7 @@ SilverStripe\Filesystem\Flysystem\FlysystemAssetStore:
 
 By default, the default extension `AssetControlExtension` will control the disposal of assets
 attached to objects when those objects are archived or replaced. For example, unpublished versioned objects
-will automatically have their attached assets moved to the protected store. The archive of 
+will automatically have their attached assets moved to the protected store. The archive of
 draft or (or deletion of unversioned objects) will have those assets permanantly deleted
 (along with all variants).
 
@@ -374,7 +355,7 @@ the `Versioned` extension.
 ```php
 use SilverStripe\ORM\DataObject;
 
-class MyVersiondObject extends DataObject 
+class MyVersiondObject extends DataObject
 {
     /** Ensure assets are archived along with the DataObject */
     private static $keep_archived_assets = true;

docs/en/02_Developer_Guides/14_Files/06_Allowed_file_types.md

@@ -0,0 +1,92 @@
+---
+title: Allowed file types
+summary: Control the type of files that can be stored in your Silverstripe CMS project
+icon: lock
+---
+
+# Allowed file types
+
+Not every kind of file should be stored in a CMS's asset management system. For example, allowing users to upload JavaScript files could lead to a risk of Cross-Site Scripting (XSS) attacks.
+
+Out of the box, your Silverstripe CMS project will limit what type of files can be uploaded into the assets management section. There's two type of restriction in place based on:
+* the extensions of the files
+* the MIME type of the files.
+
+## File extensions validation
+
+The `silverstripe/assets` module ships with a whitelist of allowed file extensions. Any file with an extensions not in this whitelist will not be allowed to be stored in Silverstripe's assets management system.
+
+The whitelist is controlled by the `SilverStripe\Assets\File::$allowed_extensions` variable.
+
+You can whitelist additional file extensions by adding them in your YML configuration.
+```yml
+SilverStripe\Assets\File:
+  allowed_extensions:
+    - 7zip
+    - xzip
+```
+
+Any file not included in this config, or in the default list of extensions, will be blocked from
+any requests to the assets directory. Invalid files will be blocked regardless of whether they
+exist or not, and will not invoke any PHP processes.
+
+[warning]
+While SVG images are a popular format to display images on the web, they are not included in the file extension whitelist because they can contain arbitrary scripts that will be executed when the image is rendered in a browser. Allowing CMS users to upload SVG images would be a significant XSS risk. We strongly advise developers against whitelisting the `svg` file extension.
+[/warning]
+
+You can also remove pre-existing entries from the whitelist by setting them to `false`.
+
+```yml
+SilverStripe\Assets\File:
+  allowed_extensions:
+    zip: false
+```
+
+## MIME type validation
+
+Another type of validation that can be applied to files uploaded in Silverstripe CMS is MIME type validation. When MIME type validation is enabled, Silverstripe will analyse the content of files at upload time to determine their MIME type and will reject files with invalid type.
+
+MIME type validation also uses a whitelist of allowed MIME types.
+
+### Enabling MIME type validation
+
+You need to install the `silverstripe/mimevalidator` module in your project to enable MIME type validation. If your project uses `silverstripe/recipe-core` 4.6.0 or greater, or any version of the Common Web Platform, the `silverstripe/mimevalidator` module will already be installed and enabled.
+
+Look at the `app/_config/mimevalidator.yml` to view the default configuration.
+
+You can explicitly require the module by running this command
+
+```sh
+composer require silverstripe/mimevalidator
+```
+
+#### Enable globally
+
+In your `app/_config/config.yml` file:
+
+```yml
+SilverStripe\Core\Injector\Injector:
+  SilverStripe\Assets\Upload_Validator:
+    class: SilverStripe\MimeValidator\MimeUploadValidator
+```
+
+#### Enable on an individual upload field
+
+```php
+$field = UploadField::create();
+$field->setValidator(MimeUploadValidator::create());
+```
+
+#### Adding MIME types
+
+By default MIME types are checked against `HTTP.MimeTypes` config set in framework. This can be limiting as this only
+allows for one MIME type per extension. To allow for multiple MIME types per extension, you can add these in your YAML
+config as below:
+
+```yml
+SilverStripe\MimeValidator\MimeUploadValidator:
+  MimeTypes:
+    ics:
+      - 'text/plain'
+      - 'text/calendar'
+```

docs/en/04_Changelogs/4.6.0.md

@@ -4,6 +4,7 @@
 
  * [MySQL tables are auto-converted from MyISAM to InnoDB](#myisam)
  * [Editing files directly in the insert-media modal](#in-modal-editing)
+ * [MIME Type validation now a core module](#mime-validator)
 
 ## MySQL tables are auto-converted from MyISAM to InnoDB {#myisam}
 
@@ -68,6 +69,13 @@ make sure your customisations still work as expected.
 If your project uses the popular [jonom/focuspoint](https://github.com/jonom/silverstripe-focuspoint) community
 module, you should upgrade it as well.
 
+## MIME Type validation now a core module {#mime-validator}
+
+`silverstripe/mimevalidator` is now a core module and will ship by default on new projects. Projects referencing `silverstripe/recipe-core` will automatically install `silverstripe/mimevalidator` when they upgrade to 4.6.0.
+
+Read [Allowed file types](Developer_Guides/Files/Allowed_file_types) in the Silverstripe CMS doc for all the details.
+
 <!--- Changes below this line will be automatically regenerated -->
 
 <!--- Changes above this line will be automatically regenerated -->
+