Creating a security release for a third-party dependency update

This guide explains how to create a security release of Drupal core that updates a third-party dependency. To update a dependency in a non-security release:

1. Ensure the dependency update meets the Drupal core allowed changes policy for the given release phase.
2. Create a patch using the instructions for managing Composer updates for Drupal core.
3. Tag the release normally.

Before you begin

Everything about a security release is private until the release itself is published, including whether or not there will even be a release. Only the security release window itself (typically the third Wednesday of the month) is announced in advance. Do not share any information about an upcoming security release with anyone outside the Drupal Security Team. See the Security Team disclosure policy for more information.

Security releases require coordination with the Security Team and (when fixes are being released for multiple branches) coordination with other branch maintainers.

Is a security release needed?

Generally, a security advisory is only required if the vulnerability is exploitable through Drupal core. In most cases, this also applies to security vulnerabilities in development dependencies, unless the simple presence of the vulnerable version causes core to be exploitable (as was the case with SA-CORE-2017-001). Discuss the issue privately with the Security Team before deciding whether to create a security release.

If core is not exploitable and the security team signs off on handling the issue in public, the lockfile version and core-recommended should be updated so that core-recommended and the tarball use the secure version, but the core/composer.json constraint generally does not need to be increased.

Creating the patch

The instructions below assume the previous patch release of 9.0.x was 9.0.8, and so a security release will be created as 9.0.9.

The composer lockfile and core metapackages change with every release, and security releases are created directly off the last release tag (rather than HEAD). There may also be dependency updates in HEAD since the last release. For these reasons, the patch for the dependency update can't simply be created normally.

1. Check out the tag of the last patch release on the production branch, for example:

   git checkout -b dep_update 9.0.8
   

2. For Drupal 8.8.x and higher, follow the instructions for managing composer updates for Drupal core, using COMPOSER_ROOT_VERSION=9.0.8 (the last release) for the commands. If the vulnerability is exploitable in core, the constraints in the core/composer.json should be increased to disallow earlier versions. (For instructions on updating JavaScript dependencies, refer to the frontend developer tools reference.)

   Each branch requiring a security release will need a separate patch, because the composer lockfile always has different hashes and versions between branches, so if you create the patch against a different branch, it will not work.

3. Upload the patches to a private issue on https://security.drupal.org and use the private security issue testing (access is restricted to the Security Team), and queue tests for each against the most recent tag on the branch.

   To be thorough, you can also create a version of the patch against HEAD and test it against the branch instead of the tag (to ensure that HEAD will not be broken by incompatible changes once the tag is merged). In an emergency, this is not required, as any non-security change that made the update incompatible with HEAD can simply be reverted after the release instead.

Creating the release

1. Follow the manual security release tagging instructions through step 4. Be sure to remove vendor and do a fresh composer install before tagging.

