@mongodb-js/sbom-tools

Utilities to generate sbom reports for webpack bundles.

Reporting of 3rd party vulnerabilities and licenses

This package exports WebpackDependenciesPlugin, a shared webpack plugin that reports bundled dependencies and licenses as a json file for each bundle.

And exposes a mongodb-sbom-tools binary providing the following commands:

- generate-vulnerability-report: Generates a report of vulnerabilities from the output of snyk test and a dependencies json file containing all the dependencies.
- generate-3rd-party-notices: Generates a 3rd party notices file based on the licenses information collected by the WebpackDependenciesPlugin. Also validates the licenses.
- scan-node-js: A script to produce a list of vulnerabilities affecting a Node.js version in the same format as snyk test (useful as we are redistributing Node.js with mongosh).
- fetch-codeql-results: A script to fetch CodeQL results from GitHub.
- sarif-to-markdown: Convert SARIF CodeQL results to markdown.

$3

This plugin taps in the webpack compilation, collects the modules from 3rd party dependencies as they are resolved and writes an output file containing metadata about dependencies and licenses included in the bundle. The plugin ignores dependencies that are removed from the bundle via resolve: {alias: {: false}}.

Setting includeExternalProductionDependencies to true the plugin will also include recursively any production and optional dependencies listed in the package.json, regardless of their inclusion in the bundle.

#### Usage

``js
// webpack.config.js

const webpackDependenciesPlugin = new WebpackDependenciesPlugin({
outputFilename: 'dependencies.json',
includePackages: ['electron'],
includeExternalProductionDependencies: true,
});


module.exports = { ..., plugins: [buildInfoPlugin] }
`

Example Output

`json
dependencies.json

[{
"name": "@aws-sdk/client-cognito-identity",
"version": "3.267.0",
"name": "@aws-sdk/client-cognito-identity",
"version": "3.321.1",
"license": "Apache-2.0",
"path": ".../node_modules/@aws-sdk/client-cognito-identity",
"licenseFiles": [
{
"filename": "LICENSE",
"content": "..."
}
]
}, ...]
`

$3

Outputs a markdown report of vulnerabilities given one or more dependencies.json files and the output of one or more multiple snyk test.

If --create-jira-issues is set then each vulnerability that is not ignored will be also reported as a jira issue.

The jira issue creation must be configured setting the following environment variables:

- JIRA_BASE_URL (required): The base url of the jira api (excluded the /rest/api/...).
- JIRA_API_TOKEN (required): A jira PAT.
- JIRA_PROJECT (required): The project used to create the ticket.
- JIRA_VULNERABILITY_BUILD_INFO: Additional build info added to the ticket description (for example the commit id).

#### Usage

`
Usage: bin generate-vulnerability-report [options]

Generate vulnerabilities report

Options:
--dependencies Comma-separated list of dependency files (default: [])
--snyk-reports Comma-separated list of snyk
result files (default: [])
--fail-on [level] Fail on the specified severity
level
--create-jira-issues Create Jira issues for the vulnerabilities found
-h, --help display help for command
`

Example output:

`md
| dep@version | id | score | fixed in | ignored |
| ------------ | --------------------- | ------------ | -------- | -------------------- |
| jquery@2.2.4 | SNYK-JS-JQUERY-567880 | 6.5 (Medium) | 3.5.0 | - |
| got@10.7.0 | SNYK-JS-GOT-2932019 | 5.4 (Medium) | 11.8.5 | Ignored. Reason: ... |
`

#### Ignored vulnerabilities

The generate-vulnerability-report command must run from a directory containing a .snyk policy file. The Snyk’s policy rules are applied to determine if a vulnerability must be reported as ignored or not.

Ignored vulnerabilities won’t cause the report to fail with an error when --fail-on is specified.

#### Fail on

--fail-on configures the command to fail with an error if the report contains a vulnerability that:

- Does not have a known severity
- Has a score greater or equal to the specified severity
- Is not ignored
- Has a know remediation path (the “fixed in” column is not empty)

$3

Takes one or more dependencies.json files and generates a markdown report for 3rd party licenses. Validates that licenses are among the list of allowed licenses.

When the command encounters a package with a license that is not allowed, the generation breaks. False positives can be ignored by excluding or overriding the license for specific packages or organizations.

The following licenses are allowed:

- MIT
- 0BSD
- BSD-2-Clause
- BSD-3-Clause
- BSD-4-Clause
- Apache-2.0
- ISC
- CC-BY-4.0
- WTFPL
- OFL-1.1
- Unlicense
- BlueOak-1.0.0

The validation can be tweaked with a configuration file (by default ${cwd}/licenses.json). The configuration allows ignoring certain orgs and packages, and overriding licenses for specific dependencies.

Overrides and excluded packages are checked for existence inside the dependencies.json in order to avoid forgetting exceptions on removed dependencies.

#### Usage

`
Usage: bin generate-3rd-party-notices [options]

Generate third-party notices

Options:
--product Product name
--config [config] Path of the configuration file (default:
"licenses.json")
--dependencies Comma-separated list of dependency files
(default: [])
-h, --help display help for command
`

Example config:

`json
{
// remove orgs and packages from the report
"ignoredOrgs": ["@mongodb-js", "@leafygreen-ui", "@mongosh"],
"ignoredPackages": ["package1"],
// include packages in the report, just skip validation
"doNotValidatePackages": ["package2"],
"additionalAllowedLicenses": ["PYTHON-2.0"],
"licenseOverrides": {
"@segment/loosely-validate-event@2.0.0": "MIT",
"component-event@0.1.4": "MIT",
"delegate-events@1.1.1": "MIT",
"events-mixin@1.3.0": "MIT",
"sprintf@0.1.3": "BSD-3-Clause"
}
}
`

Example output:

`md
The following third-party software is used by and included in Mongodb Compass.
This document was automatically generated on Sun May 14 2023.

List of dependencies

| Package | Version | License |
| --------------------------------------------------------------------------------------------------------- | ------- | ---------- |
| @aws-sdk/client-cognito-identity | 3.321.1 | Apache-2.0 |

...

Package details

$3

License tags: Apache-2.0

License files:

- LICENSE:

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

...
`

$3

This command scans a Node.js version for known vulnerabilities and produces a report that is conforming to the snyk test output format and can be used with generate-vulnerability-report.

scan-node-js fails with an error if the Node.js version is not officially supported anymore. Otherwise it builds a list of vulnerability scanning the database published by the Node.js security-wg https://raw.githubusercontent.com/nodejs/security-wg/main/vuln/core/index.json, and enriching it with cvss from the nvd.nist.gov database.

The output reports vulnerabilities as they would have been found in a “fake” .node.js npm package, with the recommended NSWG-COR-*. That is useful in conjunction with generate-vulnerability-report as it allows the use of the same policies for ignoring vulnerabilities and includes Node.js in the report as any other package.

#### Usage

`
Usage: bin scan-node-js [options]

Scan node.js version for known vulnerabilities

Options:
--version Path to the node.js security-wg core
database of vulnerabilities
-h, --help display help for command
`

Use in conjunction with generate-vulnerability-report:

`sh
echo '[{name: ".node.js", version:"'"$NODE_JS_VERSION"'"}]' > node-js-dep.json
mongodb-sbom-tools scan-node-js --version=$NODE_JS_VERSION > node-js-vuln.json

mongodb-sbom-tools generate-vulnerability-report
--dependencies=node-js-vuln.json --snyk-report=node-js-vuln.json
``