shipcra

How to generate an SBOM from a lockfile

Reviewed 3 min read

A lockfile already records every resolved dependency with its exact version, so it is the quickest input for an SBOM. Convert it to CycloneDX with a generator for your ecosystem, add your product’s name and version, check the output for components the lockfile can’t see, and regenerate it for every release.

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

  1. Check out the release commit and make sure the lockfile is current, for example with npm ci or a clean build.
  2. Pick a generator for your ecosystem. The CycloneDX project maintains official ones: @cyclonedx/cyclonedx-npm for npm, plugins for Gradle and Maven, CycloneDX for .NET, and cdxgen, which covers many ecosystems at once.
  3. Generate CycloneDX JSON. For an npm project: npx @cyclonedx/cyclonedx-npm --output-file sbom.json.
  4. Describe your product. Make sure metadata.component carries your product’s name and the exact version you are releasing. Generators often fill in the package name but not the marketing version.
  5. Validate the file. The CycloneDX CLI checks it against the schema: cyclonedx validate --input-file sbom.json.
  6. Review the gaps (see below) and add missing components by hand.
  7. 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, .so or .dll files.
  • 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

  1. Regulation (EU) 2024/2847, Annex I Part II, EUR-Lex
  2. CycloneDX tool center
  3. OSV: open source vulnerability database
  4. 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.

Turn your lockfile into an SBOM.

shipcra reads your lockfile in the browser and builds a CycloneDX SBOM for your technical documentation. The file never leaves your machine.

Join early access