[CDRIVER-5535] Add a vulnerability report artifact to the repository and release archive (#1649)

* Add a snyk-monitor-snapshot task, and tweak the way secrets are passed
* Generate and include a third_party_vulnerabilities file in releases
* Documentation and process for 3rd-party vuln tracking
* Add steps for long-term Snyk monitoring.

Part of vulnerability reporting requirements is that
we continually monitor past in-support releases for
the discovery of new vulnerabilities within bundled
dependencies. Add a release step to create a Snyk
target for monitoring a snapshot of the vulnerabilities
in the repository at the time of the release.

Author: vector-of-bool

.evergreen/config_generator/components/earthly.py

@@ -172,13 +172,12 @@ def earthly_exec(
     args: Mapping[str, str] | None = None,
 ) -> BuiltInCommand:
     """Create a subprocess_exec command that runs Earthly with the given arguments"""
-    env: dict[str, str] = {}
-    if secrets:
-        env["EARTHLY_SECRETS"] = ",".join(f"{k}={v}" for k, v in secrets.items())
+    env: dict[str, str] = {k: v for k, v in (secrets or {}).items()}
     return subprocess_exec(
         "bash",
         args=[
             "tools/earthly.sh",
+            *(f"--secret={k}" for k in (secrets or ())),
             f"+{target}",
             *(f"--{arg}={val}" for arg, val in (args or {}).items()),
         ],

.evergreen/generated_configs/tasks.yml

@@ -1338,9 +1338,12 @@ tasks:
           binary: bash
           working_dir: mongoc
           env:
-            EARTHLY_SECRETS: SILK_CLIENT_ID=${silk_client_id},SILK_CLIENT_SECRET=${silk_client_secret}
+            SILK_CLIENT_ID: ${silk_client_id}
+            SILK_CLIENT_SECRET: ${silk_client_secret}
           args:
             - tools/earthly.sh
+            - --secret=SILK_CLIENT_ID
+            - --secret=SILK_CLIENT_SECRET
             - +create-silk-asset-group
             - --branch=${branch_name}
   - name: cse-sasl-cyrus-darwinssl-macos-1100-clang-compile

Earthfile

@@ -183,7 +183,6 @@ release-archive:
     COPY --dir .git .
     COPY (+sbom-download/augmented-sbom.json --branch=$sbom_branch) cyclonedx.sbom.json
     RUN git archive -o release.tar.gz \
-        --verbose \
         --prefix="$prefix/" \ # Set the archive path prefix
         "$ref" \ # Add the source tree
         --add-file cyclonedx.sbom.json  # Add the SBOM
@@ -325,6 +324,53 @@ create-silk-asset-group:
             --sbom-lite-path=etc/cyclonedx.sbom.json \
             --exist-ok
 
+
+snyk:
+    FROM ubuntu:24.04
+    RUN apt-get update && apt-get -y install curl
+    RUN curl --location https://github.com/snyk/cli/releases/download/v1.1291.1/snyk-linux -o /usr/local/bin/snyk
+    RUN chmod a+x /usr/local/bin/snyk
+
+snyk-test:
+    FROM +snyk
+    WORKDIR /s
+    # Take the scan from within the `src/` directory. This seems to help Snyk
+    # actually find the external dependencies that live there.
+    COPY --dir src .
+    WORKDIR src/
+    # Snaptshot the repository and run the scan
+    RUN --no-cache --secret SNYK_TOKEN \
+        snyk test --unmanaged --json > snyk.json
+    SAVE ARTIFACT snyk.json
+
+# snyk-monitor-snapshot :
+#   Post a crafted snapshot of the repository to Snyk for monitoring. Refer to "Snyk Scanning"
+#   in the dev docs for more details.
+snyk-monitor-snapshot:
+    FROM +snyk
+    WORKDIR /s
+    ARG remote="https://github.com/mongodb/mongo-c-driver.git"
+    ARG --required branch
+    ARG --required name
+    IF test "$remote" = "local"
+        COPY --dir src .
+    ELSE
+        GIT CLONE --branch $branch $remote clone
+        RUN mv clone/src .
+    END
+    # Take the scan from within the `src/` directory. This seems to help Snyk
+    # actually find the external dependencies that live there.
+    WORKDIR src/
+    # Snaptshot the repository and run the scan
+    RUN --no-cache --secret SNYK_TOKEN --secret SNYK_ORGANIZATION \
+        snyk monitor \
+            --org=$SNYK_ORGANIZATION \
+            --target-reference=$name \
+            --unmanaged \
+            --print-deps \
+            --project-name=mongo-c-driver \
+            --remote-repo-url=https://github.com/mongodb/mongo-c-driver
+
 # test-vcpkg-classic :
 #   Builds src/libmongoc/examples/cmake/vcpkg by using vcpkg to download and
 #   install a mongo-c-driver build in "classic mode". *Does not* use the local

docs/dev/deps.rst

@@ -21,6 +21,7 @@ tracked separately from the library itself. These can be classified as:
       control over the versions of system dependencies that the user might
       provide to us.
 
+.. _snyk: https://app.snyk.io
 
 The Software Bill of Materials (SBOM)
 *************************************
@@ -95,14 +96,214 @@ process, as this is primarily a release artifact for end users.
 
 The augmented SBOM contains extra data about the dependencies from the
 `SBOM-lite <sbom-lite>`, including vulnerabilities known at the time of the
-augmented SBOM's generation.
+augmented SBOM's generation. [#asbom-vulns]_
 
 The augmented SBOM is produced automatically and asynchronously as part of an
 external process that is not contained within the repository itself. The
 augmented SBOM is downloaded from an internal service using the `+sbom-download`
 Earthly target, which is automatically included in the release archive for the
 `+release-archive` target.
 
+.. _silk-asset-group:
+
+Silk Asset Groups
+*****************
+
+.. note:: A Silk asset group will be created automatically for each branch that
+   is executed in CI.
+
+We use Silk's *asset groups* to allow tracking of multiple versions of the
+SBOM-lite_ simultaneously (i.e. one for each release branch). These asset groups
+correspond to branches within the repository, and are created automatically when
+CI executes for the first time on a particular branch. If you need an asset
+group for a branch that has not run in CI, use the `+create-silk-asset-group`
+Earthly target to create the asset group on-demand.
+
+Note that Silk pulls from the upstream Git repository for an asset group, so
+creating an asset group for a branch that does not exist in the main upstream
+repository will not work.
+
+.. file:: tools/create-silk-asset-group.py
+
+   A Python script that will create an `asset group <silk-asset-group>` in Silk
+   based on a set of parameters. Execute with ``--help`` for more information.
+   For the C driver, it is easier to use the `+create-silk-asset-group` Earthly
+   target.
+
+
+.. _snyk scanning:
+
+Snyk Scanning
+*************
+
+Snyk_ is a tool that detects dependencies and tracks vulnerabilities in
+packages. Snyk is used in a limited fashion to detect vulnerabilities in the
+bundled dependencies in the C driver repository.
+
+.. _snyk caveats:
+
+Caveats
+=======
+
+At the time of writing (June 20, 2024), Snyk has trouble scanning the C driver
+repository for dependencies. If given the raw repository, it will detect the
+mongo-c-driver package as the sole "dependency" of itself, and it fails to
+detect the other dependencies within the project. The `+snyk-test` Earthly
+target is written to avoid this issue and allow Snyk to accurately detect other
+dependencies within the project.
+
+Due to difficulty coordinating the behavior of Snyk and Silk at time of
+writing, vulnerability collection is partially a manual process. This is
+especially viable as the native code contains a very small number of
+dependencies and it is trivial to validate the output of Snyk by hand.
+
+.. seealso:: The `releasing.snyk` step of the release process
+
+
+.. _vuln-reporting:
+
+3rd-Party Dependency Vulnerability Reporting
+********************************************
+
+Vulnerabilities in :term:`bundled dependencies <bundled dependency>` are tracked
+by Snyk, but we maintain a hand-written document that details the
+vulnerabilities in current and past dependencies of in-support release versions.
+
+.. file:: etc/third_party_vulnerabilities.md
+
+   The third-party dependency vulnerabily report. This file is stored in the
+   repository and updated manually as vulnerabilities are added/removed.
+
+   .. seealso:: At release-time, this file is added to the release archive. See:
+      `releasing.vuln-report`
+
+
+Updating the Vulnerability Report
+=================================
+
+When updating `etc/third_party_vulnerabilities.md`, perform the following steps:
+
+1. Open the Snyk_ web UI and sign in via SSO.
+2. Open `this Snyk search query`__ (Find the **mongodb/mongo-c-driver** CLI
+   target within the **dev-prod** organization. Do not use the *GitHub target*:
+   That one is not currently useful to us.)
+
+   __ https://app.snyk.io/org/dev-prod/projects?searchQuery=mongo-c-driver&filters[Integrations]=cli
+3. Expand the **mongodb/mongo-c-driver** target, and then expand all **currently
+   supported release versions**. (If you are preparing for a new release, that
+   version should also be available and used after the `releasing.snyk` process
+   has been completed.)
+4. Take note of *all unique vulnerabilities amongst all supported versions'*
+   that are listed in Snyk. These will be the *relevant* vulnerabilities.
+5. For each relevant vulnerability that is not already listed in
+   `etc/third_party_vulnerabilities.md`, add a new entry under its corresponding
+   package heading that includes the details outlined in the `attribute table`
+   below. [#fixit]_
+
+6. For each *already recorded* vulnerability :math:`V` listed in
+   `etc/third_party_vulnerabilities.md`:
+
+   1. If :math:`V` is not *relevant* (i.e. it is no longer part of any
+      supported release version), delete its entry from
+      `etc/third_party_vulnerabilities.md`.
+   2. Otherwise, update the entry for of :math:`V` according to the current
+      details of the codebase and Snyk report. [#fixit]_
+
+      It is possible that no details need to be modified e.g. if the
+      vulnerability is old and already fixed in a past release.
+
+7. Save and commit the changes to `etc/third_party_vulnerabilities.md`.
+
+
+.. _attribute table:
+
+3rd-Party Dependency Vulnerability Attributes
+=============================================
+
+The following attributes of external vulnerabilities must be recorded within
+`etc/third_party_vulnerabilities.md`.
+
+.. list-table::
+
+   - - Attribute
+     - Explanation
+   - - **Date Detected**
+     - The ISO 8601 date at which the vulnerability was first detected.
+   - - **CVE Number**
+     - The CVE record number. Recommended to include a hyperlink to the CVE.
+
+       Example: `CVE-2023-45853 <https://www.cve.org/CVERecord?id=CVE-2023-45853>`_
+   - - **Snyk Entry**
+     - A link to the Snyk entry in the Snyk Security database.
+
+       Example:
+       `SNYK-UNMANAGED-MADLERZLIB-5969359 <https://security.snyk.io/vuln/SNYK-UNMANAGED-MADLERZLIB-5969359>`_.
+   - - **Severity**
+     - The severity of the vulnerability according to Snyk (Critical/High/Medium/Low)
+   - - **Description**
+     - Paste the description field from Snyk.
+   - - **Upstream Fix Status**
+     - One of "false positive", "won't fix", "fix pending", or "fix available".
+       If a fix is avilable, this entry should include the version number and
+       date at which the upstream project released a fix.
+   - - **mongo-c-driver Fix Status**
+     - One of "false positive", "won't fix", "fix pending", or "fix available".
+       If a fix is avilable, this entry should include the version number and
+       release date of the C driver that includes the fixed version. Use "fix
+       pending" if the bundled dependency has been upgraded but there has not
+       been a release that includes this upgrade.
+   - - **Notes**
+     - If a fix is available from the upstream package but has been purposefully
+       omitted from a C driver release, this field should explain the reasoning
+       for that omission.
+
+       Other notes about the vulnerability that may be useful to users and
+       future developers can also be included here.
+
+
+.. rubric:: Example
+
+The following is an example for a vulnerability listing in
+`etc/third_party_vulnerabilities.md`
+
+.. code-block:: markdown
+
+   # Zlib
+
+   ## CVE-2023-45853 - Integer Overflow or Wraparound
+
+   - **Date Detected**: 2024-06-24
+   - **CVE Number**: [CVE-2023-45853](https://www.cve.org/CVERecord?id=CVE-2023-45853)
+   - **Snyk Entry**: [SNYK-UNMANAGED-MADLERZLIB-5969359](https://security.snyk.io/vuln/SNYK-UNMANAGED-MADLERZLIB-5969359)
+   - **Severity**: High
+   - **Description**: Affected versions of this package are vulnerable to
+     Integer Overflow or Wraparound via the `MiniZip` function in `zlib`, by
+     providing a long filename, comment, or extra field.
+   - **Upstream Fix Status**: Fix available (1.3.1, 2024-01-22)
+   - **mongo-c-driver Fix Status**: Fix available (1.27.3, 2024-06-26)
+   - **Notes**: This issue was related to Zip file handling, which was not used
+     by mongo-c-driver. This errant code was never reachable via the C driver
+     APIs.
+
+
+.. rubric:: Footnotes
+
 .. [#f1]
 
-   This may change in the future depending on how the process may evolve.
+   This may change in the future depending on how the process may evolve.
+
+.. [#asbom-vulns]
+
+   At time of writing, the vulnerabilities listing in the augmented SBOM is
+   incomplete and vulnerability collection is partially manual. See:
+   `snyk caveats` and `releasing.vuln-report`.
+
+.. [#fixit]
+
+   If a fix is available and is reasonably easy to introduce, consider upgrading
+   the associated dependency to include a fix before the next release is
+   finalized.
+
+   If a fix is available but *not* applied, then the rationale for such a
+   decision will need to be included in the vulnerability listing (See the
+   **Notes** section in the `attribute table`).