How to Read an SBOM

An SBOM, or Software Bill of Materials, is a list of every component inside a piece of software. People compare it to a nutrition label, and that is a good analogy: it tells you exactly what is in the box. If someone hands you an SBOM, or you generate one, the file can look intimidating at first because it is machine-readable and often thousands of lines long. It is actually simpler than it looks once you know which fields matter. This guide teaches you to read one confidently.

What you will accomplish

You will open a real SBOM, understand its top-level structure and the key fields on each component, and run a check that turns the raw list into a list of known vulnerabilities. No prior experience required.

Prerequisites

• A terminal and basic command-line comfort.
• An SBOM file, or a project you can generate one from.
• The command-line JSON tool jq (optional but very helpful).
• The Safeguard CLI, installed in Step 2.

Step 1: Get an SBOM to read

If you do not have one yet, generate one from any project. Syft is a free, popular generator:

curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
syft dir:. -o cyclonedx-json=sbom.json

You now have a file called sbom.json in the CycloneDX format, one of the two common standards (the other is SPDX).

Step 2: Look at the top-level structure

Open the file and read just the header fields:

sg --version
jq 'keys' sbom.json

At the top you should see a bomFormat field set to CycloneDX, a specVersion such as 1.5, and a components array. That components array is the heart of the file. Everything else is metadata describing when and how the SBOM was made.

Step 3: Count the components

Before reading individual entries, get a sense of scale:

jq '.components | length' sbom.json

A number in the hundreds or thousands is normal. This count should roughly match the number of packages in your lockfile. If it is wildly smaller, the SBOM may have captured only direct dependencies and missed the transitive ones.

Step 4: Read a single component

Pull out the first component and study its fields:

jq '.components[0]' sbom.json

The fields that matter most to a beginner are:

• name and version — which library and which exact release.
• purl — the Package URL, a single string that unambiguously identifies the component and ecosystem, such as pkg:npm/lodash@4.17.21.
• licenses — the license terms, which matter for legal compliance.
• type — usually library, sometimes application or operating-system.

If you understand those five fields, you can read any component in the file.

Step 5: List every component by name and version

Now scan the whole inventory in a readable form:

jq -r '.components[] | "\(.name) \(.version)"' sbom.json | sort | head -40

This gives you the human-readable version of what the SBOM contains. Scroll through it. You will often recognize familiar libraries and spot a few you did not know were in your project.

Step 6: Turn the list into vulnerability information

An SBOM by itself just tells you what you have. Its real power is answering "am I affected?" when a new vulnerability drops. Cross-reference the inventory against advisory data:

sg scan --sbom sbom.json

Now the plain list becomes a prioritized set of findings: which components have known CVEs, how severe they are, and which versions fix them.

How to know it worked

• jq 'keys' sbom.json showed bomFormat, specVersion, and components.
• The component count is in the same ballpark as your lockfile.
• You can name the five key fields on a component and say what each means.
• The vulnerability check returned findings, or a clean result, tied to specific components.

If you can open the file, explain what a purl is, and produce a vulnerability list from it, you can read an SBOM.

Next steps

1. Store SBOMs for every release so that when the next big vulnerability lands, you can search past builds in minutes.
2. Automate generation in your build so the SBOM always reflects what actually shipped.
3. Learn the formats more deeply, including CycloneDX versus SPDX, in the concepts library.
4. Use the SBOM for license review, not just security, since the licenses field is right there.

To understand how an inventory becomes a risk report, read about software composition analysis, and see how the Safeguard CLI generates and scans SBOMs with one tool. When you are ready to manage SBOMs across many projects, the lessons in the Safeguard Academy show you how teams do it at scale.

Frequently Asked Questions

What is the difference between CycloneDX and SPDX? They are the two dominant SBOM formats. CycloneDX grew out of the security community and handles vulnerability references naturally, while SPDX came from the Linux Foundation with a stronger historical focus on licensing. Both describe the same kind of inventory, and good tools can read and convert between them.

What is a purl and why does it matter? A purl, short for Package URL, is a single string that identifies a component precisely, including its ecosystem, name, and version, such as pkg:npm/lodash@4.17.21. It matters because names alone are ambiguous across ecosystems, and a purl removes that ambiguity so vulnerability matching is accurate.

Do I need to read the whole SBOM by hand? No. Reading one or two components teaches you the structure, but you should let tools do the bulk work of scanning the full list for vulnerabilities and license issues. The value of an SBOM is that it is machine-readable, so machines can answer questions about it instantly.

How is an SBOM actually useful day to day? Its biggest payoff is incident response. When a widely used library has a critical vulnerability disclosed, you can search your stored SBOMs and know within minutes whether any of your releases include the affected component and version, instead of manually auditing every project.

Want your SBOMs generated, stored, and continuously scanned automatically? Get started at app.safeguard.sh/register, and deepen your knowledge in the Safeguard Academy.