How to handle security advisories (#3302)

* How to handle security advisories (#3278)
* Add security_advisories.md
* Use security_advisories.md
* Update docs/infrastructure_and_maintenance/security/security_checklist.md
* install_ibexa_dxp.md: Rm Php82HideDeprecationsErrorHandler
* install_ibexa_dxp.md: Why ~E_DEPRECATED
* code_samples.yaml: mv to config.policy.advisories.ignore-id

---------

Co-authored-by: Gunnstein Lye <289744+glye@users.noreply.github.com>
Co-authored-by: Marek Nocoń <mnocon@users.noreply.github.com>

Author: 3 people

docs/getting_started/install_ibexa_dxp.md

@@ -13,7 +13,7 @@ month_change: false
 
 !!! note "Installing [[= product_name_oss =]]"
 
-    This installation guide shows in details how to install [[= product_name =]] for users who have a subscription agreement with [[= product_name_base =]].
+    This installation guide shows in detail how to install [[= product_name =]] for users who have a subscription agreement with [[= product_name_base =]].
     If you want to install [[= product_name_oss =]], you don't need authentication tokens or an account on updates.ibexa.co, but must adapt the steps shown here to the product edition and the `ibexa/oss-skeleton` repository.
 
 ## Prepare work environment
@@ -29,7 +29,7 @@ Additional requirements:
 
 For production, you need to [configure an HTTP server](#configure-an-http-server), Apache or nginx (Apache is used as an example below).
 
-Before getting started, make sure you review other [requirements](requirements.md) to see the systems that is supported and used for testing.
+Before getting started, make sure you review other [requirements](requirements.md) to see the systems that are supported and used for testing.
 
 ### Get Composer
 
@@ -68,12 +68,12 @@ Log in to your Service portal on [support.ibexa.co](https://support.ibexa.co/),
 1. Select **Create token** (this requires the **Portal administrator** access level).
 2. Fill in a label describing the use of the token.
 This allows you to revoke access later.
-3. Save the password, **you aren't able to access it again**.
+3. Save the password. **You won't be able to access it again**.
 
 !!! tip "Save the authentication token in `auth.json` to avoid re-typing it"
 
     Composer asks whether you want to save the token every time you perform an update.
-    If you prefer, you can decline and create an `auth.json` file globally in [`COMPOSER_HOME`](https://getcomposer.org/doc/03-cli.md#composer-home) directory for machine-wide use:
+    If you prefer, you can decline and create an `auth.json` file globally in the [`COMPOSER_HOME`](https://getcomposer.org/doc/03-cli.md#composer-home) directory for machine-wide use:
 
     ``` bash
     composer config --global http-basic.updates.ibexa.co <installation-key> <token-password>
@@ -162,7 +162,11 @@ To use Composer to instantly create a project in the current folder with all the
 
     <a id="authentication-token"></a>If you added credentials to the `COMPOSER_AUTH` variable, at this point add this variable to `auth.json` (for example, by running `echo $COMPOSER_AUTH > auth.json`).
 
-!!! tip
+!!! caution "Security advisories"
+
+    If you encounter security advisories that prevent the install, see [Package security advisories](security_advisories.md#package-security-advisories).
+
+!!! tip "Version constraint"
 
     You can set [different version constraints](https://getcomposer.org/doc/articles/versions.md), for example, specific tag (`[[= latest_tag_5_0 =]]`), version range (`~5.0.1`), or stability (`^5.0@rc`):
 
@@ -193,7 +197,7 @@ git init; git add . > /dev/null; git commit -m "init" > /dev/null
 
 ### Change installation parameters
 
-At this point configure your database via the `DATABASE_URL` in the `.env` file, depending of the database you're using:
+At this point, configure your database via the `DATABASE_URL` in the `.env` file, depending on the database you're using:
 
 `DATABASE_URL=mysql://user:password@host:port/database_name`.
 
@@ -217,7 +221,7 @@ It's used by Symfony when generating [CSRF tokens]([[= symfony_doc =]]/security/
 
     The app secret is crucial to the security of your installation.
     Be careful about how you generate it, and how you store it.
-    Here's one way to generate a 64 characters long, secure random string as your secret, from command line:
+    Here's one way to generate a secure random string of 64 characters as your secret, from the command line:
 
     ``` bash
     php -r "print bin2hex(random_bytes(32));"
@@ -227,13 +231,13 @@ It's used by Symfony when generating [CSRF tokens]([[= symfony_doc =]]/security/
     If you have any suspicion that the secret may have been exposed, replace it with a new one.
     The same goes for other secrets, like database password, Varnish invalidate token, JWT passphrase, and more.
 
-    After changing the app secret, make sure that you clear the application cache and log out all the users.
+    After changing the app secret, make sure that you clear the application cache and log out all users.
 
     For more information, see [Symfony documentation]([[= symfony_doc =]]/reference/configuration/framework.html#secret).
 
-    It's recommended to store the database credentials in your `.env.local` file and not commit it to the Version Control System.
+    It's recommended that you store the database credentials in your `.env.local` file, and not commit that file to the Version Control System.
 
-In `DATABASE_VERSION` you can also configure the database server version (for a MariaDB database, prefix the value with `mariadb-`).
+In `DATABASE_VERSION`, you can also configure the database server version (for a MariaDB database, prefix the value with `mariadb-`).
 
 !!! tip "Using PostgreSQL"
 
@@ -267,11 +271,22 @@ You may choose to replace the [default search engine](legacy_search_overview.md)
 
 Install [[= product_name =]] and create a database with:
 
-``` bash
-php bin/console ibexa:install
-```
+=== "PHP 8.4"
+
+    Deprecation warnings must be suppressed when using PHP 8.4, otherwise the installation fails due to errors such as "headers have already been sent".
+
+    ``` bash
+    php -d error_reporting=`php -r 'echo E_ALL & ~E_DEPRECATED;'` bin/console ibexa:install
+    php bin/console ibexa:graphql:generate-schema
+    ```
+
+=== "PHP 8.3 and older"
+
+    ``` bash
+    php bin/console ibexa:install
+    ```
 
-Before executing the command make sure that the database user has sufficient permissions.
+Before executing the command, make sure that the database user has sufficient permissions.
 
 The installer will prompt you for a new password for the `admin` user.
 Make sure to use a [strong password](security_checklist.md#strong-passwords) meeting all the default [password rules](passwords.md#password-rules):
@@ -306,7 +321,7 @@ For development you can use the built-in PHP server.
 php -S 127.0.0.1:8000 -t public
 ```
 
-Your PHP web server is accessible at `http://127.0.0.1:8000`
+Your PHP web server is accessible at `http://127.0.0.1:8000`.
 
 You can also use [Symfony CLI](https://symfony.com/download):
 
@@ -316,7 +331,7 @@ symfony serve
 
 ## Prepare installation for development
 
-Consider adding the Symfony DebugBundle which fixes memory outage when dumping objects with circular references.
+Consider adding the Symfony DebugBundle, which prevents running out of memory when dumping objects with circular references.
 The DebugBundle contains the [VarDumper]([[= symfony_doc =]]/components/var_dumper.html) and [its Twig integration]([[= symfony_doc =]]/components/var_dumper.html#debugbundle-and-twig-integration).
 
 ``` bash
@@ -329,7 +344,7 @@ For detailed information about request treatment, you can also install [Symfony
 composer require --dev symfony/profiler-pack
 ```
 
-To get both features in one go use:
+To get both features in one go, use:
 
 ``` bash
 composer require --dev symfony/debug-pack
@@ -341,7 +356,7 @@ To use [[= product_name =]] with an HTTP server, you need to [set up directory p
 
 ### Set up permissions
 
-For development needs, the web user can be made the owner of all your files (for example with the `www-data` web user):
+For development needs, the web user can be made the owner of all your files (for example, with the `www-data` web user):
 
 ``` bash
 chown -R www-data:www-data <your installation directory>
@@ -352,7 +367,7 @@ Future files and directories created by these two users need to inherit those pe
 
 !!! caution
 
-    For security reasons, in production, the web server cannot have write access to other directories than `var`.
+    For security reasons, in production, the web server mustn't have write access to any directory other than `var`.
     Skip the step above and follow the link below for production needs instead.
 
     You must also make sure that the web server cannot interpret the files in the `var` directory through PHP.
@@ -386,18 +401,18 @@ Prepare a [virtual host configuration](https://en.wikipedia.org/wiki/Virtual_hos
 
     Finally, restart the Apache server.
     The command may vary depending on your Linux distribution.
-    For example, on Ubuntu use:
+    For example, on Ubuntu, use:
 
     ``` bash
     service apache2 restart
     ```
 
 === "nginx"
 
-    You can use [this example vhost file](https://raw.githubusercontent.com/ibexa/post-install/5.0/resources/templates/nginx/vhost.template) and modify it to fit your project. You also need the `ibexa_params.d` files that should reside in a subdirectory below where the main file is, [as is shown here](https://github.com/ibexa/post-install/tree/5.0/resources/templates/nginx).
+    You can use [this example vhost file](https://raw.githubusercontent.com/ibexa/post-install/5.0/resources/templates/nginx/vhost.template) and modify it to fit your project. You also need the `ibexa_params.d` files, which should reside in a subdirectory below the main file, [as shown here](https://github.com/ibexa/post-install/tree/5.0/resources/templates/nginx).
 
     Specify `/<your installation directory>/public` as the `root`, or ensure `BASEDIR` is set in the environment.
-    Ensure `APP_ENV` is set to `prod` or `dev` in the environment, depending on the environment that you're configuring, and uncomment the line that starts with `#if[APP_ENV`.
+    Ensure `APP_ENV` is set to `prod` or `dev` in the environment, depending on which environment you're configuring, and uncomment the line that starts with `#if [APP_ENV]`.
 
     When the virtual host file is ready, enable the virtual host and disable the default.
     Finally, restart the nginx server.

docs/infrastructure_and_maintenance/security/security_advisories.md

@@ -0,0 +1,83 @@
+---
+description: Find [[= product_name_base =]] security advisories, and learn how to handle Composer package security advisories.
+month_change: true
+---
+
+# Security advisories
+
+## [[= product_name_base =]] security advisories
+
+[[= product_name_base =]] security advisories are released via [your Service portal](https://support.ibexa.co/), and via [Security advisories](https://developers.ibexa.co/security-advisories). The latter is available to non-subscribers.
+
+## Package security advisories
+
+Overall, it's recommended to keep your Composer packages up to date.
+
+You can run the following command to check for available updates without installing them:
+
+```bash
+composer update --dry-run
+```
+
+When a security issue is discovered in a Composer package, a security advisory is issued, and the affected versions of the package become blocked from installation unless you take action.
+
+When installing or updating, Composer avoids installing packages that are affected by security advisories.
+However, this can create constraint issues that make installation or updates impossible.
+For example, security fixes might not be available for [unsupported PHP versions](https://www.php.net/supported-versions.php).
+
+Example of a Composer output about a package with security issues when trying to install:
+
+```text
+- Root composer.json requires twig/cssinliner-extra v3.11.0 (exact version match),
+  found twig/cssinliner-extra[v3.11.0] but these were not loaded, because they are
+  affected by security advisories ("PKSA-fs5b-x5k4-1h39").
+```
+
+Composer's output doesn't always mention that a security advisory is blocking installation or updates.
+
+For example, when trying to install [[= product_name =]] 4.6 on PHP 7.4 you might see an error like the following one:
+
+```text
+- ibexa/user[v4.6.0, ..., v4.6.31] require twig/twig ^3.0 -> satisfiable by twig/twig[v3.27.0, v3.27.1, v3.28.0].
+- twig/twig[v3.27.0, ..., v3.28.0] require php >=8.1.0 -> your php version (7.4.33) does not satisfy that requirement.
+```
+
+To gather more information, check package information on [Packagist](https://packagist.org/) and try installing a specific version of the package blocking installation.
+
+In this case, trying to install [`twig/twig:3.11.3`](https://packagist.org/packages/twig/twig#v3.11.3) shows explicitly that this version is blocked by a security advisory:
+
+```terminal
+% composer require twig/twig:3.11.3
+Your requirements could not be resolved to an installable set of packages.
+
+  Problem 1
+    - Root composer.json requires twig/twig 3.11.3 (exact version match: 3.11.3 or 3.11.3.0),
+      found twig/twig[v3.11.3] but these were not loaded, because they are affected by
+      security advisories ("PKSA-8zx5-v2nz-58pb").
+```
+
+It's highly recommended that you not install the affected package, and instead meet the requirements of the fixed version.
+
+You can use the [Packagist Security Advisories database](https://packagist.org/security-advisories/) to learn more about a security advisory, such as the affected packages and versions, a detailed description of the issue, and other possible reference IDs for the advisory: PKSA (Packagist Security Advisory), GHSA (GitHub Security Advisories), and CVE (Common Vulnerabilities and Exposures).
+
+If you need to, upgrade PHP and migrate your custom code to be compatible with the newer PHP version, for example by using [Rector](https://github.com/rectorphp/rector).
+
+If updating the affected package isn't possible, carefully review the security issue and assess the risk.
+If you choose to implement countermeasures instead of upgrading, you can ignore the security advisory.
+Use Composer's [`config.policy.advisories.ignore-id`](https://getcomposer.org/doc/06-config.md#ignore-id) setting, providing for each entry the reason why you consider it safe to ignore.
+This way, you'll still be warned if the package is affected by a new security advisory.
+
+```json
+{
+    "config": {
+        "policy": {
+            "advisories": {
+                "ignore-id": {
+                    "PKSA-fs5b-x5k4-1h39": "Description of the countermeasures you've implemented causing this one to be safe to ignore.",
+                    "PKSA-8zx5-v2nz-58pb": "Description of the countermeasures you've implemented causing this one to be safe to ignore."
+                }
+            }
+        }
+    }
+}
+```

docs/infrastructure_and_maintenance/security/security_checklist.md

@@ -8,15 +8,15 @@ When getting ready to go live with your project for the first time, or when re-l
 
 !!! caution
 
-    Security is an ongoing process. After going live, you should pay attention to security advisories released via [your Service portal](https://support.ibexa.co/), or via [Security advisories](https://developers.ibexa.co/security-advisories) if you're not a subscriber.
+    Security is an ongoing process. After going live, you should pay attention to Ibexa security advisories released via [your Service portal](https://support.ibexa.co/), or via [Security advisories](https://developers.ibexa.co/security-advisories) if you're not a subscriber.
 
 ## [[= product_name =]]
 
 ### Carefully select admin users
 
 Make sure Admin users and other privileged users who have access to System Information and setup in the back end are vetted and fully trustworthy.
 
-As administrator you have access to full information about the system through the `setup/system_info` policy, and also to user data, role editing, and many other critical aspects.
+As administrator, you have access to full information about the system through the `setup/system_info` policy, and also to user data, role editing, and many other critical aspects.
 
 The users in your organization who have backend access must be kept up-to-date.
 Any user leaving the organization must be disabled without delay.
@@ -323,6 +323,7 @@ Those steps aren't needed when using [[= product_name_cloud =]], where the provi
 
 - Run servers on a recent operating system and install security patches for dependencies.
 - Configure servers to alert you about security updates from vendors. Pay special attention to dependencies used by your project directly, or by PHP. The provider of the operating system usually has a service for this.
+- Update your Composer packages regularly. Don't underestimate [package security advisories](security_advisories.md#package-security-advisories) and update your dependencies so you can install the fixed versions. Also consider the risk of [supply chain attacks](https://en.wikipedia.org/wiki/Supply_chain_attack) which could be mitigated by adopting a policy of waiting a minimum amount of time before using new releases.
 - Enable [GitHub Dependabot](https://docs.github.com/en/code-security/concepts/supply-chain-security/dependabot-security-updates)
 to receive notifications when a security fix is released in a GitHub-hosted dependency.
 - If you're not using GitHub for your project, you can create a dummy project on GitHub with the same dependencies as your real project, and enable Dependabot notifications for that.