Key facts
- Best input
- The lockfile committed with the release you ship
- Common output
- CycloneDX JSON
- When to regenerate
- Every release that changes dependencies
- What lockfiles miss
- Vendored code, native binaries, engines and runtimes
Why start from the lockfile
A manifest such as package.json lists the ranges you asked for. A lockfile records what your package manager actually resolved: every direct and transitive dependency, pinned to an exact version, often with an integrity hash. That is exactly what an SBOM needs to describe, and it is already in your repository.
Starting from the lockfile also makes the SBOM reproducible. The same commit always produces the same component list, which is what you want in technical documentation.
Lockfiles by ecosystem
| Ecosystem | Lockfile | Note |
|---|---|---|
| npm | package-lock.json |
Written by default |
| Yarn | yarn.lock |
Classic and Berry formats differ |
| pnpm | pnpm-lock.yaml |
Written by default |
| CocoaPods | Podfile.lock |
Commit it with the app |
| Swift Package Manager | Package.resolved |
Inside the Xcode project for app targets |
| Gradle | gradle.lockfile |
Only after you enable dependency locking |
| Flutter and Dart | pubspec.lock |
Commit it for apps |
| Unity | Packages/packages-lock.json |
Covers Unity packages, not the engine |
| NuGet | packages.lock.json |
Only with RestorePackagesWithLockFile enabled |
If your project has no lockfile, turn locking on first. Generating an SBOM from loose version ranges gives you a list that may not match what you shipped.
Generate it, step by step
- Check out the release commit and make sure the lockfile is current, for example with
npm cior a clean build. - Pick a generator for your ecosystem. The CycloneDX project maintains official ones:
@cyclonedx/cyclonedx-npmfor npm, plugins for Gradle and Maven,CycloneDXfor .NET, andcdxgen, which covers many ecosystems at once. - Generate CycloneDX JSON. For an npm project:
npx @cyclonedx/cyclonedx-npm --output-file sbom.json. - Describe your product. Make sure
metadata.componentcarries your product’s name and the exact version you are releasing. Generators often fill in the package name but not the marketing version. - Validate the file. The CycloneDX CLI checks it against the schema:
cyclonedx validate --input-file sbom.json. - Review the gaps (see below) and add missing components by hand.
- Store it with the release and in your technical documentation, then feed it to your vulnerability monitoring so new advisories are matched against what you shipped.
Check the result before you keep it
- The number of components is in the same range as the packages in your lockfile.
- Every top-level dependency appears. That is the CRA’s minimum.
- Components have package URLs (
purl), so vulnerability databases such as OSV can match them. - Licences are filled in where the registry knows them.
- The product name and version are yours, not a placeholder.
What the lockfile can’t see
- Vendored or copied code: a library pasted into your source tree has no lockfile entry.
- Native and binary dependencies: SDKs shipped as frameworks,
.soor.dllfiles. - Engines and runtimes: Unity, Unreal, Godot, Electron or the JavaScript runtime you bundle.
- Platform services: system libraries on the user’s device are normally out of your SBOM, but anything you ship inside your package is in.
List these by hand in the SBOM, with a version and supplier, so the inventory matches the product. If your product runs in containers, an image scan adds the operating-system packages the lockfile never mentions.
Keep it alive
An SBOM is only useful while it matches what users run. Regenerate it in CI on every release, keep each version next to the build it describes, and match it daily against vulnerability data. When a component in a shipped version turns out to be actively exploited, the SBOM is how you know which versions and users are affected within the 24 hours Article 14 allows. For the basics of the format itself, see what an SBOM is.
Questions
Can I generate an SBOM without uploading my code anywhere?
Yes. Open-source generators run locally or in your CI, and shipcra parses the lockfile in your browser so the file never leaves your machine. Only the resulting SBOM is stored if you choose to save it.
How often should I regenerate the SBOM?
For every release that changes your dependencies. The SBOM in your technical documentation has to describe the version you actually shipped, so tie generation to your release process.
Does an SBOM generator make my product compliant with the CRA?
No. It produces one piece of evidence: the component inventory Annex I asks for. You still have to meet the other essential requirements, handle vulnerabilities and complete the conformity assessment.
Should I scan my container image or my lockfile?
They answer different questions. The lockfile describes your application’s dependencies. An image scan also finds operating-system packages in the container. A server-side product may need both; a mobile app or game usually starts from the lockfile and adds the engine by hand.
Sources
- Regulation (EU) 2024/2847, Annex I Part II, EUR-Lex
- CycloneDX tool center
- OSV: open source vulnerability database
- OCCTET toolkit: ORT Server, Curator and VulnerableCode for SBOM, VEX and audit reports
This guide explains the regulation in general terms. It isn’t legal advice for your product.