A CycloneDX SBOM, the vulnerabilities that apply to it, and one HTML report you can send to an auditor — from a single command in any npm project.
cd your-project
npx cradle-cliThree files land in .cradle/:
| File | What it is |
|---|---|
report.html |
One self-contained page. No external requests, prints cleanly, sends by email |
sbom.cdx.json |
CycloneDX 1.6, with real dependency edges rather than a flat list |
findings.json |
Known vulnerabilities, each with the route from your product to it |
Three more appear when you ask for them: sbom.spdx.json, vex.csaf.json, and
vex.json once you suppress something.
No configuration, no account, no sign-up. The only network call is the
vulnerability lookup, and --offline removes that one too.
Works with npm, pnpm, Yarn Classic and Yarn Berry — all read from the lockfile, all producing the same graph for the same dependencies.
The EU Cyber Resilience Act, Regulation (EU) 2024/2847, arrives in stages:
| Date | What starts applying |
|---|---|
| 11 June 2026 | Chapter IV — notification of conformity assessment bodies |
| 11 September 2026 | Article 14 — reporting obligations |
| 11 December 2027 | Full application |
Two things are worth getting right about what that actually means.
The SBOM requirement is smaller than people say. Annex I, Part II(1) asks for a bill of materials "in a commonly used machine-readable format covering at the very least the top-level dependencies". Transitive dependencies are not legally required. It belongs to the technical documentation, is kept for ten years, and is shown to market surveillance authorities on request — there is no obligation to publish it. cradle records the whole tree anyway, because triage under a 24-hour clock does not work without it. That is our argument, not the legislator's.
The reporting duty is not one deadline, it is three. Article 14: an early warning within 24 hours of becoming aware, a vulnerability notification within 72 hours, and a final report within 14 days of a corrective or mitigating measure becoming available — note which clock that last one runs on. All of it to the ENISA single reporting platform and your national CSIRT, simultaneously.
Container images have had good tooling for years. npm projects have SBOM generators, and then you are on your own for the part that takes the time: keeping it current, deciding which findings apply to you, and writing that decision down somewhere an auditor can read it.
Not everyone reading this is in scope. The CRA covers products with digital elements placed on the EU market. Open-source development outside a commercial activity is largely out of scope, and "open-source software stewards" have lighter obligations under Article 24.
| 🌳 A real dependency graph | ms hangs off debug, not off your root. That is the difference between an SBOM and a text file. |
| 🧭 Findings with a route | acme-widget › express › body-parser tells you whether this is an upgrade you can make, or one you have to ask someone else for. |
| 🔢 CVSS computed, not copied | The v3 base score is calculated from the vector. Every finding records whether its severity came from that or from the advisory's own rating — and the report says which. |
| 🗂️ VEX that survives review | An OpenVEX statement with one of the five standard justifications, attributed and dated, in a file you commit. |
| 📉 A baseline, so the gate is adoptable | Every real project has a backlog. cradle check reports what is new. |
| ✅ A CRA readiness checklist | The documentation and process questions, not just the packages. Where cradle cannot tell, it says so rather than guessing. |
| 🎯 Triage by exploitation, not only severity | EPSS and the CISA KEV catalogue. A medium somebody is actually exploiting outranks a critical nobody has touched — check --sort exploit says so. |
| 🇩🇪 Built for the German and EU case | A BSI TR-03183-2 profile, CSAF, Article 14 drafts and a German report. See below. |
| 🪶 Four runtime dependencies | Six including transitives. For a tool about the size of dependency trees, that felt like the minimum standard of care. |
Deliberately, so you know it is a decision and not a gap:
- Any ecosystem other than npm — no Python, no Go, no container images
- Signed attestations, Sigstore, SLSA. The npm publish carries a provenance attestation; cradle signs nothing of yours
- A web interface or a hosted service
- Automatic update pull requests — Dependabot and Renovate do that better
- Licence policy enforcement. Licences are shown, never blocked on
- Deciding whether a vulnerability is being actively exploited, or whether you owe anyone a report. cradle shows the signals and drafts the paperwork; the determination is yours
- Telemetry. Not now, not later
SPDX used to be on this list and no longer is: --sbom-format spdx writes
SPDX 2.3 JSON from the same graph. It is a second rendering, not a second
opinion — a test counts the dependency edges in both documents and requires them
to match.
name: cradle
on: [pull_request]
permissions:
contents: read
pull-requests: write # only needed for comment-on-pr
jobs:
sbom:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: '22'
- run: npm ci
- uses: P-hinn/cradle-cli@v0.3.0
with:
fail-on: high
upload-artifact: true
comment-on-pr: trueThe action scans, checks against the baseline, uploads the report as a build artifact, and edits one pull-request comment in place rather than adding a new one on every push.
For GitLab, examples/gitlab-ci.yml does the same
three things — evidence, gate, merge-request comment — and feeds the Security
dashboard through check --format sarif.
Pin the exact tag while the project is pre-1.0. The action's default
cradle-cli version is the release it was cut from, so a pinned tag means a
pinned tool. A moving v1 will exist once there is a 1.0 worth moving.
Exit codes are part of the contract:
| Code | Meaning |
|---|---|
0 |
Nothing new above the threshold |
1 |
New findings above the threshold |
2 |
cradle could not run |
The difference between 1 and 2 is the point. A broken tool must never read
as a security result.
A gate that is red on day one gets switched off. So accept what is there today:
npx cradle-cli check --baselineCommit .cradle/baseline.json. From then on cradle check reports only what is
new.
A finding is identified by advisory and package name, without the version — bumping a still-vulnerable dependency is not news, and a gate that reddens on unrelated churn is a gate nobody trusts. The severity you accepted is recorded too: if an advisory is later re-rated worse, it counts as new again.
The daily pain is not "I cannot find vulnerabilities". It is drowning in findings that do not apply to you.
npx cradle-cli suppress CVE-2021-44906 \
--justification vulnerable_code_not_in_execute_path \
--note "Only our own CI wrapper parses argv here; no untrusted input reaches minimist." \
--expires 2027-03-31That writes an OpenVEX statement into .cradle/vex.json:
{
"@context": "https://openvex.dev/ns/v0.2.0",
"author": "you@example.com",
"statements": [
{
"vulnerability": { "name": "GHSA-xvch-5gv4-984h", "aliases": ["CVE-2021-44906"] },
"products": [{ "@id": "pkg:npm/minimist@1.2.0" }],
"status": "not_affected",
"justification": "vulnerable_code_not_in_execute_path",
"status_notes": "Only our own CI wrapper parses argv here; …",
"cradle:expires": "2027-03-31"
}
]
}The category is mandatory, and only the five OpenVEX defines are accepted:
| Justification | Means |
|---|---|
component_not_present |
The vulnerable component is not in the delivered product |
vulnerable_code_not_present |
The component is there, the vulnerable code is not |
vulnerable_code_not_in_execute_path |
The vulnerable code is there but never runs |
vulnerable_code_cannot_be_controlled_by_adversary |
It runs, but an attacker cannot reach or influence it |
inline_mitigations_already_exist |
Existing mitigations already prevent exploitation |
That is deliberately a little inconvenient. The category is what makes a suppression something a reviewer can disagree with, rather than a silent dismissal. Your free text goes alongside it, not instead of it.
Suppressed findings stay in the report, in their own section, with the reason. Hiding them would defeat the point.
--expires is a cradle extension — OpenVEX has no notion of expiry, so it is
written as cradle:expires. When it lapses the finding comes back, carrying the
note that its ruling expired. A decision about a dependency should have to be
renewed, not quietly outlive its reasoning.
Know what that costs. OpenVEX has no extension point: its JSON Schema sets
additionalProperties: falseon a statement. So a strict validator does not ignorecradle:expires— it rejects the whole document. Remove that one key and the file validates exactly, and a test pins both halves of that. If you need a file that passes validation as-is, leave--expiresoff; the trade is an expiry date against strict conformance, and it is yours to make, not ours.
**/.cradle/*
!**/.cradle/config.json
!**/.cradle/vex.json
!**/.cradle/baseline.jsonThe three exceptions record decisions. The rest is output, regenerated on every run.
Two details that cost us an afternoon, so they need not cost you anything: the
negations need .cradle/* rather than .cradle/, because git cannot re-include
a file whose parent directory is excluded — and the **/ matters in a monorepo,
because a pattern containing a slash is anchored to the directory its
.gitignore sits in. A blanket .cradle/ silently drops the files holding your
own rulings.
Entirely optional. .cradle/config.json answers the questions cradle cannot work
out from your code:
{
"productName": "Acme Widget",
"contactEmail": "security@acme.example",
"placedOnMarket": "2026-01-15",
"supportPeriodEnd": "2031-01-15"
}placedOnMarket is what lets the readiness check actually test the five-year
support floor, instead of only noting that a date exists.
An unknown key is an error rather than a no-op: a misspelt supportPeriodEnd
would otherwise leave the check reporting "not documented" while you are certain
you documented it.
Not a scoring table. They solve different problems, and for several of these the honest answer is "use that one instead".
| Scope | Where cradle differs | |
|---|---|---|
| Syft / Grype | Many ecosystems, container-first | The right answer for images and polyglot repositories, and far wider than cradle will ever be. cradle only knows npm, and spends that narrowness on the report and the checklist. |
| Trivy | Images, filesystems, IaC, secrets | A broad security scanner with an SBOM mode. cradle is an SBOM and documentation tool with a vulnerability lookup. Different centre of gravity. |
| cdxgen | CycloneDX for many languages | Richer, more configurable SBOMs across far more ecosystems. cradle produces a narrower one and then does something with it. |
| @cyclonedx/cyclonedx-npm | CycloneDX for npm | The closest comparison, actively maintained, and good at its job. If an SBOM file is all you need, use it. cradle exists for what comes after: findings with a route, VEX, a baseline, a readiness checklist, and a report you can hand to someone. |
npm audit |
Built in, nothing to install | Fast and free, but no SBOM, no VEX, no baseline, and nothing to send to an auditor. |
SBOM generation is table stakes. The difference is everything after it.
The rest of this README applies everywhere. This part is for the case cradle was built around: a manufacturer placing a product on the EU market, being asked for evidence in a particular shape.
npx cradle-cli check --profile bsi-tr-03183Eighteen data fields from BSI TR-03183-2 version 2.1.0 (20 August
2025), each citing the section it comes from and the place the guideline's own
mapping table puts it in CycloneDX 1.6. It appears as its own report section, and
in --format github and --format markdown.
It never changes the exit code. Several fields the guideline requires are
statements about your delivery — whether the artefact you ship is executable, an
archive, a structured file — and an npm package is fetched as a .tgz and
installed as a directory, so which of those you ship is not in your lockfile.
Those come back not assessable with the reason. A build that is permanently red
gets switched off, and a checklist nobody can satisfy is worth nothing.
The only verdict it will give is "no required field is open". Not "compliant" — that word appears nowhere in the profile, and a test keeps it that way.
npx cradle-cli scan --vex-format both --sbom-format both --lang de| Flag | What you get |
|---|---|
--vex-format csaf |
vex.csaf.json — CSAF 2.0 in the VEX profile, from the same suppressions as vex.json. CSAF's flags[].label enumerates exactly the five OpenVEX justifications, so nothing is lost in translation |
--sbom-format spdx |
sbom.spdx.json — SPDX 2.3, same graph, same timestamp, the CycloneDX serial number in its namespace |
--lang de |
The report and the pull-request comment in German, with lang="de" set. The terminology follows the German text of the regulation: Schwachstelle, Komponente, Begründung, Unterstützungszeitraum |
Both exports validate against their official schemas. A file that claims a format and does not meet it is worse than no file.
From 11 September 2026, Article 14 is three obligations with three clocks.
npx cradle-cli notify GHSA-xvch-5gv4-984h --stage early-warning| Stage | Deadline | From |
|---|---|---|
early-warning |
24 hours | becoming aware |
notification |
72 hours | becoming aware |
final |
14 days | a corrective or mitigating measure becoming available — not from becoming aware |
Each draft carries the content its paragraph asks for, filled in from the scan:
the component, its version, the route through your tree, the advisory and its
aliases, the fix where there is one. Everything a lockfile cannot answer — the
Member States the product is placed on, any malicious actors, the version of
your product that carries the fix — is a visible [TO BE COMPLETED]
placeholder, and the console counts them.
cradle does not decide that you owe a report, and it never submits one. Article 14 is about actively exploited vulnerabilities. cradle knows an advisory exists and that your lockfile resolves the affected version. Whether anyone is exploiting it is not something a dependency scanner can know. The determination is yours; this writes a file.
npx cradle-cli check --sort exploitEPSS estimates the probability of exploitation in the next 30 days. The
CISA KEV catalogue is evidence that it is already happening. Both appear
as a column in the report and a line in check, and this ordering puts
known-exploited first — a medium CISA has evidence about ahead of a critical
nobody has touched, which is the opposite of what sorting by severity says.
--fail-on stays CVSS-based, and is still the default on its own. A gate
whose threshold moves daily with somebody else's model goes red overnight for
reasons nobody on your team changed. --no-priority turns the signals off
without going fully offline, and only CVE identifiers are ever sent — no package
name, no version, nothing about your project.
Two opt-in flags add the other dimensions, because severity alone asks the wrong question for Article 14 — its 24-hour clock starts on actively exploited, not on a score:
npx cradle-cli check --fail-on never --fail-on-kev # only active exploitation
npx cradle-cli check --fail-on high --fail-on-epss 0.5A finding fails on any threshold it crosses, and the output names which one, because a KEV hit is an upgrade today while a severity hit may be a decision to record.
The two are not equally well behaved, and the paragraph above is the reason.
--fail-on-kev is the safe one: the catalogue only grows, and an entry means
CISA has evidence someone is exploiting it — going red on that is the point.
--fail-on-epss is the one that bites: the model re-scores daily, so a build
that passed yesterday can fail today with nothing on your side changed. Use it
knowing that.
Gating on either while --offline or --no-priority switches the lookup off is
refused rather than silently passing. A gate that cannot see is worse than no
gate.
npx cradle-cli check --from-sbom shipped.cdx.jsonA lockfile describes what your repository resolves today. Two things it cannot describe:
- A product that has shipped. Its tree is frozen, the lockfile has moved on, and the SBOM in your technical documentation is what was placed on the market. That is the one the support period obliges you to keep watching.
- A supplier's component. Their SBOM is often the only description of it you will ever have, and you have no lockfile for it at all.
Both read as CycloneDX JSON and produce the same graph a lockfile does, so
findings, VEX, the baseline and the report work on them unchanged. scan takes
the flag too, which doubles as a converter: read CycloneDX, write SPDX.
What the document cannot support is said rather than guessed. A component from
another ecosystem, or one without a package URL, is counted and then reported as
a resolution note — cradle only knows npm, and a component count that silently
shrank would still look complete. Output says from <file> where it would
otherwise name a package manager, because a supplied document claims nothing
about the tool that installed anything. For the same reason the Article 14 draft
says read from the supplied software bill of materials instead of resolved
from the npm lockfile.
SPDX is write-only for now: cradle emits it, and cannot read it back.
cradle scan [path] [--from-sbom <file>] [--include-dev] [--offline] [--no-cache]
[--no-priority]
[--spec-version 1.6|1.7] [--sbom-format cyclonedx|spdx|both]
[--vex-format openvex|csaf|both] [--lang en|de]
[--workspace <name|all>] [--profile bsi-tr-03183]
[--timestamp <iso>] [--serial-number <urn>]
[--output-dir <dir>]
cradle check [path] [--from-sbom <file>]
[--fail-on <severity>] [--fail-on-kev] [--fail-on-epss <0-1>]
[--baseline] [--no-baseline]
[--format text|github|markdown|sarif] [--sort severity|exploit]
[--workspace <name>] [--profile bsi-tr-03183] [--lang en|de]
[--artifact-name <name>] [--no-priority] [--output-dir <dir>]
cradle suppress <advisory-id> [path] --justification <category>
[--component <purl>] [--note "…"] [--expires <date>]
cradle notify <advisory-id> [path] --stage early-warning|notification|final
[--output <file>]
cradle <command> --help prints the rest.
npx cradle-cli scan --workspace allOne report per package, written into that package's own directory, with the
package as the product and only its own dependencies in it. The route starts
where a team can act on it: @acme/api › fastify › find-my-way rather than
acme-monorepo › @acme/api › fastify › find-my-way.
The per-package graph is sliced out of the repository-wide one, never resolved separately — a monorepo has one lockfile and therefore one resolution, and two reports about the same code that disagree are worse than one.
cradle check --workspace <name> gates a single package, with its baseline in
that package's directory, so a sibling's backlog no longer reddens your gate.
check --workspace all is deliberately refused: a gate has one exit code and one
pull-request comment, and neither can honestly speak for several packages.
npx cradle-cli scan --timestamp 2026-09-26T12:00:00Z --serial-number urn:uuid:…Two runs over the same lockfile with the same values produce byte-identical
sbom.cdx.json, findings.json and report.html. The defaults stay as they
are — a report should say when it was made, and a fresh serial number is what
lets a reader tell two BOMs apart.
import { resolveNpm, buildBom } from 'cradle-cli'
const graph = await resolveNpm({ projectDir: process.cwd(), includeDev: false })
const bom = buildBom(graph, {
specVersion: '1.6',
timestamp: new Date().toISOString(),
serialNumber: `urn:uuid:${crypto.randomUUID()}`,
})Everything under core/ takes its input as arguments and returns values. It
reads a lockfile where it must, but never writes files and never prints. File
access and output live in the CLI layer.
Node.js 22.9 or newer. Node 20 reached end of life in April 2026, and a security tool has no business running on an unsupported runtime.
Four runtime dependencies — packageurl-js, semver,
spdx-expression-parse and yaml — six including transitives.
They are deliberately not bundled, so a security fix in any of them reaches
you without waiting for a cradle release.
examples/express-service is a project pinned to
deliberately dated dependencies, with a lockfile, a SECURITY.md, a config and a
workflow — and no node_modules, because cradle reads the lockfile.
git clone https://github.com/P-hinn/cradle-cli
cd cradle-cli/examples/express-service
npx cradle-cli scan && open .cradle/report.htmlReads your lockfile and node_modules manifests, writes to .cradle/, and talks
to api.osv.dev, registry.npmjs.org, api.first.org (EPSS) and www.cisa.gov
(the Known Exploited Vulnerabilities catalogue) — all skipped by --offline, and
the last two by --no-priority. The two exploitation sources receive only CVE
identifiers: no package name, no version, nothing about your project. It runs
git config --get user.email once, in cradle suppress, to know who is
recording a decision; --author avoids even that. No telemetry.
SECURITY.md has the full table.
Tagging is the whole process:
npm version patch # or minor - writes package.json and creates the tag
git push --follow-tags.github/workflows/release.yml takes it from there: it refuses a tag that
disagrees with package.json, runs the full gate, publishes to npm with a
provenance attestation, scans cradle with cradle, and opens a GitHub release
carrying the changelog section for that version and cradle's own SBOM as an
asset. A tool that asks people to keep an SBOM should ship one.
The attestation is why publishing happens in CI rather than from a laptop: it is cryptographic proof that a given tarball was built from a given commit by a given workflow. Publishing by hand produces a package that is fine and proves nothing.
A published version is final; tags do not move. A re-run skips the publish
when the version is already on the registry, and compares npm's recorded
gitHead against the commit being built — if they differ it stops rather than
attaching an SBOM and a report describing one commit to a tarball built from
another. For a tool whose subject is supply-chain evidence, that is the worst
available outcome, because it looks green.
One-time setup on npmjs.com, under the package's Settings → Trusted
Publisher: GitHub Actions, repository P-hinn/cradle-cli, workflow
release.yml. That removes the need for a token entirely — worth doing before
January 2027, when npm restricts tokens that bypass 2FA. Without it, set an
NPM_TOKEN secret instead; the workflow accepts either.
Issues and pull requests welcome. CONTRIBUTING.md has the
setup, the four commands that make up the gate, and how to add a lockfile
fixture — which is the most useful contribution there is, because a lockfile
shape cradle gets wrong is a bug report with a fix attached.
SPEC.md is the working specification — what was decided, and why —
and is worth reading before changing behaviour. It is in German; this README is
authoritative for users.
Security reports go through SECURITY.md, not the issue tracker.
Everyone taking part is covered by the
Code of Conduct.
Every push and pull request runs the full gate on Node 22 and 24 across Linux, macOS and Windows, then scans the example project with the freshly built CLI. CodeQL and OpenSSF Scorecard run alongside it — for a tool whose subject is supply-chain evidence, publishing its own score is the least it can do.
cradle is a technical aid for documentation and process. It is not legal advice, not a conformity assessment, and not a declaration of conformity. Whether a product meets Regulation (EU) 2024/2847 is not something this or any tool decides. The harmonised standards for the CRA are not final at the time of writing.
Nothing cradle produces makes anyone compliant. It makes it easier to show what you shipped and what you decided about it — which is the tedious part, not the hard part.