Introducing parlay, a tool for enriching SBOMs

Written by:

June 7, 2023

0 mins read

We need richer SBOMs

The increasing adoption of software bill of materials (SBOM) standards are starting to drive better interoperability between security tools. The NTIA’s work on defining a minimum set of elements for an SBOM was a key part of that, especially with multiple formats like CycloneDX and SPDX in widespread use. But with work on SPDX 3.0 and CycloneDX 1.5 progressing, there are lots of things we can do with the SBOM formats beyond the minimum elements.

Maybe you want to make policy-based decisions around package license information. Maybe you want quick links to the websites of the packages you’re using or want to know who created them. Maybe you want to understand the vulnerabilities in those packages alongside that information.

Introducing Parlay

parlay is a new open source tool from Snyk that enriches SBOMs. It’s easiest to demonstrate with an example, so let's take a simple SBOM of a JavaScript application.

1$ cat testing/sbom.cyclonedx.json
2...
3{
4	"bom-ref": "68-subtext@6.0.12",
5	"type": "library",
6	"name": "subtext",
7	"version": "6.0.12",
8	"purl": "pkg:npm/subtext@6.0.12"
9}
10...

Using parlay, we enrich it using data from ecosyste.ms:

$ cat testing/sbom.cyclonedx.json | parlay ecosystems enrich -

This adds information about each package including license details, external links, maintainer information, and more.

1...
2{
3	"bom-ref": "68-subtext@6.0.12",
4	"type": "library",
5	"supplier": {
6		"name": "hapi.js",
7		"url": [
8			"https://hapi.dev"
9		]
10	},
11	"author": "hapi.js",
12	"name": "subtext",
13	"version": "6.0.12",
14	"description": "HTTP payload parsing",
15	"licenses": [
16		{
17			"expression": "BSD-3-Clause"
18		}
19	],
20	"purl": "pkg:npm/subtext@6.0.12",
21	"externalReferences": [
22		{
23			"url": "https://github.com/hapijs/subtext",
24			"type": "website"
25		},
26		{
27			"url": "https://www.npmjs.com/package/subtext",
28			"type": "distribution"
29		},
30		{
31			"url": "https://github.com/hapijs/subtext",
32			"type": "vcs"
33		}
34	],
35	"properties": [
36		{
37			"name": "ecosystems:first_release_published_at",
38			"value": "2014-09-29T01:56:03Z"
39		},
40		{
41			"name": "ecosystems:latest_release_published_at",
42			"value": "2019-01-31T19:36:58Z"
43		}
44	]
45}
46...

parlay also supports enrichment with Snyk vulnerability data for Snyk customers.

parlay snyk enrich testing/sbom.cyclonedx.json

This adds add a new vulnerabilities attribute to the SBOM, for example:

1"vulnerabilities": [
2  {
3    "bom-ref": "68-subtext@6.0.12",
4    "id": "SNYK-JS-SUBTEXT-467257",
5    "ratings": [
6      {
7        "source": {
8          "name": "Snyk",
9          "url": "https://security.snyk.io"
10        },
11        "score": 7.5,
12        "severity": "high",
13        "method": "CVSSv31",
14        "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H"
15      }
16    ],
17    "cwes": [
18      400
19    ],
20    "description": "Denial of Service (DoS)",
21    "detail": "...",
22    "advisories": [
23      {
24        "title": "GitHub Commit",
25        "url": "https://github.com/brave-intl/subtext/commit/9557c115b1384191a0d6e4a9ea028fedf8b44ae6"
26      },
27      {
28        "title": "GitHub Issue",
29        "url": "https://github.com/hapijs/subtext/issues/72"
30      },
31      {
32        "title": "NPM Security Advisory",
33        "url": "https://www.npmjs.com/advisories/1168"
34      }
35    ],
36    "created": "2019-09-19T10:25:11Z",
37    "updated": "2020-12-14T14:41:09Z"
38  }

parlay is a big fan of stdin and stdout — you can pipe SBOMs from other tools into parlay, and pipe between the separate enrich commands as well.

Maybe you want to enrich an SBOM with both ecosyste.ms and Snyk data:

cat testing/sbom.cyclonedx.json | parlay e enrich - | parlay s enrich - | jq

Maybe you want to take the output from Syft and add vulnerability data:

syft -o cyclonedx-json nginx | parlay s enrich - | jq

Maybe you want to generate an SBOM with Snyk, enrich it with extra information, and test with bomber:

snyk sbom | parlay e enrich - | bomber scan --provider snyk -

The ecosyste.ms enrichment adds license information, which Bomber reveals when scanning an SBOM for vulnerabilities:

1Ecosystems detected: gem
2■ Scanning 18 packages for vulnerabilities...
3■ Vulnerability Provider: Snyk (https://security.snyk.io)
4
5■ Files Scanned
6        - (sha256:701770b2317ea8cbd03aa398ecb6a0381c85beaf24d46c45665b53331816e360)
7
8■ Licenses Found: MIT, Apache-2.0, BSD-3-Clause, Ruby

What’s next?

We’d like to hear what people think about the concept of enriching SBOMs. Lots of existing and new tools are generating SBOMs in both CycloneDX and SPDX, but those SBOMs are often fairly minimal. With richer SBOMs we can build more interesting tools on top. And for all the work on generating SBOMs to be worth the investment, we need more tools to consume them and solve user problems.

You can download parlay from the releases section of the GitHub repository. To learn some advanced scenarios — including pipelining and policy checking — and follow along with a sample project, check out our guide to parlay and what you can do with an enriched SBOM.

We’ve started with Ecosyste.ms, Snyk enrichment, and CycloneDX, but if you have ideas for other sources of data, or want to help support SPDX, please open an issue in the official GitHub repository.