2. When you get to the step where you are merging the 9.0.9 tag back into 9.0.x, you must resolve the merge conflicts manually, because:

   • Every release modifies the lockfile and metapackages.
   • Your dependency update modifies the lockfile and metapackages.
   • HEAD may have already updated other dependencies, which also modify the lockfile and metapackages.

   Sample merge conflict diff:

   diff --cc composer.lock
   index 3e12db831b,9d5a017376..0000000000
   --- a/composer.lock
   +++ b/composer.lock
   @@@ -482,11 -482,11 +482,19 @@@
             },
             {
                 "name": "drupal/core",
   ++<<<<<<< HEAD
    +            "version": "9.0.x-dev",
    +            "dist": {
    +                "type": "path",
    +                "url": "core",
    +                "reference": "806585e0390b77d1a38aa32b3947f93004788c88"
   ++=======
   +             "version": "9.0.9",
   +             "dist": {
   +                 "type": "path",
   +                 "url": "core",
   +                 "reference": "fff7132ae97c13f120ba5be64b3ac1a52ea47bbb"
   ++>>>>>>> 9.0.9-security
                 },
                 "require": {
                     "asm89/stack-cors": "^1.1",
   @@@ -511,8 -511,8 +519,13 @@@
                     "laminas/laminas-diactoros": "^2.1",
                     "laminas/laminas-feed": "^2.12",
                     "masterminds/html5": "^2.1",
   ++<<<<<<< HEAD
    +                "pear/archive_tar": "^1.4.9",
    +                "php": "^7.3",
   ++=======
   +                 "pear/archive_tar": "^1.4.11",
   +                 "php": ">=7.3",
   ++>>>>>>> 9.0.9-security
                     "psr/log": "^1.0",
                     "stack/builder": "^1.0",
                     "symfony-cmf/routing": "^2.1",
   @@@ -729,7 -729,7 +742,11 @@@
             },
             {
                 "name": "drupal/core-project-message",
   ++<<<<<<< HEAD
    +            "version": "9.0.x-dev",
   ++=======
   +             "version": "9.0.9",
   ++>>>>>>> 9.0.9-security
                 "dist": {
                     "type": "path",
                     "url": "composer/Plugin/ProjectMessage",
   @@@ -762,7 -762,7 +779,11 @@@
             },
             {
                 "name": "drupal/core-vendor-hardening",
   ++<<<<<<< HEAD
    +            "version": "9.0.x-dev",
   ++=======
   +             "version": "9.0.9",
   ++>>>>>>> 9.0.9-security
                 "dist": {
                     "type": "path",
                     "url": "composer/Plugin/VendorHardening",
   diff --cc composer/Metapackage/CoreRecommended/composer.json
   index b1c94c88af,9125a57e63..0000000000
   --- a/composer/Metapackage/CoreRecommended/composer.json
   +++ b/composer/Metapackage/CoreRecommended/composer.json
   @@@ -7,7 -7,7 +7,11 @@@
             "webflo/drupal-core-strict": "*"
         },
         "require": {
   ++<<<<<<< HEAD
    +        "drupal/core": "9.0.x-dev",
   ++=======
   +         "drupal/core": "9.0.9",
   ++>>>>>>> 9.0.9-security
             "asm89/stack-cors": "1.3.0",
             "composer/semver": "1.5.1",
             "doctrine/annotations": "1.10.3",
   diff --cc composer/Metapackage/PinnedDevDependencies/composer.json
   index 0c80dcac81,1710896f2a..0000000000
   --- a/composer/Metapackage/PinnedDevDependencies/composer.json
   +++ b/composer/Metapackage/PinnedDevDependencies/composer.json
   @@@ -7,7 -7,7 +7,11 @@@
             "webflo/drupal-core-require-dev": "*"
         },
         "require": {
   ++<<<<<<< HEAD
    +        "drupal/core": "9.0.x-dev",
   ++=======
   +         "drupal/core": "9.0.9",
   ++>>>>>>> 9.0.9-security
             "behat/mink": "v1.8.1",
             "behat/mink-browserkit-driver": "v1.3.4",
             "behat/mink-goutte-driver": "v1.2.1",
   diff --cc core/lib/Drupal.php
   index e98f73911b,a6162d523a..0000000000
   --- a/core/lib/Drupal.php
   +++ b/core/lib/Drupal.php
   @@@ -80,7 -80,7 +80,11 @@@ class Drupal 
       /**
        * The current system version.
        */
   ++<<<<<<< HEAD
    +  const VERSION = '9.0.9-dev';
   ++=======
   +   const VERSION = '9.0.9';
   ++>>>>>>> 9.0.9-security
     
       /**
        * Core API compatibility.
   
     

   • Wherever you see 9.0.x-dev, use that, because we are merging back into the developmental version of HEAD.
   • The constant version in core/lib/Drupal.php should be set to 9.0.10-dev (for the next release).
   • Wherever you see your dependency update, use the updated version. However, for the most part, use the lines around it from HEAD. For example, for this hunk:
     

     ++<<<<<<< HEAD
      +                "pear/archive_tar": "^1.4.9",
      +                "php": "^7.3",
     ++=======
     +                 "pear/archive_tar": "^1.4.11",
     +                 "php": ">=7.3",
     ++>>>>>>> 9.0.9-security
     

     The correct resolution is:

                     "pear/archive_tar": "^1.4.11",
                     "php": "^7.3",
     

   • For the file hashes, pick the version from HEAD. We will fix these again once we've finished resolving the merge conflict.
3. Once you've resolved the merge conflicts, commit the changes with a commit message like: "Merge 9.0.9, resolve merge conflicts, and update lockfile and dev versions."
4. Now, to correct the lockfile hash and ensure everything else is as it should be, run:
   

   COMPOSER_ROOT_VERSION=9.0.x-dev composer update drupal/core*
   

   This should correct the lockfile hash:

   diff --git a/composer.lock b/composer.lock
   index a5e9d11906..09f8424f58 100644
   --- a/composer.lock
   +++ b/composer.lock
   @@ -486,7 +486,7 @@
                "dist": {
                    "type": "path",
                    "url": "core",
   -                "reference": "806585e0390b77d1a38aa32b3947f93004788c88"
   +                "reference": "d9034346624e6edc758fe912c3840544a2c6b15a"
                },
                "require": {
                    "asm89/stack-cors": "^1.1",
   

5. Amend the previous commit with the result:
   git commit --amend -am "Merge 9.0.9, resolve merge conflicts, and update lockfile and dev versions."