Install the Safeguard CLI, run safeguard scan --dir . in your project, and it builds an SBOM and matches it against vulnerability databases, writing JSON results under ./output. Check any CycloneDX or SPDX file with safeguard validate. Then run safeguard and ask the built-in assistant, in plain language, what the results mean and what to fix.
You do not have to give up the AI tools you already pay for to work this way. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. If you prefer to stay in a chat window, connect Claude or ChatGPT to the Safeguard MCP server and ask about your SBOMs from there.
This guide covers what belongs in an SBOM, how CycloneDX and SPDX differ, a full terminal walkthrough with real commands, and the questions worth asking an assistant once the file exists.
What an SBOM is and what should be in it
A software bill of materials is a list of the components that make up a piece of software, with enough detail to identify each one and look it up in vulnerability and licence databases. The useful test is simple: when a new advisory lands, can you answer "do we ship this?" from the SBOM alone, without rebuilding anything?
The baseline most teams still work from is the NTIA report "The Minimum Elements For a Software Bill of Materials", published on 12 July 2021. It names seven data fields:
- Supplier name: the entity that creates, defines and identifies the component.
- Component name: the name the supplier gives the unit of software.
- Version of the component: the identifier that marks a change from a previous release.
- Other unique identifiers: look-up keys such as CPE, SWID tags and Package URLs (PURL).
- Dependency relationship: that an upstream component X is included in software Y.
- Author of SBOM data: who created the SBOM data for the component.
- Timestamp: when the SBOM data was assembled.
The same report sets out practices that matter as much as the fields. On frequency, a new build or release needs a new SBOM. On depth, the SBOM should list all top level components with their transitive dependencies, or at minimum enough detail to find them. On known unknowns, where the graph is incomplete the author must say so explicitly, and the default reading of the data should be that it is incomplete.
In August 2025 CISA published a public comment draft, "2025 Minimum Elements for a Software Bill of Materials". It is marked pre-decisional and not the final position of the US Government, but it shows where expectations are heading. The draft adds four new fields: Component Hash, License, Tool Name and Generation Context (whether the SBOM was produced before, during or after the build). It also updates SBOM Author, Software Producer, Component Version, Software Identifiers and Dependency Relationship, and it asks agencies to avoid SBOMs generated in deprecated versions of a format.
Two practical takeaways for anyone generating SBOMs from a terminal:
- Prefer tooling that records Package URLs, versions and the dependency graph, not just a flat list of names.
- Record when and how the SBOM was made. The timestamp and the tool are part of the evidence, and the draft's Generation Context field makes this explicit.
CycloneDX or SPDX: picking a format
Both formats are open standards, both are machine readable, and both are accepted widely. The choice usually comes down to what your customers or auditors ask for. These facts come from each project's own pages.
| CycloneDX | SPDX | |
|---|---|---|
| Steward | OWASP Foundation, with Ecma International TC54 | Linux Foundation project |
| Formal standard | ECMA-424 | ISO/IEC 5962:2021 |
| Current version named on its site | 1.7 | 3.0 |
| Serialisations | JSON, XML, Protobuf | Machine and human readable formats (tag-value, JSON, YAML and RDF are the ones safeguard validate reads) |
| Scope beyond software | SaaSBOM, HBOM, cryptographic assets, operational configuration | Provenance, licensing and security data |
| Vulnerability and VEX data | Built in, described as suited to "vulnerability disclosure and VEX use cases" | Security data is part of its stated scope |
A few rules of thumb:
- If a customer contract names a format, produce that one. Converting later loses detail more often than people expect.
- If the SBOM is mostly for your own vulnerability management, either format works. Pick one and stay consistent across releases so diffs are meaningful.
- Keep VEX statements next to the SBOM they describe. A VEX that says "not affected" means little without the exact component list it refers to.
Tools that appear in this walkthrough
| Tool | Interface | Licence | What it does here | Where it runs |
|---|---|---|---|---|
| Safeguard CLI | Terminal binary with an interactive assistant | Not described as open source | Builds an SBOM, matches it to vulnerability data, validates CycloneDX, SPDX and VEX, answers questions | Your machine; only SBOMs and findings are uploaded |
| Syft | Terminal, also a Go library | Apache-2.0 | Generates SBOMs from container images and filesystems in CycloneDX, SPDX and its own JSON | Your machine |
| Grype | Terminal | Apache-2.0 | Scans images, directories and SBOM files for known vulnerabilities, with OpenVEX support | Your machine |
The Safeguard usage docs note that safeguard scan requires Syft and Grype, either on your PATH or in a folder set by TOOLS_DIR. On a normal first run the CLI downloads its scanner tools for you; in a fresh CI container, check that they are present.
Build an SBOM from the terminal, step by step
This walkthrough takes a project from nothing to a validated SBOM with vulnerability results. Every command comes from the Safeguard CLI docs or the Syft README.
Step 1: install the CLI
On macOS and Linux:
curl -fsSL https://cli.safeguard.sh/install | bash
On Windows, in PowerShell:
irm https://cli.safeguard.sh/install.ps1 | iex
It is a single static binary, so there is no Node, Python or JVM to install first. The download page lists CLI 1.4.0 with builds for macOS on Apple Silicon and Intel, Linux on x86_64 and arm64, and Windows on x86_64. Each release ships a SHA256SUMS file that the installer checks.
Step 2: sign in
safeguard login
Your browser opens to approve the session. On a machine with no browser, add --no-browser. Check who you are signed in as with safeguard whoami.
Step 3: scan the project folder
cd ~/projects/payments-api
safeguard scan --dir .
The CLI builds an SBOM for the directory and matches it against vulnerability databases. Results are written as JSON files in a folder per scan under ./output, including vuln.json, license.json and collection.json. Use --output to choose a different folder.
Two flags from the usage docs are worth knowing on the first run: --resolve-transitive, which matters for the depth practice above, and --verbose for more detail when something looks wrong. safeguard scan --help has the exact behaviour of each flag.
Step 4: read the exit code
Scripts should look at the exit code before they look at the files:
0: the scan ran.1: the command failed.2: results were written, but the vulnerability scan did not run.
Exit code 2 is the one people miss. The files exist, so a careless script treats it as success. Treat it as a failure and investigate.
Step 5: scan an image, a repo, or an existing SBOM
safeguard scan takes exactly one target:
safeguard scan --image nginx:latest
safeguard scan --repo https://github.com/org/repo
safeguard scan --sbom sbom.json
For private repositories, pass --git-token. For private images, the image flag takes optional registry credentials. With --sbom, the CLI accepts SPDX or CycloneDX and detects which one automatically; force it with --format spdx or --format cyclonedx if detection guesses wrong.
Step 6: produce a standalone file in the format a customer asked for
When someone asks you for "a CycloneDX file" or "an SPDX file", generate it with Syft and keep it with the release:
syft ./ -o cyclonedx-json=./sbom.cdx.json -o spdx-json=./sbom.spdx.json
The Syft README shows writing several formats in one run this way, and syft <image> -o cyclonedx-json for container images. Then feed that exact file back into Safeguard so the findings match what you hand over:
safeguard scan --sbom ./sbom.cdx.json
Step 7: validate before you ship
safeguard validate sbom.cdx.json
safeguard validate ./sboms --recursive
safeguard validate sbom.spdx.json --strict -o report.json
safeguard validate checks CycloneDX (JSON and XML), SPDX (JSON, YAML, tag-value and RDF) and VEX documents (CSAF and OpenVEX). --strict turns warnings into errors, --fail-fast stops at the first problem, and -o writes a report you can attach to a release ticket.
Step 8: keep the databases fresh, even offline
safeguard update
safeguard update refreshes the vulnerability databases, not the binary. On a machine with no internet access, safeguard update --import loads a database downloaded elsewhere. To update the CLI itself, use safeguard self-update.
Do the work properly with the Safeguard CLI
The Safeguard CLI scans code, container images and SBOMs on your own machine, sends only the results to the platform, and includes an assistant that can fix what it finds. That last part is what turns an SBOM from a file you produce for someone else into something you act on.
Install
curl -fsSL https://cli.safeguard.sh/install | bash
On Windows, irm https://cli.safeguard.sh/install.ps1 | iex. It runs on macOS, Linux and Windows, on x86_64 or arm64; Windows is x86_64 only.
First session
Run safeguard with no arguments to open the interactive terminal. Type /login to sign in through the browser, then /scan . to scan the current folder. From there you can ask in plain language, for example "how many critical vulns do we have" or "fix the lodash CVE in this repo".
The assistant has tools for local files and for your Safeguard data, and it picks whichever the question needs. Type @ to attach a file from the folder you started in, such as an SBOM you just generated. /resume picks up the last session in that folder tomorrow.
Writing and fixing code
The Safeguard CLI writes code, not only scans it. With your approval it can find and read files, edit code and run commands. So after a scan you can ask it to upgrade a vulnerable dependency, run your tests, and rescan, all in one session. A typical sequence looks like this:
/scan .
which critical findings in this repo have a fixed version?
upgrade that package in the manifest and lockfile, then run the tests
/scan .
Steps that write a file or run a command ask before they act, according to your /permissions mode; in Ask mode you see every change before it lands. The second /scan . is the step people skip; it is the one that proves the finding is gone and that the SBOM now lists the new version.
This walkthrough shows that loop: attach a computer running the Safeguard CLI and a folder, ask for a fix, review the diff and approve the command before it runs. The demo notes that computer work from Search is available and expanding.
Click through it at your own pace, or open it full screen.
Use your Claude, ChatGPT or Codex plan
Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. /model shows or switches the AI model. For connecting a model, see the CLI docs and the /model picker.
Approvals
Tools that change things ask before they act. /permissions sets the mode: Ask prompts before every action, Auto approves known actions and asks about anything new (the default), and Yolo approves everything. For SBOM work in a release branch, Ask or Auto is the sensible choice.
CI with safeguard exec
safeguard exec runs one non-interactive assistant turn, which suits a pipeline step after the scan:
safeguard scan --dir .
safeguard exec "summarise the critical findings in this repository"
Policies and gates are evaluated in the Safeguard platform, not by the CLI. There is no severity threshold flag on safeguard scan; if you want a build to fail on findings, set that up as a platform policy gate.
Ask the assistant about your SBOM
An SBOM is only useful if someone reads it. Few people want to read a long JSON file line by line. This is where an assistant earns its place. Start in the project folder, run safeguard, and try prompts like these. Answers depend on your project and your account.
Prompts that read the local files
Type @, pick the SBOM or a results file from ./output, then ask:
how many components are in this SBOM, and how many have no version?
which packages in this file have no Package URL?
list the licences in license.json and flag any that are copyleft
does this SBOM list transitive dependencies, or only direct ones?
These questions map straight onto the NTIA fields and practices. Missing versions and missing identifiers are the most common reasons an SBOM fails to match against vulnerability data.
Prompts that use your Safeguard data
how many critical vulns do we have
which of the critical findings in this repo have a fixed version available?
fix the lodash CVE in this repo
The first comes straight from the docs. The last one edits code, so it asks before it acts. Read the proposed change, approve it, then run /scan . again to confirm the finding is gone.
Prompts that compare releases
Generate an SBOM for each release tag and keep both. Then attach them one after another and ask:
what components were added or removed between these two SBOMs?
This is the question auditors and customers ask after an incident: did the vulnerable component arrive in this release, or was it always there?
Asking from Claude or ChatGPT instead
If you spend your day in a chat app, you can ask the same questions there. The download page lists Claude in its connector directory (web, desktop or mobile, with OAuth sign in) and ChatGPT in its plugin directory. Other MCP clients can use the endpoint at mcp.safeguard.sh/mcp.
This walkthrough connects Claude to the Safeguard MCP server with OAuth and lets you choose which tools Claude can use.
Click through it at your own pace, or open it full screen.
Terminal, desktop and phone
The CLI is one door into a single platform, and the download page lists the others. Generate and validate the SBOM in the terminal, open the desktop app (3.2.2, for Windows, macOS and Linux) to ask your supply chain anything in plain English in a native window, and check new findings on the iOS or Android app on the way home. IDE extensions for VS Code, JetBrains and Open VSX editors and a browser extension cover the rest. If you want to try it with nothing installed, the cloud sandbox gives you an isolated tenant against a seeded demo repo, free for seven days with no card.
For a deeper look at the assistant itself, see the security aware coding assistant post. If another agent writes most of your code, checking coding agent changes with the Safeguard CLI shows how to scan its changes before you merge.
Common mistakes
Generating the SBOM from the wrong place. An SBOM of the source folder and an SBOM of the built container image are different documents. The image includes the base OS packages; the folder does not. Decide which one your customer needs, and record that choice. The CISA draft's Generation Context field exists for exactly this reason.
Shipping without a lockfile. Without a lockfile, a directory scan sees version ranges, not resolved versions. Commit the lockfile, then scan.
Treating exit code 2 as success. It means results were written but the vulnerability scan did not run. Run safeguard doctor to check environment, sign in, tools and policy. It changes nothing.
Missing scanner tools in CI. Fresh containers often lack Syft and Grype. Put them on PATH or set TOOLS_DIR.
Handing over one file and scanning another. If you give a customer sbom.cdx.json, run safeguard scan --sbom sbom.cdx.json on that same file. Otherwise your findings and theirs will not match.
Skipping validation. A hand edited SBOM can be valid JSON and still invalid CycloneDX. safeguard validate --strict catches that before your customer's tooling does.
Regenerating only at major releases. The NTIA frequency practice says every new build or release needs a new SBOM. Make it a pipeline step, not a quarterly chore.
Leaving VEX statements orphaned. A VEX document needs the exact SBOM it refers to. Version them together, and validate both.
FAQ
What is the fastest way to generate an SBOM from the terminal?
Install the Safeguard CLI, sign in, and run safeguard scan --dir . in your project. It builds an SBOM, matches it against vulnerability databases, and writes JSON results under ./output. If you need a standalone CycloneDX or SPDX file to hand over, generate it with Syft and scan that file with safeguard scan --sbom.
Should I use CycloneDX or SPDX?
Use whichever your customer or regulator asks for. CycloneDX is standardised as ECMA-424 and carries vulnerability and VEX data in the same document. SPDX is ISO/IEC 5962:2021 and is widely used for licence compliance. Safeguard reads and validates both.
Does my source code leave my machine?
Your source code never leaves the machine when the local runner runs platform scan jobs; only SBOMs and findings are uploaded. The same holds for /scan . from the interactive terminal while signed in.
Can I keep using my Claude, ChatGPT or Codex plan?
Yes. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. You can also connect Claude or ChatGPT to the Safeguard MCP server and ask about your SBOMs from the chat you already use. See the CLI docs or /model for connecting a model.
How do I check that an SBOM file is valid?
Run safeguard validate sbom.json. Add --recursive for a folder of files, --strict to treat warnings as errors, and -o report.json to save a report. It checks CycloneDX, SPDX and VEX documents.
Can I fail a CI build on critical findings?
Not with a CLI flag. There is no severity threshold option on safeguard scan. Gating on findings is done through policy gates in the Safeguard platform. In the pipeline, the CLI produces the SBOM and findings, and safeguard exec can summarise them for the job log.
Does it work without internet access?
Scanning runs locally. To keep vulnerability data current on an isolated machine, download the database elsewhere and load it with safeguard update --import.
Will the assistant change my files on its own?
Only within the approval mode you choose. Writing a file, editing code and running a command ask before they act. Auto, the default, approves known actions and asks about anything new. You can switch to Ask with /permissions for release branches.
Try it yourself
This walkthrough sets up the runner on your own machine: pick the platform, start it, approve it with its device code, then use the same CLI to scan from the terminal.
Click through it at your own pace, or open it full screen.
Ready to generate your first SBOM? Download the Safeguard CLI, run safeguard scan --dir ., and validate the result with safeguard validate. The full reference is in the CLI docs.
Quick check
What does exit code 2 from safeguard scan mean?
Results were written, but the vulnerability scan did not run. Treat it as a failure and run safeguard doctor.
Which four fields does the CISA 2025 draft add to the NTIA minimum elements?
Component Hash, License, Tool Name and Generation Context. The draft is a public comment version, not final guidance.
Where are policies and gates evaluated?
In the Safeguard platform, not by the CLI. The CLI produces SBOMs and findings; the platform decides whether a build passes.
Sources
- Safeguard CLI overview
- Safeguard CLI usage guide
- Safeguard CLI interactive terminal
- Safeguard downloads
- NTIA: The Minimum Elements For a Software Bill of Materials (PDF)
- CISA: 2025 Minimum Elements for a Software Bill of Materials, public comment draft (PDF)
- CycloneDX specification overview
- SPDX overview
- Syft repository and README
- Grype repository and README
Last reviewed: 21 October 2026.
