Introduction
nanobom is a self-hosted tracker of the vulnerabilities in the software you ship. Your CI uploads a CycloneDX or SPDX SBOM (software bill of materials) of each project; nanobom checks every component against OSV right after the upload and again every night, keeps the history of what it found, and tells you when something new appears.
It is one binary and one SQLite file (or a PostgreSQL database): no queue, no cache server, no scanner to keep up to date. The container image is about 20 MB.
What it does
- Keeps an inventory. Each upload replaces the project’s list of components, so nanobom always knows what each project ships today, and can tell you which projects use a given package.
- Matches it against OSV, every day. New advisories appear for old versions all the time; the nightly run catches them without a new build.
- Tracks findings over time. A vulnerability affecting a component is a finding. It is fixed when the component goes away, reopened if it comes back, and can be ignored with a reason and an expiry date. Identifiers of the same vulnerability in different databases (a GHSA and its CVE, for instance) are merged into one finding.
- Helps you prioritize. Findings carry a severity from their CVSS scores, and two exploitation signals: whether CISA lists the vulnerability as exploited in the wild (KEV), and the EPSS probability of exploitation. Known exploited findings come first.
- Gates CI. An upload can wait for its evaluation and fail the pipeline when open findings reach a severity, or are known exploited.
- Notifies you. Each organization can send new findings and projects whose SBOM stopped coming to a webhook (JSON, Slack or Microsoft Teams); the instance can report failed runs to another.
- Separates teams. Organizations are isolated from each other; members have one of four roles. Sign-in uses local accounts, OpenID Connect, or both, with roles mapped from your identity provider’s groups.
What it does not do
- It does not generate SBOMs. Your build does, with the generator of your ecosystem (see Generate an SBOM). nanobom only reads JSON: CycloneDX 1.3 to 1.7 and SPDX 2.2 and 2.3.
- It does not scan images or file systems. It trusts the SBOM. A component missing from the SBOM is invisible to nanobom.
- It only knows what OSV knows. Components are matched by their
package URL (
pkg:npm/lodash@4.17.20); a component without one, or from an ecosystem OSV does not cover, cannot be checked. Vulnerabilities of your own code are out of scope. - It does not judge reachability. A finding means a vulnerable version is present, not that the vulnerable code is called. Triage, with a reason kept in the history, is how you record that a finding does not apply.
- It has no API besides uploads. The web interface is the way to read findings and manage organizations; the HTTP API accepts SBOMs (and returns an evaluation for CI). Webhooks and Prometheus metrics are the machine-readable outputs.
How this documentation is organized
It has four parts, one per need:
- Tutorials are lessons. Follow them in order, step by step, when you are new to nanobom: Your first scan runs it on your machine, Gate a repository’s CI wires a GitHub repository to it.
- How-to guides are recipes for a goal you already have: install an
instance, upload from GitLab CI, set up single sign-on, back up the database, fix an upload
that answers
503. - Reference describes the machinery, completely and without commentary: every option, command, API field, webhook field, permission and metric. Look things up there.
- Explanation is background to read away from the keyboard: what organizations, runs and findings are, how findings are kept up to date, why exploitation signals come first, what protects what, how the code is laid out.
nanobom is free software under the Apache-2.0 license; the source, issues and releases are on GitHub.
Your first scan
In this tutorial you run nanobom on your own machine, send it the SBOM of a small project, read the vulnerabilities it finds, and set one of them aside with a reason. It takes about fifteen minutes.
You need Docker with Compose, git, and curl. Port 8080 must be free.
1. Start nanobom
Clone the repository, which contains a ready compose.yaml, and start it:
git clone https://github.com/AlixANNERAUD/nanobom.git
cd nanobom
docker compose up -d --wait
The command returns once the container reports itself healthy. Check that nanobom answers:
curl http://localhost:8080/healthz
{"status":"ok"}
2. Create the administrator
Nobody can sign in yet. Create an instance administrator named admin:
docker compose exec nanobom /app/nanobom create-administrator --username admin
Type a password of at least 12 characters and press Enter. It is shown as you type it.
Open http://localhost:8080 and sign in as admin with that password. You land on
Organizations, which already lists one organization, admin: every new user gets a personal
one.
3. Create an organization and a project
Your CI will send the SBOMs of a project, in an organization, with the project’s upload token.
- Under New organization, enter
Acmeas the name andacmeas the slug, then Create. - On the page of Acme, under New project, enter
demoas the slug, leave the name empty, and Create project. - You land on the project
demo, which says No SBOM yet. Under Upload token, copy the token: it starts withnanobom_. It stays on this page, for admins and owners, and so do a GitHub Actions step and acurlcommand that use it.
In the terminal, keep it in a variable for the next steps:
export NANOBOM_TOKEN=nanobom_…
4. Upload an SBOM
Real SBOMs come from your build. For this tutorial, write a small one by hand: a project that
depends on two old npm packages, lodash 4.17.20 and minimist 1.2.5.
cat > sbom.json <<'EOF'
{
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"version": 1,
"components": [
{
"type": "library",
"name": "lodash",
"version": "4.17.20",
"purl": "pkg:npm/lodash@4.17.20"
},
{
"type": "library",
"name": "minimist",
"version": "1.2.5",
"purl": "pkg:npm/minimist@1.2.5"
}
]
}
EOF
The purl of each component, its package URL, is what nanobom looks up in OSV.
Send the file to the project demo:
curl --fail-with-body -X PUT \
-H "Authorization: Bearer $NANOBOM_TOKEN" \
--data-binary @sbom.json \
"http://localhost:8080/api/organizations/acme/projects/demo/sbom?wait=true"
wait=true holds the request until nanobom has checked the project against OSV, which takes a
few seconds. The answer looks like this, shortened:
{
"organization": "acme",
"project": "demo",
"project_created": false,
"component_count": 2,
"components_without_purl": 0,
"evaluation": {
"status": "succeeded",
"open": { "critical": 1, "high": 2, "medium": 2, "low": 0, "unknown": 0 },
"known_exploited": 0,
"findings": [ … ]
}
}
Check two things: component_count is 2, and evaluation.status is succeeded.
(project_created is false: the project existed already. An upload with an organization
token to a new slug would have created it.) The counts in open depend on what OSV knows today; expect
at least a critical finding (minimist) and a high one (lodash). Each entry of findings names a
vulnerability, the component it affects, and the address of its page.
5. Read the findings
Open http://localhost:8080/organizations/acme. The project demo is listed with a bar of
its open findings by severity next to their counts, how many are known exploited (KEV) or
ignored, and the day of its last SBOM. Under Recent runs, the run your upload started is
listed as succeeded, with its counts of new and fixed findings.
Open demo. Under its name, a bar and its legend count the open findings by severity. Below,
the findings are listed most urgent first: known exploited ones, then by severity.
Open the high finding of lodash. Its page shows:
- the vulnerability’s description, and the version that fixes it under Fixed in;
- its Aliases: the same vulnerability under other identifiers, such as a CVE;
- its References: the advisories and fixes OSV links to;
- Exploitation: whether it is known to be exploited, and its EPSS score;
- Also affected: other components with the same vulnerability, here none;
- History: an Opened entry, from the run of your upload.
6. Ignore a finding
Suppose your team checked that the vulnerable lodash function is never called. Record that
decision on the finding’s page, under Triage:
- In Reason, write
Tutorial: the vulnerable function is not used. - In Ignore until, pick a date a month from now.
- Select Ignore finding.
The page says Finding ignored., and History gains an Ignored entry with your name and the reason. Back on the project page, the summary counts one open finding less, and the finding is marked Ignored next to its name. The default filter, Open and ignored, still lists it; set Status to Open and select Filter to hide it.
Upload the same SBOM again:
curl --fail-with-body -X PUT \
-H "Authorization: Bearer $NANOBOM_TOKEN" \
--data-binary @sbom.json \
"http://localhost:8080/api/organizations/acme/projects/demo/sbom?wait=true"
This time evaluation.open.high is one lower than before: ignored findings do not count. On the date you picked, the finding opens again by itself.
7. Clean up
To delete the instance and its data:
docker compose down --volumes
What you learned
You started nanobom, created an organization and a project, uploaded an SBOM with the project’s upload token, read its findings, and ignored one with a reason and an expiry date.
Next:
- Gate a repository’s CI: the same loop, driven by a GitHub repository.
- Concepts: what organizations, projects, runs and findings are.
- Install nanobom: a real deployment.
Gate a repository’s CI
In this tutorial you connect a GitHub repository to nanobom: every push uploads its SBOM, the job shows the project’s vulnerabilities, and the job fails when one of them is high or critical. You then make it pass again, once by upgrading the dependency and once by triaging the finding.
You need:
- a nanobom instance that GitHub’s runners can reach over the internet (an instance on
localhost, as in Your first scan, is not reachable from them); - an organization on it, here
acme, where you are an admin or an owner (see step 3 of Your first scan); - a GitHub account, git, and npm.
1. Create a small project
The project depends on an old version of lodash with a known high-severity vulnerability:
mkdir nanobom-gate && cd nanobom-gate
git init -b main
npm init -y
npm install --save-exact lodash@4.17.20
echo node_modules > .gitignore
git add . && git commit -m "Depend on lodash"
Create an empty repository named nanobom-gate on GitHub, then push to it:
git remote add origin https://github.com/<you>/nanobom-gate.git
git push -u origin main
2. Give the repository the token and the address
In nanobom, open acme, and under New project enter nanobom-gate, the repository’s name,
as the slug, then Create project. The project page that opens shows its Upload token.
In the repository on GitHub, open Settings → Secrets and variables → Actions:
- On the Secrets tab, add a repository secret
NANOBOM_TOKENwith the project’s upload token. - On the Variables tab, add a repository variable
NANOBOM_URLwith the instance’s address, such ashttps://nanobom.example.org.
3. Upload on every push
Add .github/workflows/sbom.yml:
name: SBOM
on:
push:
branches: [main]
permissions:
contents: read
jobs:
sbom:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7.0.1
- uses: AlixANNERAUD/nanobom-action@v1
with:
url: ${{ vars.NANOBOM_URL }}
token: ${{ secrets.NANOBOM_TOKEN }}
organization: acme
Commit and push it:
git add .github && git commit -m "Upload the SBOM to nanobom" && git push
Open the repository’s Actions tab and the run of this commit. The job succeeds. The action
generated an SBOM of the checkout with Syft (it reads package-lock.json), uploaded it, and
waited for nanobom to check it. The run’s summary page shows the result: a link to the project,
the number of components uploaded, the evaluation’s status, the open findings by severity, and a
table of those findings, each linked to its page.
In nanobom, the project nanobom-gate, which the action names after the repository, now has the
findings of lodash 4.17.20.
4. Make the job fail
Ask the action to fail when an open finding is high or critical, with fail-on:
- uses: AlixANNERAUD/nanobom-action@v1
with:
url: ${{ vars.NANOBOM_URL }}
token: ${{ secrets.NANOBOM_TOKEN }}
organization: acme
fail-on: high
git commit -am "Fail on high vulnerabilities" && git push
This run fails. The job is annotated with each finding that crosses the threshold, among them
the high finding of pkg:npm/lodash@4.17.20, with a link to its page in nanobom. The upload
itself was recorded: nanobom answered 409, the status of a gate that failed, after storing
the SBOM.
5. Fix it by upgrading
Upgrade lodash to its latest version, which fixes the vulnerability:
npm install --save-exact lodash@latest
git commit -am "Upgrade lodash" && git push
The run passes. In nanobom, the findings of lodash 4.17.20 are now Fixed, since that
component left the SBOM.
6. Or triage it
Upgrading is not always possible right away. Go back to the vulnerable version to see the other way out:
npm install --save-exact lodash@4.17.20
git commit -am "Back to lodash 4.17.20" && git push
The run fails again, and the finding is reopened. Open it in nanobom from the job’s annotation,
and under Triage, ignore it with a reason (Tutorial: the template function is not used.)
and an Ignore until date a month from now.
On GitHub, open the failed run and select Re-run jobs. The run passes: ignored findings do not count. When the date passes, the finding opens again and the next push fails, unless the dependency was upgraded by then.
What you learned
You added the nanobom action to a repository, read its result in the job summary, turned it into
a gate with fail-on, and made the gate pass both by fixing the dependency and by triaging the
finding.
Next:
- Upload from CI: the action’s options, GitLab CI, and any other CI with curl.
- Fail CI on vulnerabilities: what to know before gating real pipelines.
- How findings are kept up to date: why a gate can fail without a code change.
Install nanobom
nanobom listens on port 8080 and keeps everything in one SQLite file. Install it with Docker
Compose, docker run, or from a release archive, then create the first administrator. Every
setting is listed in the configuration reference. To keep the
data in PostgreSQL instead, see Run on PostgreSQL.
With Docker Compose
The repository contains a ready
compose.yaml:
git clone https://github.com/AlixANNERAUD/nanobom.git
cd nanobom
docker compose up -d --wait
--wait returns once the container reports itself healthy. The file uses the published image
(ghcr.io/alixanneraud/nanobom:latest, for amd64 and arm64; the same image is on Docker Hub
as alixanneraud/nanobom) and builds it from the checkout
when it is not available. Settings come from the environment or a .env file next to
compose.yaml, for example:
# .env
NANOBOM_PUBLIC_URL=http://localhost:8080
NANOBOM_PORT=8080
compose.yaml only passes a few variables to the container. To set others, add them under
environment: in the file. Leave optional settings out rather than empty: an empty
NANOBOM_FAILURE_WEBHOOK_URL is an invalid URL, not “no webhook”.
With docker run
docker run -d --name nanobom -p 8080:8080 -v nanobom-data:/data \
-e NANOBOM_PUBLIC_URL=http://localhost:8080 \
ghcr.io/alixanneraud/nanobom:latest
The database lives in the /data volume. The image is distroless: it has no shell, so run
nanobom’s own commands with docker exec nanobom /app/nanobom …. It runs as the unprivileged
user 65532; a bind mount instead of a volume must be writable by that user.
Without containers
Each release has an archive per
architecture, nanobom-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz and
nanobom-vX.Y.Z-aarch64-unknown-linux-gnu.tar.gz, with a .sha256 checksum and build
provenance. It holds the nanobom binary and the site directory of the web interface. The
binary is built on Debian 12 and needs its glibc or a newer one.
tar -xzf nanobom-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz
cd nanobom-vX.Y.Z-x86_64-unknown-linux-gnu
export NANOBOM_SITE_ROOT="$PWD/site"
export NANOBOM_DATABASE_URL="sqlite://$HOME/nanobom/nanobom.db"
mkdir -p "$HOME/nanobom"
./nanobom serve
NANOBOM_SITE_ROOT defaults to site, relative to the working directory, which only works when
nanobom starts from the extracted directory; otherwise pages load without their styles and
scripts. The default database path, /data/nanobom.db, suits the image; elsewhere, set
NANOBOM_DATABASE_URL to a file in a directory the service can write to.
As a systemd service:
# /etc/systemd/system/nanobom.service
[Unit]
Description=nanobom
After=network-online.target
Wants=network-online.target
[Service]
User=nanobom
ExecStart=/opt/nanobom/nanobom serve
Environment=NANOBOM_SITE_ROOT=/opt/nanobom/site
Environment=NANOBOM_DATABASE_URL=sqlite:///var/lib/nanobom/nanobom.db
Environment=NANOBOM_PUBLIC_URL=https://nanobom.example.org
Environment=NANOBOM_LOG_FORMAT=text
StateDirectory=nanobom
Restart=on-failure
[Install]
WantedBy=multi-user.target
Create the first administrator
Nobody can sign in to a new instance. Create an instance administrator from the command line; the password is read from standard input:
# Docker Compose
docker compose exec nanobom /app/nanobom create-administrator --username admin
# docker run
docker exec -it nanobom /app/nanobom create-administrator --username admin
# Without containers (same environment as the server, for NANOBOM_DATABASE_URL)
./nanobom create-administrator --username admin
The password is read as a plain line and shown as you type it; it must have at least
NANOBOM_PASSWORD_MINIMUM_LENGTH characters (12 by default). In scripts, pass it in
NANOBOM_ADMINISTRATOR_PASSWORD instead. --email sets an email address, which can then be used
to sign in instead of the username. All options are in the
command-line reference.
If you only use single sign-on, you can skip this step and grant administration through a claim of your identity provider instead: see Set up single sign-on.
Before opening the instance to your users
- TLS is terminated by a reverse proxy, and
NANOBOM_PUBLIC_URLis itshttpsaddress: Run behind a reverse proxy. - The proxy accepts bodies of one and a half times
NANOBOM_MAXIMUM_SBOM_SIZE(24 MiB by default, for Dependency-Track clients) and lets uploads waitNANOBOM_UPLOAD_WAIT_SECONDS. - The commands of Check the setup print what they should.
-
NANOBOM_TRUST_FORWARDED_HEADERS=true, so sign-in rate limiting sees client addresses. -
/metricsis scraped, and reachable only by your monitoring: Monitor with Prometheus. - An alert fires when the last successful run is too old, and
NANOBOM_FAILURE_WEBHOOK_URLreaches the operators: Get notified. - The database is backed up daily, and a restore was tried once: Back up, restore and upgrade.
- The instance can reach
api.osv.dev,www.cisa.govandapi.first.org, or uses mirrors, or has exploitation data turned off: Run without internet access. - Only one nanobom process uses the database (why).
A production configuration, behind a reverse proxy, with single sign-on and an alarm for failed runs:
NANOBOM_PUBLIC_URL=https://nanobom.example.org
NANOBOM_LISTEN_ADDRESS=127.0.0.1:8080
NANOBOM_TRUST_FORWARDED_HEADERS=true
NANOBOM_FAILURE_WEBHOOK_URL=https://hooks.example.org/nanobom-ops/7f3c9a
NANOBOM_OIDC_ISSUER=https://keycloak.example.org/realms/acme
NANOBOM_OIDC_CLIENT_ID=nanobom
NANOBOM_OIDC_CLIENT_SECRET=…
NANOBOM_OIDC_GROUPS_CLAIM=groups
NANOBOM_OIDC_GROUP_MAPPING="security=acme:admin;developers=acme:member"
NANOBOM_OIDC_ADMINISTRATOR_CLAIM=groups
NANOBOM_OIDC_ADMINISTRATOR_VALUE=nanobom-admins
Run on PostgreSQL
nanobom keeps its data in SQLite by default. It can use a PostgreSQL database instead, for example a managed one or a server you already back up: see SQLite or PostgreSQL to decide. Decide before the first start: nanobom has no tool to move its data from one database to the other.
nanobom is tested on PostgreSQL 17 and needs nothing beyond a database and a role that owns it.
With Docker Compose
examples/compose-postgres.yaml
runs nanobom next to a postgres:17-alpine container. Set the database password first, in the
environment or a .env file next to the Compose file:
# examples/.env
NANOBOM_POSTGRES_PASSWORD=a-long-random-password
NANOBOM_PUBLIC_URL=http://localhost:8080
docker compose -f examples/compose-postgres.yaml up -d --wait
docker compose -f examples/compose-postgres.yaml exec nanobom /app/nanobom create-administrator --username admin
The PostgreSQL container has a health check (pg_isready), and nanobom starts once it passes
(depends_on with condition: service_healthy), since it applies its migrations at startup.
The data lives in the postgres-data volume; nanobom itself needs no volume.
The password is part of a URL in NANOBOM_DATABASE_URL: keep it to letters, digits and -._~,
or percent-encode the other characters.
With an existing PostgreSQL server
-
Create a role and a database it owns, so that nanobom can create its tables:
CREATE ROLE nanobom LOGIN PASSWORD 'a-long-random-password'; CREATE DATABASE nanobom OWNER nanobom; -
Point nanobom at it, with the URL form:
NANOBOM_DATABASE_URL=postgres://nanobom:a-long-random-password@db.example.org:5432/nanobom?sslmode=verify-fullsslmode=verify-fullencrypts the connection and checks the server’s certificate and name against the public certificate authorities; addsslrootcert=/path/to/ca.pemwhen the server’s certificate comes from a private one, as with most managed databases. Avoidverify-ca, which accepts any publicly trusted certificate whatever the host. -
Start nanobom (
nanobom serve): it creates the schema on the first start, and applies new migrations on later ones. Then create the first administrator, with the sameNANOBOM_DATABASE_URL.
Run a single nanobom process per database (why); the reference says how many connections it opens.
Back up
nanobom backup copies SQLite databases only. Use PostgreSQL’s tools: see
Back up and restore PostgreSQL.
Generate an SBOM
nanobom reads CycloneDX JSON (specification versions 1.3 to 1.7) and SPDX JSON (SPDX 2.2 and
2.3), and matches each component by its package URL (pkg:npm/lodash@4.17.20). Whatever the
generator, make sure it writes one of these formats in JSON and gives components a package URL
with a version. How nanobom reads the document is described in the
upload API reference.
Prefer CycloneDX when the generator offers both: its dependency graph names the project’s direct dependencies more reliably, so findings show what to upgrade more often (see SPDX documents).
Choose a generator
Prefer the generator of your ecosystem when you build from source: it reads the lock file or the resolved dependency tree, so versions are exact and development dependencies can be left out. Use Syft for container images, binaries, and anything else.
| Ecosystem | Command | Notes |
|---|---|---|
| Rust | cargo cyclonedx --format json --override-filename sbom | cargo-cyclonedx; one file per crate of a workspace (see below) |
| npm | npx @cyclonedx/cyclonedx-npm --omit dev --output-file sbom.json | cyclonedx-npm; run after npm ci |
| Yarn (berry) | yarn cyclonedx --output-file sbom.json | yarn-plugin-cyclonedx |
| Python | cyclonedx-py environment --output-file sbom.json | cyclonedx-py; run inside the project’s virtual environment |
| Maven | mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom | writes target/bom.json |
| Gradle | the org.cyclonedx.bom plugin, task cyclonedxBom | writes to build/reports/ |
| Go | cyclonedx-gomod app -json -output sbom.json | cyclonedx-gomod |
| Container images, binaries, anything | syft <image or directory> -o cyclonedx-json=sbom.json | Syft |
Generate SPDX
When a tool or policy requires SPDX, ask for SPDX JSON, version 2.2 or 2.3. Tag-value
(.spdx), RDF and SPDX 3.0 are refused.
| Generator | Command | Notes |
|---|---|---|
| Syft | syft <image or directory> -o spdx-json=sbom.spdx.json | SPDX 2.3; -o spdx-json@2.2=… for 2.2. Not -o spdx, which is tag-value |
| Trivy | trivy image --format spdx-json --output sbom.spdx.json <image>, or trivy fs on a directory | Not --format spdx, which is tag-value |
| GitHub dependency graph | Insights → Dependency graph → Export SBOM, or gh api repos/OWNER/REPO/dependency-graph/sbom --jq .sbom > sbom.spdx.json | SPDX 2.3, from the manifests and lock files GitHub reads (see below) |
GitHub’s export describes the default branch as GitHub last analyzed it, not your build. For a
package no lock file pins, it gives the manifest’s version requirement (^6.1.2, 2.*.*)
instead of a version: nanobom skips such packages and reports them in skipped, since a
requirement cannot be matched. Commit lock files to get versions. The --jq .sbom unwraps the
document from the API’s response.
Rust
cargo cyclonedx writes an SBOM next to each Cargo.toml of a workspace. For a binary, upload
the SBOM of the binary’s crate: it includes its dependencies, workspace crates among them. With
--override-filename sbom each file is named sbom.json in its crate’s directory.
Feature flags change the dependency tree; --all-features covers everything that might be built,
at the cost of possibly listing crates your build does not use. Syft scanning the
Cargo.lock (syft dir:. -o cyclonedx-json=sbom.json) gives one SBOM for the whole workspace,
including development dependencies.
npm and pnpm
cyclonedx-npm reads the installed tree (node_modules), so install first with npm ci.
--omit dev leaves development dependencies out, which is usually what you ship. For pnpm, Syft
on the checkout reads pnpm-lock.yaml.
Python
cyclonedx-py environment lists what is installed in the current environment: run it in the
project’s virtual environment after installing the project, not in a shared one, or it will list
unrelated packages (including itself). Other sources:
cyclonedx-py requirements requirements.txt: only pinned requirements (==) have a version; unpinned ones cannot be matched;cyclonedx-py poetryandcyclonedx-py pipenvread the lock files.
Container images
Syft lists the operating system packages (pkg:deb/…, pkg:apk/…, pkg:rpm/…) and the
language packages it finds in the image:
syft ghcr.io/acme/web:1.4.0 -o cyclonedx-json=sbom.json
Scan the image you push, not the build context: base image packages are part of what you ship.
Pass the tag with image_tag at upload so the history says which image each SBOM describes.
Distribution packages are matched when OSV covers the distribution.
Check an SBOM before uploading
For CycloneDX:
jq '{format: .bomFormat, version: .specVersion,
components: (.components | length),
without_purl: ([.components[] | select(.purl == null)] | length)}' sbom.json
format must be CycloneDX and version between 1.3 and 1.7. Most generators can emit an
older or newer specification with an option (Syft: -o cyclonedx-json@1.6=sbom.json).
without_purl counts the components nanobom will not be able to check.
For SPDX:
jq '{version: .spdxVersion,
packages: (.packages | length),
without_purl: ([.packages[]
| select(.primaryPackagePurpose | IN("FILE", "OPERATING-SYSTEM") | not)
| select(all(.externalRefs[]?; .referenceType != "purl"))]
| length)}' sbom.spdx.json
version must be SPDX-2.2 or SPDX-2.3. without_purl leaves out files and the operating
system, which nanobom ignores, but counts the package the document describes (the scanned
directory or image) when it has no package URL, though it is the project and not a component.
Check what nanobom received
After an upload, open the project and its Components tab. It lists every component nanobom stored for the version shown, vulnerable or not, and says how many components of the SBOM had no package URL and were left out.
- Is the SBOM complete? Compare the count with what the generator should have found. Type a dependency’s name in Name to confirm it is there; a missing one usually means the generator read another lockfile or directory.
- Which licenses does it declare? Choose Without license to list the components whose SBOM entry gives none.
- Which components are vulnerable? Choose With open findings: they come first anyway, the most severe first.
The columns and filters are described in Components of a version.
Upload from CI
Each build that produces something you ship generates an SBOM (Generate an
SBOM) and sends it with one PUT request, authenticated with an upload token.
The request and its answer are described in the upload API reference.
Pipelines written for Dependency-Track keep their client: see Upload with Dependency-Track
clients.
Choose which builds upload
Upload from the builds that produce what you ship (the default branch, release tags), not from
every pull request: each upload replaces the project’s components, so an SBOM of a feature
branch would hide the state of production until the next upload from main. To check a pull
request without replacing anything, use a separate project (web-pr), or none at all.
Maintenance branches that ship next to the default one upload to their own version of the
project: see Track several versions of a product.
Get an upload token
Every project has an upload token of its own, which uploads to that project only and never creates one: a typo in the URL fails instead of creating a project.
- On the organization page, under New project, enter the project’s slug (the name is optional), and Create project. This needs the admin or owner role.
- The project page opens on Upload token: the token, a GitHub Actions step and a
curlcommand, ready to paste. Admins and owners find them there again at any time.
A project that already exists has its token there too. With access to the database, the command line does the same and prints the token alone, so a script can capture it (see the command-line reference):
TOKEN=$(nanobom project create --organization acme --project web)
TOKEN=$(nanobom project token --organization acme --project web)
Store the token as a secret of the CI system, and the instance’s address as a plain variable.
To replace it, select Renew on the project page (or nanobom project token --renew): the old
value stops working at once, so update the secret right after. The page shows when the token was
last used.
Other tokens are created in Settings → API tokens and shown once (tokens):
- an organization token for a pipeline that creates projects as it goes, such as a monorepo or a fleet of images: its first upload to a new slug creates the project;
- a second project token, for a pipeline you want to revoke on its own;
- a Read only token for tools that only read.
To replace one of those, create a new one, update the secret, then revoke the old one.
GitHub Actions
nanobom-action uploads an SBOM, writes the
evaluation to the job summary, annotates the job with the findings that fail the gate, and sets
outputs for later steps. Without an sbom input it generates one with Syft from the checkout.
name: SBOM
on:
push:
branches: [main]
permissions:
contents: read
jobs:
sbom:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7.0.1
- uses: AlixANNERAUD/nanobom-action@v1
with:
url: ${{ vars.NANOBOM_URL }}
token: ${{ secrets.NANOBOM_TOKEN }}
organization: acme
fail-on: high
The project defaults to the repository’s name. Useful inputs:
| Input | Default | |
|---|---|---|
project | repository name | Project slug |
sbom | An existing CycloneDX or SPDX JSON file; without it, Syft generates one | |
scan-path | . | Directory Syft scans |
scan-image | Container image Syft scans instead | |
fail-on | critical, high, medium, low, exploited or license, or several separated by commas (high,license); see Fail CI | |
wait | true | Wait for the evaluation and report it |
source-commit, image-tag | the commit; the Git tag, if any | Shown in the upload history |
summary | true | Write the evaluation to the job summary |
Outputs include http-status, project-url, evaluation-status, the open findings per severity
(critical, high, medium, low) and known-exploited. The
action’s README lists them all.
An SBOM from your own generator, for a Rust project:
- run: cargo install cargo-cyclonedx --locked
- run: cargo cyclonedx --format json --override-filename sbom
- uses: AlixANNERAUD/nanobom-action@v1
with:
url: ${{ vars.NANOBOM_URL }}
token: ${{ secrets.NANOBOM_TOKEN }}
organization: acme
sbom: sbom.json
fail-on: exploited
examples/github-actions.yml
is that workflow in full. Without the action, upload with curl as in
Any CI, with curl.
GitLab CI
The GitLab CI template adds a nanobom job that does what
the GitHub action does: it generates the SBOM with Syft unless you give one, uploads it, writes
the evaluation to the job log, and fails the job on your threshold. Include it in
.gitlab-ci.yml, pinned to a release tag:
include:
- remote: https://raw.githubusercontent.com/AlixANNERAUD/nanobom/vX.Y.Z/ci/gitlab/nanobom.yml
inputs:
organization: acme
fail-on: high
Replace vX.Y.Z with a release, v0.1.0 or
later (older releases do not contain the template). main works too, but changes under you. Define NANOBOM_URL and NANOBOM_TOKEN (masked) under
Settings → CI/CD → Variables. The project defaults to the GitLab project’s name, the scanned
directory to the checkout. Every input is in the reference.
The template sets no rules: the job runs in every pipeline. Add them, and anything else, in a
job of the same name:
nanobom:
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
To scan the image a tag pipeline built, in the project’s registry (the job logs in with the job’s credentials):
include:
- remote: https://raw.githubusercontent.com/AlixANNERAUD/nanobom/vX.Y.Z/ci/gitlab/nanobom.yml
inputs:
organization: acme
scan-image: $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
stage: deploy
fail-on: high,exploited
nanobom:
needs: [build-image]
rules:
- if: $CI_COMMIT_TAG
To upload an SBOM from your own generator, give its path in sbom and take it from the job that
writes it:
include:
- remote: https://raw.githubusercontent.com/AlixANNERAUD/nanobom/vX.Y.Z/ci/gitlab/nanobom.yml
inputs:
organization: acme
sbom: sbom.json
nanobom:
needs: [cargo-sbom]
Later jobs that need the nanobom job read the counts from its dotenv report, such as
$NANOBOM_HIGH and $NANOBOM_PROJECT_URL (outputs).
To upload several SBOMs, include the template once per SBOM with a different job-name and
project or version; each copy writes the same variable names, so a job reading them should
need only the copy it reads.
The job runs in alpine:3.24 and installs curl and jq at each run. To run it elsewhere,
such as in a mirror of the image or in an image that already has curl, jq and syft, set
the image input (requirements).
The template is not in the GitLab CI/CD Catalog: include: component does not work, and the
remote include is fetched from GitHub when the pipeline is created.
examples/gitlab-ci.yml
is a complete pipeline. Without the template, upload with curl as below.
Any CI, with curl
#!/bin/sh
set -eu
# NANOBOM_URL, NANOBOM_TOKEN, COMMIT and the SBOM come from the CI system.
curl --fail-with-body --silent --show-error \
--request PUT \
--header "Authorization: Bearer $NANOBOM_TOKEN" \
--data-binary @sbom.json \
--output response.json \
"$NANOBOM_URL/api/organizations/acme/projects/web/sbom?source_commit=$COMMIT&fail_on=high" \
|| { cat response.json; exit 1; }
jq -r '.evaluation | "\(.status): \(.open.critical) critical, \(.open.high) high, \(.known_exploited) known exploited"' response.json
--data-binarysends the file unchanged (--datawould strip its line breaks);-Fwould wrap it in a multipart form, which nanobom does not read.--fail-with-bodymakescurlexit with an error on any status from 400, so the job fails on409and503as well as on configuration mistakes, while keeping the body for the log.- When many jobs wait at once, the instance may refuse one with a
503and aRetry-Afterheader, before storing anything (limit).--retry 3sends it again after that delay, but also after a503for an evaluation that did not complete, which uploads the SBOM again.
Without fail_on (and wait), the request returns as soon as the SBOM is stored. To fail the
job on vulnerabilities, see Fail CI on vulnerabilities.
Pick a project slug that is valid as is: ${GITHUB_REPOSITORY#*/} and $CI_PROJECT_NAME are
usually fine, but a repository name with spaces, slashes, a leading dot or upper-case letters is
folded or refused (see the slug rules).
Upload with Dependency-Track clients
nanobom accepts the upload requests of Dependency-Track’s API, so a pipeline that uploads SBOMs to Dependency-Track can upload to nanobom by changing two settings: the server’s address, and the API key, which becomes a nanobom upload token. The requests and answers are described in the upload API reference; what the mapping implies is explained in Dependency-Track compatibility.
Before you start
-
Generate the SBOM in JSON. Many Dependency-Track setups upload
bom.xml; nanobom reads CycloneDX JSON and SPDX JSON only, so switch the generator’s output format (see Generate an SBOM). -
Get an upload token as in Upload from CI. A client that uploads to one project uses that project’s upload token;
autoCreateis accepted with it but never creates the project, which must exist. Use an organization token for clients that create projects (autoCreate). -
Name projects with a slug. The project name becomes the project’s slug, folded to lower case:
Web-Appuploads toweb-app, butWeb Appis refused, since a slug cannot contain a space. -
Identify projects by name, not by UUID. nanobom has no project UUIDs: a client configured with a project UUID only gets a
400. -
Send a version that names a release, not a build.
projectVersionis the project version the SBOM goes to. A build number or a commit hash, new at every build, creates a version per build: it works, but past 50 active versions each build makes the oldest one inactive (the cap), and the project page lists every build. Use a release or branch name, or leaveprojectVersionout to keep one version per project. Version names are 1 to 64 letters, digits,.,_,+,/or-.
Earlier nanobom releases recorded projectVersion as the upload’s image tag and kept one
inventory per project. Since project versions, each projectVersion is a version of its own
(what changed).
GitHub Actions, with gh-upload-sbom
- uses: DependencyTrack/gh-upload-sbom@v4.3.0
with:
server-hostname: nanobom.example.org
api-key: ${{ secrets.NANOBOM_TOKEN }}
project-name: web
project-version: ${{ github.ref_name }}
auto-create: true
bom-filename: bom.json
Run it on the default and release branches only: on every pull request branch, ref_name would
create a version per branch.
auto-create: true is required even when the project exists: without it, the action sends the
project’s UUID instead of its name. For an instance on another port or over plain HTTP, set
port and protocol.
The action does not wait for the evaluation. To fail the job on vulnerabilities, use nanobom-action instead.
Jenkins
In Manage Jenkins → System → Dependency-Track, set Dependency-Track Backend URL to the nanobom address and API key to a credential holding the upload token. Then publish from the pipeline:
dependencyTrackPublisher artifact: 'target/bom.json', projectName: 'web',
projectVersion: env.BRANCH_NAME, synchronous: false
env.BRANCH_NAME is set in multibranch pipelines; avoid env.BUILD_NUMBER, which would create
a version per build.
Keep synchronous publishing off: in synchronous mode the plugin fetches findings and policy
violations through Dependency-Track endpoints that nanobom does not have, and fails the build. For
the same reason, leave project properties (tags, group, description, SWID tag ID) unset. Thresholds
need synchronous mode; to fail a build on vulnerabilities, call the native upload with fail_on
(Fail CI on vulnerabilities).
Maven
Generate the SBOM in JSON with the CycloneDX Maven plugin, then upload it with the Dependency-Track Maven plugin:
mvn org.cyclonedx:cyclonedx-maven-plugin:2.9.3:makeAggregateBom -DoutputFormat=json \
io.github.pmckeown:dependency-track-maven-plugin:0.8.8:upload-bom \
-Ddependency-track.dependencyTrackBaseUrl=https://nanobom.example.org \
-Ddependency-track.apiKey="$NANOBOM_TOKEN" \
-Ddependency-track.bomLocation=target/bom.json
The project name defaults to the artifact ID and the version to the Maven version; set
dependency-track.projectName when the artifact ID is not a valid slug. The plugin creates
missing projects. With a -SNAPSHOT version, every snapshot of a release uploads to the same
version, as wanted; set dependency-track.projectVersion to override it.
After the upload, the upload-bom goal looks the project up and refreshes its metrics through
Dependency-Track endpoints that nanobom does not have, and logs an error. The SBOM is stored all
the same, and with failOnError at its default, false, the build passes. Keep it so.
Gradle
There is no widely used Gradle plugin for Dependency-Track uploads. Generate the SBOM in JSON
with the CycloneDX Gradle plugin, then upload the file with curl, as below.
Scripts and curl
As a multipart form, which is what most clients send:
curl --fail-with-body --silent --show-error \
-H "X-Api-Key: $NANOBOM_TOKEN" \
-F projectName=web -F projectVersion=1.4.0 -F autoCreate=true \
-F bom=@bom.json \
https://nanobom.example.org/api/v1/bom
Or as JSON, with the SBOM base64-encoded:
base64 < bom.json | tr -d '\n' |
jq -Rs '{projectName: "web", projectVersion: "1.4.0", autoCreate: true, bom: .}' |
curl --fail-with-body --silent --show-error -X PUT \
-H "X-Api-Key: $NANOBOM_TOKEN" -H "Content-Type: application/json" \
--data-binary @- \
https://nanobom.example.org/api/v1/bom
The SBOM travels through pipes: passing it as a command-line argument (jq --arg bom "$(base64 …)") fails for SBOMs of about 100 KiB or more, since the system limits the size of an
argument. tr removes the line breaks that GNU base64 adds; nanobom ignores them, but
Dependency-Track does not, so the same command works against both.
Both answer {"token": "…"}. A script that must wait for the project’s evaluation polls
GET /api/v1/event/token/{token} with the same header until it answers
{"processing": false}.
Track several versions of a product
When a product has maintenance branches next to its main one (main ships 3.x while release/2.4
still gets security fixes), upload each branch to its own version of the same project. Each
version keeps its own components, findings and triage, so a dependency fixed on main still
shows as vulnerable on the branch that ships the old one. How versions work is explained in
Concepts; the parameters are in the
upload API reference.
Name the version in the upload
Add version to the upload URL. The first upload naming a version creates it, with the open and
ignored findings of the latest version, so a release branch starts with the triage already done
on main.
curl --fail-with-body --silent --show-error \
--request PUT \
--header "Authorization: Bearer $NANOBOM_TOKEN" \
--data-binary @sbom.json \
"$NANOBOM_URL/api/organizations/acme/projects/web/sbom?version=$BRANCH&fail_on=high"
- A version name is 1 to 64 letters, digits,
.,_,+,/or-, and is case-sensitive:release/2.4and2.4.xare fine; a name with a space is refused with a422. Encode/as%2Fand+as%2Bin the URL. - Name a version after something that lasts: a release branch or a release line. A build number or a commit hash creates a new version at every build; past 50 active versions, each new one makes the version uploaded to the longest ago inactive (the cap).
- Projects that never name a version keep their single, unnamed version: nothing changes for
them. Uploads without
versionkeep going to the unnamed version.
Keep the latest version on the main branch
The latest version is the one the project page, the read API and the VEX export show when
they are not asked for another. A version an upload creates becomes the latest, which is right
for the branch that will ship next, and wrong for a maintenance branch. Upload maintenance
branches with latest=false:
name: SBOM
on:
push:
branches: [main, "release/**"]
jobs:
sbom:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v7.0.1
# Writes sbom.json: see Generate an SBOM.
- run: cargo install cargo-cyclonedx --locked && cargo cyclonedx --format json --override-filename sbom
- name: Upload the SBOM
env:
NANOBOM_URL: ${{ vars.NANOBOM_URL }}
NANOBOM_TOKEN: ${{ secrets.NANOBOM_TOKEN }}
VERSION: ${{ github.ref_name }}
LATEST: ${{ github.ref_name == 'main' }}
run: |
VERSION=$(printf %s "$VERSION" | sed 's|/|%2F|g; s|+|%2B|g')
curl --fail-with-body --silent --show-error \
--request PUT \
--header "Authorization: Bearer $NANOBOM_TOKEN" \
--data-binary @sbom.json \
"$NANOBOM_URL/api/organizations/acme/projects/web/sbom?version=$VERSION&latest=$LATEST&fail_on=high"
Uploads from main keep the main version latest (latest=true), and uploads from
release/2.4 go to the release/2.4 version without taking the flag (latest=false). The
workflow runs on the main and release branches only: on pull request branches, ref_name would
create a version per branch.
To version by release line rather than by branch, send the line instead: version=2.4 from
every v2.4.* tag.
Read one version
-
On the project page, the Version field of the filters shows the latest version by default; choose another and select Filter. The other filters are sent with it, so they stay as they are. The findings, the summary of open findings, the license violations, the component count and the Export VEX button follow the version shown. The upload history lists every upload of the project, with its version.
-
With the read API, add
versionto the findings, components and license violations endpoints, and list the versions with/versions(reference):curl --silent --header "Authorization: Bearer $NANOBOM_TOKEN" \ "$NANOBOM_URL/api/organizations/acme/projects/web/findings?version=release%2F2.4" -
VEX documents are exported from and imported into one version with the same parameter (VEX API).
Compare a vulnerability across versions
Open a finding: Versions of this project lists every version of the project, newest first,
with where it stands with that vulnerability (open, ignored, fixed or not affected, aliases
included) and a link to its finding. Use it to see which releases still need a fix. The read
API’s finding has the same list in versions
(reference).
The component search lists a package once per version that has it, with the version’s name.
Retire a version
When a release is no longer supported, make its version inactive rather than deleting it: runs stop checking it, and it no longer counts on the organization page, shows up in searches or sends notifications, while its findings and triage stay readable and exportable (what changes).
- Open the project page; the Versions table lists every version with its open findings.
- Select Make inactive on the version’s row. The latest version has no such button: make another version latest first.
The project page shows an inactive version on request, marked inactive. To check it again, select Make active: a run starts at once. An upload to an inactive version also makes it active again.
These buttons, and the ones below, are for organization admins and owners.
Change the latest version
Select Make latest on the version’s row. Pipelines usually keep the flag where it belongs
(latest=true from the main branch); use the button to fix it after a wrong upload, or when
the main line moves to another version without an upload yet. An inactive version cannot be the
latest: make it active first.
Delete a version
Deleting a version deletes its components, upload history and findings, with their triage and history, for good; other versions keep what they inherited from it. To keep the history, make the version inactive instead.
- On the version’s row, select Delete.
- Tick the box confirming what is deleted, and select Delete version.
The latest version cannot be deleted (make another one latest first), nor the only version of a project: delete the project instead.
What to expect
- The gate judges the version uploaded.
fail_oncounts the findings of the version the upload went to, not those of the other versions: a release branch fails on its own vulnerabilities only. - Triage is per version. Ignoring a finding in
release/2.4does not ignore it inmain. Versions created later inherit the ignores of the latest version at the time. - Notifications are per vulnerability. A new advisory against a dependency several versions share is announced once, with the list of the versions it affects; findings a new version inherits are never announced (payloads).
- Counts are per issue. The organization page counts a vulnerability of a package once per project, at its highest severity, however many active versions have it.
- Dependency-Track clients already send a version:
projectVersionis the version, andisLatestthe latest flag (Upload with Dependency-Track clients).
Fail CI on vulnerabilities
An upload with fail_on waits for the project’s evaluation and answers 409 when its open
findings reach the threshold, so the CI job fails. The thresholds, the response and the status
codes are in the upload API reference.
Turn the gate on
Add the threshold to the upload:
- with the GitHub Action or the GitLab CI template, the input
fail-on: high; - with any other client, the query parameter
fail_on=high, as in the curl example.
exploited fails on known exploited findings whatever their severity; it needs exploitation data,
and is refused with a 422 on an instance with NANOBOM_EXPLOITATION_DATA=false rather than
always passing.
Thresholds combine, separated by commas: fail_on=high,exploited fails on either. license
fails on components whose license the organization forbids
(Enforce a license policy).
The client must treat any status from 400 as a failure while printing the body, which lists the
findings that crossed the threshold in evaluation.findings: the action and the GitLab template
do it, and so do curl --fail-with-body and wget --content-on-error.
Before turning it on
- The gate looks at the whole project, not at what changed. A pipeline that never touched
lodashfails when a new advisory for it appears overnight. That is the point of a gate on the default branch; on pull requests, it can surprise contributors. - Ignoring is how a pipeline passes while the fix is planned. Ignored findings do not count: ignore with a reason and an expiry date (Triage findings).
- No answer is not a pass. When the evaluation fails (OSV unreachable) or times out, the
upload answers
503: the findings are not up to date, so the gate cannot say they are fine. If you would rather not block releases on OSV’s availability, treat503as a warning in your script. unknownseverity never fails a severity gate. Findings whose advisory has no score or rating are only caught byexploited(if they are), or by reading the project page.
Let uploads wait through your proxies
A waiting upload holds its HTTP request open for up to NANOBOM_UPLOAD_WAIT_SECONDS (300 by
default). Every proxy between CI and nanobom must allow that, or CI gets a 504 from the proxy
while the run goes on:
- nginx:
proxy_read_timeout 330s;on the API location (the default is 60 seconds); - Traefik 3: the entry point’s
transport.respondingTimeouts.readTimeoutdefaults to 60 seconds; raise it above the wait as a precaution, and keepforwardingTimeouts.responseHeaderTimeoutunset (no limit) or above it; - Caddy does not limit how long a proxied response takes by default (unless
response_header_timeoutis set); - cloud load balancers often have an idle timeout of 60 seconds that needs raising.
Alternatively, lower NANOBOM_UPLOAD_WAIT_SECONDS below your proxy’s timeout. Complete proxy
configurations are in Run behind a reverse proxy.
Keep NANOBOM_UPLOAD_WAIT_SECONDS above the usual duration of a project’s run plus the time it
may wait behind the nightly run: runs execute one at a time.
When the gate fails
409: fix the findings listed inevaluation.findingsby upgrading the components, or ignore the ones that do not apply, then run the job again.503: see Upload answers 503.
The SBOM is stored in both cases: the inventory is up to date even when the gate fails.
Turn the gate off
Remove fail_on (or fail-on) from the upload; the SBOM is still recorded.
Enforce a license policy
Tell nanobom which licenses your organization accepts, see the components that break the rule, and fail CI when one is forbidden. Every setting and how licenses are judged are in the license policy reference. You need the admin role in the organization.
Check that your SBOMs carry licenses
nanobom reads licenses from the SBOM; it does not look at the packages themselves. Search for a
license you know you use, such as MIT, in the License field of the search page: if your
projects’ components show up, the generator writes licenses. If they do not, or many show
Unknown, check the generator’s options first, then upload again: licenses are read at each
upload. Some generators write free-text names (Apache Software License) rather than SPDX
identifiers; nanobom treats those as unknown.
Forbid a few licenses
-
Open the organization, then Settings, then License policy.
-
Write the licenses to forbid in Forbidden licenses, one per line or separated by commas, as SPDX identifiers:
AGPL-3.0-only AGPL-3.0-or-later SSPL-1.0 -
Optionally, write licenses to review in Licenses to warn about (
GPL-3.0-only,MPL-2.0), and set Unknown licenses to Warn to see the components whose license the SBOM does not give. -
Keep Licenses not listed at Allow, and save.
Allow only some licenses
An allowlist forbids everything you did not approve:
-
In Allowed licenses, list what you accept:
MIT Apache-2.0 BSD-2-Clause BSD-3-Clause ISC -
Set Licenses not listed to Forbid.
-
Set Unknown licenses to Warn while you clean up, then to Forbid to require a license on every component.
-
Save.
A component licensed MIT OR GPL-3.0-only passes, since you can choose MIT; one licensed
MIT AND GPL-3.0-only does not, since both apply (why).
See the violations
Each project page gets a Licenses section listing the components the policy forbids or warns about, forbidden first, and the organization page shows a badge on each project with violations. The policy applies at once to every project, without waiting for an upload.
Scripts read the same list from the read API:
curl --fail-with-body -H "Authorization: Bearer $NANOBOM_READ_TOKEN" \
"$NANOBOM_URL/api/organizations/acme/projects/web/license-violations"
Fail CI on forbidden licenses
Add license to fail_on in the upload URL. Alone, it gates on licenses only; with a severity
it gates on both:
curl --fail-with-body -X PUT \
-H "Authorization: Bearer $NANOBOM_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @sbom.json \
"$NANOBOM_URL/api/organizations/acme/projects/web/sbom?fail_on=high,license"
The upload answers 409 when a component is forbidden, and lists the first violations in
evaluation.licenses (response). Warnings
never fail it. The SBOM is stored either way.
Deal with a violation
- Replace the component, or upgrade it to a version under a license you accept.
- Accept the license: move it to Allowed licenses, or to Licenses to warn about to keep seeing it.
- Name a license outside the SPDX list: when your SBOM gives
LicenseRef-Acme-Commercialfor a component you bought, list that identifier in Allowed licenses. - Unknown license: fix the generator’s settings, or the component’s metadata, so the SBOM
gives an SPDX expression; a free-text name such as
Apache License 2.0is unknown.
Turn the policy off
Empty the three lists, set both defaults to Allow and save. Remove license from fail_on:
without a policy it always passes anyway.
Triage findings
A project with a few hundred dependencies easily has dozens of findings. Why they are ordered as they are is explained in Prioritization; a reasonable routine, from most to least urgent:
- Known exploited findings, tagged KEV on the project page: someone exploits them in the wild. CISA gives federal agencies a due date to fix each one; it is a fair deadline for anyone.
- Critical and high findings with a high EPSS score.
- The rest, by severity, during regular dependency updates.
Findings that do not apply (vulnerable code not reachable, feature not compiled in, accepted risk) are ignored with a reason, ideally with an expiry date so the decision is revisited. Ignoring and restoring need the member role or above (roles).
Choose what to upgrade
The vulnerable component is often not one your manifest names. On the finding’s page,
Introduced via lists the paths from the project’s direct dependencies to it, such as
web-framework 2.1.0 → template-engine 0.9.0 → lodash 4.17.20:
- A component marked direct dependency is yours: upgrade it to a version listed under Fixed in.
- Otherwise, upgrade the direct dependency that starts the path to a release that requires a fixed version of the component; its changelog, or the diff of your lock file, tells.
- When no such release exists yet, force the transitive version with your package manager
(npm
overrides, Yarnresolutions, a Cargo[patch]section, Maven<dependencyManagement>), or ignore the finding with a reason and an expiry.
Each listed path needs the fix: a component reached through two direct dependencies stays until both require a fixed version. The Introduced via column of the project page shows the direct dependencies of every finding at a glance; findings that share one are often fixed by a single upgrade. When the page says the SBOM does not tell the project’s direct dependencies, its generator left the graph out (Dependency paths).
Ignore a finding
On the finding’s page, under Triage:
- Reason (required, up to 2,000 characters): why it does not apply or is accepted. It is kept in the finding’s history with your name, for whoever reads it next year.
- Justification (optional): why the product is not affected, in the CycloneDX vocabulary (Vulnerable code not reachable, Requires a configuration not in use…), or False positive. Leave None for an accepted risk. VEX exports state that the product is not affected only for findings ignored with a justification.
- Ignore until (optional): a date,
YYYY-MM-DD, after which the finding opens again. - Select Ignore finding.
Good reasons are specific and checkable:
- “Only the
sqlitefeature of sqlx is compiled; the PostgreSQL driver is not linked.” - “Affects the CLI parsing of
foo; we only use its library API. Revisit when upgrading to 3.x.”
An expiry date turns a decision into a reminder: ignore until the date of the planned upgrade, not forever. Only open findings can be ignored. Findings can also be ignored by importing VEX statements; the history then names the upload token instead of a member. What an ignored finding still does, and when it opens again, is described in How findings are kept up to date.
Restore a finding
Restore finding, on the page of an ignored finding, returns it to open at once. Only ignored findings can be restored; fixed findings need no action.
Filter a project’s findings
On the project page, filters narrow the findings by severity, status (open and ignored by default, or one status, or all), ecosystem, or to Only known exploited vulnerabilities: choose them and select Filter. For a project that names versions, the same form chooses the version shown.
The summary under the project’s name does not follow the filters: it always counts the open findings of the version shown, by severity, and how many of them are known exploited.
Find which projects use a package
The search box at the top of every page finds components across all the organizations you can see:
| Query | Finds |
|---|---|
openssl | components whose name contains openssl (case-insensitive) |
openssl 3. | the same, with a version starting with 3. |
lodash@4.17 | the same as lodash 4.17 |
babel/core | @babel/core; leave out a leading @, which would start the version |
Names include the namespace of the package URL (@scope/name for npm, group/name for Maven).
At most 200 results are shown. Search is the quickest answer to “are we affected?” when an
advisory is in the news, before the nightly run has even picked it up.
Results show each component’s license. To find components by license, fill the license field
of the search page (GPL finds GPL-3.0-only and MIT OR LGPL-2.1-or-later), with or without
a name; components whose SBOM gives no license show Unknown and never match.
From a finding’s page, Also affected lists the other components affected by the same vulnerability in the organizations you can see.
Check a project now
Check now, on an organization or project page (members and above), starts a run of that scope instead of waiting for the next upload or the nightly run.
Retire a project
A project whose SBOM stopped coming is flagged Stale (stale projects). If it was retired, delete it from its page (admins): its components, upload history and findings are deleted. With an organization token, a later upload under the same slug creates it again.
Exchange VEX statements
A VEX document tells someone which vulnerabilities of your product matter and which do not (VEX). nanobom writes one from a project’s findings and reads others’ to ignore findings. The exact formats and rules are in the VEX API reference.
Record why a finding does not apply
Exports only say a vulnerability does not affect the product when a member said why, in machine-readable form. When you ignore a finding (Triage findings), choose a Justification as well as the reason:
- Vulnerable code not reachable, Vulnerable code not present, Requires a configuration not in use and the other justifications state that the product is not affected;
- False positive says the vulnerability was wrongly associated with the component;
- None fits an accepted risk: the finding is ignored in nanobom, but exported as still being
analysed (
in_triage), with your reason.
Export a VEX for a customer or an auditor
From the interface: on the project page, select Export VEX. Any member, viewers included, can download it.
From a script or CI, with a token of the project or its organization, of either scope (a read token is enough to export):
curl -fsS -H "Authorization: Bearer $NANOBOM_TOKEN" \
-o web.vex.cdx.json \
https://nanobom.example.org/api/organizations/acme/projects/web/vex
Send it with the SBOM of the same release: the VEX names components by package URL, so it reads on its own, but the SBOM tells what else the product contains. Before sending, check that the project’s latest upload is the release you describe, since the export reflects the current findings.
Import a vendor’s VEX
When a supplier ships a VEX for a component you use, import it into each project that uses the component:
curl -fsS -X PUT -H "Authorization: Bearer $NANOBOM_TOKEN" \
--data-binary @vendor.vex.cdx.json \
https://nanobom.example.org/api/organizations/acme/projects/web/vex
Statements saying not_affected or false_positive ignore the open findings they cover; the
response lists what was ignored and what was skipped, and why. Read the results with
no_matching_finding or unresolved_reference: the vendor may name the component in a way
nanobom cannot match, such as a package URL without a version.
The ignores show by upload token and the token’s name in each finding’s history. Give the
token used for imports a name that says where the statements come from, such as vendor VEX.
Keep your own statements in the repository
To keep triage decisions next to the code and review them in pull requests, write them as a CycloneDX VEX file in the repository and import it in CI after each upload:
- name: Upload the SBOM
run: |
curl -fsS -X PUT -H "Authorization: Bearer $NANOBOM_TOKEN" --data-binary @sbom.json \
"https://nanobom.example.org/api/organizations/acme/projects/web/sbom?wait=true"
- name: Import our VEX statements
run: |
curl -fsS -X PUT -H "Authorization: Bearer $NANOBOM_TOKEN" --data-binary @vex.cdx.json \
https://nanobom.example.org/api/organizations/acme/projects/web/vex
A minimal file, for one finding:
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"version": 1,
"vulnerabilities": [
{
"id": "CVE-2021-23337",
"analysis": {
"state": "not_affected",
"justification": "code_not_reachable",
"detail": "We never call lodash.template."
},
"affects": [{ "ref": "pkg:npm/lodash@4.17.20" }]
}
]
}
The package URL includes the version: when the component is upgraded and still vulnerable, the new finding is not covered until you review the statement and update it.
An export, edited, is a good starting point: change analysis where it applies and drop the
other entries.
Put the statements in the SBOM
Generators and tools that write statements into the SBOM’s own vulnerabilities need no second
call: the upload imports them. Upload with wait=true or fail_on so they also cover findings
opened by this upload, and so the gate ignores them
(statements inside an SBOM).
Share a vulnerability report
This guide gives a customer, an auditor or a regulator a document describing the vulnerabilities of a release: what nanobom checked, what is open, and what was assessed as not affecting the product. What the report contains is in the reference.
Print it from the interface
- Open the project and, if the project has versions, choose the version in the filters.
- Select Report. The report opens for the version shown.
- Print the page from the browser (
Ctrl+P, orCmd+Pon macOS), and choose Save as PDF as the printer to get a file.
The printout leaves out the interface around the report and always uses light colors. Before sharing it, check the Scope and provenance section: a warning says when the project stopped receiving SBOMs or when the version is no longer checked.
Ignored findings appear with their reason and justification. Write reasons for this audience: the triage guide explains how to ignore a finding with a justification.
Archive it from CI
The same report is served as an HTML document under the API, so a release workflow can store it next to the release’s artifacts.
- Create a token: in the organization’s Settings → API tokens, choose the project and the Read only scope. An upload token of the project works too.
- Store it as a secret of the repository (
NANOBOM_TOKEN), and the address of nanobom as a variable (NANOBOM_URL). - After the upload of the release’s SBOM, download the report of the release’s version:
- name: Archive the vulnerability report
env:
NANOBOM_URL: ${{ vars.NANOBOM_URL }}
NANOBOM_TOKEN: ${{ secrets.NANOBOM_TOKEN }}
VERSION: ${{ github.ref_name }}
run: |
curl --fail-with-body --silent --show-error \
--get --data-urlencode "version=$VERSION" \
-H "Authorization: Bearer $NANOBOM_TOKEN" \
-o vulnerability-report.html \
"$NANOBOM_URL/api/organizations/acme/projects/web/report"
- uses: actions/upload-artifact@v7.0.2
with:
name: vulnerability-report
path: vulnerability-report.html
Replace acme and web with the organization and project slugs. Without version, the report
is about the latest version. Add -H "Accept-Language: fr" for a report in French. The file
opens in any browser, without access to nanobom, and prints like the page.
A 404 means the version has no SBOM in nanobom yet, or the token does not reach the project;
the reference lists the statuses.
Give the machine-readable form too
The report is the readable form of the project’s VEX statements. Tools that read VEX get the same assessments from the VEX export, whose address the report gives.
Export findings to a spreadsheet
This guide writes the open findings of every project of an organization to a CSV file, which
any spreadsheet opens, with the read API, curl and jq.
Create a read token
A read token reads everything its organization holds and changes nothing, so it is the token to give a script (Tokens and scopes).
- In the organization’s Settings → API tokens, name the token (
spreadsheet export), keep Whole organization as project, choose Read only as scope, and select Create token. - Copy the token: it is shown once.
From the command line, on the server:
nanobom token create --organization acme --name "spreadsheet export" --scope read
Store it in an environment variable for the steps below:
export NANOBOM_URL=https://nanobom.example.com
export NANOBOM_TOKEN=nanobom_…
Check the token
curl -fsS -H "Authorization: Bearer $NANOBOM_TOKEN" "$NANOBOM_URL/api/organizations" | jq
The answer lists the token’s organization, with the role viewer. A 401 means the token is
wrong or revoked.
Write the CSV file
Save this script as export-findings.sh:
#!/bin/sh
# Writes the open findings of every project of an organization as CSV.
set -eu
organization=$1
api() {
curl -fsS -H "Authorization: Bearer $NANOBOM_TOKEN" "$NANOBOM_URL/api/$1"
}
echo 'project,vulnerability,aliases,severity,known exploited,EPSS,component,version,introduced via,first seen,link'
for project in $(api "organizations/$organization/projects" | jq -r '.items[].slug'); do
offset=0
while :; do
page=$(api "organizations/$organization/projects/$project/findings?status=open&limit=500&offset=$offset")
echo "$page" | jq -r '.items[] | [
.project,
.vulnerability_id,
(.aliases | join(" ")),
.severity,
.exploitation.known_exploited,
(.exploitation.epss_score // ""),
.component.name,
(.component.version // ""),
([.introduced_via[].name] | join(" ")),
.first_seen_at,
.url
] | @csv'
offset=$((offset + 500))
[ "$offset" -lt "$(echo "$page" | jq .total)" ] || break
done
done
Run it:
sh export-findings.sh acme > findings.csv
Each project’s findings come in the project page’s order: known exploited first, then by severity and EPSS score.
Adjust the selection
Change the query of the findings request:
| To export | Query |
|---|---|
| Open and ignored findings, as the project page shows them | remove status=open |
| Critical and high findings only | add &severity=critical,high |
| Known exploited findings only | add &exploited=true |
| Every finding, fixed ones included | status=all |
The reference lists every field of a finding, such as the ignore reason and justification, to add as columns.
Run it on a schedule
The script only reads, so it can run as often as needed, for example nightly after the scheduled run, from cron or a CI schedule. Keep the token in the scheduler’s secrets, and revoke it in Settings → API tokens when the export is no longer needed.
Query nanobom from an assistant (MCP)
This guide connects an assistant that speaks the Model Context Protocol (MCP), such as Claude Code or Claude Desktop, to nanobom’s MCP endpoint, so you can ask it about your organization’s vulnerabilities in plain words. The assistant reads; it cannot change anything in nanobom.
Create a read token
The assistant authenticates with a token, as scripts do. Give it a read token: it reads everything its reach holds and changes nothing (Tokens and scopes). A project token limits it to one project.
- In the organization’s Settings → API tokens, name the token (
assistant), choose the whole organization or one project, choose Read only as scope, and select Create token. - Copy the token: it is shown once.
From the command line, on the server (add --project web for one project):
nanobom token create --organization acme --name assistant --scope read
Connect the assistant
The endpoint is /mcp under your instance’s public URL, with the token in the
Authorization header.
Claude Code
claude mcp add --transport http nanobom https://nanobom.example.com/mcp \
--header "Authorization: Bearer nanobom_…"
To share the server with a repository’s contributors without sharing the token, add it to the
project’s .mcp.json, and have each contributor set NANOBOM_TOKEN in their environment:
{
"mcpServers": {
"nanobom": {
"type": "http",
"url": "https://nanobom.example.com/mcp",
"headers": {"Authorization": "Bearer ${NANOBOM_TOKEN}"}
}
}
}
Claude Desktop and clients without HTTP headers
Clients that only start local servers reach the endpoint through mcp-remote, which needs Node.js. In Claude Desktop, open Settings → Developer → Edit Config and add:
{
"mcpServers": {
"nanobom": {
"command": "npx",
"args": [
"mcp-remote",
"https://nanobom.example.com/mcp",
"--header",
"Authorization:${NANOBOM_AUTHORIZATION}"
],
"env": {"NANOBOM_AUTHORIZATION": "Bearer nanobom_…"}
}
}
}
Restart Claude Desktop afterwards.
Other clients
Any client of the Streamable HTTP transport works: give it the URL and the header
Authorization: Bearer nanobom_… (or X-Api-Key: nanobom_…). In VS Code, for example, in
.vscode/mcp.json:
{
"servers": {
"nanobom": {
"type": "http",
"url": "https://nanobom.example.com/mcp",
"headers": {"Authorization": "Bearer ${input:nanobom-token}"}
}
},
"inputs": [
{"id": "nanobom-token", "type": "promptString", "description": "nanobom token", "password": true}
]
}
Check the connection
In Claude Code, /mcp lists the server and its seven tools. If the client reports an
authentication error, the token is wrong or revoked: the endpoint answers 401 to a request
without a valid token, and does not accept the session of the interface.
Ask questions
- “Which of my projects are affected by CVE-2021-44228?” (
affected_by, which also matches the GHSA and other aliases of the CVE) - “What is open and critical in web on release/2.4, and how does it come in?” (
list_findings, thenget_findingfor the dependency paths) - “Which known exploited vulnerabilities are still open, and which is due first?”
- “Which components use a GPL license?” (
search_components) - “Does api 3.1 break our license policy?” (
license_violations) - “Which projects have not received an SBOM for a while?” (
list_projects,stale)
The answers link to the findings and projects in the interface, where you triage them.
Mind the advisory text
Advisories come from OSV and are written by third parties. Someone could write one to steer an assistant that reads it. nanobom returns that text in clearly marked fields and tells the assistant to treat it as data, but the defence that holds is on your side:
- give the assistant a read token, so whatever it is told, it cannot change anything in nanobom;
- be careful when the same session can act elsewhere (run commands, write files, open pull requests), and review what the assistant proposes after reading advisories.
Revoking the token in Settings → API tokens disconnects the assistant at once.
Show a badge in a README
This guide puts a badge with a project’s open findings in its README, like a coverage badge: a small image reading, for example, “vulnerabilities | 1 critical, 2 high”.
nanobom data is private, so a badge is off until an admin or owner of the organization turns it on. Once on, anyone with the badge’s address sees the open findings of the project’s latest version, and nothing else (Badges lists what it shows).
Turn the badge on
- Open the project’s page and find the Badge section, near the bottom. Only admins, owners and instance administrators see it.
- Select Turn on.
The section now shows the badge and the Markdown to paste.
Paste the snippet
Copy the Markdown for a README field into the README:
[](https://nanobom.example.com/organizations/acme/projects/web)
The image links to the project page, which only members can open. For an open-source project,
publish a public page: while it is on, the snippet links to the public page
instead, so visitors who click the badge see the findings behind the counts and how they were
triaged. The addresses start with NANOBOM_PUBLIC_URL
(Configuration): for a public README, that address must be
reachable from the internet, or at least the /badges/ path of it (and /public/ for the
public page).
To show another version than the latest, add ?version= and the version’s name to the image
address:

The badge follows triage: an ignored finding no longer counts. Image proxies such as GitHub’s may keep a badge for up to five minutes.
Restyle it with shields.io
The same address with .json instead of .svg answers in the
shields.io endpoint format. Give it to shields.io to
change the style, the label or add a logo:

shields.io then fetches the counts from nanobom, so the nanobom address must be reachable from the internet.
Change or revoke the address
The address is the badge’s only protection. If it leaks where it should not, or the README goes private:
- New address gives the badge another address; the old one stops working at once. Paste the new snippet where the old one was.
- Turn off removes the badge; its address stops working at once.
Deleting the project removes its badge too.
Publish a public page of a project
This guide publishes a page of a project’s findings that anyone with its address can read, for an open-source project whose README carries the nanobom badge. Visitors who click the badge see what is behind the counts, and how each advisory was triaged, for example “not affected, vulnerable code not reachable”, instead of filing an issue about their own scanner’s alert.
The page is off by default, project by project. Once on, anyone with its address sees the open and ignored findings of the latest version (or another version by name) and a VEX document of them, never the reasons members wrote when ignoring a finding nor who triaged it. Public pages lists exactly what is shown.
When not to
Leave the page off for private and commercial projects: their findings tell an attacker which vulnerable components they ship. The address is the page’s only protection, and anyone it reaches can pass it on.
Turn the page on
- Open the project’s page and find the Public page section, near the bottom. Only admins, owners and instance administrators see it.
- Select Turn on.
The section now shows the page’s address, such as
https://nanobom.example.com/public/9b2d…41. Open it to check what visitors will see. The
address starts with NANOBOM_PUBLIC_URL (Configuration): it
must be reachable from the internet, or at least its /public/ path.
Link it from the badge
While the public page is on, the Markdown for a README field of the Badge section links the badge to the public page instead of the project page, which only members can open:
[](https://nanobom.example.com/public/9b2d…41)
Paste it in place of the old snippet. The badge and the page have separate addresses: turning the page on does not change the badge’s.
Write triage for the public
The page shows each ignored finding’s VEX justification, such as Vulnerable code not reachable, but never the reason typed with it. Choose a justification when ignoring a finding (Triage findings): an ignore without one appears as None (accepted risk).
Point scanners at the VEX document
The page links its VEX document, at the page’s address followed by /vex.json. Users whose
scanner reads CycloneDX VEX documents can give it this one to hide what the maintainers assessed
as not affecting the project.
Change or revoke the address
- New address gives the page another address; the old one stops working at once. Update the badge snippet in the README.
- Turn off removes the page; its address stops working at once, and the badge snippet links to the project page again.
Pages are cached for up to five minutes by browsers and proxies, so a page turned off may still show briefly where it was already opened. Deleting the project removes its page too.
Get notified
nanobom posts to webhooks and sends emails: new findings and stale projects to each organization’s webhook and email recipients, failed runs to the instance’s failure webhook. An organization’s webhook receives JSON documents, or messages that Slack and Microsoft Teams show in a channel. The documents, the messages, the emails, and when each is sent, are described in the webhook and email reference.
Send an organization’s new findings to a webhook
An organization’s admins configure one webhook in Settings → Webhook:
- URL: an
httporhttpsaddress; - Format: JSON document (the default), Slack message or Microsoft Teams message (Workflows); see Post to Slack and Post to Microsoft Teams;
- Minimum severity: findings below it are not sent (known exploited ones always are);
- Only known exploited vulnerabilities: send only known exploited findings, whatever their severity;
- Enabled: unchecked, nothing is sent, and deliveries waiting for a retry are abandoned.
Then Save webhook. After the next run that opens findings, Recent deliveries on the settings page lists the documents sent, newest first: the event, whether it is Sending (its first attempt is in progress), was Delivered, is Retrying (with the time of the next attempt), Failed or Cancelled (the webhook was removed, disabled or moved before an attempt was recorded), the number of attempts, and the time and answer of the last attempt (the HTTP status, or the error). Remove webhook deletes the configuration and abandons the deliveries still waiting for a retry; disabling the webhook or changing its URL abandons them too, so retries never go to the old address, and changing its format does as well, since their bodies were written for the previous one.
A receiver that is down for a while misses nothing: failed deliveries are retried after 1 minute,
10 minutes and 1 hour. A 4xx answer other than 408 and 429 is not retried, so fix the
receiver or the URL and wait for the next document. The rules are in the
webhook reference.
Requests are not signed: use an unguessable URL (most receivers put a random identifier in the
path) over https, and answer within 15 seconds. A document can arrive twice when an answer is
lost; receivers that must not act twice can remember the run’s id per event.
Post to Slack
nanobom posts to a Slack Incoming Webhook:
- Open api.slack.com/apps, choose Create New App, then
From scratch; name it
nanobomand pick your workspace. - In the app’s Incoming Webhooks page, turn Activate Incoming Webhooks on.
- Choose Add New Webhook to Workspace, pick the channel that should receive the alerts and
allow the app. Slack shows a URL like
https://hooks.slack.com/services/T0000/B0000/XXXXXXXX; copy it. Anyone with this URL can post to the channel, so keep it secret. - In nanobom, open the organization’s Settings → Webhook, paste the URL, set Format to Slack message and choose the minimum severity. Then Save webhook.
The next run that opens findings posts a message with a header (organization, number of findings, highest severity), then up to 10 findings: the vulnerability identifier linking to its page in nanobom, the component, the severity, whether it is known exploited and which direct dependency introduces it. A last line counts the findings left out and links to the organization. Messages are in English whatever the language of the interface; what they contain is in the webhook reference.
Slack answers 200 with ok. A 400 (invalid_payload, invalid_blocks) or a 404
(no_service: the webhook was revoked, or the URL is wrong) is not retried and shows as
Failed in Recent deliveries; fix the URL and wait for the next message.
Post to Microsoft Teams
The connectors that Teams used to offer for incoming webhooks were
retired
in favor of the Workflows app (Power Automate). nanobom sends what a Workflows webhook
accepts: a message carrying an Adaptive Card, not the
MessageCard format of the old connectors, which a Workflows webhook does not render.
- In Teams, open the channel that should receive the alerts, choose More options (…) next to its name, then Workflows.
- Choose the template Send webhook alerts to a channel, name the workflow and sign in the connections it asks for, then Next.
- Pick the team and the channel, then Add workflow.
- Copy the webhook URL Teams shows (it is also on the workflow’s page in Power Automate). It
is a long
https://…logic.azure.com/…address that carries its own key: keep it secret. - In nanobom, open the organization’s Settings → Webhook, paste the URL, set Format to Microsoft Teams message (Workflows) and choose the minimum severity. Then Save webhook.
The next run that opens findings posts a card with the same content as the Slack message: a title, up to 10 findings and a Open … in nanobom button. What it contains is in the webhook reference.
A Workflows webhook usually answers 202 Accepted as soon as it has received the request, before
the workflow posts the card: nanobom counts it as delivered. If cards do not show up in the
channel while Recent deliveries says Delivered, look at the workflow’s run history in
Power Automate: the workflow runs under the account of whoever created it, so it can stop working
when that account loses access to the channel.
Send them by email
Emails go through an SMTP server of yours, which the operator configures once for the instance; then each organization’s admins choose who receives its emails.
-
Set the SMTP server and the sender, then restart nanobom:
NANOBOM_SMTP_URL=smtps://nanobom%40example.org:app-password@smtp.example.org NANOBOM_SMTP_FROM="nanobom <nanobom@example.org>"smtps://connects with TLS on port 465; for a server that only offers STARTTLS on port 587, usesmtp://…:587?tls=required. nanobom refuses to start with a user or password in asmtp://URL withouttls=, which would send them in clear text. Percent-encode the user and password (@becomes%40). Most providers (Google Workspace, Microsoft 365, Amazon SES, Mailgun, Postmark…) give SMTP credentials for applications; use those rather than a person’s password. Every option is in the configuration reference. The log saysemail notifications are onat startup. -
In nanobom, open the organization’s Settings → Email notifications and fill in:
- Recipients: one address per line (or separated by commas), at most 20; a team’s mailing list is easier to keep up to date than a list of people;
- Language: English or French;
- Minimum severity and Only known exploited vulnerabilities, which work as for the webhook and independently of it.
Then Save email settings.
-
Choose Send a test email. The page says Test email sent once the SMTP server accepted it, or shows its reply, such as
permanent error (535): authentication failedfor wrong credentials, with the address it concerns. A test can be sent every 30 seconds per organization and per user, and 10 every 10 minutes on the whole instance.
The next run that opens findings emails each recipient, with a subject such as
nanobom: 3 new vulnerabilities in acme/web and the findings, each linking to its page in
nanobom. Stale projects are emailed too. What an email contains is in the
reference.
Emails show in Recent deliveries with the webhook’s, one line per recipient, marked
Email to and the address. An SMTP reply in the 4xx range (greylisting, a full mailbox) is
retried like a webhook; a 5xx reply (an unknown address, a message refused as spam) is not,
and the delivery shows as Failed with the reply. Either way, only the refused address is
concerned: the other recipients get the email.
Changing the recipients or the language abandons the emails waiting for a retry; Remove email
notifications turns email off for the organization.
If emails land in spam, make sure the sender’s domain allows your SMTP server to send for it (SPF, DKIM): nanobom does not sign messages itself.
Receive them in Home Assistant
examples/home-assistant.yaml
turns findings.new into phone notifications. Set the organization’s webhook to
https://home-assistant.example.org/api/webhook/nanobom-acme, then add the automation:
alias: nanobom new vulnerabilities
triggers:
- trigger: webhook
webhook_id: nanobom-acme
allowed_methods: [POST]
local_only: false
conditions:
- condition: template
value_template: "{{ trigger.json.event == 'findings.new' }}"
actions:
- action: notify.mobile_app_phone
data:
title: >-
{{ trigger.json.count }} new {{ trigger.json.highest_severity }}
vulnerabilities in {{ trigger.json.organization.name }}
{% if trigger.json.known_exploited_count > 0 %}
({{ trigger.json.known_exploited_count }} known exploited)
{% endif %}
message: >-
{% for finding in trigger.json.findings[:5] %}
{{ '[exploited] ' if finding.known_exploited }}{{ finding.vulnerability }} ({{ finding.severity }}) in {{ finding.component }}, {{ finding.project }}
{% endfor %}
data:
url: "{{ trigger.json.findings[0].url }}"
local_only: false is needed when nanobom is not on Home Assistant’s local network.
Forward them to another chat
For a chat nanobom does not format, keep the JSON document format and put a small receiver in
between. This one turns every event into one chat line, with Python’s standard library only;
adapt forward to your chat’s incoming webhook:
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
def describe(event):
kind = event["event"]
if kind == "findings.new":
exploited = event["known_exploited_count"]
line = (f"{event['count']} new findings in {event['organization']['name']}, "
f"highest {event['highest_severity']}")
if exploited:
line += f", {exploited} known exploited"
return line + f": {event['organization']['url']}"
if kind == "projects.stale":
names = ", ".join(project["project"] for project in event["projects"])
return f"No SBOM received lately in {event['organization']['name']}: {names}"
if kind == "run.failed":
return f"nanobom run {event['run']['id']} ({event['scope']}) failed: {event['error']}"
return f"Unknown nanobom event {kind}"
def forward(line):
print(line, flush=True) # replace with a POST to your chat
class Receiver(BaseHTTPRequestHandler):
def do_POST(self):
body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
self.send_response(204) # answer first: nanobom waits 15 seconds at most
self.end_headers()
forward(describe(json.loads(body)))
HTTPServer(("0.0.0.0", 9000), Receiver).serve_forever()
Ignore fields you do not know rather than rejecting the request: later versions may add some.
Be told about stale projects
A project is stale when no SBOM arrived for NANOBOM_STALE_AFTER_DAYS (30 by default); see
stale projects. An organization with an enabled
webhook or email recipients receives its newly stale projects as projects.stale after
scheduled runs, whatever the minimum severity and the known exploited option. Nothing else is
needed.
Choose the threshold above the longest normal gap between two builds: a library released twice a
year would be stale most of the time with the default, so either raise the threshold or upload
its SBOM from a scheduled pipeline. NANOBOM_STALE_AFTER_DAYS=0 turns the feature off.
Report failed runs to the operators
Set NANOBOM_FAILURE_WEBHOOK_URL to the operators’ webhook:
NANOBOM_FAILURE_WEBHOOK_URL=https://hooks.example.org/nanobom-ops/7f3c9a
It receives a run.failed document for every failed run of the instance, whatever its
organization. Changing or removing the variable abandons, at the next start, the run.failed
deliveries still waiting for a retry to the previous address. Since the error may name the
packages of any organization, send it to the operators, not to an organization’s channel. Pair
it with the alert rules, which also catch a schedule that
stopped running.
Set up single sign-on
nanobom signs users in with any OpenID Connect provider. Setting the issuer and the client identifier enables it; a Sign in with single sign-on button then appears on the sign-in page, next to the password form if local accounts stay on. How single sign-on users are created and matched is described in the accounts reference, and why in the security model.
1. Create the client at the provider
Create a client (also called application or relying party) for nanobom:
| Setting | Value |
|---|---|
| Type | Web application, authorization code flow |
| Redirect URI | <public URL>/auth/oidc/callback, e.g. https://nanobom.example.org/auth/oidc/callback |
| Client authentication | a client secret (confidential client), or none (public client, PKCE only) |
| Scopes | openid profile email, plus whatever your provider needs for groups |
The steps for Keycloak, Zitadel and Authentik are below.
2. Configure nanobom
NANOBOM_PUBLIC_URL=https://nanobom.example.org
NANOBOM_OIDC_ISSUER=https://id.example.org/realms/acme
NANOBOM_OIDC_CLIENT_ID=nanobom
NANOBOM_OIDC_CLIENT_SECRET=… # omit for a public client
Restart nanobom. All NANOBOM_OIDC_* options are in the
configuration reference.
- The redirect URI is built from
NANOBOM_PUBLIC_URL, so the two must agree exactly, scheme and port included: most “redirect URI mismatch” errors come from a public URL left at its default,http://localhost:8080. - nanobom reads the provider’s discovery document (
<issuer>/.well-known/openid-configuration) at the first sign-in, not at startup, so a provider that is down does not prevent nanobom from starting. The discovery request does not follow redirects: give the issuer exactly as the provider announces it.
3. Grant instance administration from the provider (optional)
NANOBOM_OIDC_ADMINISTRATOR_CLAIM=groups
NANOBOM_OIDC_ADMINISTRATOR_VALUE=nanobom-admins
A user whose claim contains the value is an instance administrator. The claim is applied at each sign-in, both ways: it also removes administration given on the Administration page from users who do not have it. See administrator claim.
To give organization roles from groups as well, see Map identity-provider groups to organizations.
4. Sign in
Sign out, then select Sign in with single sign-on. The first sign-in creates your user. If it fails, the page shows a short message and the logs say why: see Single sign-on in the troubleshooting guide.
Before inviting people, know that:
- A local account and a single sign-on identity are two different users, even with the same email address. There is no linking: if someone used a local account before single sign-on was set up, their memberships do not carry over; add the new user to the organizations, then disable the local account.
- A single sign-on user only exists after their first sign-in, so they can only be added to an organization by hand after that (group mapping avoids the wait).
- With
NANOBOM_OIDC_CREATE_USERS=false, only users who signed in before can sign in. Turn it off once everyone who should have access has an account, if the provider serves more people than nanobom should.
5. Turn local accounts off (optional)
Once single sign-on works and an administrator signs in through it (with the administrator claim,
or after an existing administrator granted it), set NANOBOM_LOCAL_ACCOUNTS=false. This removes
the password form and the password sign-in route: every user, administrators included, signs in
through the identity provider. Local accounts stay in the database and work again if the setting
is turned back on. nanobom refuses to start with local accounts off and no OpenID Connect
configured, since nobody could sign in.
Keep a way back: if the provider is down, nobody can sign in until local accounts are turned on again.
Keycloak
- In the realm, Clients → Create client: OpenID Connect, client ID
nanobom; Client authentication on, Standard flow on; Valid redirect URIshttps://nanobom.example.org/auth/oidc/callback. Copy the secret from Credentials. - For groups: Clients → nanobom → Client scopes → nanobom-dedicated → Add mapper → By
configuration → Group Membership, with token claim name
groups, Full group path off, Add to ID token and Add to userinfo on.
NANOBOM_OIDC_ISSUER=https://keycloak.example.org/realms/acme
NANOBOM_OIDC_CLIENT_ID=nanobom
NANOBOM_OIDC_CLIENT_SECRET=…
NANOBOM_OIDC_GROUPS_CLAIM=groups
NANOBOM_OIDC_GROUP_MAPPING="security=acme:admin;developers=acme:member"
NANOBOM_OIDC_ADMINISTRATOR_CLAIM=groups
NANOBOM_OIDC_ADMINISTRATOR_VALUE=nanobom-admins
To use realm roles instead of groups, set NANOBOM_OIDC_GROUPS_CLAIM=realm_access.roles, and turn
on Add to ID token (or Add to userinfo) in the realm roles mapper of the roles client
scope: by default Keycloak puts roles in the access token only, which nanobom does not read.
Zitadel
- In a project, New application → Web, authentication method Code (with a secret) or
PKCE (public client); redirect URI
https://nanobom.example.org/auth/oidc/callback. During tests over plainhttp, enable Development Mode on the application. - Create the project roles (
nanobom-admin,acme-developers, …), grant them to users, and enable Assert Roles on Authentication in the project’s settings, so the roles are part of the user information.
NANOBOM_OIDC_ISSUER=https://acme-abc123.zitadel.cloud
NANOBOM_OIDC_CLIENT_ID=289746…@nanobom
NANOBOM_OIDC_CLIENT_SECRET=…
NANOBOM_OIDC_GROUPS_CLAIM=urn:zitadel:iam:org:project:roles
NANOBOM_OIDC_GROUP_MAPPING="acme-developers=acme:member;acme-security=acme:admin"
NANOBOM_OIDC_ADMINISTRATOR_CLAIM=urn:zitadel:iam:org:project:roles
NANOBOM_OIDC_ADMINISTRATOR_VALUE=nanobom-admin
Zitadel’s roles claim is an object whose keys are the role names, which nanobom reads as the list of groups.
Authentik
- Applications → Providers → Create → OAuth2/OpenID Provider: client type Confidential,
redirect URI
https://nanobom.example.org/auth/oidc/callback(strict). - Applications → Create with slug
nanobom, using that provider.
Authentik’s default profile scope includes a groups claim listing the user’s group names.
NANOBOM_OIDC_ISSUER=https://authentik.example.org/application/o/nanobom/
NANOBOM_OIDC_CLIENT_ID=…
NANOBOM_OIDC_CLIENT_SECRET=…
NANOBOM_OIDC_GROUPS_CLAIM=groups
NANOBOM_OIDC_GROUP_MAPPING="security=acme:admin;developers=acme:member"
NANOBOM_OIDC_ADMINISTRATOR_CLAIM=groups
NANOBOM_OIDC_ADMINISTRATOR_VALUE=nanobom-admins
Authentik’s issuer ends with a slash (…/application/o/nanobom/); keep it in
NANOBOM_OIDC_ISSUER.
Other providers
- Providers that only include groups when asked need the scope:
NANOBOM_OIDC_SCOPES="openid profile email groups"(Authelia, Dex). - Microsoft Entra ID puts group object IDs in
groups, not names: use the IDs in the mapping, or emit application roles and map therolesclaim.
Map identity-provider groups to organizations
With single sign-on in place (Set up single sign-on), nanobom can give each user their organization roles from the groups (or roles) their identity provider lists, at every sign-in. Nobody then has to add members by hand, and a user who leaves a group loses its role.
1. Put the groups in a claim nanobom reads
nanobom reads claims from the ID token and from the provider’s user information endpoint, not from the access token. Configure the provider to send the user’s groups in one of them: see the steps for Keycloak, Zitadel and Authentik, and other providers.
2. Name the claim and write the mapping
NANOBOM_OIDC_GROUPS_CLAIM=groups
NANOBOM_OIDC_GROUP_MAPPING="security=acme:admin;developers=acme:member;auditors=acme:viewer;platform=infra:owner"
NANOBOM_OIDC_GROUPS_CLAIM is the claim’s name, or a dotted path into nested claims
(realm_access.roles). The mapping is a list of group=organization:role entries separated by
; or line breaks; the roles are viewer, member, admin and owner
(what each allows). The exact syntax, and how
memberships are synchronized, are in the
accounts reference.
Organizations named by the mapping are created at the first sign-in that needs them. Map at least
one group to owner in each, or only instance administrators can manage its owners.
Restart nanobom: an invalid entry stops it at startup with invalid NANOBOM_OIDC_GROUP_MAPPING,
naming the entry.
3. Check
Sign out and in again: roles are applied at sign-in. In the organization’s Settings → Members, roles that come from groups are listed apart, under From groups; they cannot be changed in nanobom.
If a role is missing, see Groups or administrator rights are not applied.
Remove someone’s access at once
A user who left a group keeps its role until their next sign-in, as long as their session lasts. To cut access at once, disable the user (Manage users).
Manage users, administrators and organizations
What each role allows, and the rules for usernames and passwords, are in the accounts reference. Users and instance administration are managed by instance administrators on the Administration page; organizations and their members by the organization’s admins and owners.
Create a local account
There is no self-registration. An instance administrator opens Administration → New local account and sets the username, an optional email address, the initial password, and whether the user is an instance administrator. The user signs in with their username or email address.
The first administrator is created on the command line, with nanobom create-administrator
(Install nanobom). Users who sign in with single
sign-on are created at their first sign-in (Set up single sign-on).
Reset a password
There is no reset by email. An instance administrator sets a new password for the user on the Administration page. Setting a new password ends all of the user’s sessions.
Disable a user
On the Administration page, an instance administrator disables the user. A disabled user cannot sign in, and their current sessions stop working at their next request. Their memberships are kept, so enabling them again restores their access. Administrators cannot disable themselves.
Grant or remove instance administration
On the Administration page, an instance administrator grants or removes instance
administration. Administrators cannot remove their own, so an instance cannot lose its last
administrator by accident. With NANOBOM_OIDC_ADMINISTRATOR_CLAIM set, the identity provider
decides at each sign-in instead, and overrides changes made here
(administrator claim).
Create an organization
Any signed-in user can create an organization from the Organizations page, under New
organization (a name and a slug), and becomes its owner. The slug appears in addresses and
upload URLs, so keep it short (acme).
With NANOBOM_PERSONAL_ORGANIZATIONS on (the default), every new user also gets a personal
organization. Turn the setting off when organizations mirror teams and personal spaces would only
clutter the list; it applies to users created afterwards.
With single sign-on, organizations can also be created by the group mapping.
Add and manage members
An organization’s admins manage members in Settings → Members:
- Add member takes the username or email address of an existing account. Users who sign in with single sign-on only exist after their first sign-in.
- Admins can give and take away the viewer, member and admin roles; granting, changing or removing an owner needs an owner.
- An organization always keeps at least one owner: removing or demoting the last one is refused.
- Any member can Leave an organization, unless they are its last owner.
Typical assignments: viewer for auditors and managers who read reports; member for the developers who triage findings; admin for whoever maintains the CI integration; owner for the people accountable for the organization.
Roles from the identity provider’s groups are listed apart, under From groups, and cannot be changed here; removing a role given in nanobom leaves the one from groups.
Rename or delete an organization
In the organization’s Settings, admins rename it; owners delete it, with its projects, findings, tokens and memberships, for good.
Run behind a reverse proxy with TLS
nanobom speaks plain HTTP. Put a reverse proxy in front of it to terminate TLS, and tell nanobom the address users reach it at:
NANOBOM_PUBLIC_URL=https://nanobom.example.org
NANOBOM_TRUST_FORWARDED_HEADERS=true
Bind nanobom to the loopback interface or a private network
(NANOBOM_LISTEN_ADDRESS=127.0.0.1:8080 on the same host),
so the proxy is the only way in. Only set NANOBOM_TRUST_FORWARDED_HEADERS when that is the case:
a client talking to nanobom directly could otherwise choose its own address and escape sign-in
rate limiting.
What the proxy must get right:
| Why | |
|---|---|
| Serve nanobom at the root of a host name | Pages and redirects use absolute paths (/login, /organizations/…); a sub-path such as https://example.org/nanobom/ is not supported. |
| The public URL matches the browser’s address bar | Form submissions whose Origin differs from NANOBOM_PUBLIC_URL are refused as cross-site (403 cross-site request refused); cookies are Secure when it is https; OpenID Connect redirects to it. |
| Request bodies of 24 MiB | Native uploads are at most NANOBOM_MAXIMUM_SBOM_SIZE (16 MiB), but Dependency-Track clients send the SBOM base64-encoded, a third larger. nginx accepts 1 MiB by default and answers 413 itself. Scale the limit with NANOBOM_MAXIMUM_SBOM_SIZE (one and a half times it). |
Responses that take up to NANOBOM_UPLOAD_WAIT_SECONDS (300 s) | Uploads with wait or fail_on hold the request until the evaluation; many proxies give up after 60 seconds with a 504. |
Client addresses in X-Forwarded-For | Sign-in rate limiting is per client address; behind a proxy, every request otherwise comes from the proxy. nanobom reads the first address of the header, so the proxy must replace the header, not append to what the client sent. |
/metrics kept internal | It needs no authentication; it reveals only instance-wide counts, but there is no reason to publish them. |
HSTS is left to the proxy: nanobom does not send it.
The examples below assume nanobom on 127.0.0.1:8080 and an internal network in 10.0.0.0/8;
adapt both. Then check the setup.
nginx
server {
listen 443 ssl;
http2 on;
server_name nanobom.example.org;
ssl_certificate /etc/letsencrypt/live/nanobom.example.org/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/nanobom.example.org/privkey.pem;
# 16 MiB SBOMs, base64-encoded by Dependency-Track clients.
client_max_body_size 24m;
proxy_set_header Host $host;
# Replaces whatever the client sent, so it cannot pick its own address.
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
location / {
proxy_pass http://127.0.0.1:8080;
}
# Uploads that wait for their evaluation (NANOBOM_UPLOAD_WAIT_SECONDS is 300 by default).
location /api/organizations/ {
proxy_pass http://127.0.0.1:8080;
proxy_read_timeout 330s;
}
location = /metrics {
allow 10.0.0.0/8;
deny all;
proxy_pass http://127.0.0.1:8080;
}
}
server {
listen 80;
server_name nanobom.example.org;
return 301 https://$host$request_uri;
}
Caddy
Caddy obtains and renews the certificate, replaces X-Forwarded-For with the client’s address,
and has no body size limit or response timeout by default:
nanobom.example.org {
@external_metrics {
path /metrics
not remote_ip 10.0.0.0/8
}
respond @external_metrics 403
reverse_proxy 127.0.0.1:8080
}
Traefik
With Docker Compose, next to a Traefik instance whose websecure entry point terminates TLS:
services:
nanobom:
image: ghcr.io/alixanneraud/nanobom:latest
restart: unless-stopped
volumes:
- nanobom-data:/data
environment:
NANOBOM_PUBLIC_URL: https://nanobom.example.org
NANOBOM_TRUST_FORWARDED_HEADERS: "true"
labels:
traefik.enable: "true"
traefik.http.routers.nanobom.rule: Host(`nanobom.example.org`)
traefik.http.routers.nanobom.entrypoints: websecure
traefik.http.routers.nanobom.tls.certresolver: letsencrypt
traefik.http.services.nanobom.loadbalancer.server.port: "8080"
# /metrics from the internal network only. The longer rule wins over the router above.
traefik.http.routers.nanobom-metrics.rule: Host(`nanobom.example.org`) && Path(`/metrics`)
traefik.http.routers.nanobom-metrics.entrypoints: websecure
traefik.http.routers.nanobom-metrics.tls.certresolver: letsencrypt
traefik.http.routers.nanobom-metrics.middlewares: nanobom-internal
traefik.http.middlewares.nanobom-internal.ipallowlist.sourcerange: 10.0.0.0/8
volumes:
nanobom-data:
No port is published: Traefik reaches the container on the Docker network. Traefik discards the
X-Forwarded-* headers of untrusted clients and sets its own, and has no body size limit by
default. Traefik 3 limits reading a request to 60 seconds by default
(respondingTimeouts.readTimeout); waiting uploads hold their request longer, so raise it on the
entry point as a precaution, in Traefik’s static configuration:
entryPoints:
websecure:
address: ":443"
transport:
respondingTimeouts:
readTimeout: 330s
Apache httpd
With the proxy, proxy_http, headers and ssl modules enabled (a2enmod proxy proxy_http headers ssl on Debian and Ubuntu):
<VirtualHost *:443>
ServerName nanobom.example.org
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/nanobom.example.org/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/nanobom.example.org/privkey.pem
ProxyPreserveHost On
# Uploads that wait for their evaluation (NANOBOM_UPLOAD_WAIT_SECONDS is 300 by default).
ProxyTimeout 330
RequestHeader set X-Forwarded-Proto "https"
# mod_proxy appends the client's address to X-Forwarded-For: drop what the client sent first.
RequestHeader unset X-Forwarded-For early
ProxyPass / http://127.0.0.1:8080/
ProxyPassReverse / http://127.0.0.1:8080/
<Location "/metrics">
Require ip 10.0.0.0/8
</Location>
</VirtualHost>
<VirtualHost *:80>
ServerName nanobom.example.org
Redirect permanent / https://nanobom.example.org/
</VirtualHost>
Apache accepts bodies of up to 1 GiB by default (LimitRequestBody).
HAProxy
crt is a PEM file holding the certificate chain and its key:
defaults
mode http
timeout connect 5s
timeout http-request 10s
# Uploads that wait for their evaluation (NANOBOM_UPLOAD_WAIT_SECONDS is 300 by default).
timeout client 330s
timeout server 330s
frontend web
bind :443 ssl crt /etc/haproxy/certs/nanobom.example.org.pem alpn h2,http/1.1
bind :80
http-request redirect scheme https code 301 unless { ssl_fc }
http-request deny deny_status 403 if { path /metrics } !{ src 10.0.0.0/8 }
# Not `option forwardfor`: it adds a header after the client's, and nanobom reads the first.
http-request set-header X-Forwarded-For %[src]
http-request set-header X-Forwarded-Proto https
default_backend nanobom
backend nanobom
server nanobom 127.0.0.1:8080 check
HAProxy sets no body size limit.
Behind a CDN or a second proxy
When requests cross another proxy first, such as Cloudflare, a cloud load balancer or a
tunnel, the address your proxy sees is that proxy’s, and the client’s comes in a header the first
proxy adds. Those headers are not safe to pass on as they are: Cloudflare, for one, appends to an
X-Forwarded-For the client sent, so its first address is whatever the client chose.
Have the last proxy, the one in front of nanobom, take the client’s address from the first proxy
only when the request comes from it, and send nanobom a single address. With nginx and
Cloudflare, add the real IP module
directives to the server block above:
# One line per range listed at https://www.cloudflare.com/ips/
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 2400:cb00::/32;
real_ip_header CF-Connecting-IP;
$remote_addr, and so X-Forwarded-For and the allow rules, are then the client’s address.
For a load balancer that appends to X-Forwarded-For, use real_ip_header X-Forwarded-For; and
real_ip_recursive on; with set_real_ip_from set to its addresses.
Do not point a tunnel or a load balancer straight at nanobom with
NANOBOM_TRUST_FORWARDED_HEADERS=true unless it replaces X-Forwarded-For: otherwise leave the
option off, and sign-in rate limiting sees every client as the tunnel.
Keep nanobom private, publish badges and public pages
Badges and public pages carry their
own key and need no session. To show them on the internet while the rest of nanobom stays on
your network, keep one host name, the one in NANOBOM_PUBLIC_URL (the links nanobom gives for
badges and pages use it), and open only their paths to everyone. With nginx, replace the
location blocks of the example above:
location / {
allow 10.0.0.0/8;
deny all;
proxy_pass http://127.0.0.1:8080;
}
location /api/organizations/ {
allow 10.0.0.0/8;
deny all;
proxy_pass http://127.0.0.1:8080;
proxy_read_timeout 330s;
}
# Open to everyone: the key in the address is the authorization.
location /badges/ {
proxy_pass http://127.0.0.1:8080;
}
location /public/ {
proxy_pass http://127.0.0.1:8080;
}
With Caddy:
nanobom.example.org {
@internal_only {
not path /badges/* /public/*
not remote_ip 10.0.0.0/8
}
respond @internal_only 403
reverse_proxy 127.0.0.1:8080
}
/metrics is then internal too. Pages and badges are self-contained: they load nothing else
from nanobom. CI runners outside your network, such as GitHub-hosted ones, also need /api/;
open it the same way, since uploads require a token.
Check the setup
From a machine outside the internal network, with your host name:
# The proxy reaches nanobom: prints {"status":"ok"}.
curl -fsS https://nanobom.example.org/healthz
# /metrics is refused: prints 403.
curl -s -o /dev/null -w '%{http_code}\n' https://nanobom.example.org/metrics
# A 20 MB body reaches nanobom: prints 401 (no token), not the proxy's 413.
head -c 20000000 /dev/zero | tr '\0' 'a' | curl -s -o /dev/null -w '%{http_code}\n' \
-X PUT -H 'Content-Type: application/json' --data-binary @- \
https://nanobom.example.org/api/v1/bom
# The client cannot choose its address: after 5 failed sign-ins, prints 429.
for i in 1 2 3 4 5 6; do
curl -s -o /dev/null -w '%{http_code} ' -H "X-Forwarded-For: 192.0.2.$i" \
-H 'Origin: https://nanobom.example.org' -d 'login=check&password=check' \
https://nanobom.example.org/auth/login
done; echo
The last command prints 303 303 303 303 303 429. Six 303 mean the proxy passes on the
address the client sent: each attempt counts against a different address, so rate limiting
does not hold. It also blocks sign-in from your address for a few seconds.
Without a proxy
For a test instance on a private network, nanobom can be reached directly on port 8080. Keep
NANOBOM_PUBLIC_URL at the address you type in the browser (http://192.168.1.20:8080):
otherwise every form submission is refused as cross-site.
Monitor with Prometheus
nanobom serves Prometheus metrics at /metrics and a health endpoint at /healthz; the metrics,
the health answers and the log messages are listed in the
metrics and logs reference.
Check health
Point your orchestrator or supervisor at GET /healthz, which answers 200 when the database
answers. The container image already checks itself with nanobom healthcheck, which requests
/healthz over loopback (the image has no shell or curl). Outside containers, the same command
works in any supervisor; --url checks another address.
The health check does not cover OSV, CISA or FIRST: an orchestrator restarting nanobom would not bring them back. Their outages show in failed runs and in the metrics.
Scrape the metrics
# prometheus.yml
scrape_configs:
- job_name: nanobom
static_configs:
- targets: ["nanobom.internal:8080"]
/metrics needs no authentication: keep it internal at the proxy
(Run behind a reverse proxy), or scrape nanobom on a private network.
Add alert rules
groups:
- name: nanobom
rules:
# Nothing has been checked against OSV for a day and a half: the nightly run failed,
# or the schedule is off. Matches any successful run, uploads included.
- alert: NanobomNoRecentSuccessfulRun
expr: time() - nanobom_last_successful_run_timestamp_seconds > 36 * 3600
for: 15m
labels:
severity: warning
annotations:
summary: "nanobom has not completed a run for {{ $value | humanizeDuration }}"
- alert: NanobomRunsFailing
expr: increase(nanobom_run_failures_total[6h]) > 0
labels:
severity: warning
annotations:
summary: "nanobom runs are failing (OSV unreachable?); findings are not up to date"
- alert: NanobomKnownExploitedFindings
expr: nanobom_open_findings_known_exploited > 0
for: 1h
labels:
severity: critical
annotations:
summary: "{{ $value }} open findings are known to be exploited in the wild"
- alert: NanobomStaleProjects
expr: nanobom_stale_projects > 0
for: 1d
labels:
severity: info
annotations:
summary: "{{ $value }} projects have not received an SBOM lately"
- alert: NanobomExploitationDataFailing
expr: increase(nanobom_exploitation_refresh_failures_total[1d]) >= 3
labels:
severity: info
annotations:
summary: "KEV or EPSS downloads keep failing; exploitation data is getting old"
- alert: NanobomDown
expr: up{job="nanobom"} == 0
for: 5m
labels:
severity: critical
Adjust the first rule to your schedule: with NANOBOM_SCHEDULE=0 */6 * * *, a few hours is enough.
On a new instance, nanobom_last_successful_run_timestamp_seconds only appears after the first
successful run.
The known exploited and stale project alerts are about the projects, not about nanobom: route them to the people who fix dependencies, or rely on the organizations’ webhooks instead.
Alert on logs
nanobom writes one JSON object per line on standard error (Docker and systemd collect both
streams, so a collector reading only standard output must read both now). If you collect logs,
alert on the messages listed in the logs reference, first of all
run failed; findings left unchanged, a stage of a run panicked; the worker continues and
database error. Webhook receivers that stay down, or an SMTP server that refuses emails, show
as a growing nanobom_webhook_deliveries_total{outcome="abandoned"} (its channel label says
which).
Back up, restore and upgrade
Everything lives in the database, the SQLite file (/data/nanobom.db in the image) or the
PostgreSQL database: users and password hashes, organizations, upload token digests,
inventories, findings and their history, sessions, and the cached OSV and exploitation data.
Back up the database and nothing else; treat the backups as sensitive.
Take a backup of SQLite
Do not copy the database file of a running instance with cp: nanobom uses SQLite’s
write-ahead log, so recent changes may still be in nanobom.db-wal and the copy can be
inconsistent. Use nanobom backup <file>, which writes a consistent copy of the live database
without stopping nanobom or blocking it. It refuses to overwrite an existing file, and the
directory must exist and be writable by the user nanobom runs as.
The image has no shell to manage files, so give it a backup directory. With Compose, add a bind mount owned by the container’s user (65532):
services:
nanobom:
volumes:
- nanobom-data:/data
- ./backups:/backups
mkdir -p backups && sudo chown 65532:65532 backups
# Daily, from cron on the host; $(date) is expanded by the host's shell.
docker compose exec -T nanobom /app/nanobom backup "/backups/nanobom-$(date +%F).db"
Then rotate and copy backups/ off the host with your usual tools. Without containers:
nanobom backup "/var/backups/nanobom/nanobom-$(date +%F).db"
A backup is an ordinary SQLite database, so it can be checked with
sqlite3 nanobom-2026-11-08.db 'PRAGMA integrity_check'.
Restore a SQLite backup
- Stop nanobom.
- Replace the database with the backup, and delete the
-waland-shmfiles next to it, which belong to the old database. - Start nanobom. If the backup comes from an older version, its migrations run at startup.
With a Docker volume, a throwaway container does the copy (the volume of a Compose project is
named after the project, here nanobom_nanobom-data):
docker compose stop nanobom
docker run --rm -v nanobom_nanobom-data:/data -v "$PWD/backups:/backups" alpine sh -c '
cp /backups/nanobom-2026-11-08.db /data/nanobom.db &&
rm -f /data/nanobom.db-wal /data/nanobom.db-shm &&
chown 65532:65532 /data/nanobom.db'
docker compose start nanobom
Sessions are in the database too, so users signed in after the backup was taken have to sign in again; uploads and runs since then are lost and come back with the next uploads and the next nightly run.
Back up and restore PostgreSQL
nanobom backup copies SQLite databases only; on PostgreSQL it stops with a message pointing to
pg_dump. pg_dump writes a consistent snapshot of the live database without stopping nanobom;
the custom format (--format=custom) is compressed and restored with pg_restore. Use a
pg_dump at least as recent as the server. With
examples/compose-postgres.yaml, from cron on the host:
docker compose -f examples/compose-postgres.yaml exec -T postgres \
pg_dump --username nanobom --format=custom nanobom > "backups/nanobom-$(date +%F).dump"
Against another server, pg_dump --format=custom --file nanobom.dump "$NANOBOM_DATABASE_URL"
does the same (pg_dump reads the URL, sslmode included). It is libpq, not nanobom, that
connects: with sslmode=verify-full and no sslrootcert, it looks for the authorities in
~/.postgresql/root.crt instead of the public ones, and fails if the file is missing. Give it
sslrootcert=/path/to/ca.pem, or sslrootcert=system on PostgreSQL 16 and later, to use the
operating system’s authorities. A managed database’s own snapshots work too.
To restore:
-
Stop nanobom.
-
Empty the database.
pg_restore --cleanonly drops the objects that are in the dump, so restoring an older dump after an upgrade would leave the tables of newer migrations behind, and the next start would fail on them. Drop the schema, or drop and recreate the database:docker compose -f examples/compose-postgres.yaml exec -T postgres \ psql --username nanobom --dbname nanobom \ --command 'DROP SCHEMA public CASCADE; CREATE SCHEMA public;' -
Restore the dump:
docker compose -f examples/compose-postgres.yaml exec -T postgres \ pg_restore --username nanobom --dbname nanobom --no-owner \ < backups/nanobom-2026-11-08.dump -
Start nanobom. If the dump comes from an older version, its migrations run at startup.
As with SQLite, sessions, uploads and runs since the dump are lost.
Upgrade
Take a backup first (nanobom backup or pg_dump): migrations only go forward, so going back
to an older version means restoring it. Then:
docker compose pull && docker compose up -d --wait
Database migrations run when the server starts, before it accepts requests. nanobom migrate
runs them alone, for a deployment that wants them as a separate step.
To check which version runs, sign in: the line at the bottom of every page names it, and links to
the About page (also in the account menu), with the release notes and when the instance last
read OSV, the KEV catalog and EPSS. From a shell, nanobom --version prints it.
Images are tagged X.Y.Z, X.Y, X and latest. Pin a tag that matches how you want to
upgrade: X.Y follows fixes only. While nanobom’s version is below 1.0, a breaking change raises
the minor version (0.3 to 0.4): read the
changelog before changing it.
On shutdown (SIGTERM), requests in progress finish; a run in progress is not resumed and stays
listed as running. The next scheduled run covers its scope again.
After an upgrade from a version without exploitation signals, the first run delivers every open
known exploited finding of its scope once to the organizations’ webhooks, with the exploited
reason, since none had been notified as such.
Run without internet access
nanobom makes outbound requests to three services: OSV during runs, and CISA and FIRST for exploitation data after runs. On an instance behind a firewall or an outbound proxy, allow them, point nanobom at mirrors, or turn exploitation data off. The settings are in the configuration reference.
| Service | Setting | Default |
|---|---|---|
| OSV | NANOBOM_OSV_URL | https://api.osv.dev/ |
| CISA KEV | NANOBOM_KEV_URL | https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json |
| FIRST EPSS | NANOBOM_EPSS_URL | https://api.first.org/data/v1/epss |
Use an OSV mirror
OSV is needed for runs: an instance that cannot reach api.osv.dev needs an OSV-compatible
mirror. Point NANOBOM_OSV_URL at it; it must offer /v1/querybatch and /v1/vulns/{id}.
NANOBOM_OSV_URL=https://osv-mirror.internal/
Use exploitation data mirrors
Point NANOBOM_KEV_URL and NANOBOM_EPSS_URL at them: the KEV mirror must serve the catalog’s
JSON as is, and the EPSS mirror must answer GET <url>?cve=CVE-…,CVE-… like FIRST’s API.
Turn exploitation data off
Without access to either service, set:
NANOBOM_EXPLOITATION_DATA=false
Nothing is downloaded, no finding becomes known exploited, and uploads with fail_on=exploited
are refused with a 422, since that gate could never fail. Data downloaded before the setting was
changed stays in the database as it was, without updates.
Check
After the next run, Recent runs on an organization page shows it as succeeded. A run that
cannot reach OSV fails and changes no finding; failed exploitation downloads are logged as
refreshing exploitation data failed and counted by
nanobom_exploitation_refresh_failures_total.
Troubleshoot
Each entry gives the symptom, its cause, and the fix. Status codes and messages of the upload API are listed in the upload API reference; log messages in the logs reference.
Uploads
Upload answers 401
a valid upload token is required in the Authorization header (Bearer): the request has no
Authorization: Bearer … header, or the token is unknown, revoked, or a project’s upload token
that was renewed since.
- Check that the CI secret is set and reaches the job. On GitHub, workflows triggered by pull
requests from forks get no secrets, so the header is
Bearerwith nothing after it. - Check the token in Settings → API tokens: its first characters, whether it is revoked, and when it was last used. A token that was never used never reached nanobom.
- A project’s upload token is shown on the project page under Upload token: compare it with the CI secret, and update the secret after each Renew. Other tokens are shown once: if in doubt, create a new one and revoke the old one.
- A token revoked while its upload waited for the evaluation also gets this answer; the SBOM was stored anyway (see waiting for the evaluation).
Upload answers 403
this token does not allow uploads to this project: a project token was used for another project
of the organization. Fix the project slug in the URL, or use the token of that project.
this token is read-only: uploads need a token with the upload scope: the token was created
with the Read only scope, for the read API. Create a token with
the Upload and read scope for CI.
Upload answers 404
not found, for one of these reasons:
- the organization slug in the URL is wrong, or the token belongs to another organization (nanobom does not say which, so as not to reveal which organizations exist);
- the token is a project token and the project does not exist, or no longer does: the slug in the URL differs from the token’s project, or the project was deleted with its tokens. Project tokens never create projects. Create the project on the organization page (New project) and use its upload token, or upload with an organization token.
Upload answers 413
The SBOM is larger than the limit. The limit may be:
- nanobom’s,
NANOBOM_MAXIMUM_SBOM_SIZE(16 MiB by default); the answer is then plain text, not JSON. Raise the limit, or split the SBOM; - the reverse proxy’s: nginx accepts 1 MiB by default and answers with an HTML page. Set
client_max_body_size(see Run behind a reverse proxy).
Very large SBOMs often list each file of an image; generators can usually list packages only.
Upload answers 422
The error field says what is wrong; the
upload API reference lists the messages. The usual
ones:
the SBOM must be a CycloneDX JSON document (…) or an SPDX JSON document- the generator’s default format, or another JSON file: ask for CycloneDX JSON or SPDX JSON explicitly (Syft:-o cyclonedx-json=sbom.jsonor-o spdx-json=sbom.json);XML SBOMs are not supported,SPDX tag-value documents are not supported,SPDX RDF documents are not supported- the same SBOM in another serialization: switch the generator to JSON (Syft-o spdxand Trivy--format spdxwrite tag-value; usespdx-json);unsupported CycloneDX version- the generator writes a version older than 1.3, or newer than 1.7;unsupported SPDX version- SPDX older than 2.2, or SPDX 3.0;the project slug must be …- the project name in the URL contains spaces, slashes or other characters.${GITHUB_REPOSITORY#*/}and$CI_PROJECT_NAMEare usually fine; a repository name with a dot at the start or with upper-case letters is folded or refused;fail_on=exploited needs exploitation data (NANOBOM_EXPLOITATION_DATA)- exploitation data is off on this instance: gate on a severity instead.
Upload answers 409
That is the gate doing its job: open findings reach fail_on. The response lists them in
evaluation.findings. Fix them by upgrading the components, or ignore the ones that do not
apply, with a reason (see Triage findings); ignored findings do not count.
With fail_on=license, components have forbidden licenses: the components are listed in
evaluation.licenses.violations. Replace them, or change the policy
(Enforce a license policy).
Upload answers 503
the evaluation did not complete, with fail_on: the run failed (evaluation.status is
failed) or did not finish in time (timed_out). The SBOM is stored; only the gate could not
decide.
failed: nanobom could not reach OSV. Look forrun failedin the logs, and check that the instance can reachhttps://api.osv.dev/.timed_out: the run took longer thanNANOBOM_UPLOAD_WAIT_SECONDS, often because it waited behind another run, such as the nightly run of a large instance. Retry, raise the setting, or move the schedule away from your busiest CI hours.
too many uploads are waiting for their evaluation, with wait or fail_on: a burst of CI jobs
reached NANOBOM_MAX_WAITING_UPLOADS. Nothing was stored: send the upload again after the
seconds of the Retry-After header, spread the jobs out, or raise the setting
(configuration).
Upload answers 502 or 504 after a minute
A reverse proxy between CI and nanobom gave up on a waiting upload (most default to 60 seconds).
nanobom still finishes the run. Raise the proxy’s read timeout above
NANOBOM_UPLOAD_WAIT_SECONDS, or lower the setting: see
Let uploads wait through your proxies.
Components without package URL
The response’s components_without_purl is not zero, and the project page says some components
cannot be checked. OSV matches components by package URL, so those are invisible to it. The
skipped list in the response names them with the reason (no package URL, or an invalid one).
The project’s Components tab lists the components that were stored, and counts those left
out.
Usually the generator could not identify them: vendored code, binaries copied into an image, packages installed outside a package manager. Use the generator of the ecosystem instead of a generic scanner where you can (see Generate an SBOM). Components that are genuinely your own code have no package URL, and need none.
A project appeared twice, or with an unexpected name
Organization tokens create a project for each new slug, so a typo or a renamed repository creates a new project. Delete the unwanted one from its page (admins), and switch the pipeline to the project’s upload token, shown on the project page, which cannot create projects.
Findings
No findings at all
Check, in order:
- Did a run happen? The organization page lists Recent runs. With
NANOBOM_RUN_AFTER_UPLOAD=false, a project waits for the nightly run or a Check now. - Did it succeed? A failed run leaves findings as they were, so a new project stays empty.
- Are the components checkable? The project page shows the component count and warns about components without package URL. Components whose package URL has no version cannot be matched.
- Does OSV cover them? OSV covers language ecosystems and several Linux distributions; it does not cover everything (some distributions, firmware, proprietary software).
An SBOM of up-to-date dependencies may simply have no known vulnerabilities.
Findings were fixed, but nothing was upgraded
Each upload replaces the project’s components: a component missing from the new SBOM fixes its
findings. Typical causes are an SBOM generated from a different directory, a partial build, a
per-crate SBOM of a workspace instead of the binary’s, or development dependencies left out where
they used to be included. Compare component_count across uploads in the project’s
Upload history.
A finding has an unexpected severity
Severity comes from the highest-rated record among the finding’s aliases, using the most recent CVSS version available. A GitHub advisory and the CVE it aliases can rate the same issue differently; nanobom shows the higher. See Severity.
No finding is known exploited
- Only CVEs are looked up: findings without a CVE among their identifiers have no exploitation data.
- Exploitation data is refreshed after successful runs; check
nanobom_exploitation_refresh_failures_totaland look forrefreshing exploitation data failedin the logs. The instance must reachwww.cisa.govandapi.first.org. NANOBOM_EXPLOITATION_DATA=falseturns it off.
A webhook does not arrive
- Settings → Recent deliveries lists the recent deliveries, their state and the last answer: an HTTP
status from your receiver, or a network error. Sending means the first attempt is in
progress; Retrying means the receiver failed and another attempt is scheduled; Failed
means it refused the document (a
4xx), every retry failed, or the webhook was removed, disabled or moved to another URL after a failed attempt; Cancelled means the webhook was removed, disabled or moved before any attempt was recorded. - The webhook must be Enabled, and findings must reach the minimum severity (or be known exploited). With Only known exploited vulnerabilities, nothing else is sent.
findings.newis only sent for new, reopened or newly exploited findings: a finding that was already open is not sent again.projects.staleis only sent after scheduled runs.- Deliveries must be answered within 15 seconds. Failed ones are retried after 1 minute, 10 minutes and 1 hour, then abandoned.
An email does not arrive
- If Settings → Email notifications says email is off, the operator has not set
NANOBOM_SMTP_URL(andNANOBOM_SMTP_FROM); see Send them by email. - Send a test email shows the SMTP server’s reply for each address it refuses:
535means the credentials inNANOBOM_SMTP_URLare wrong,550or554that a recipient or the sender is refused. A network or TLS error means nanobom cannot reach the server with the scheme and port given (smtps://uses port 465,smtp://…?tls=requiredport 587). - Recent deliveries lists one line per recipient, marked Email to and the address, with
the SMTP server’s last reply. A
5xxreply is not retried. - nanobom does not start: a
smtp://URL with a user or password needs?tls=required(or usesmtps://), so that the credentials are not sent in clear text. - An email accepted by the server (Delivered) but not in the inbox is in the hands of the mail system: look in the spam folder, and check that the sender’s domain allows the SMTP server to send for it (SPF, DKIM).
- The same filters as for webhooks apply, with the email’s own minimum severity and Only known exploited vulnerabilities.
A run failed with “the run stopped unexpectedly”
The run did not end normally: a bug made it panic (look for a stage of a run panicked in the
logs, and report it), or nanobom was stopped or crashed while it was running, in which case it
was closed at the next start. It is not resumed; the next run of the same scope does the work.
Interface
Forms answer “cross-site request refused”
The browser’s address does not match NANOBOM_PUBLIC_URL: another host name, http instead of
https, or another port. Set NANOBOM_PUBLIC_URL to the address you use, or use the address it
names.
Signing in returns to the sign-in page
The session cookie is not kept. Most often NANOBOM_PUBLIC_URL is https://… while you browse
over plain http: the cookie is then marked Secure, and the browser does not send it back.
Pages have no styles
nanobom cannot find its assets: NANOBOM_SITE_ROOT must point at the site directory of the
release. In the image, it is set to /app/site.
Sign-in answers 429
Too many failed attempts from the same address: wait a few seconds. If every user is limited at
once, nanobom sees all requests coming from the reverse proxy: set
NANOBOM_TRUST_FORWARDED_HEADERS=true, only behind a proxy that replaces X-Forwarded-For (see
Run behind a reverse proxy).
Single sign-on
The sign-in page shows a short message, and the logs say why:
| Message | Cause |
|---|---|
| The identity provider could not sign you in | Discovery failed, the provider refused the sign-in (wrong redirect URI or client secret), or its answer could not be verified; see the OpenID Connect sign-in refused or starting the OpenID Connect sign-in failed log line, and below |
| The sign-in took too long; please try again | The session cookie set when leaving for the provider was not sent back: the sign-in took longer than the session, or the public URL’s host or scheme differs from the address in the browser |
| This account is not known here and new accounts are not created automatically | NANOBOM_OIDC_CREATE_USERS=false and the user never signed in |
| This account is disabled | An instance administrator disabled the user |
The provider reports a redirect URI mismatch
The redirect URI nanobom sends is NANOBOM_PUBLIC_URL followed by auth/oidc/callback. Register
exactly that at the provider, scheme, host and port included: if NANOBOM_PUBLIC_URL was left at
its default, nanobom sends http://localhost:8080/auth/oidc/callback.
“The identity provider could not sign you in”
The logs say why (OpenID Connect sign-in refused or starting the OpenID Connect sign-in failed):
the identity provider could not be reached- nanobom cannot fetch<issuer>/.well-known/openid-configuration: wrong issuer, provider unreachable from nanobom’s network, or a redirect (anhttpissuer redirected tohttps, for example), which nanobom does not follow;unexpected issuer URI- the issuer in the discovery document differs fromNANOBOM_OIDC_ISSUER. Copy it exactly from the discovery document, including a trailing/if there is one;the identity provider refused the sign-in- usually a wrong client secret, or a client not allowed to use the authorization code flow.
Groups or administrator rights are not applied
- Roles from groups and the administrator claim are applied at sign-in: sign out and in again after changing them at the provider.
- The claim must be in the ID token or in the user information. Many providers put groups and roles in the access token only by default, which nanobom does not read; see the provider examples.
NANOBOM_OIDC_GROUPS_CLAIMmust name the claim exactly, as a top-level name or a dotted path (realm_access.roles).- Group names in
NANOBOM_OIDC_GROUP_MAPPINGmust match the claim’s values exactly; Keycloak sends/developerswith Full group path on.
An administrator lost their rights after signing in
With NANOBOM_OIDC_ADMINISTRATOR_CLAIM set, the claim decides at each sign-in, and removes rights
given in the interface from users who do not have it. Grant the claim at the provider instead.
Startup errors
| Message | Fix |
|---|---|
no sign-in method | Enable local accounts or configure OpenID Connect |
OpenID Connect needs both NANOBOM_OIDC_ISSUER and NANOBOM_OIDC_CLIENT_ID | Set both, or neither |
invalid NANOBOM_SCHEDULE | Use a five-field cron expression, or off |
invalid NANOBOM_OIDC_GROUP_MAPPING | Fix the entry named in the message: group=organization:role |
invalid value '' for '--failure-webhook-url …' (or another option) | An empty variable: remove it instead |
unable to open database file | The database’s directory does not exist or is not writable by nanobom’s user (65532 in the image) |
Develop and contribute
nanobom is a Rust workspace; how its crates fit together is described in Architecture.
Run nanobom locally
mise installs the pinned toolchain (Rust, cargo-leptos, cargo-nextest,
cargo-deny, wasm-bindgen, mdBook…) and runs the tasks. Every cargo command goes through it
(mise run … or mise exec -- cargo …), since it also sets up the target directory.
mise install
mise run dev # server with live reload on http://127.0.0.1:3000
mise run dev-admin # first administrator of the development database
mise run check # formatting, clippy, rustdoc, tests and cargo-deny, as CI
mise run test # tests only (cargo-nextest)
mise run test-postgres # tests on PostgreSQL (see below)
mise run coverage # tests with coverage, written to lcov.info
mise run build # release binary and site in target/
mise run docs # this book, in docs/book
mise run doc # the API documentation (rustdoc); broken links fail it
mise run sbom # CycloneDX SBOM of the server, in crates/server/sbom.json
mise run dev needs neither /data nor root. It runs cargo leptos watch -- serve (cargo-leptos
passes what follows -- to the nanobom binary, which requires a subcommand) with development
settings that match site-addr and site-root in Cargo.toml: a SQLite database in
target/dev/nanobom.db, the site in target/site, scheduled runs off, text logs, and
http://127.0.0.1:3000 as the public URL. The first build takes a few minutes (it compiles the
server and the browser bundle); later changes rebuild and reload the page.
Create the first administrator in that database, then sign in at http://127.0.0.1:3000/login:
mise run dev-admin # username "admin"; asks for the password
Delete target/dev/ to start over with an empty database.
To run the release build: mise run build, then
NANOBOM_SITE_ROOT=target/site target/release/nanobom serve.
Run the tests
mise run test runs every test with cargo-nextest. Tests never call real network services: OSV,
CISA, FIRST and webhooks are replaced by wiremock servers or by the
helpers of nanobom_domain::testing.
crates/domain/tests/tests the domain against a temporary database, with SBOM fixtures from real generators incrates/domain/tests/fixtures/.crates/server/tests/server/drives the HTTP server end to end (uploads, sign-in, the interface, operations);common.rsstarts a server on a fresh database.- Unit tests sit next to the code they test.
Tests use an in-memory SQLite database each. To run them on PostgreSQL, as CI also does, start an
empty database and point NANOBOM_TEST_DATABASE_URL at it; the schema is dropped and recreated
for each test, so mise run test-postgres runs them one at a time:
docker run -d --name nanobom-test-postgres -p 127.0.0.1:5432:5432 \
-e POSTGRES_USER=nanobom -e POSTGRES_PASSWORD=nanobom -e POSTGRES_DB=nanobom postgres:17-alpine
NANOBOM_TEST_DATABASE_URL=postgres://nanobom:nanobom@localhost:5432/nanobom mise run test-postgres
docker rm -f nanobom-test-postgres
Never point it at a database you care about: every test empties it.
Change the database schema
- Add a migration to
crates/migration/src/and list it inlib.rs. Never edit a migration that was released: instances have already applied it. - Regenerate the entities with
mise run entities(it applies the migrations to a temporary database and runssea-orm-cli).
Migrations run at startup, on SQLite and on PostgreSQL: write them with SeaORM’s schema builder rather than SQL of one database, keep them compatible with existing data, and run the tests on both.
Add a language
Texts of the interface are in crates/app/locales/en.json and fr.json, used through the
t!, tf! and tp! macros; messages of the domain (validation errors) are in
crates/domain/locales/. Every key must exist in every language: a missing one fails the build.
- Copy
en.jsonto<tag>.jsonin both locale directories, and translate every message (language.nameis the language’s name in itself, shown in the account menu). - Add the tag to
available_localesin theembedded_i18n::i18n!call at the root of both crates,crates/app/src/lib.rsandcrates/domain/src/lib.rs.
The upload API’s messages stay in English on purpose: they are read in CI logs.
Write documentation
This book lives in docs/ and is built with mdBook:
mise run docs builds it into docs/book/, and mise exec -- mdbook serve docs --port 3001
serves it with live reload on http://localhost:3001 (port 3000 is the development server’s).
It is published to GitHub Pages from main.
It follows Diátaxis: tutorials teach, how-to guides reach a goal, reference describes, explanation gives the why. Put each page in the part of its type, link to the reference rather than repeating a fact, and check options, defaults and messages against the code.
Contribute
- Pull request titles follow Conventional Commits
(
feat: add SPDX uploads,fix(osv): retry on timeouts); CI checks them. Pull requests are squash-merged, so the title becomes the commit onmain, from which the version bump and the changelog are derived. - Run
mise run checkbefore pushing; CI runs the same checks, plus the release build and the container image. mainis protected: changes arrive through pull requests, which merge once theCI passedandPull request titlechecks succeed.CI passedsucceeds when every CI job does, except coverage, which depends on Codecov being up.- Keep comments and documentation about what the code does not say: why, constraints, trade-offs.
Release
Releases are automated with release-plz through a release pull request; merging it tags the version, builds the archives and the images, and publishes the release. RELEASING.md describes the process and the required repository settings.
Configuration
Every option is an environment variable and a command-line flag of the same name
(NANOBOM_PUBLIC_URL is --public-url); a flag wins over the variable. nanobom <command> --help lists them with their defaults. This page lists the options of the server,
nanobom serve, and those every command reads; the options of the other commands are in the
command-line reference.
Boolean options take true or false, as variables and as flags (--run-after-upload false).
Leave an option unset rather than empty: an empty variable is a value, and an empty URL is an
invalid one, which stops nanobom at startup.
Every command
| Variable | Flag | Default | |
|---|---|---|---|
NANOBOM_DATABASE_URL | --database-url | sqlite:///data/nanobom.db | The database. SQLite: sqlite:///absolute/path.db (three slashes before an absolute path) or sqlite://relative/path.db, created if missing. PostgreSQL: postgres://user:password@host:port/database, an existing database (see below). |
NANOBOM_LOG_FORMAT | --log-format | json | json (one object per line, for collectors) or text. |
NANOBOM_LOG_LEVEL | --log-level | info | A tracing filter, such as info,nanobom=debug. On PostgreSQL, the notices the server sends at startup (“relation already exists, skipping”) are logged from WARN up, not at INFO, unless the filter mentions sqlx; a filter such as error or off is never made more verbose. |
PostgreSQL URLs
postgres://user:password@host:port/database?parameter=value&… (postgresql:// works too). The
port defaults to 5432. Characters of the user or password outside letters, digits and -._~ are
percent-encoded (@ is %40). The database must exist; nanobom creates its tables at startup,
so the role needs to own the database or to be allowed to create tables in its public schema.
nanobom opens at most 8 connections.
| Parameter | |
|---|---|
sslmode | disable, prefer (the default: TLS when the server offers it, without checking the certificate), require (TLS, certificate not checked), verify-ca (certificate checked against the trusted authorities) or verify-full (also checks that it names the host). The trusted authorities are the public ones of webpki-roots, plus sslrootcert if given. Use verify-full: with verify-ca, any server holding a certificate from a public authority passes, whatever its name. |
sslrootcert | A PEM file of authorities to trust in addition to the public ones, such as a managed database’s CA bundle. |
sslcert, sslkey | A client certificate and its key, for servers that require one. |
application_name | The name shown in pg_stat_activity. |
See Run on PostgreSQL.
Addresses and files
| Variable | Flag | Default | |
|---|---|---|---|
NANOBOM_PUBLIC_URL | --public-url | http://localhost:8080 | The address users reach nanobom at. Used for links in webhooks, emails and API responses, the OpenID Connect redirect URI, the Secure flag of cookies (set when it is https) and the cross-site request check (the Origin of form submissions must match it). Set it to the address in the browser’s address bar, scheme and port included. |
NANOBOM_LISTEN_ADDRESS | --listen-address | 0.0.0.0:8080 | Address and port to listen on. 127.0.0.1:8080 keeps nanobom reachable only through a local reverse proxy. |
NANOBOM_SITE_ROOT | --site-root | site | The directory of the web interface’s assets (the site directory of a release archive; /app/site in the image). Relative paths are relative to the working directory. |
Runs
| Variable | Flag | Default | |
|---|---|---|---|
NANOBOM_SCHEDULE | --schedule | 0 3 * * * | When every project is re-evaluated: a cron expression in UTC with five fields (minute, hour, day of month, month, day of week), or off. 0 */6 * * * runs every six hours, 30 2 * * 1-5 at 02:30 on weekdays. off turns scheduled runs off; uploads and manual checks still run. An invalid expression stops the server at startup. |
NANOBOM_RUN_AFTER_UPLOAD | --run-after-upload | true | Evaluate a project right after each upload. With false, projects are evaluated by the schedule, manual checks and uploads that wait. |
NANOBOM_UPLOAD_WAIT_SECONDS | --upload-wait-seconds | 300 | Longest time an upload with wait or fail_on waits for its evaluation. Keep it below your reverse proxy’s read timeout. |
NANOBOM_MAX_WAITING_UPLOADS | --max-waiting-uploads | 32 | Most uploads with wait or fail_on waiting for their evaluation at once; at least 1. Another one is refused with a 503 and Retry-After before anything is stored (status codes). Uploads that do not wait are not counted. Each waiting upload holds a connection open, through every proxy in between. |
NANOBOM_OSV_URL | --osv-url | https://api.osv.dev/ | The OSV API, or a compatible mirror offering /v1/querybatch and /v1/vulns/{id}. |
NANOBOM_MAXIMUM_SBOM_SIZE | --maximum-sbom-size | 16 | Largest accepted SBOM, in MiB. Parsing takes a few times this much memory. |
NANOBOM_STALE_AFTER_DAYS | --stale-after-days | 30 | Days without an SBOM after which a project is stale; 0 turns the feature off. |
NANOBOM_FAILURE_WEBHOOK_URL | --failure-webhook-url | Receives a run.failed document when a run fails. |
| Variable | Flag | Default | |
|---|---|---|---|
NANOBOM_SMTP_URL | --smtp-url | The SMTP server that sends email notifications. Unset, email is off and organizations’ email settings are hidden. smtps://user:password@smtp.example.org connects with TLS (port 465 by default); smtp://user:password@smtp.example.org:587?tls=required upgrades the connection with STARTTLS and fails without it; smtp://relay.internal:25 sends in clear text, for a relay on a trusted network only, so a smtp:// URL with a user or password must set tls=required or tls=opportunistic (STARTTLS when the server offers it); nanobom refuses to start otherwise. Percent-encode special characters of the user and password (@ as %40). Certificates are checked against the public authorities of webpki-roots. Treat it as a secret: it is not shown by --help nor logged. | |
NANOBOM_SMTP_FROM | --smtp-from | The sender of the emails, nanobom@example.org or nanobom <nanobom@example.org>. Required with NANOBOM_SMTP_URL. |
nanobom refuses to start when NANOBOM_SMTP_URL is set without NANOBOM_SMTP_FROM, when either
is invalid, or when a smtp:// URL has credentials but no tls=required or tls=opportunistic
(the error says so without repeating the URL). The SMTP server itself is contacted at the first email: send a test email from an
organization’s settings to check it. Removing NANOBOM_SMTP_URL abandons, at the next start, the
emails still waiting for a retry.
Exploitation data
| Variable | Flag | Default | |
|---|---|---|---|
NANOBOM_EXPLOITATION_DATA | --exploitation-data | true | Download exploitation data (CISA KEV, FIRST EPSS) after each run. false for instances that cannot reach them; fail_on=exploited is then refused. |
NANOBOM_KEV_URL | --kev-url | https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json | CISA’s Known Exploited Vulnerabilities catalog (JSON). A mirror must serve the catalog’s JSON as is. |
NANOBOM_EPSS_URL | --epss-url | https://api.first.org/data/v1/epss | FIRST’s EPSS API. A mirror must answer GET <url>?cve=CVE-…,CVE-… like FIRST’s API. |
Accounts and sessions
| Variable | Flag | Default | |
|---|---|---|---|
NANOBOM_LOCAL_ACCOUNTS | --local-accounts | true | Sign-in with a username or email address and a password. |
NANOBOM_PASSWORD_MINIMUM_LENGTH | --password-minimum-length | 12 | Minimum length of local passwords. |
NANOBOM_PERSONAL_ORGANIZATIONS | --personal-organizations | true | Give each new user an organization of their own; applies to users created afterwards. |
NANOBOM_SESSION_INACTIVITY_DAYS | --session-inactivity-days | 7 | Sign users out after this many days without a request (at least 1). |
NANOBOM_TRUST_FORWARDED_HEADERS | --trust-forwarded-headers | false | Read client addresses from X-Forwarded-For, X-Real-IP and Forwarded, for sign-in rate limiting. Only behind a reverse proxy that sets them. |
nanobom refuses to start when local accounts are off and OpenID Connect is not configured.
OpenID Connect
Enabled by setting both NANOBOM_OIDC_ISSUER and NANOBOM_OIDC_CLIENT_ID; setting only one stops
nanobom at startup. See Set up single sign-on.
| Variable | Flag | Default | |
|---|---|---|---|
NANOBOM_OIDC_ISSUER | --oidc-issuer | Issuer URL of the provider; its discovery document is read from it. | |
NANOBOM_OIDC_CLIENT_ID | --oidc-client-id | Client identifier. | |
NANOBOM_OIDC_CLIENT_SECRET | --oidc-client-secret | Client secret, for confidential clients; public clients rely on PKCE alone. | |
NANOBOM_OIDC_SCOPES | --oidc-scopes | openid profile email | Scopes to request, separated by spaces. |
NANOBOM_OIDC_CREATE_USERS | --oidc-create-users | true | Create users at their first sign-in. |
NANOBOM_OIDC_ADMINISTRATOR_CLAIM | --oidc-administrator-claim | Claim granting instance administration, applied at each sign-in (administrator claim). Dotted paths reach nested claims. | |
NANOBOM_OIDC_ADMINISTRATOR_VALUE | --oidc-administrator-value | Value the administrator claim must contain; without it, the claim must be true. | |
NANOBOM_OIDC_GROUPS_CLAIM | --oidc-groups-claim | Claim listing the user’s groups or roles, for the group mapping. | |
NANOBOM_OIDC_GROUP_MAPPING | --oidc-group-mapping | group=organization:role entries separated by ; or line breaks (syntax). | |
NANOBOM_OIDC_BUTTON_LABEL | --oidc-button-label | Sign in with single sign-on | Label of the sign-in button. |
Command line
nanobom [--database-url …] [--log-format …] [--log-level …] <command> [options]
Every option is also an environment variable; the options every command reads, and those of
serve, are in the configuration reference. nanobom --version prints the
version, and nanobom <command> --help lists a command’s options with their defaults.
In the container image, run commands with docker exec <container> /app/nanobom … (or
docker compose exec nanobom /app/nanobom …), which inherits the server’s
NANOBOM_DATABASE_URL. Elsewhere, run them with the same NANOBOM_DATABASE_URL as the server.
| Command | |
|---|---|
nanobom serve | Apply pending migrations, then serve the web interface and the API. |
nanobom migrate | Apply pending database migrations and exit. |
nanobom backup <destination> | Write a consistent copy of the live database to a new file. |
nanobom create-administrator | Create a local instance administrator. |
nanobom token create, list, revoke | Manage API tokens. |
nanobom project create, token | Create projects and print their upload token. |
nanobom healthcheck | Check that the running server is healthy. |
create-administrator, token and project apply pending migrations first, so they work on a
new database; backup copies the database as it is.
nanobom serve
Serves the web interface, the upload API, /healthz and /metrics, and runs the schedule.
Database migrations run at startup, before it accepts requests. On SIGTERM, requests in
progress finish; a run in progress is not resumed and stays listed as running. Options: see
Configuration.
nanobom migrate
Applies pending database migrations and exits, for a deployment that wants them as a separate step. Migrations only go forward.
nanobom backup
| Argument | Variable | |
|---|---|---|
<destination> | NANOBOM_BACKUP_DESTINATION | The file to write; it must not exist yet. |
Writes a consistent copy of the live SQLite database with SQLite’s VACUUM INTO, without
stopping the server or blocking it. It never overwrites a file; the directory must exist and be
writable by the user nanobom runs as.
On PostgreSQL it writes nothing and fails with nanobom backup copies SQLite databases only; back up this Postgres database with its own tools, pg_dump for PostgreSQL: see
Back up and restore PostgreSQL.
nanobom create-administrator
| Flag | Variable | |
|---|---|---|
--username | NANOBOM_ADMINISTRATOR_USERNAME | Required. |
--email | NANOBOM_ADMINISTRATOR_EMAIL | Optional; can then be used to sign in instead of the username. |
--password | NANOBOM_ADMINISTRATOR_PASSWORD | Read from standard input when unset, as a plain line, shown as it is typed. |
--personal-organizations | NANOBOM_PERSONAL_ORGANIZATIONS | Give the user a personal organization (default true). |
--password-minimum-length | NANOBOM_PASSWORD_MINIMUM_LENGTH | Minimum password length (default 12). |
Creates a local account that is an instance administrator, typically the first one.
nanobom token
Manages API tokens with direct access to the database, like Settings → API tokens.
| Command | Flags | |
|---|---|---|
nanobom token create | --organization (NANOBOM_TOKEN_ORGANIZATION), --name (NANOBOM_TOKEN_NAME), --project (NANOBOM_TOKEN_PROJECT, optional), --scope (NANOBOM_TOKEN_SCOPE, upload or read, default upload) | Create a token and print it. Without --project, the token covers the organization and, with the upload scope, may create projects. A read token only reads (scopes). |
nanobom token list | --organization (NANOBOM_TOKEN_ORGANIZATION) | List an organization’s tokens. |
nanobom token revoke | --id | Revoke a token, by the identifier token list prints. A project’s upload token cannot be revoked: renew it with nanobom project token --renew. |
nanobom token create --organization acme --name "web CI" --project web
nanobom token create --organization acme --name Grafana --scope read
nanobom token list --organization acme
# 8 nanobom_91d0e2 Grafana (organization) never used active read
# 7 nanobom_3f9a1c web CI web 2026-11-08T03:12:44+00:00 active upload
# 6 nanobom_c04e7b Project token web 2026-11-08T03:10:02+00:00 active upload
nanobom token revoke --id 7
token create prints the token alone on standard output, so a script can capture it:
TOKEN=$(nanobom token create --organization acme --name CI). It cannot be shown again.
token list prints one tab-separated line per token, revoked ones included: identifier, first
characters, name, project (or (organization)), last use, state, scope. The scope comes last, so
scripts written for earlier versions keep their columns. Each project’s own upload token is
named Project token.
nanobom project
Creates projects and prints their upload token, with direct access to the database.
| Command | Flags | |
|---|---|---|
nanobom project create | --organization, --project, --name (optional, the slug by default) | Create an empty project and print its upload token. A taken slug fails with the project "…" already exists. |
nanobom project token | --organization, --project, --renew | Print the project’s upload token. With --renew, replace it first: the old value stops working at once. |
TOKEN=$(nanobom project create --organization acme --project web --name "Web shop")
TOKEN=$(nanobom project token --organization acme --project web --renew)
Both print the token alone on standard output, like token create.
nanobom healthcheck
| Flag | Variable | Default | |
|---|---|---|---|
--listen-address | NANOBOM_LISTEN_ADDRESS | 0.0.0.0:8080 | The server’s listen address; its health endpoint is reached over loopback when it listens on every interface. |
--url | NANOBOM_HEALTHCHECK_URL | Health endpoint to check instead of the one derived from the listen address. | |
--timeout-seconds | 5 | Seconds to wait for an answer. |
Exits successfully when the running server answers its health endpoint, /healthz, with 200.
It is the container image’s health check, which has no shell or curl. It does not open the
database.
Upload API
Request
PUT /api/organizations/{organization}/projects/{project}/sbom
Authorization: Bearer nanobom_…
The body is the CycloneDX or SPDX JSON document, as is; the Content-Type header is not
checked, and a multipart form is not read. One request replaces the components of one
version of the project with those of the document and records the upload in the
project’s history. The project is created if it does not exist and the token allows it.
Organization and project slugs are case-insensitive (Web and web are the same project). A new
project’s slug must be 1 to 64 characters among lower-case letters, digits, ., _ and -,
starting with a letter or a digit.
The body may be at most NANOBOM_MAXIMUM_SBOM_SIZE MiB (16 by default).
Tokens
Tokens are random 256-bit values prefixed with nanobom_. Tokens authenticate on the upload API,
the VEX API and the read API, never on the interface.
A token has a reach, its organization or one project, and a scope:
| Reach | Created with | May |
|---|---|---|
| Organization token | project Whole organization in Settings → API tokens, or nanobom token create without --project | reach any project of its organization; with the upload scope, create projects by uploading to a new slug |
| Project token | a project chosen, or --project web | reach that project only; it never creates one |
| Scope | Created with | May |
|---|---|---|
upload (default) | scope Upload and read, or --scope upload | upload SBOMs, import VEX documents, and read |
read | scope Read only, or --scope read | read only, through the read API and the VEX export; uploads and VEX imports answer 403 |
The project’s upload token
Every project has one upload token of its own: a project token with the upload scope, created
with the project, whether it was created in the interface, by nanobom project create, or by an
upload with an organization token (Dependency-Track’s autoCreate included). Projects created
before nanobom had project upload tokens got one when the server was upgraded.
| The project’s upload token | Other tokens | |
|---|---|---|
| Shown | on the project page, under Upload token, at any time, and by nanobom project token | once, at creation |
| Stored | its SHA-256 digest, and its clear value | its SHA-256 digest only |
| Replaced | Renew on the project page, or nanobom project token --renew: the old value stops working at once | create a new token, then revoke the old one |
| Revoked | never, so a project always has one: the settings offer no Revoke for it, and nanobom token revoke refuses it | Revoke in Settings → API tokens, or nanobom token revoke |
| Deleted | with its project | with their project or organization |
Settings → API tokens lists it as Project token, without its value, with a link to the project instead of Revoke; a renewed token stays listed there, revoked. Its value is kept in clear so that it can be shown again: whoever can read the database can upload to the project (security model).
Who manages tokens
Tokens, the project’s upload token included, are created, renewed, revoked and seen by the
organization’s admins and owners (roles), in Settings → API
tokens, which shows each token’s project, scope and last use, on the project page, or with
nanobom token and
nanobom project. Members and viewers never see a token’s
value. Which token to give to what is discussed in Tokens and scopes.
The document
nanobom reads two formats, told apart by the document’s content, never by a header:
| Format | Recognized by | Versions | Recorded as |
|---|---|---|---|
| CycloneDX JSON | "bomFormat": "CycloneDX" | specVersion 1.3 to 1.7 | 1.6 |
| SPDX JSON | spdxVersion | SPDX-2.2 and SPDX-2.3 | SPDX-2.3 |
A document with both "bomFormat": "CycloneDX" and an spdxVersion is read as CycloneDX.
Anything else is refused with a 422 and a message naming what was sent: XML (CycloneDX XML),
SPDX tag-value, SPDX RDF (RDF/XML, Turtle, or JSON-LD with the SPDX 2 vocabulary), SPDX 3.0
JSON-LD (recognized by its @context), older or newer versions of either format
(error messages). The recorded version is shown in the project’s upload
history.
In both formats:
- Components are identified by their package URL (purl), such as
pkg:npm/lodash@4.17.20. Components with the same package URL are merged. - A component without a package URL, or with an invalid one, is skipped: it is reported in the
response (
components_without_purl,skipped) and flagged on the project page, but cannot be checked. So is a component whose package URL gives a version requirement rather than a version (pkg:npm/ava@%5E6.1.2, that is^6.1.2;2.*.*): itsreasonisversion requirement "^6.1.2" instead of a resolved version. - A component whose package URL has no version is kept in the inventory and in search results, but cannot be matched.
- Qualifiers and subpath of the package URL (
?arch=amd64&distro=debian-12) are kept for display and dropped when querying OSV. - The dependency graph is kept between the components stored. It is optional: without it, or without the project’s own dependencies in it, findings show no path (Dependency paths).
- Each component’s license is kept as one SPDX license expression (
MIT,Apache-2.0 OR MIT), read as described below for each format. It is trimmed but neither parsed nor validated, so it may hold free-text license names. A license longer than 1000 characters is dropped, and the component has no license, rather than cut into an expression that names other licenses. When several components share a package URL, the first one’s license is kept. Licenses are replaced with the components at each upload; components uploaded before nanobom read licenses have none until their project’s next upload.
CycloneDX
- Only
componentscount (nested components included). Themetadata.component, which describes the project itself, is not a component. - Components of type
fileandoperating-systemare skipped silently: they describe what was scanned, not packages. - The graph comes from
dependencies; the entry ofmetadata.componentgives the project’s direct dependencies. - The serial number (
serialNumber) is recorded with the upload. - The license comes from the component’s
licenses. Each entry gives anexpression, an SPDX license identifier (license.id) or a free-text name (license.name, kept as written). One entry gives the license. Several are joined withAND, sorted and without duplicates, with compound expressions in parentheses: anMITidentifier and aGPL-2.0-only OR BSD-3-Clauseexpression give(GPL-2.0-only OR BSD-3-Clause) AND MIT. CycloneDX does not say whether several entries are alternatives or all apply;ANDis the conservative reading, since a component is then only as permissive as its most restrictive license. Licensetext,urlandevidence.licensesare not read. - Entries of
vulnerabilitieswith ananalysis.stateare VEX statements: they are imported into the project (statements inside an SBOM). Entries without one, such as a scanner’s results, are not read.
SPDX
-
Only
packagescount;filesandsnippetsare ignored. A package’s package URL is its firstexternalRefsentry of typepurlin thePACKAGE-MANAGERcategory (PACKAGE_MANAGERin SPDX 2.2, or no category). -
A
nullor missing field counts as absent, even one SPDX requires: a package without anameis kept, a relationship missing one of its ends is ignored. -
The package the document describes (a
DESCRIBESrelationship from the document, ordocumentDescribes) is the project, not a component. -
Packages whose
primaryPackagePurposeisFILEorOPERATING-SYSTEMare skipped silently. -
The graph comes from
relationships:Relationship Edge A DEPENDS_ON BA depends on B B DEPENDENCY_OF A, andBUILD_,DEV_,OPTIONAL_,PROVIDED_,RUNTIME_,TEST_DEPENDENCY_OFA depends on B A CONTAINS B,B CONTAINED_BY A, between two packagesA depends on B CONTAINSfrom the projectnone: a scanned directory or image contains every package, direct dependency or not any other none Edges from the project are its direct dependencies, but only to packages that are also linked to another package (as a dependency or a dependent): a document whose project depends on every crate of a lock file, with no edge between crates, gives no direct dependency, and neither does a direct dependency that depends on nothing and that no other package depends on (why).
-
An
SPDXIDgiven to several packages with different package URLs (or with and without one) is ambiguous: relationships naming it are ignored. -
The license is the package’s
licenseConcluded, or itslicenseDeclaredwhenlicenseConcludedis missing,NOASSERTIONorNONE.NOASSERTIONorNONEin both means no license is known. Expressions are kept as written,LicenseRef-identifiers included. A license field that is not a string is ignored like a missing one. -
The document namespace (
documentNamespace) is recorded with the upload as its serial number.
Query parameters
| Parameter | Value | Effect |
|---|---|---|
version | 1 to 64 characters among letters, digits, ., _, +, / and - | The project version the SBOM describes; without it, the unnamed version |
latest | true or false | true makes the version the latest; false keeps a version this upload creates from becoming the latest |
source_commit | text, up to 300 characters | The commit the SBOM was built from, shown in the upload history |
image_tag | text, up to 300 characters | The container image tag the SBOM describes, shown in the upload history |
wait | true or false | Wait for the project’s evaluation and return it |
fail_on | critical, high, medium, low, exploited or license, or several separated by commas | Fail the upload when one of these thresholds is reached; implies wait |
All are optional. Empty source_commit and image_tag count as absent; control characters are
refused. version is trimmed and case-sensitive (2.4-RC1 and 2.4-rc1 are two versions); an
empty version is refused. Each fail_on value is trimmed and case-insensitive
(fail_on=high,license); wait and latest accept exactly true or false. Invalid
parameters are refused with a 422 before the body is read, so nothing is stored.
Versions
A project has one or more versions, each with its own components, findings and triage
(concepts). The version of an upload is the version
parameter only: nanobom never reads it from the SBOM (CycloneDX metadata.component.version
or SPDX versionInfo).
- Without
version, the upload goes to the unnamed version, the only version of a project that never names one. - The first upload naming a version creates it. A project created by an upload starts with the
version the upload names, without an unnamed version next to it. A project created in the
interface or with
nanobom project createstarts with an unnamed version; if it has received nothing when the first upload names a version, it is renamed to that version instead of staying next to it, empty. - One version of each project is the latest: the one the project page, the
read API and the VEX export show unless they are asked for
another. A version the upload creates becomes the latest, unless
latest=false;latest=truemakes the version uploaded to the latest, whether it is new or not. Withoutlatest, an existing version keeps its flag, andlatest=falseon an existing version changes nothing: a project always has exactly one latest version. - A new version starts with the open and ignored findings of the latest version, with their status, ignore and first-seen date. The run that follows the upload then compares them with the new SBOM, like any findings: those whose component is gone are fixed. They are never announced as new. Fixed findings are not copied (why).
- An upload to an inactive version makes it active again.
- A project has at most 50 active versions. An upload that would create the 51st, or make an inactive version active past 50, first makes the active version uploaded to the longest ago inactive (never the latest one), and proceeds (the cap). Nothing is deleted.
Versions are also made inactive, marked latest and deleted in the interface (Project versions).
The run after an upload evaluates every active version of the project; the evaluation
returned, and fail_on, judge the version uploaded only.
fail_on thresholds
fail_on | Fails (409) when an open finding is |
|---|---|
critical | critical |
high | high or critical |
medium | medium, high or critical |
low | low, medium, high or critical (anything but unknown) |
exploited | known exploited, whatever its severity |
license | not a finding: a component has a license the organization’s license policy forbids |
Ignored findings do not count. Findings of unknown severity (open.unknown) never reach a
severity threshold, not even low. exploited needs exploitation data: with
NANOBOM_EXPLOITATION_DATA=false it is refused with a 422.
With several thresholds, the upload fails when any of them is reached, and error names each
one, separated by ; (1 open finding at or above high; 3 components have forbidden licenses).
license counts only forbid verdicts: licenses the policy warns about never fail the upload,
and an organization without a policy always passes. Licenses come from the uploaded SBOM, not
from the run, so a run that fails or times out does not fail fail_on=license alone; with a
vulnerability threshold as well, it fails with 503 as before.
Waiting for the evaluation
Without wait or fail_on, the request returns as soon as the SBOM is stored, and the project
is checked in the background (unless NANOBOM_RUN_AFTER_UPLOAD is false, in which case it waits
for the next scheduled run).
With wait=true or fail_on, the request returns once a run of the project that started after
the upload has finished, and the response gets an evaluation object. Runs execute one at a
time, so a waiting upload can queue behind a long scheduled run. The wait is bounded by
NANOBOM_UPLOAD_WAIT_SECONDS (300 by default); past it, the response says timed_out and the run
still completes in the background. Waiting runs the project even when NANOBOM_RUN_AFTER_UPLOAD
is false.
At most NANOBOM_MAX_WAITING_UPLOADS uploads (32 by default) wait at once. Another upload with
wait or fail_on is refused with a 503 and a Retry-After header before its body is parsed,
so nothing is stored and it can be sent again unchanged. The body is still received first, up to
NANOBOM_MAXIMUM_SBOM_SIZE. Uploads without wait or fail_on are
not limited.
The token is checked again when the wait ends. If it was revoked or renewed meanwhile, or deleted
with its project or organization, the upload answers 401 with no evaluation, as an invalid token would,
and VEX statements in the SBOM are not imported. The SBOM, accepted while the token was valid,
stays stored.
When exploitation data is on, the run refreshes the KEV and EPSS data of the CVEs it found before
the upload is answered, so fail_on=exploited sees a vulnerability first reported by this very
run. That refresh is bounded to 60 seconds. Webhooks are sent after waiting uploads are answered.
Response
A successful upload returns 201 Created when it created the project, 200 OK otherwise:
{
"organization": "acme",
"project": "web",
"project_id": 3,
"project_created": false,
"version": "2.4",
"version_created": false,
"upload_id": 58,
"component_count": 212,
"components_without_purl": 2,
"skipped": [
{ "name": "internal-tool", "version": "1.2.0", "reason": "no package URL" },
{ "name": "vendored-lib", "version": null, "reason": "invalid package URL \"pkg:foo\": …" }
],
"evaluation": {
"status": "succeeded",
"run_id": 42,
"open": { "critical": 0, "high": 2, "medium": 5, "low": 1, "unknown": 0 },
"known_exploited": 1,
"findings": [
{
"vulnerability": "GHSA-35jh-r3h4-6jhm",
"component": "pkg:npm/lodash@4.17.20",
"severity": "high",
"known_exploited": true,
"introduced_via": ["web-framework"],
"url": "https://nanobom.example.org/findings/17"
}
],
"licenses": {
"forbidden": 1,
"warned": 2,
"violations": [
{
"component": "pkg:npm/left-pad@1.3.0",
"name": "left-pad",
"version": "1.3.0",
"license": "MIT AND GPL-3.0-only",
"verdict": "forbid",
"licenses": ["GPL-3.0-only"]
}
]
}
}
}
| Field | |
|---|---|
organization, project | The slugs, normalized to lower case |
project_id, upload_id | Identifiers in nanobom |
project_created | Whether this upload created the project |
version | The version uploaded to; "" for the unnamed version |
version_created | Whether this upload created the version (always true when it created the project) |
component_count | Distinct components stored (by package URL) |
components_without_purl | Components skipped for a missing or invalid package URL |
skipped | The first 100 of them, with name, version and reason |
evaluation | Only with wait or fail_on, see below |
vex | Only when the SBOM carries VEX statements: what importing them did, as in the VEX API |
error | Only when the upload fails, as {"error": "…"} alone or next to the fields above |
The evaluation object
| Field | |
|---|---|
status | succeeded; failed when the run could not complete (OSV unreachable, for example); timed_out when it did not finish within NANOBOM_UPLOAD_WAIT_SECONDS |
run_id | The run’s identifier, null when timed out |
open | The open findings of the version uploaded by severity (critical, high, medium, low, unknown); ignored findings are not counted |
known_exploited | How many open findings are known exploited |
findings | The open findings, most severe first, known exploited first within a severity, then by EPSS score; at most 100, so a long list drops the least severe. Each has vulnerability, component (package URL), severity, known_exploited, introduced_via and url (the finding’s page) |
findings[].introduced_via | The names of the project’s direct dependencies that lead to the component, sorted; the component’s own name when it is one; empty when the SBOM’s dependency graph does not say (Dependency paths) |
licenses | Only when the organization has an active license policy, whatever fail_on says: forbidden and warned, the number of components with each verdict, and violations, the first 20 of them, forbidden first, then by name |
licenses.violations[] | component (package URL), name, version, license (as read from the SBOM, null when it gave none), verdict (forbid or warn) and licenses, the identifiers that lead to the verdict (empty when the action for unknown licenses alone gives it) |
open and findings describe the findings of the version uploaded as they are when the
response is written; other versions of the project do not count.
After a failed or timed_out evaluation, they are the findings of the previous successful run,
not of this SBOM.
Status codes
| Status | When | What to do |
|---|---|---|
200 | The SBOM replaced the components of the version | |
201 | The SBOM created the project | |
401 | No Authorization: Bearer header, or a token that is unknown or revoked, including one revoked while the upload waited and a project’s upload token since renewed | Check the secret in CI; the response has a WWW-Authenticate: Bearer header |
403 | A project token used for another existing project, or a read token | Use that project’s slug, or an organization token; upload with a token of the upload scope |
404 | The organization does not exist or is not the token’s; or a project token used for a project that does not exist | Check the organization slug in the URL; create the project first, in the interface or with an organization token |
409 | With fail_on: the evaluation succeeded and open findings reach a threshold, or, with license, a component has a forbidden license | Fix or triage the findings listed in evaluation.findings; replace the components listed in evaluation.licenses.violations, or change the policy |
413 | The body is larger than NANOBOM_MAXIMUM_SBOM_SIZE (16 MiB by default) | Raise the limit, or split the SBOM; this error’s body is plain text, not JSON |
422 | Invalid parameter, invalid project slug, or invalid document (not JSON, neither CycloneDX nor SPDX, unsupported version) | Read error |
500 | A database error | See the server’s logs |
503 | With a fail_on threshold other than license: the evaluation failed or timed out, so the findings are not up to date | Retry later; see Troubleshoot |
503 | With wait or fail_on: NANOBOM_MAX_WAITING_UPLOADS uploads are already waiting; the response has a Retry-After header (in seconds) | Send the upload again after Retry-After; nothing was stored |
The 409 and 503 responses still stored the SBOM, except a 503 for too many waiting uploads:
the inventory is up to date even when the gate fails. So did a 401 for a token revoked while
the upload waited. A 422 for a parameter is answered before anything is stored.
Error messages
API messages are always in English, whatever the instance’s users read: they end up in CI logs.
Values of the document they quote (a version, the part of the document a parse error names) are
cut to 200 characters, followed by ….
| Status | error |
|---|---|
401 | a valid upload token is required in the Authorization header (Bearer) |
403 | this token does not allow uploads to this project |
403 | this token is read-only: uploads need a token with the upload scope |
404 | not found |
422 | wait must be true or false (or latest must be …) |
422 | the version must be 1 to 64 characters: letters, digits, '.', '_', '+', '/' or '-' |
422 | fail_on must be critical, high, medium, low, exploited or license, or several of them separated by commas |
422 | fail_on=exploited needs exploitation data (NANOBOM_EXPLOITATION_DATA): exploitation data is off on this instance, so no finding could ever be known exploited and the gate would always pass |
422 | the source commit must be at most 300 printable characters (or the image tag …) |
422 | the project slug must be 1 to 64 characters: letters, digits, '.', '_' or '-', starting with a letter or a digit |
422 | the SBOM is not valid JSON: … |
422 | XML SBOMs are not supported: generate the SBOM as CycloneDX JSON or SPDX JSON |
422 | SPDX tag-value documents are not supported: generate the SBOM as SPDX JSON (SPDX 2.2 or 2.3) or CycloneDX JSON |
422 | SPDX RDF documents are not supported: generate the SBOM as SPDX JSON (SPDX 2.2 or 2.3) or CycloneDX JSON |
422 | the SBOM must be a CycloneDX JSON document (bomFormat "CycloneDX") or an SPDX JSON document (spdxVersion "SPDX-2.3") |
422 | unsupported CycloneDX version "1.2"; supported versions are 1.3, 1.4, 1.5, 1.6, 1.7 |
422 | unsupported SPDX version "SPDX-3.0.1"; supported versions are SPDX-2.2, SPDX-2.3, in JSON |
422 | invalid CycloneDX document: … |
422 | invalid SPDX document: … |
503 | the evaluation did not complete |
503 | too many uploads are waiting for their evaluation (at most 32, NANOBOM_MAX_WAITING_UPLOADS): nothing was stored, retry later |
Dependency-Track API
nanobom also answers the upload requests of Dependency-Track’s API, for clients written for it (see Upload with Dependency-Track clients, and Dependency-Track compatibility for what the mapping implies). The document, the tokens, the size limit and the run after the upload are the same as above.
Requests
PUT /api/v1/bom JSON body, the SBOM base64-encoded in "bom"
POST /api/v1/bom multipart/form-data, the SBOM in the "bom" part
GET /api/v1/bom/token/{token} processing status of an upload
GET /api/v1/event/token/{token} same as above
X-Api-Key: nanobom_…
The upload token goes in X-Api-Key; Authorization: Bearer nanobom_… is accepted too. The
organization is the token’s.
| Field | Value | Effect |
|---|---|---|
projectName | text | The project slug: trimmed and folded to lower case, then 1 to 64 characters among letters, digits, ., _ and -, starting with a letter or a digit. Required |
projectVersion | 1 to 64 characters among letters, digits, ., _, +, / and - | The project version, like the native version; blank or missing, the unnamed version |
isLatest (form), isLatestProjectVersion (JSON) | true or false | Like the native latest: true makes the version the latest, false keeps a new version from becoming it; missing, a new version becomes the latest |
autoCreate | true or false (default) | Create the project if it does not exist (organization tokens only). Without it, a missing project is a 404 |
bom | base64 text (PUT), file or text part (POST) | The CycloneDX or SPDX JSON document. In PUT, line breaks in the base64 text are ignored. A UTF-8 byte order mark is removed. In POST, only the first bom part is read |
project | UUID | Refused with a 400 when projectName is missing; ignored otherwise |
projectTags, parentUUID, parentName, parentVersion, isActive | Accepted and ignored; an upload makes its version active whatever isActive says |
In PUT, the body is parsed as JSON whatever its Content-Type; autoCreate and
isLatestProjectVersion may be booleans or strings ("true"). In POST, autoCreate and
isLatest are true when the field reads true in any case, false otherwise.
The decoded SBOM may be at most NANOBOM_MAXIMUM_SBOM_SIZE MiB, like a native upload. The PUT
body may be larger, for the base64 encoding (a third more) and for the line breaks of wrapped
base64 (about 5% more), plus 64 KiB for the other fields. Like Dependency-Track, nanobom
requires the base64 text to be padded (=).
Response
A stored upload answers 200 OK, whether or not it created the project:
{ "token": "0b8f3c2e-5d1a-4c47-9e0b-3a6f1d2c4b5e" }
The processing status endpoints answer 200 OK with:
{ "processing": true }
processing is true from the upload until the run of the project it queued has finished,
including the refresh of exploitation data, or until NANOBOM_UPLOAD_WAIT_SECONDS have passed.
It is false for an unknown token: a finished one, one issued before the server restarted, one
of another organization, and every token when NANOBOM_RUN_AFTER_UPLOAD is false. Both
endpoints need a valid token in X-Api-Key.
Status codes
Error bodies are plain text, as Dependency-Track’s, except invalid documents, which are RFC 9457
problems (Content-Type: application/problem+json):
{ "status": 400, "title": "The uploaded BOM is invalid", "detail": "the SBOM is not valid JSON: …" }
| Status | When | Body |
|---|---|---|
200 | The SBOM replaced the components of the version | {"token": …} |
400 | No projectName (projectName is required), a project given by UUID only (nanobom cannot find projects by UUID: send projectName (the nanobom project slug) instead of project), a projectName that cannot be a slug (projectName "…" cannot be a nanobom project slug: …), a projectVersion nanobom cannot name a version with (the version must be 1 to 64 characters: …), a request that is not JSON (invalid upload request: …), bom not base64 (The BOM must be Base64 encoded), no SBOM (No BOM file provided.) | Plain text |
400 | An invalid document: any document error of the native API, XML and SPDX tag-value included | Problem |
401 | No X-Api-Key, or a token that is unknown or revoked | a valid nanobom upload token is required in the X-Api-Key header |
403 | A project token used for another existing project | Access to the specified project is forbidden |
403 | A read token | This nanobom token is read-only: uploads need a token with the upload scope. |
404 | A missing project without autoCreate, or with a project token | The project could not be found. |
409 | autoCreate and another upload created the same project first: send the upload again | the project "…" already exists |
413 | An SBOM larger than NANOBOM_MAXIMUM_SBOM_SIZE | Plain text |
500 | A database error | internal error |
The status endpoints answer 400 (the token must be a UUID) for a token that is not a UUID,
and 401 like uploads.
GitLab CI template
ci/gitlab/nanobom.yml
adds one job to a GitLab pipeline: it generates an SBOM with Syft unless one is given, uploads
it with the upload API, writes the project’s evaluation to the job log and
fails the job when it crosses a threshold. It is included from this repository, not from the
GitLab CI/CD Catalog:
include:
- remote: https://raw.githubusercontent.com/AlixANNERAUD/nanobom/vX.Y.Z/ci/gitlab/nanobom.yml
inputs:
organization: acme
The template is in releases from v0.1.0 on: an older tag answers 404.
How to use it is in Upload from CI.
Inputs
Only organization is required. Inputs are text: quote true and false (wait: "false").
A value may refer to CI/CD variables (version: $CI_COMMIT_REF_NAME), which are expanded when
the job runs.
| Input | Default | |
|---|---|---|
url | $NANOBOM_URL | Address of the nanobom instance, such as https://nanobom.example.org |
organization | Slug of the organization | |
project | $CI_PROJECT_NAME | Slug of the project; created by the first upload when the token covers the organization |
sbom | Path of an existing CycloneDX or SPDX JSON SBOM; empty, Syft generates one | |
scan-path | . | Directory Syft scans when sbom is empty |
scan-image | Container image Syft scans instead of scan-path when sbom is empty | |
fail-on | critical, high, medium, low, exploited or license, or several separated by commas (high,license): the upload’s fail_on. Implies wait | |
wait | "true" | "true" or "false": wait for the evaluation and report it |
version | The project version the SBOM describes; empty, the unnamed version | |
latest | "true", "false" or empty: the upload’s latest parameter | |
source-commit | $CI_COMMIT_SHA | Commit the SBOM was built from, shown in the upload history |
image-tag | $CI_COMMIT_TAG | Container image tag the SBOM describes, shown in the upload history; empty outside tag pipelines |
stage | test | Stage of the job |
job-name | nanobom | Name of the job |
image | alpine:3.24 | Image of the job |
fail-on is trimmed and folded to lower case before it is sent. wait and latest are checked
before anything is uploaded.
Variables
| Variable | |
|---|---|
NANOBOM_TOKEN | Required. An upload token; define it under Settings → CI/CD → Variables, masked. It is never an input, since inputs are visible in the pipeline configuration |
NANOBOM_URL | Read through the default of url only |
CI_REGISTRY, CI_REGISTRY_USER, CI_REGISTRY_PASSWORD | Set by GitLab. When scan-image is in the project’s registry (it starts with $CI_REGISTRY/) and SYFT_REGISTRY_AUTH_AUTHORITY is not set, Syft logs in with them |
SYFT_* | Read by Syft, such as SYFT_REGISTRY_AUTH_AUTHORITY, SYFT_REGISTRY_AUTH_USERNAME and SYFT_REGISTRY_AUTH_PASSWORD for another registry |
The job passes its inputs to its script as variables named NANOBOM_INPUT_*; a project or
group variable with one of these names would override the input.
The job
| Name | The job-name input |
| Stage | The stage input |
| Image | The image input, with an empty entrypoint |
| Rules, needs | None: the job runs in every pipeline, after the jobs of earlier stages |
| Artifacts | The dotenv report nanobom.env, kept even when the job fails |
Override or add keys in a job of the same name, or in a job that extends it. The template
does not set rules, needs, dependencies, tags or interruptible.
The image needs a POSIX shell, and curl and jq or apk to install them; the default
Alpine image installs them at each run. When sbom is empty and syft is not on the PATH,
the job downloads Syft 1.57.0 for x86_64 or aarch64 from its GitHub release and checks it
against a SHA-256 digest written in the template; another architecture needs an image with
syft.
Outputs
The dotenv report gives these variables to the jobs of later stages, as GitLab does with every
artifact unless needs or dependencies limit which jobs a job downloads from. A value nanobom
did not return is left out: without wait, there is no evaluation, and without a
license policy, no license counts. Every copy of the template writes the same
names, so a job that downloads the reports of two copies gets the values of only one: limit it
with needs or dependencies to the job it reads. Values are checked before they are written
(numbers, a known status, a URL on one line), so a server cannot add other variables.
| Variable | |
|---|---|
NANOBOM_HTTP_STATUS | HTTP status of the upload |
NANOBOM_PROJECT_URL | The project’s page in nanobom |
NANOBOM_EVALUATION_STATUS | succeeded, failed or timed_out |
NANOBOM_CRITICAL, NANOBOM_HIGH, NANOBOM_MEDIUM, NANOBOM_LOW | Open findings of the version uploaded, by severity |
NANOBOM_KNOWN_EXPLOITED | Open findings known to be exploited |
NANOBOM_FORBIDDEN_LICENSES, NANOBOM_WARNED_LICENSES | Components whose license the policy forbids, or warns about |
Job log
- The Syft run, in a collapsed section.
- The upload: components stored, HTTP status, project page, and a warning for components without a package URL.
- With an evaluation, a section with its status, the open findings per severity and known exploited, the first 25 findings (severity, vulnerability, component, known exploited, page) and, with a license policy, the counts and the first 25 components it forbids or warns about.
- When the gate fails, the findings and forbidden licenses over the threshold, at most 25 of
each, then the server’s
error.
Exit status
| Upload answer | Job |
|---|---|
200, 201 | Succeeds |
409: a fail-on threshold is crossed | Fails |
503: with a severity or exploited threshold, the evaluation failed or timed out; or too many uploads are waiting | Fails |
401, 403, 404, 413, 422, any other status, or no answer | Fails, with the reason |
The job also fails before uploading on an empty url, organization or project, a missing
NANOBOM_TOKEN, an invalid wait or latest, a missing SBOM file, or when Syft cannot
generate the SBOM. Like nanobom-action,
curl sends the upload again up to twice after a 503 or a connection error, which uploads the
SBOM again.
Project versions
What a project version is and why is explained in
Concepts; how to use them, in
Track several versions of a product. Uploads name versions with
the upload API’s version and latest parameters.
States
Every version of a project has two flags:
| Flag | |
|---|---|
| latest | Exactly one version of a project is the latest: the one the project page, the read API and the VEX export show when they are not asked for another, and the one a new version inherits its findings from |
| active | Whether runs evaluate the version. A new version is active. The latest version is always active |
An inactive version is kept as it was when it was made inactive:
| Active version | Inactive version | |
|---|---|---|
| Evaluated by runs (findings opened, fixed, reopened; ignores expire) | ✓ | |
| Counted on the organization page and in the projects of the read API | ✓ | |
Counted in the metrics (nanobom_open_findings, nanobom_open_findings_known_exploited) | ✓ | |
| Found by component searches | ✓ | With Include inactive versions (interface) or inactive=true (read API) |
Listed in a finding’s Also affected (affected_components) | ✓ | |
Notified: findings.new, known exploited, emails | ✓ | |
Shown on the project page (Version filter, Versions table) and in /versions | ✓ | ✓, marked inactive |
| Readable: findings, components, license violations, finding pages, VEX export | ✓ | ✓ |
Listed in a finding’s Versions of this project (versions) | ✓ | ✓, marked inactive |
Staleness stays per project: an inactive version does not make its project stale.
Changes
| Change | How | Refused when |
|---|---|---|
| Make a version inactive | Make inactive in the project page’s Versions table | It is the latest: mark another version latest first |
| Make a version active again | Make active, or any upload to the version | Through the interface only: the project already has 50 active versions (an upload makes room instead, see the cap) |
| Mark a version latest | Make latest, or an upload with latest=true; an upload creating a version also makes it the latest unless latest=false | It is inactive: make it active first (an upload with latest=true makes it active) |
| Delete a version | Delete, then tick the confirmation box and select Delete version | It is the latest, or the project’s only version: delete the project instead |
Changing versions takes the permission to delete projects: admins and owners (roles); viewers and members see the Versions table without its actions. There is no API to change versions besides uploads. A version made active in the interface is checked at once by a run of its project; otherwise the next run catches up. A run evaluates the versions active when it starts: a version made active, or created by an upload, while a run is in progress waits for the next run, and keeps its findings as they are until then.
Deleting a version deletes its components, dependency graph, upload history and findings with their history, in one transaction. Other versions keep theirs, including findings they inherited from the deleted one. Nothing else deletes a version, except deleting its project.
The error messages:
| Refusal | Message |
|---|---|
| Making the latest version inactive | the latest version cannot be made inactive: mark another version latest first |
| Marking an inactive version latest | an inactive version cannot be the latest: make it active first |
| Deleting the latest version | the latest version cannot be deleted: mark another version latest first |
| Deleting the only version | a project keeps at least one version: delete the project instead |
| Making a version active past the cap | this project already has 50 active versions: make one inactive first |
The cap
A project has at most 50 active versions. When an upload would create a version, or make an inactive one active again, while the project already has 50, nanobom first makes one other version inactive, in the upload’s transaction, and the upload proceeds:
- the active version whose last upload is the oldest goes, a version never uploaded to counting from its creation;
- never the latest version, nor the version uploaded to;
- the server logs it (
version made inactive: the project reached its maximum of active versions, with the project and the version).
Inactive versions are never deleted automatically: a project that receives a new version name with every build keeps every build, the last 50 of them active.
Components of a version
The components page lists what the latest SBOM of a project version holds, vulnerable or not: to check that an SBOM arrived complete, read a component’s license, or confirm that a dependency is there. The steps are in Check what nanobom received.
Address
The Components tab of the project page opens
/organizations/{organization}/projects/{project}/components, for the version the page shows.
Any member of the organization can open it, as for the project page; another organization’s
project, or an unknown version, is a 404.
| Query parameter | Meaning | Default |
|---|---|---|
version | The name of a project version; an empty version= names the unnamed version | The latest version |
name | Only components whose name contains this text, namespace included, ignoring case (% and _ match themselves) | Every name |
show | open: components with at least one open finding (ignored and fixed ones do not count). unlicensed: components whose SBOM entry gives no license | Every component |
page | The page, from 1 | 1 |
The filter form and the page links keep the version and the filters; filtering goes back to the first page.
What it shows
Above the table: the number of components of the version, the components of its latest upload that had no package URL (not stored, so not listed, see Components without package URL), and how many components match the filters when there are any.
| Column | Content |
|---|---|
| Component | The name, with its namespace (org.apache.logging.log4j/log4j-core), and the package URL |
| Version | The package URL’s version |
| Ecosystem | The package URL type: npm, cargo, maven… |
| License | The license expression of the SBOM, or None declared |
| Open findings | The severity of the worst open finding and their number, linking to the finding when there is one, to the version’s findings otherwise; None without open findings |
| Dependency | Direct when the SBOM lists it among the project’s own dependencies, Transitive otherwise, Not known when the SBOM does not say which components the project depends on directly (see Dependency paths) |
Components with open findings come first, the most severe first, then every component by name and version. A page holds 100 components; asking for a page past the last shows the last.
When some links of the SBOM’s dependency graph could not be followed (components without a package URL, or a reference shared by several packages), the page says so: a direct dependency whose link was lost shows as Transitive.
The read API’s /components returns the same components as JSON, by package URL,
without these filters.
VEX API
nanobom exports the findings of a project version as a CycloneDX VEX document and imports VEX statements into a project version. Why and when to use them is explained in VEX; the steps are in Exchange VEX statements.
Endpoints
GET /api/organizations/{organization}/projects/{project}/vex
PUT /api/organizations/{organization}/projects/{project}/vex
| Method | Authentication | Does |
|---|---|---|
GET | A token of either scope, in Authorization: Bearer nanobom_… or X-Api-Key, or the session of a signed-in member (any role), as on the read API | Returns the findings of a project version as a CycloneDX 1.6 JSON document |
PUT | Authorization: Bearer nanobom_… only, with a token of the upload scope | Applies the statements of a CycloneDX VEX document to the open findings of a project version |
Both take version, the name of a project version
(?version=2.4; an empty version= names the unnamed version). Without it, they work on the
latest version. An unknown version is a 404. Statements imported into one version change
nothing in the others: each version keeps its own triage.
A token reaches its organization’s projects, or its own project for a project token. Any other project, like a missing one, is a 404:
unlike uploads, these endpoints never create a project.
Slugs are case-insensitive. The body of a PUT may be at most NANOBOM_MAXIMUM_SBOM_SIZE MiB
(16 by default). The Export VEX button of the project page links to the GET endpoint, for
the version the page shows.
Export
The response is 200 with Content-Type: application/vnd.cyclonedx+json and
Content-Disposition: attachment; filename="{organization}-{project}.vex.cdx.json", or
{organization}-{project}-{version}.vex.cdx.json for a named version, with its / replaced by
-. Like
every read API response, it is Cache-Control: private, no-cache and
varies on Cookie, Authorization and X-Api-Key.
| Part of the document | Content |
|---|---|
specVersion | 1.6 |
serialNumber | A new random urn:uuid: at each export |
metadata.timestamp | The time of the export, UTC |
metadata.tools.components | nanobom and its version |
metadata.component | The project: its name, bom-ref {organization}/{project}, and the version name in version (absent for the unnamed version) |
components | Each component that has a finding, with bom-ref and purl set to its package URL |
vulnerabilities | One entry per finding, open, ignored or fixed, sorted by identifier then package URL |
Each entry of vulnerabilities:
| Field | Content |
|---|---|
id | The finding’s vulnerability identifier (GHSA-…, CVE-…, RUSTSEC-…) |
source | Where the identifier is published: NVD for CVE-, GitHub Advisories for GHSA-, OSV otherwise, with the URL of the record |
references | The aliases, each with its source |
ratings | The severity, with the CVSS score, method (CVSSv2, CVSSv3, CVSSv31, CVSSv4) and vector when known |
description | The OSV summary |
published, updated | The OSV record’s dates |
analysis | See the mapping below; firstIssued is when the finding was first seen, lastUpdated its latest change |
affects | [{"ref": "<package URL>"}], a bom-ref of components |
Mapping of findings
| Finding | analysis.state | analysis.justification | analysis.detail |
|---|---|---|---|
| Open | in_triage | ||
| Ignored with a justification | not_affected | The justification | The reason |
| Ignored as False positive | false_positive | The reason | |
| Ignored without a justification | in_triage | The reason | |
| Fixed | resolved |
The justifications are those of CycloneDX:
| Value | In the interface |
|---|---|
code_not_present | Vulnerable code not present |
code_not_reachable | Vulnerable code not reachable |
requires_configuration | Requires a configuration not in use |
requires_dependency | Requires a dependency not present |
requires_environment | Requires an environment not present |
protected_by_compiler | Protected by the compiler |
protected_at_runtime | Protected at runtime |
protected_at_perimeter | Protected at the perimeter |
protected_by_mitigating_control | Protected by a mitigating control |
False positive is offered in the same list. It is not a CycloneDX justification but the
false_positive state, which takes none.
Import
The body is a CycloneDX JSON document, specification 1.4 to 1.7 (earlier versions have no
vulnerabilities). Only vulnerabilities and the bom-refs of components and
metadata.component are read; an entry without analysis.state is not a statement and is left
out.
Which findings a statement covers
A statement covers a finding of the project version when both hold:
- Vulnerability: its
id, or theidof one of itsreferences, equals the finding’s identifier or one of its aliases, ignoring case. A statement aboutCVE-2021-23337covers a finding filed asGHSA-35jh-r3h4-6jhmwith that alias. - Component: one of its
affects[].refresolves to the finding’s package URL, compared without qualifiers and subpath. A reference resolves when it is thebom-refof a component of the same document with apurl, or is a package URL itself. A BOM-Link (urn:cdx:{serial}/{version}#{ref}) is read the same way from its fragment, percent-decoded.
A package URL without a version covers nothing: it would cover every version of the package.
affects[].versions is not read.
What it does
analysis.state | Effect on covered findings |
|---|---|
not_affected | Open findings are ignored, with analysis.justification (if it is one of the values above) |
false_positive | Open findings are ignored, as False positive |
resolved, resolved_with_pedigree, exploitable, in_triage | None; reported as informational |
An ignore made by an import:
- has
analysis.detailas its reason, cut to 2,000 characters; without a detail, the reason isVEX statement: not_affected (code_not_reachable)orVEX statement: false_positive; - has no expiry;
- is recorded in the finding’s history as made by the upload token, by name.
Ignored and fixed findings are left as they are, so importing the same document again changes nothing. The whole import is one transaction.
Response
200 with what was done:
{
"statements": 3,
"ignored": 1,
"already_ignored": 1,
"skipped": 1,
"results": [
{
"vulnerability": "CVE-2021-23337",
"component": "pkg:npm/lodash@4.17.20",
"state": "not_affected",
"result": "ignored",
"findings": [17]
}
]
}
| Field | |
|---|---|
statements | Statements read (entries with an analysis.state) |
ignored | Findings this import ignored |
already_ignored | Covered findings that were already ignored |
skipped | Statement targets that changed nothing, for any result below except ignored and already_ignored |
results | One entry per target (affects[].ref) of each statement, the first 500 |
results[].vulnerability | The statement’s id (or its first reference’s) |
results[].component | The affects[].ref as written; null when affects is empty |
results[].findings | The identifiers of the findings covered |
result | Meaning |
|---|---|
ignored | Open findings were ignored |
already_ignored | The covered findings were already ignored |
no_matching_finding | No open or ignored finding of the project version is covered |
informational | The state does not ignore findings |
unresolved_reference | The reference is neither a bom-ref of the document nor a package URL |
no_version | The package URL has no version |
no_target | affects is empty |
Statements inside an SBOM
An SBOM sent to the upload API may carry statements in its own
vulnerabilities, and they are imported like a VEX document, with the upload’s token, into the
version the upload went to. The response then has a vex object, shaped like the import
response above.
- With
waitorfail_on, they are imported after the evaluation and before the gate: they also cover the findings this upload’s run opened, andfail_ondoes not count what they ignore. - Without, they are imported at once, so they cover only findings of earlier runs; findings the coming run opens are covered by the next upload with the same statements.
The Dependency-Track API does not read them.
Status codes and errors
Errors are English JSON, {"error": "…"}.
| Status | When |
|---|---|
200 | Exported, or imported |
401 | GET: neither a valid token nor a session; PUT: no valid token. The response has a WWW-Authenticate: Bearer header |
403 | PUT with a read token |
404 | The organization, project or version does not exist, or the token or member does not reach it |
413 | The body is larger than NANOBOM_MAXIMUM_SBOM_SIZE |
422 | Invalid document |
500 | A database error |
| Status | error |
|---|---|
401 | a valid upload token is required in the Authorization header (Bearer) |
401 | sign in, or send a token in the Authorization header (Bearer) or in X-Api-Key (GET without either) |
403 | this token is read-only: uploads need a token with the upload scope |
404 | not found |
422 | the VEX document is not valid JSON: … |
422 | the VEX document must be a CycloneDX JSON document (bomFormat "CycloneDX") |
422 | unsupported CycloneDX version "1.3" for a VEX document; supported versions are 1.4, 1.5, 1.6, 1.7 |
422 | invalid CycloneDX VEX document: … |
Read API
The read API returns what nanobom knows as JSON: organizations, projects, findings, components, runs and license policies. It changes nothing. Scripts, dashboards and other tools use it instead of the interface. An example is in Export findings to a spreadsheet; which token to give a tool is explained in Tokens and scopes.
The API is described in OpenAPI 3.1 at /api/openapi.json on every instance, without
authentication. Load it in an OpenAPI viewer or a client generator.
Endpoints
Every endpoint is a GET.
| Path | Returns | Paginated |
|---|---|---|
/api/organizations | The organizations the caller sees, by name | |
/api/organizations/{organization}/projects | The organization’s projects, by slug, with their open findings by severity | |
/api/organizations/{organization}/projects/{project}/versions | The project’s versions, newest first | |
/api/organizations/{organization}/projects/{project}/findings | The findings of a project version, filtered, in the project page’s order | ✓ |
/api/organizations/{organization}/projects/{project}/components | The components of a project version from its latest SBOM, by package URL | ✓ |
/api/organizations/{organization}/runs | The latest runs that covered the organization, newest first | |
/api/findings/{finding} | One finding with its vulnerability, history and dependency paths | |
/api/components?q={name}&license={license} | Components by name, license or both across the active versions of the projects the caller sees | |
/api/organizations/{organization}/license-policy | The organization’s license policy | |
/api/organizations/{organization}/projects/{project}/license-violations | The components of a project version whose license the policy forbids or warns about, forbidden first | ✓ |
/api/openapi.json | The OpenAPI description |
Slugs are case-insensitive. A project’s findings as a CycloneDX VEX document come from the VEX API, and its vulnerability report as HTML, with the same authentication.
Versions
Findings, components and license violations belong to one version
of a project. Their endpoints take version, the version’s name (case-sensitive); without it,
they return the latest version. An empty version= names the unnamed version, the one
uploads without a version go to. An unknown version is 404, like an unknown project.
GET /api/organizations/{organization}/projects/{project}/findings?version=2.4
/versions lists them, newest first, inactive ones included:
{
"items": [
{
"name": "2.4",
"latest": true,
"active": true,
"created_at": "2026-11-09T08:12:40Z",
"last_upload_at": "2026-11-09T08:12:40Z",
"open": {"critical": 0, "high": 1, "medium": 2, "low": 0, "unknown": 0}
},
{
"name": "",
"latest": false,
"active": true,
"created_at": "2026-10-02T14:03:11Z",
"last_upload_at": "2026-11-08T03:00:12Z",
"open": {"critical": 0, "high": 1, "medium": 3, "low": 1, "unknown": 0}
}
]
}
| Field | |
|---|---|
name | The version name; "" for the unnamed version |
latest | Whether it is the latest version, the one read when a request names none; exactly one version of a project is |
active | Whether runs evaluate it; an inactive version is not counted, searched or notified, and stays readable (states) |
last_upload_at | The version’s latest upload; null before the first |
open | The version’s open findings by severity |
Authentication
| Caller | Sends | Reads |
|---|---|---|
A token of either scope, read or upload | Authorization: Bearer nanobom_…, or X-Api-Key: nanobom_… as on the Dependency-Track API | Its organization, as a viewer; a project token, its project only |
| A signed-in user | The session cookie of the interface | What the interface shows them: every organization they belong to, with their role |
When a request carries Authorization or X-Api-Key, the token decides, even if it is invalid
and a session cookie comes along: the request is then 401.
A project token sees, of its organization:
- the project in
/projects, and only that project’s findings and components; - in a finding’s
affected_components, no other project; - in
/runs, whole-instance runs and the runs of its project, not the runs of the whole organization (their counts cover the other projects).
Anything out of the caller’s reach answers 404, exactly like something that does not exist.
Pagination
Findings, components and license violations are paginated with limit and offset:
| Parameter | Default | |
|---|---|---|
limit | 100 | Items per page, from 1 to 500 |
offset | 0 | Items to skip |
A page is an object:
{"items": [], "total": 42, "limit": 100, "offset": 0}
total counts the whole list. Fetch pages until offset + limit reaches total. The list is
computed at each request: a run between two requests can move findings from one page to the
next.
Lists that are not paginated are {"items": […]}. /runs takes a limit from 1 to 100,
20 by default, and has no offset: it is refused with 422 rather than ignored.
/api/components returns at most 200 components, by name then version, and adds
"truncated": true when more matched: make the search narrower (a longer name, or a version
prefix such as lodash@4.17).
Findings
GET /api/organizations/{organization}/projects/{project}/findings?status=open&severity=critical,high
| Parameter | Values | Default |
|---|---|---|
status | all, or a comma-separated list of open, ignored, fixed | open,ignored, as on the project page |
severity | A comma-separated list of critical, high, medium, low, unknown | Any |
exploited | true: only findings with a CVE in the CISA KEV catalog | false |
ecosystem | The package URL type: npm, cargo, pypi… | Any |
version | A version name | The latest version |
The order is the project page’s: known exploited first, then by severity, EPSS score, CVSS score, component name and vulnerability (Prioritization).
A finding:
{
"id": 17,
"project": "web",
"version": "2.4",
"vulnerability_id": "GHSA-35jh-r3h4-6jhm",
"aliases": ["CVE-2021-23337"],
"summary": "Command Injection in lodash",
"component": {
"purl": "pkg:npm/lodash@4.17.20",
"name": "lodash",
"version": "4.17.20",
"ecosystem": "npm",
"license": "MIT"
},
"severity": "high",
"cvss_score": 7.2,
"status": "ignored",
"exploitation": {
"known_exploited": true,
"kev_date_added": "2021-11-03",
"kev_due_date": null,
"kev_ransomware": false,
"epss_score": 0.5,
"epss_percentile": 0.9,
"epss_date": "2024-01-01"
},
"introduced_via": [
{"purl": "pkg:npm/express@4.17.1", "name": "express", "version": "4.17.1"}
],
"first_seen_at": "2026-11-08T03:00:12Z",
"last_seen_at": "2026-11-08T03:00:12Z",
"fixed_at": null,
"ignore": {
"reason": "template() is never called",
"justification": "code_not_reachable",
"expires_at": null
},
"url": "https://nanobom.example.com/findings/17"
}
| Field | |
|---|---|
version | The project version the finding belongs to; "" for the unnamed version |
component.license | The component’s license in the latest SBOM; null when it is not in it any more (components) |
severity | The highest among the vulnerability’s aliases at the latest run that reported it |
exploitation | Aggregated over the finding’s CVEs; empty values when nothing is known, which is not the same as “not exploited” for a finding without a CVE |
introduced_via | The project’s direct dependencies that lead to the component; empty when the SBOM’s dependency graph does not say (Dependency paths) |
ignore | Set while the finding is ignored, null otherwise. justification is one of the VEX justifications or false_positive |
url | The finding’s page in the interface, built from NANOBOM_PUBLIC_URL |
One finding
GET /api/findings/{finding} takes the id of a finding. It returns every field of a finding
in a list, plus:
| Field | |
|---|---|
organization | The organization’s slug |
details | The advisory’s description, in Markdown |
published, modified | The advisory’s dates |
cvss_version, cvss_vector | The CVSS vector the score comes from |
fixed_versions | Versions of the package that fix the vulnerability, per the OSV record |
references | The advisory’s links: {"type": "ADVISORY", "url": "…"} |
ignored_by, ignored_by_token | The member, or the token of a VEX import, that ignored the finding, while it is ignored |
events | The history, oldest first: kind (opened, fixed, reopened, ignored, restored, ignore_expired, inherited), created_at, user or token, reason, justification, run_id. An inherited event starts the history of a finding copied into a new version: its reason is the name of the version it was copied from ("" for the unnamed version), and token the token of the upload that created the version |
dependency_paths | {"paths": [[…]], "more": 0, "partial": false}, each path from a direct dependency to the component; null when the SBOM does not say which components are direct dependencies |
affected_components | The same vulnerability in the active versions of the projects the caller sees, other findings of the finding’s own project included: finding_id, organization, project, version (the project version, "" for the unnamed one), purl, status |
versions | Every version of the finding’s project, newest first, inactive ones included, with where it stands with the vulnerability or any of its aliases: name, latest, active, current (the finding’s own version), status and finding_id. status is open when one of the version’s findings for the vulnerability is open, else ignored when one is ignored, else fixed; not_affected when the version never had one, with a null finding_id. finding_id is the finding that decides the status, the one of the same component when there is one |
Projects, components, runs and search
A project:
| Field | |
|---|---|
slug, name | |
last_upload_at | The latest upload; null before the first |
stale | No SBOM for longer than NANOBOM_STALE_AFTER_DAYS |
open | Open issues by severity: critical, high, medium, low, unknown |
ignored | Ignored issues |
known_exploited | Open issues with a CVE in the CISA KEV catalog |
The counts cover the project’s active versions, by issue: a vulnerability of a package
counts once, at its highest severity, however many versions (or versions of the package) have
it. An issue is open when it is open in any version, ignored when it is ignored in every version
that has it open or ignored. Each version’s own counts are in /versions.
| url | The project’s page in the interface |
A component is purl, name, version (of the package), ecosystem and license. license is an SPDX
license expression as the SBOM gave it, possibly with free-text license names (MIT,
Apache-2.0 OR MIT, LicenseRef-Acme); it is null when the SBOM gives none, and for
components uploaded before nanobom read licenses until their project’s next upload
(how licenses are read). A search result adds organization,
project, project_version ("" for the unnamed version) and project_version_active: a
package in several versions of a project is one result per version.
A search takes q, license or both, and refuses a request with neither (422):
qis a name, matched anywhere in the component’s name, optionally followed by a space or@and a version prefix (openssl 3.,lodash@4.17), both ignoring case;licenseis matched anywhere in the component’s license, ignoring case:GPLfindsGPL-3.0-onlyandMIT OR LGPL-2.1-or-later. Components without a license never match;inactive=truealso searches inactive versions, left out by default (trueorfalse, anything else is422).
A run is id, trigger (scheduled, manual, upload), scope (all, organization,
project), status (running, succeeded, failed), started_at, finished_at, error,
new_findings and fixed_findings. A whole-instance run covers every organization, so its
error and its counts are shown to instance administrators only: others read
the run could not complete, and null counts.
An organization is slug, name and role: the caller’s role, viewer for tokens.
License policy and violations
The policy is changed in the interface only (Enforce a license policy); the API reads it:
{
"active": true,
"unlisted": "forbid",
"unknown": "warn",
"rules": [
{"license": "Apache-2.0", "action": "allow"},
{"license": "MIT", "action": "allow"}
]
}
| Field | |
|---|---|
active | Whether the policy can report anything: a rule or a default other than allow. An organization that never set a policy is false, with allow everywhere |
unlisted | The action (allow, warn, forbid) for licenses no rule lists |
unknown | The action for components whose license is missing or is not a valid SPDX expression |
rules | license (canonical SPDX identifier or LicenseRef-…) and action, by identifier |
A page of violations adds active, forbidden and warned (the number of components with
each verdict across the project version; total is their sum) to the usual page fields. Each item is
component (as above), verdict (forbid or warn) and licenses, the identifiers that
lead to the verdict, empty when the action for unknown licenses alone gives it. Items are forbidden components first,
then warned ones, each by name then package URL. Violations are computed at each request from
the current policy and the version’s latest SBOM (how); without an active
policy the list is empty and active is false.
Caching
Every 200 carries a weak ETag. Send it back in If-None-Match and the answer is
304 Not Modified, without a body, while the data is unchanged. The comparison is the weak one
of RFC 9110: the W/ prefix is
ignored on either side, and a list of tags matches when one of them does. The response is still
computed: this saves bandwidth, not server work.
The same URL answers differently for each caller, so every response of the read API (errors and
304 included, and the VEX export) carries Cache-Control: private, no-cache
and Vary: Cookie, Authorization, X-Api-Key. Shared caches and proxies must not store it;
the caller’s own cache may, after revalidating.
Status codes and errors
Errors are English JSON, {"error": "…"}, as on the upload API.
| Status | When | error |
|---|---|---|
304 | If-None-Match matches | |
401 | No token and no session, or a token that is unknown or revoked. The response has a WWW-Authenticate: Bearer header | sign in, or send a token in the Authorization header (Bearer) or in X-Api-Key |
400 | A path segment that is not valid percent-encoded UTF-8 | A description of the problem |
404 | Missing (a project version included), or out of the caller’s reach | not found |
422 | An invalid query parameter | For example limit must be a number from 1 to 500, severity must be a comma-separated list of critical, high, medium, low and unknown, q, the name to search for, is required, offset is not supported on runs: use limit, up to 100 |
500 | A database error | internal error |
Stability
The paths have no version number, like those of the upload API; /api/v1/… belongs to the
Dependency-Track API. Changes to the read API are
additive: new endpoints, new query parameters, new fields in responses, new values in
documented enumerations only when the release notes say so. Clients must ignore fields they do
not know. Removing or renaming a field or an endpoint, or changing its meaning, is a breaking
change: it is marked as such in the release notes,
and from version 1.0 on happens only in a major release.
MCP endpoint
nanobom serves its data as tools for assistants that speak the Model Context Protocol (MCP): Claude Code, Claude Desktop, VS Code, Cursor and other MCP clients. The tools read what the read API reads, with the same tokens; they change nothing. Connecting a client is described in Query nanobom from an assistant.
Endpoint
| URL | /mcp, under the public URL: https://nanobom.example.com/mcp |
| Transport | Streamable HTTP, stateless: every request is a POST answered on its own in JSON, with no session (Mcp-Session-Id) and no server-to-client stream |
| Protocol versions | 2024-11-05 to 2026-07-28 |
| Server name | nanobom, with the instance’s version |
| Setting | None: the endpoint is always on (see Why it is always on) |
Requests send Content-Type: application/json and accept both application/json and
text/event-stream, as the transport requires; MCP clients do so by themselves.
Authentication
Exactly as on the read API, with a token only:
| Sends | Reads |
|---|---|
Authorization: Bearer nanobom_…, or X-Api-Key: nanobom_…, a token of either scope | Its organization, as a viewer; a project token, its project only |
The session cookie of the interface authenticates nothing here: a request without a token is
401, whatever cookie it carries. A request with an Origin header, which browsers add and MCP
clients do not, is 403, and no CORS header is sent: a web page cannot drive the endpoint.
Anything out of the token’s reach is reported as not found, exactly like something that does not exist. Projects are named by slug within the token’s organization.
Status codes
The token is checked first: a request without a valid token is 401, whatever else is wrong
with it.
| Status | When |
|---|---|
200 | A JSON-RPC answer, including tool errors (see Errors) |
202 | A notification (notifications/initialized), which has no answer |
400 | The body is not a JSON-RPC message, or MCP-Protocol-Version names an unknown version |
401 | No token, or one that is not valid (revoked or mistyped): {"error": "…"} with WWW-Authenticate: Bearer |
403 | The request has an Origin header |
405 | Any method but POST |
406 | Accept does not list both application/json and text/event-stream |
413 | The body is larger than 64 KiB |
415 | Content-Type is not application/json |
Tools
Every tool is read-only (readOnlyHint) and describes its inputs in a JSON schema, which
clients read from tools/list. Answers are JSON objects, as structured content and as text.
| Tool | Inputs | Answers |
|---|---|---|
list_projects | None | The projects the token reaches, by organization and slug: open issues of their active versions by severity (a vulnerability of a package counted once), known_exploited, ignored, last_upload_at, stale, url |
list_versions | project | The project’s versions, newest first: name ("" for the unnamed version), latest, active, created_at, last_upload_at, open findings by severity |
list_findings | project, version, status, minimum_severity, known_exploited_only, component | The findings of a version, most urgent first (prioritization), with total, the number matching the filters |
get_finding | id | One finding in full: identifiers and aliases, severity and CVSS vector, exploitation (KEV, EPSS), fixed versions, dependency paths, triage, the status of each version of the project, and the advisory |
affected_by | vulnerability, any_status, include_inactive | The findings of a vulnerability across the projects the token reaches, by project and version |
search_components | name, license, include_inactive | Components by name (and version prefix), license or both, one match per project version, as the component search |
license_violations | project, version | The components of a version that the license policy forbids or warns about, forbidden first, with policy_active and the forbidden and warned counts |
Inputs
| Input | Tools | Values | Default |
|---|---|---|---|
project | list_versions, list_findings, license_violations | A project slug, case-insensitive | Required |
version | list_findings, license_violations | A version name, case-sensitive; "" for the unnamed version | The latest version |
status | list_findings | open, ignored or fixed | open |
minimum_severity | list_findings | critical, high, medium, low or unknown: that severity and above (unknown is the lowest) | Every severity |
known_exploited_only | list_findings | Only vulnerabilities in CISA’s KEV catalog | false |
component | list_findings | Text the component name contains, ignoring case | Every component |
id | get_finding | A finding identifier, from list_findings or affected_by | Required |
vulnerability | affected_by | An identifier or alias, ignoring case: CVE-2021-23337 also finds findings filed under GHSA-35jh-r3h4-6jhm, which lists it as an alias | Required |
any_status | affected_by | Also ignored and fixed findings | false: open ones |
include_inactive | affected_by, search_components | Also inactive versions | false |
name | search_components | Text the name contains, optionally followed by a space or @ and the start of the version: openssl 3., log4j-core@2.14 | |
license | search_components | Text the license contains, ignoring case: GPL finds GPL-3.0-only and LGPL-2.1-or-later |
search_components needs name, license or both. Unknown inputs are refused, not ignored.
Example
{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "affected_by", "arguments": {"vulnerability": "CVE-2021-23337"}}}
{
"vulnerability": "CVE-2021-23337",
"known_as": ["GHSA-35jh-r3h4-6jhm"],
"items": [
{
"finding_id": 412,
"organization": "acme",
"project": "web",
"version": "2.4",
"version_latest": true,
"version_active": true,
"component": "lodash",
"component_version": "4.17.20",
"purl": "pkg:npm/lodash@4.17.20",
"vulnerability_id": "GHSA-35jh-r3h4-6jhm",
"severity": "high",
"status": "open",
"url": "https://nanobom.example.com/findings/412"
}
],
"truncated": false
}
known_as lists the identifiers the vulnerability is filed under in nanobom: the one asked for,
or those that list it as an alias, among the findings of the projects the token reaches. It is
empty when none of them has the vulnerability: it never reveals what other organizations have.
Limits
| Limit | Value |
|---|---|
| Items in a list | 100; the answer has "truncated": true when there are more. list_findings also gives total |
| Advisory details | 4000 characters; details_truncated says when they were cut |
| Advisory references | 20; references_truncated says when there were more |
Versions of a finding (get_finding) | 100; versions_truncated says when there were more |
| Request body | 64 KiB |
A truncated list calls for a narrower question: a filter on list_findings, a longer name or a
version prefix on search_components.
Errors
A tool that cannot answer returns a result with isError: true and a message the assistant can
act on, in English: not found: … for a project, version or finding that does not exist or is
out of the token’s reach, or what is wrong with the inputs: an unknown or missing field, a value
outside an enumeration (failed to deserialize parameters: …), an empty vulnerability, a
search with neither name nor license. A database failure is a JSON-RPC internal error,
without details.
Untrusted text
Advisory summaries and details come from OSV, written by third parties. An
advisory could hold text meant to steer an assistant (“ignore previous instructions…”), so
nanobom returns it only in delimited fields: advisory_summary in list_findings, and the
advisory object of get_finding, which carries a notice saying the text is data. The tool
descriptions and the server’s instructions say the same. Ignore reasons are written by members
of the organization, or come from imported VEX documents.
The endpoint has no tool that changes anything, so text that steers an assistant can at most mislead its answer; it cannot triage, upload or delete through nanobom.
Why it is always on
The endpoint adds no reach to what the read API already gives: the same tokens, the same domain functions and the same checks, and nothing the session cookie unlocks. Turning it off would protect no data, so there is no setting. To keep a token from it, do not give that token to an assistant; revoking the token stops both.
Vulnerability report
The vulnerability report describes one version of a project for readers who do not use nanobom: customers, auditors, regulators. It is a page of the interface, made to be printed or saved as PDF, and the same content as an HTML document from the API, for archiving. The steps are in Share a vulnerability report.
In the interface
The Report button of the project page opens
/organizations/{organization}/projects/{project}/report, for the version the page shows
(?version=…, the latest version without it). Any member of the organization can open it, as
for the project page. The page is in the language of the interface; printing leaves out the
header, the breadcrumb and the printing hint, and always uses light colors.
Endpoint
GET /api/organizations/{organization}/projects/{project}/report
| Authentication | A token of either scope, in Authorization: Bearer nanobom_… or X-Api-Key, or the session of a signed-in member, as on the read API |
version | The name of a project version (?version=2.4; an empty version= names the unnamed version). Without it, the latest version |
Accept-Language | The language of the report, English or French; English when absent or not offered |
A token reaches its organization’s projects, or its own project for a project token.
| Status | When |
|---|---|
200 | The report, Content-Type: text/html; charset=utf-8: a complete HTML document with the interface’s stylesheet inlined, so a saved copy keeps its layout without the server (fonts fall back to the system’s) |
401 | No token or session, or an invalid token |
404 | Unknown organization, project or version, or one the token does not reach |
422 | An invalid query string, such as version given twice |
Errors are JSON, {"error": "…"}, in English. Like every read API
response, the report is Cache-Control: private, no-cache and varies on Cookie,
Authorization and X-Api-Key. It is not described in the OpenAPI document, which covers the
JSON endpoints.
Content
The page and the document hold the same sections, in this order. Dates are in UTC.
| Section | Content |
|---|---|
| Title | Organization, project and version (or “Unnamed version”), the time of generation, the nanobom version and the host of NANOBOM_PUBLIC_URL |
| Warnings | When the project received no SBOM for longer than NANOBOM_STALE_AFTER_DAYS (as on the project page), and when the version is inactive, so no longer checked |
| Scope and provenance | The latest upload of the version (time, SBOM format, source commit and image tag when given), the components checked, the components of that SBOM without a package URL (not checked), the end of the last successful run covering the project, and the last reads of the CISA KEV catalog and of FIRST EPSS scores |
| Summary | A sentence on open findings of high or critical severity, the open findings by severity, how many are known exploited, the ignored findings, and the findings fixed in the last 90 days |
| Open vulnerabilities | Each open finding, in the order of the project page (known exploited first, then by severity and EPSS): identifier and aliases, component and version, severity and CVSS score, known exploited, EPSS percentile, direct or transitive dependency (and through which direct dependencies), fixed versions per the OSV record, first seen |
| Assessed as not affecting the product | Each ignored finding with its justification (“None (accepted risk)” without one), its reason, when it was ignored and by which member or upload token, and its expiry. The address of the VEX export of the same version precedes them, for machine-readable use |
| Licenses | With a license policy, the components it forbids or warns about; without one, the components by license expression, the 10 most common, then the others together and those without a license |
| Method | What nanobom checks and what it does not, and that the report reflects the time of generation |
Lists are bounded so that a large project gives a report of reasonable size: at most 500 open findings, 500 ignored findings and 200 license violations, each followed by how many more the project page lists. The counts of the summary always cover every finding.
The report shows nothing a viewer of the project cannot see: who ignored a finding is the username the finding page shows.
Badges
A project’s badge is a small image of the open findings of one of its versions, for a README. It is off by default; admins, owners and instance administrators turn it on, give it a new address and turn it off from the project page (Show a badge in a README, permissions).
Endpoints
| Path | Returns |
|---|---|
GET /badges/{key}.svg | The badge as an SVG image |
GET /badges/{key}.json | The badge in the shields.io endpoint format |
{key} is 32 lowercase hexadecimal digits (128 random bits), drawn when the badge is turned on
and again for each new address. The key is the only authorization: no session or token is
needed, and none is read. The address names neither the organization nor the project.
| Parameter | Meaning |
|---|---|
version | The name of the version to show (case-sensitive). Without it, the latest version. Empty (version=) names the unnamed version |
HEAD is answered like GET, without a body.
Messages and colours
The label is always vulnerabilities, in English whatever the interface language. The message
counts the open findings of the version, as the project page’s summary does: ignored and
fixed findings do not count. The colour is that of the worst open finding.
| Open findings | Message | Colour |
|---|---|---|
| None | none | green #1f883d |
| Some known exploited (CISA KEV) | N exploited, then the counts below | red #cf222e |
| Worst is critical | the counts, e.g. 1 critical, 2 high | red #cf222e |
| Worst is high | e.g. 2 high, 3 medium | orange #bc4c00 |
| Worst is medium | e.g. 3 medium | yellow #d4a72c, dark text |
| Worst is low | e.g. 1 low | yellow-green #a2b82c, dark text |
| Only unknown severity | e.g. 1 unknown | grey #6e7781 |
| The version never received an SBOM | no SBOM | grey #6e7781 |
Counts are listed from the worst severity to the least (critical, high, medium, low,
unknown), zero counts left out, separated by , . A known exploited finding is also counted
under its severity.
The JSON document:
{"schemaVersion":1,"label":"vulnerabilities","message":"1 critical, 2 high","color":"cf222e"}
Responses
| Status | When |
|---|---|
200 | The badge |
304 | If-None-Match names the badge’s current ETag (or is *) |
404 | The key is unknown, was replaced by a new address, or the badge is off; the version is unknown; the extension is neither .svg nor .json; the query string is malformed (such as version given twice). The body is empty and does not say which |
Headers of a 200:
| Header | Value |
|---|---|
Content-Type | image/svg+xml; charset=utf-8 or application/json |
Cache-Control | public, max-age=300: image proxies, such as GitHub’s, may serve a badge up to five minutes old |
ETag | A strong tag of the body; badges are never compressed, so it names the bytes sent |
X-Content-Type-Options | nosniff |
Content-Security-Policy | SVG only: default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none', so the image opened on its own runs nothing |
A 304 carries the ETag and Cache-Control headers.
What a badge exposes
To anyone with its address:
- the open findings of a version, by severity, and how many are known exploited;
- whether the version has received an SBOM;
- with
?version=, whether a version of that name exists.
Not the project’s or the organization’s name, the findings themselves, the components or anything else. The Markdown snippet of the project page links the image to the project page, which only members can open, or to the project’s public page while it is on. The badge’s key never opens the public page, which has a key of its own.
The key is stored in clear in the database, unlike API tokens, so the project page can show the
snippet again. Request logs write badge paths as /badges/…, without the key, at debug level
(Metrics, health and logs).
Public pages
A project’s public page shows the findings of one of its versions and how they were triaged, to anyone with its address. It is off by default; admins, owners and instance administrators turn it on, give it a new address and turn it off from the project page (Publish a public page of a project, permissions).
Endpoints
| Path | Returns |
|---|---|
GET /public/{key} | The page, as a complete HTML document |
GET /public/{key}/vex.json | The findings of the same version as a CycloneDX 1.6 VEX document |
{key} is 32 lowercase hexadecimal digits (128 random bits), drawn when the page is turned on
and again for each new address. It is the page’s own: a badge has a different key,
and turning one on, giving it a new address or turning it off leaves the other alone. The key
is the only authorization: no session or token is needed, and none is read, so a signed-in
member sees the same page as anyone else. The address names neither the organization nor the
project.
| Parameter | Meaning |
|---|---|
version | The name of the version to show (case-sensitive). Without it, the latest version. Empty (version=) names the unnamed version |
Accept-Language (header, page only) | The language of the page, English or French; English when absent or not offered |
HEAD is answered like GET, without a body.
Responses
| Status | When |
|---|---|
200 | The page or the document |
404 | The key is unknown, was replaced by a new address, or the page is off; the version is unknown; the query string is malformed (such as version given twice). The body is empty and does not say which, and the response is Cache-Control: no-store |
Headers of a 200:
| Header | Value |
|---|---|
Content-Type | text/html; charset=utf-8 for the page, application/vnd.cyclonedx+json for the VEX document |
Cache-Control | public, max-age=300: browsers and proxies may show a page up to five minutes old, including after it is turned off |
Vary | Page only: Accept-Language |
Referrer-Policy | no-referrer: following a link from the page to an advisory does not send the page’s address, and its key, to the advisory’s site |
X-Robots-Tag | noindex: search engines that find the address do not list it |
X-Content-Type-Options | nosniff |
Content-Security-Policy | Page: default-src 'none'; style-src 'unsafe-inline'; font-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none', so it runs no script and cannot be framed. Document: default-src 'none'; frame-ancestors 'none' |
The page works without JavaScript and has none. Its stylesheet is inlined, as in the
vulnerability report; it also carries <meta name="robots" content="noindex"> and
<meta name="referrer" content="no-referrer">.
What the page shows
The page follows the layout of the vulnerability report and shows only:
| Section | Content |
|---|---|
| Header | The project’s name, the version’s name, and the host serving it (not the nanobom release, which would tell anyone whether the instance runs one with a known flaw) |
| Warnings | Whether the project received no SBOM for longer than NANOBOM_STALE_AFTER_DAYS (Configuration), and whether the version is inactive |
| Scope and provenance | When the version’s SBOM was uploaded, the number of components checked and of components without a package URL, the last check against OSV, and when the CISA KEV catalog and FIRST EPSS scores were last read |
| Summary | Open findings by severity, how many are known exploited, how many are ignored, how many were fixed in the last 90 days |
| Open vulnerabilities | For each: the identifier (linked to osv.dev), its aliases and summary, the component’s name, version and package URL, the severity and CVSS score, whether it is known exploited, the EPSS percentile, the versions that fix it and the day it was first seen |
| Assessed by the maintainers | For each ignored finding: the identifier and aliases, the component, the severity, the VEX justification (or None (accepted risk)) and the day it was ignored |
Both lists show at most 500 findings, known exploited first, then by severity and EPSS; the page says how many more there are.
The page never shows:
- the organization, its name or its slug, or the project’s slug;
- who ignored a finding, a member’s username or the name of the upload token that imported a VEX statement;
- the reason typed when ignoring a finding, nor when an ignore expires;
- the source commit or image tag of an upload, or the format of the SBOM;
- licenses and the license policy;
- dependency paths (which direct dependency pulls in a component);
- other versions, other projects, finding identifiers, or any link into the interface.
Package URLs are shown as the SBOM gives them, qualifiers included: a qualifier such as
repository_url that names a private registry appears on the page and in the VEX document.
Check the SBOM before turning the page on if its package URLs carry such qualifiers.
The VEX document
/public/{key}/vex.json is the VEX export of the same version, open, ignored
and fixed findings included, with two differences:
- no vulnerability has an
analysis.detail, which carries the reason of an ignore in the members’ export:analysis.stateandanalysis.justificationremain; metadata.componenthas nobom-ref, which names the organization in the members’ export; itsnameis the project’s name and itsversionthe version’s name;- the nanobom entry of
metadata.toolshas noversion.
Load
A page costs what the report costs: every finding of the version, and the OSV records of the
open ones. At most two pages or VEX documents are built at once across the instance; further
requests wait their turn, so a crawler or a script in a loop cannot keep more of the database
busy, away from uploads and checks. A cache in front of nanobom can serve repeated requests for
the five minutes of Cache-Control.
Storage and logs
The key is stored in clear in the database, as a badge’s is, so the project page can show the
address again. Request logs write public page paths as /public/…, without the key, at debug
level (Metrics, health and logs). Deleting the project deletes its page.
License policy
An organization’s license policy says which licenses of its components it allows, warns about or forbids. Admins change it in the organization’s Settings (how-to: Enforce a license policy); why it evaluates licenses the way it does is in License policies.
Settings
| Setting | Values | Default | |
|---|---|---|---|
| Allowed licenses | identifiers | none | Rules with the action allow |
| Licenses to warn about | identifiers | none | Rules with the action warn |
| Forbidden licenses | identifiers | none | Rules with the action forbid |
| Licenses not listed | allow, warn, forbid | allow | The action for a license no rule lists; forbid turns the allowed list into an allowlist |
| Unknown licenses | allow, warn, forbid | allow | The action for a component whose license is unknown (see Evaluation) |
The actions, from the least to the most severe: allow, warn, forbid. Saving replaces the
whole policy, the three lists and both defaults.
A policy is active when a rule or a default is not allow. Without an active policy,
nothing is a violation and the interface does not mention licenses: every organization starts
that way.
Identifiers
Each list holds identifiers separated by spaces, commas or new lines:
- an identifier of the SPDX license list that nanobom is built
with, in any case (
mitis stored asMIT); the deprecated GNU identifiers without a suffix (GPL-2.0,LGPL-2.1,AGPL-3.0) are stored as their-onlyvariant, which they mean, and the deprecated ones with an exception as the license they carry: the GNU ones (GPL-2.0-with-classpath-exception) as the-onlyvariant of their license,eCos-2.0asGPL-2.0-or-laterandwxWindowsasLGPL-2.0-or-later; no other deprecated identifier is replaced; - or
LicenseRef-followed by letters, digits,.and-(LicenseRef-Proprietary), for licenses outside the SPDX list.
An identifier with + (GPL-2.0+) is refused: name the -or-later variant, or the license
itself. Exception identifiers (Classpath-exception-2.0) and NOASSERTION are refused too: a
rule judges a license whatever exception follows it, and NOASSERTION is an unknown license.
The -only and -or-later variants of a GNU license are two licenses: a rule on
GPL-3.0-only does not cover GPL-3.0-or-later, and a typed GPL-3.0 is stored as
GPL-3.0-only. To judge both, list both.
The same identifier, ignoring case, may appear once; in two lists it is refused. A policy holds at most 1000 rules, and an identifier is at most 200 characters. Refused input changes nothing, and the settings page says why:
| Message |
|---|
"…" is not an SPDX license identifier (see https://spdx.org/licenses) nor LicenseRef- followed by letters, digits, '.' or '-' |
"…" is listed with two different actions |
a license policy holds at most 1000 rules |
Evaluation
Each component has one license, an SPDX license expression as read from its latest SBOM (how licenses are read). Its verdict:
- A component without a license is unknown: it gets the action for unknown licenses, and the verdict names no identifier.
- The expression is parsed, ignoring the case of identifiers and operators. Deprecated
identifiers,
/forORand+after an identifier are accepted. - Each license of the expression gets its rule, or the action for licenses not listed.
WITHexceptions are ignored:GPL-2.0-only WITH Classpath-exception-2.0is judged asGPL-2.0-only.GPL-2.0matches a rule onGPL-2.0-only,GPL-2.0+one onGPL-2.0-or-later,GPL-2.0-with-classpath-exceptionone onGPL-2.0-only,eCos-2.0one onGPL-2.0-or-laterandwxWindowsone onLGPL-2.0-or-later;+after another license is ignored (Apache-1.0+is judged asApache-1.0).DocumentRef-…:LicenseRef-…names a license of another document, which a rule on theLicenseRef-…alone does not match.NOASSERTIONgets the action for unknown licenses. ORkeeps the least severe side,ANDthe most severe.ANDbinds tighter thanOR(A OR B AND CisA OR (B AND C)); parentheses group as written.- The verdict is the resulting action, with the identifiers that lead to it; when both sides of an operator give the same action, both are named.
- An expression that does not parse is unknown: a free-text name (
Apache License 2.0), an identifier outside the SPDX list (Apache, which is not guessed), an exception outside the list, unbalanced parentheses. Its words are still read (see Identifiers in invalid text): each SPDX identifier orLicenseRef-…among them gets its action as in step 3, and the verdict is the most severe of these actions and the action for unknown licenses, as if everything were joined withAND. It names the identifiers that give it, none when only the action for unknown licenses does. A forbidden identifier is therefore never allowed because the rest of the text is not SPDX.
With a policy that forbids GPL-3.0-only, warns about LGPL-2.1-only, allows the licenses
not listed and warns about unknown ones:
| License | Verdict | Because of |
|---|---|---|
MIT | allow | |
GPL-3.0-only | forbid | GPL-3.0-only |
MIT OR GPL-3.0-only | allow | |
MIT AND GPL-3.0-only | forbid | GPL-3.0-only |
GPL-3.0-only OR LGPL-2.1-only | warn | LGPL-2.1-only |
(MIT OR GPL-3.0-only) AND LGPL-2.1-only | warn | LGPL-2.1-only |
gpl-3.0-only with classpath-exception-2.0 | forbid | GPL-3.0-only |
| none | warn | |
Apache License 2.0 | warn | |
(GNU Affero General Public License v3) AND GPL-3.0-only | forbid | GPL-3.0-only |
GPL-3.0-only WITH Some-Custom-exception | forbid | GPL-3.0-only |
MIT AND Some-Custom-License | warn | |
Licensed under GPL-3.0-only. | forbid | GPL-3.0-only |
Intel Simplified Software License | warn |
Identifiers in invalid text
Words are runs of letters, digits, ., : and -; case does not matter. A word is matched,
in order:
- as it is;
- without the
.,:and-at its start and end (GPL-3.0-only.andGPL-3.0-only:areGPL-3.0-only); - when it holds a
:and is not aDocumentRef-…:LicenseRef-…, part by part, each without.and-at its ends (License:GPL-3.0-onlynamesGPL-3.0-only).
+ right after a word that ends with a GNU identifier means its -or-later variant, as in an
expression.
Which matches count depends on the identifier:
- An identifier shaped like one, holding a digit,
-,.or+, and everyLicenseRef-…, counts wherever it appears:Licensed under AGPL-3.0-onlynamesAGPL-3.0-only. - An identifier that is a plain word, letters only (
MIT,Intel,Ruby,DOC,JSON,Unlicense, close to 200 of the SPDX list), counts only when it is the whole of a part of the text, found as it is or by step 2, alone or followed by+. Parts are separated by parentheses, the operatorsAND,ORandWITHin any case,,,;and/. Such words are common in prose:Intel Simplified Software License,SEE LICENSE IN doc/LICENSEandLizenz mit Ausnahmenname no license, whileMIT, Some proprietary thingand(Ruby) AND Foo barnameMITandRuby.
A component whose verdict is warn or forbid is a violation. Violations are computed
when read, from the current policy and each project’s latest SBOM: a policy change applies to
every project at once, without a run, and nothing about past verdicts is kept.
Where violations show
| Where | What |
|---|---|
| The project page | A Licenses section, while the policy is active: the violations, forbidden first, then by name, with their license and the identifiers behind the verdict; at most 200, the read API lists every one |
| The organization page | A badge on each project with violations: the number of forbidden licenses, or of warnings when nothing is forbidden |
| Read API | GET /api/organizations/{organization}/license-policy and GET /api/organizations/{organization}/projects/{project}/license-violations |
| Upload API | evaluation.licenses in the response of an upload that waited: the counts and the first 20 violations |
| The upload gate | fail_on=license fails the upload with 409 when a component is forbidden (thresholds) |
Webhooks and metrics do not report license violations, and the Dependency-Track API does not gate on them.
Permissions
| Viewer | Member | Admin | Owner | |
|---|---|---|---|---|
| See the violations on project pages | ✓ | ✓ | ✓ | ✓ |
| Read the policy and the violations through the read API | ✓ | ✓ | ✓ | ✓ |
| See and change the policy in Settings | ✓ | ✓ |
Tokens of either scope read the policy of their organization, and a project token the violations of its project only (Accounts, roles and permissions).
Webhook payloads and emails
nanobom sends documents with POST to webhooks, as JSON or, for an organization’s webhook,
as a message for Slack or Microsoft Teams, and emails them to an organization’s recipients:
| Event | Sent to | When |
|---|---|---|
findings.new | the organization’s webhook and email recipients | after a successful run that opened or reopened findings worth reporting, or found open findings newly known exploited |
projects.stale | the organization’s webhook and email recipients | after a successful scheduled run, when projects became stale |
run.failed | NANOBOM_FAILURE_WEBHOOK_URL (instance) | when a run fails |
An organization’s webhook is configured in Settings → Webhook (URL, format, minimum severity, only known exploited vulnerabilities, enabled), its email recipients in Settings → Email notifications (recipients, language, minimum severity, only known exploited vulnerabilities); see Get notified. The webhook and the email apply their own filters: each gets the findings that pass its own.
Formats
The Format of an organization’s webhook says what its findings.new and projects.stale
events are posted as:
| Format | Posted as | For |
|---|---|---|
json (default) | The JSON documents described below | Your own receiver, Home Assistant, n8n |
slack | A Slack message: text and Block Kit blocks (Slack messages) | A Slack Incoming Webhook |
teams | A message with an Adaptive Card (Microsoft Teams messages) | A Microsoft Teams Workflows webhook |
run.failed, which goes to the instance’s NANOBOM_FAILURE_WEBHOOK_URL and not to an
organization’s webhook, is always JSON. The same filters apply to every format: minimum severity,
known exploited findings, which projects are reported. The format is stored per organization,
json for webhooks created before it existed.
The body is written when the delivery is recorded, so a retry posts exactly what the first attempt did. Changing the format abandons the deliveries waiting for a retry, as changing the URL does.
Slack messages
The body is {"text": …, "blocks": […]}, the payload of a Slack Incoming Webhook. text is the
notification preview and the fallback of clients that do not display blocks. Texts are in English
whatever the language of the interface, since nanobom does not know the readers’ language.
findings.new:
| Block | Content |
|---|---|
header | Acme: 3 new findings (highest severity: critical, 1 known exploited) |
one section per finding, at most 10 | *<finding page|vulnerability id>* - severity - reopened - known exploited, then the component’s package URL in code and the project, Versions: the project versions (at most 5, unnamed version for the unnamed one) when the project names versions, the OSV summary, and Introduced via the project’s direct dependencies (at most 5) when the SBOM’s dependency graph says |
context | N more findings not shown. when some were left out, and a link to the organization |
projects.stale: a header (Acme: 2 projects stopped sending SBOMs), one section per project
at most 10 (*<project page\|slug>* - last SBOM 2026-09-30 14:21 UTC, or never received an SBOM)
and the same context.
The tags after the identifier are the severity, reopened for a reopened finding, and known exploited (newly known exploited for an open finding that CISA added to its catalog after it
was reported). Findings come in the order of the JSON document.
Limits that nanobom stays within: a section’s text is clipped to 3000 characters (Slack’s limit),
the header to 150, and a message has at most 12 blocks. Values that come from SBOMs and
vulnerability records are clipped too, and &, < and > in them are escaped as &,
< and >, as Slack requires, so that a package name cannot mention a channel
(<!channel>) or add a link. Slack has no other escape: *, _ and ~ in a value can still
format it.
Slack answers 200 with the body ok. Bad requests (400) and revoked webhooks (404) are
not retried.
Microsoft Teams messages
The body is the envelope Teams’ Workflows webhooks accept, a message with one Adaptive Card
attachment, not the MessageCard format of the Office 365 connectors that Microsoft
retired
in May 2026:
{
"type": "message",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"contentUrl": null,
"content": {
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.2",
"msteams": { "width": "Full" },
"body": [ … ],
"actions": [
{ "type": "Action.OpenUrl", "title": "Open Acme in nanobom", "url": "https://nanobom.example.org/organizations/acme" }
]
}
}
]
}
The body has the same content as the Slack message, in English: a bold title, then one
container per finding or project (at most 10) with the vulnerability identifier linking to its
page, its tags, the component and project, the Versions: line, the summary and the Introduced via line, and a last
line counting what was left out. Known exploited findings are in the card’s attention color. The
button opens the organization’s page.
Texts are Markdown, as Adaptive Cards allow in a TextBlock; \, *, _, [, ], `,
< and > in values from SBOMs are backslash-escaped, so a value cannot add a link or
formatting. Teams refuses incoming messages above 28 KB: nanobom lists fewer items, and says how
many were left out, until the message is under 24 KB.
A Workflows webhook usually answers 202 Accepted before the workflow posts the card, so a
delivery shown as delivered can still fail inside Power Automate (see the workflow’s run
history).
Emails
When the instance has an SMTP server (NANOBOM_SMTP_URL, see
configuration), an organization’s findings.new and projects.stale
events are also emailed to its recipients:
- One message per event and organization, sent to each recipient separately: the SMTP
envelope of each copy holds one recipient, so an address the SMTP server refuses fails alone
and the others still get the email. The
Toheader lists every recipient: they are the organization’s own people, and seeing who else was told helps them coordinate. At most 20 recipients; use a mailing list for more. - From
NANOBOM_SMTP_FROM. - Language: English or French, chosen per organization (English by default).
- Subject:
nanobom: 3 new vulnerabilities in acme/web(the organization’s slug and the project when every finding is in one project, the organization’s name otherwise) andnanobom: 2 projects stopped sending SBOMs; in French,nanobom : 3 nouvelles vulnérabilités dans acme/webandnanobom : 2 projets n’envoient plus de SBOM. - Body: a plain-text part and an HTML alternative with the same content: a headline (the
organization and the number of findings or projects), the highest severity and the number of
known exploited findings, then up to 50 findings, each with its identifier linking to its page,
its severity and tags (
reopened,known exploited,newly known exploited), the component and project, the project versions when the project names versions (unnamed version, orversion sans nomin French, for the unnamed one), the summary and the direct dependencies that introduce it; for stale projects, each project linking to its page with the time of its last SBOM. A line counts the items left out, a link opens the organization, and a footer says why the reader gets the email and links to the organization’s settings. - Values from the data (names, components, summaries) are kept on one line and clipped (100 characters for names, 250 for components, 300 for summaries); the HTML part escapes them.
- Links use
NANOBOM_PUBLIC_URL.
run.failed is not emailed: it goes to the failure webhook only.
The Send a test email button of the settings sends a test message to each saved recipient at once and shows the SMTP server’s reply for each address it refuses. The test message names the organization by its slug, never its display name, since it goes on demand to addresses nobody verified. Test emails are limited to one every 30 seconds per organization, one every 30 seconds per user, and 10 every 10 minutes for the whole instance.
Delivery
Webhook documents and emails go through the same queue, with the same retries.
-
One
POSTper document,Content-Type: application/json, with theUser-Agentnanobom/<version>; the body is in the webhook’s format. -
Each document is recorded in the database before it is sent, then posted right away. All the documents of a run are recorded before the first is posted, so a receiver that hangs delays the others but a restart meanwhile loses none. Deliveries happen after uploads waiting for the run have been answered, so they never slow CI down.
-
An attempt that takes more than 15 seconds fails.
-
How the receiver’s answer is handled:
Answer Outcome 2xx(200 okfrom Slack,202 Acceptedfrom a Teams Workflows webhook,204from most receivers)Delivered 4xx, except408and429Failed for good: the receiver refuses the document and would refuse it again, so it is not retried 408,429,5xx, any other status, a network error or a timeoutRetried -
Each recipient of an email is a delivery of its own, retried and abandoned on its own. Its copy is sent in one connection; each SMTP command may take 15 seconds, the whole message 60. How the SMTP server’s reply is handled:
Reply Outcome 2xx(250once the message is queued)Delivered 5xx(unknown mailbox, refused as spam, authentication failed)Failed for good, not retried 4xx(mailbox busy, greylisting), a network or TLS error, or a timeoutRetried No SMTP server configured any more Failed for good -
Retries come 1 minute after the first attempt, then 10 minutes after the first retry, then 1 hour after the second; when the third retry fails, the delivery is abandoned. Due retries are looked for every 30 seconds, so one can come up to 30 seconds late. The schedule survives a restart; an attempt cut short by a restart is retried 2 minutes later.
-
Every attempt that fails is logged (
notification delivery failed, with the delivery, its channel, its event, the attempt number and the status) and counted bynanobom_webhook_deliveries_total(metrics). The latest deliveries of an organization, webhook and email, are listed in its settings with their channel, and the recipient of each email. -
Removing an organization’s webhook, disabling it or changing its URL or format abandons its deliveries still waiting for an attempt or a retry: no new attempt goes to an address the admins replaced or turned off. An attempt already in progress at that moment is not stopped, so its request may still reach the old address; its result is not recorded and it is not retried. A delivery abandoned before any attempt was recorded shows as Cancelled in the settings, one abandoned after a failed attempt as Failed. In the same way, the
run.faileddeliveries still waiting for a retry are abandoned at startup whenNANOBOM_FAILURE_WEBHOOK_URLchanged or was removed. -
Changing an organization’s email recipients or language, or removing its email settings, abandons its emails still waiting for an attempt or a retry, the same way; changing only its filters does not. All pending emails are abandoned at startup when
NANOBOM_SMTP_URLwas removed. -
Delivered and abandoned deliveries are deleted after 30 days.
-
A document can arrive more than once, when the receiver accepted it but its answer was lost or came after 15 seconds. The
event, with the run’sidforfindings.newandrun.failed, identifies it. -
The document is the one prepared after the run: a retry sends it unchanged (in the same format), even if the findings changed since.
-
Requests are not signed.
-
New fields may be added to the documents in later versions.
findings.new
These are the JSON documents; the other formats carry the same findings.
After each successful run, each organization with an enabled webhook receives one document listing its findings that are:
- new or reopened by this run, at or above the minimum severity, or known exploited at any severity;
- open, known exploited, and never notified as such: findings reported earlier that CISA has
added to its catalog since, sent once with the
exploitedreason.
With Only known exploited vulnerabilities, only the known exploited ones among them are sent. Nothing is sent when nothing remains after filtering. Ignored findings are never sent.
A project with several versions has one finding per
version. They are sent as one entry per project, vulnerability and component (package
URL), with the versions it stands for in versions: a new advisory against a dependency five
versions share is one entry, not five. Two components hit by one advisory, such as a direct
pkg:npm/lodash@4.17.20 and a nested pkg:npm/lodash@4.17.15, stay two entries, each with its
own introduced_via; a project that never names versions gets one entry per finding. Findings
a new version inherits from the latest one when it is created are not new, and are never sent.
Inactive versions are not evaluated, so they send nothing, known exploited
findings included; made active again, a version’s next run sends what it missed.
Rarely, an advisory is announced twice when an upload creates a version during a run. The run in progress leaves the new version to the next run (versions), so an advisory it finds in the latest version after the new one inherited that version’s findings is announced again, for the new version, by the next run; so is a finding that just became known exploited.
{
"event": "findings.new",
"organization": {
"slug": "acme",
"name": "Acme",
"url": "https://nanobom.example.org/organizations/acme"
},
"run": { "id": 42, "trigger": "scheduled", "started_at": "2026-11-08T03:00:00.081+00:00" },
"count": 1,
"highest_severity": "high",
"known_exploited_count": 1,
"findings": [
{
"project": "web",
"component": "pkg:npm/lodash@4.17.20",
"vulnerability": "GHSA-35jh-r3h4-6jhm",
"aliases": ["CVE-2021-23337"],
"severity": "high",
"cvss_score": 7.2,
"summary": "Command Injection in lodash",
"reopened": false,
"reason": "new",
"known_exploited": true,
"kev_due_date": "2026-11-29",
"epss": 0.0149,
"epss_percentile": 0.78,
"introduced_via": ["web-framework"],
"versions": ["2.4", "3.0"],
"url": "https://nanobom.example.org/findings/17"
}
]
}
| Field | |
|---|---|
organization | Slug, display name and page of the organization |
run | The run that found them: identifier, trigger (upload, scheduled or manual) and start time |
count | Number of entries in findings, one per project, vulnerability and component |
highest_severity | The highest severity among them |
known_exploited_count | How many of them are known exploited |
findings[].project | Project slug |
findings[].component | The component’s package URL |
findings[].vulnerability | The finding’s identifier; aliases lists the others |
findings[].severity | critical, high, medium, low or unknown |
findings[].cvss_score | CVSS base score of the finding’s record, or null |
findings[].summary | One-line summary from OSV, or null |
findings[].reason | new, reopened or exploited |
findings[].reopened | true when reason is reopened |
findings[].known_exploited | In CISA’s KEV catalog |
findings[].kev_due_date | CISA’s due date, or null |
findings[].epss, epss_percentile | EPSS score and percentile, from 0 to 1, or null |
findings[].introduced_via | The names of the project’s direct dependencies that lead to the component, sorted; the component’s own name when it is one; empty when the SBOM’s dependency graph does not say (Dependency paths) |
findings[].versions | The names of the project versions the entry stands for, sorted; "" is the unnamed version, the only one of a project that never names versions. introduced_via and url are those of the latest version’s finding when the latest version is among them, of the first one otherwise; severity, cvss_score and known_exploited are the highest among them, and reason the first of new, reopened, exploited |
findings[].url | The finding’s page |
Every known exploited open finding of a run’s scope is marked as notified once that run is over, whether a webhook received it or not: enabling a webhook later does not replay old findings. A finding notified to a receiver that is down is not lost: its delivery is retried (see Delivery), and never prepared a second time.
projects.stale
After a successful scheduled run (and unless NANOBOM_STALE_AFTER_DAYS is 0), each
organization with an enabled webhook or email recipients receives the projects that became
stale since they were last notified, whatever the
minimum severity and the known exploited option:
{
"event": "projects.stale",
"organization": {
"slug": "acme",
"name": "Acme",
"url": "https://nanobom.example.org/organizations/acme"
},
"projects": [
{
"project": "web",
"last_upload_at": "2026-09-30T14:21:07.512+00:00",
"url": "https://nanobom.example.org/organizations/acme/projects/web"
}
]
}
| Field | |
|---|---|
organization | Slug, display name and page of the organization |
projects[].project | Project slug |
projects[].last_upload_at | Time of the project’s last upload; null for a project that never received an SBOM |
projects[].url | The project’s page |
A project is notified once per stale period: again only if it receives an SBOM and later goes stale again. Projects of an organization without an enabled webhook or email recipients are not marked as notified, so configuring either sends the currently stale projects after the next scheduled run.
run.failed
Sent to NANOBOM_FAILURE_WEBHOOK_URL for every failed run of the instance, whatever its
organization, including a run that stopped unexpectedly (a bug, or nanobom stopped while it
was running: such a run is closed at the next start, and its document is sent by the retry loop
within 30 seconds, so an unreachable receiver does not delay the startup):
{
"event": "run.failed",
"instance_url": "https://nanobom.example.org/",
"run": { "id": 43, "trigger": "upload", "started_at": "2026-11-08T10:12:31.904+00:00" },
"scope": "project",
"error": "querying vulnerabilities failed: …"
}
| Field | |
|---|---|
instance_url | NANOBOM_PUBLIC_URL |
run | Identifier, trigger (upload, scheduled or manual) and start time |
scope | all (the scheduled run), organization or project |
error | Why the run failed; it may name the packages of any organization. the run stopped unexpectedly for a run that did not end normally |
Accounts, roles and permissions
Who can see and do what depends on two things: instance administration, a flag on the user account, and the user’s organization role, per organization. API tokens are not user accounts: they authenticate CI and scripts on the upload API, the VEX API and the read API only, where they read as viewers of their organization.
Organization roles
Each member of an organization has one of four roles, each including the ones before it:
| Permission | Viewer | Member | Admin | Owner |
|---|---|---|---|---|
| See the organization, its projects, components, findings, license violations and runs; export VEX documents and vulnerability reports | ✓ | ✓ | ✓ | ✓ |
| Ignore and restore findings | ✓ | ✓ | ✓ | |
| Start a run (Check now) | ✓ | ✓ | ✓ | |
| Add, change and remove members other than owners | ✓ | ✓ | ||
| Create and delete projects; make their versions inactive or active, mark one latest, delete them; turn their badge and public page on or off and give them a new address | ✓ | ✓ | ||
| Create and revoke API tokens, upload or read; see and renew each project’s upload token | ✓ | ✓ | ||
| Configure the webhook and email notifications, send a test email | ✓ | ✓ | ||
| Change the license policy | ✓ | ✓ | ||
| Rename the organization | ✓ | ✓ | ||
| Grant and remove the owner role | ✓ | |||
| Delete the organization | ✓ |
- Any signed-in user can create an organization and becomes its owner.
- Any member can leave an organization, unless they are its last owner. An organization always keeps at least one owner: removing or demoting the last one is refused.
- Projects are created on the organization page (New project), or by the first upload of an organization-wide upload token, which therefore creates projects without any role.
- A user who is not a member of an organization gets “not found” for its pages, projects and findings. Search results and a finding’s Also affected list only cover organizations the user belongs to (every organization, for instance administrators).
- A member with both a role given in nanobom and a role from groups has the higher of the two.
Instance administrators
Instance administrators:
- act as owners in every organization, including those they are not a member of;
- see every organization on the Administration page;
- create local accounts, reset passwords, disable and enable users, and grant or remove instance administration;
- see the error messages and the finding counts of instance-wide runs.
They cannot disable themselves or remove their own administration. The first one is created with
nanobom create-administrator; with OpenID
Connect, the administrator claim can grant it instead.
Personal organizations
With NANOBOM_PERSONAL_ORGANIZATIONS on (the default), every new user, local or single sign-on,
gets an organization owned by them and named after their username (alice, or alice-2 if that
slug is taken). It is marked “personal” in the list and otherwise behaves like any organization:
members can be added to it, and it can be deleted.
Names
- Organization and project slugs are 1 to 64 characters among lower-case letters, digits,
.,_and-, starting with a letter or a digit; upper-case letters are folded to lower case, soAcmeandacmeare the same organization. Organizations also have a display name. - Usernames follow the same rules.
- Email addresses are not verified; they are only another way to sign in and to add the user to an organization, and each address belongs to one account at most.
Local accounts
Local accounts are on by default (NANOBOM_LOCAL_ACCOUNTS=true). Users sign in with their
username or their email address, and a password. There is no self-registration and no password
reset by email.
- Passwords must have at least
NANOBOM_PASSWORD_MINIMUM_LENGTHcharacters (12 by default) and at most 1,024. There are no composition rules. - They are hashed with Argon2id.
- Setting a new password ends all of the user’s sessions.
- Password sign-in attempts are limited per client address: a burst of 5, then one attempt every
4 seconds. Beyond that, the server answers
429 Too Many Requests. Behind a reverse proxy, the client address is read fromX-Forwarded-For,X-Real-IPorForwardedonly withNANOBOM_TRUST_FORWARDED_HEADERS=true.
With NANOBOM_LOCAL_ACCOUNTS=false, the password form and the password sign-in route are
removed; local accounts stay in the database and work again if the setting is turned back on.
Single sign-on users
A single sign-on user is identified by the provider’s issuer and subject (iss and sub),
never by email address. At the first sign-in, with NANOBOM_OIDC_CREATE_USERS=true (the
default), nanobom creates the user:
- the username comes from
preferred_username, else the part ofemailbefore@, folded to lower case with other characters than letters, digits,.,_and-replaced by-;-2,-3… is appended when it is taken; - the email address is kept if no other account uses it;
- the display name comes from
name.
These are taken at the first sign-in and not updated afterwards. Claims are read from the ID token and from the provider’s user information endpoint, the ID token winning when both have one; the access token is not read.
A local account and a single sign-on identity are two different users, even with the same email
address; there is no linking. With NANOBOM_OIDC_CREATE_USERS=false, only users who signed in
before can sign in; others see “This account is not known here and new accounts are not created
automatically”.
Administrator claim
With NANOBOM_OIDC_ADMINISTRATOR_CLAIM set, a single sign-on user is an instance administrator
when the claim contains NANOBOM_OIDC_ADMINISTRATOR_VALUE: as an element of a list
(["nanobom-admins", "developers"]), a key of an object (Zitadel’s roles), or the whole string.
Without NANOBOM_OIDC_ADMINISTRATOR_VALUE, the claim must be the boolean true. Dotted paths
reach nested claims.
The claim is applied at each sign-in, both ways: it grants administration, and removes it
from a user who no longer has it, including rights given on the Administration page. Without
NANOBOM_OIDC_ADMINISTRATOR_CLAIM, sign-in never changes the flag.
Roles from identity-provider groups
NANOBOM_OIDC_GROUPS_CLAIM=groups
NANOBOM_OIDC_GROUP_MAPPING="security=acme:admin;developers=acme:member;auditors=acme:viewer;platform=infra:owner"
NANOBOM_OIDC_GROUP_MAPPING is a list of group=organization:role entries, separated by ; or
line breaks:
groupis a name as it appears in the groups claim; it may contain:but not=;organizationis an organization slug;roleisviewer,member,adminorowner.
Spaces around entries and parts are ignored. An invalid entry stops the server at startup with
invalid NANOBOM_OIDC_GROUP_MAPPING, naming the entry.
The groups claim, named by NANOBOM_OIDC_GROUPS_CLAIM, can be a list of strings, an object whose
keys are the names, or a single string. Its name is looked up as a whole first
(urn:zitadel:iam:org:project:roles is one claim), then as a dot-separated path into nested
objects (realm_access.roles).
At each sign-in, nanobom reads the user’s groups from the claim and replaces the user’s synchronized memberships with those the mapping gives:
- when several groups give a role in the same organization, the highest wins;
- an organization named by the mapping is created if it does not exist, with its slug as its
name; if no group maps to
ownerin it, only instance administrators can manage its owners; - a user who left a group loses its role at their next sign-in; until then, and as long as their session lasts, they keep it;
- groups that are not in the mapping are ignored.
Synchronized memberships are kept apart from the ones given in nanobom, and shown under From groups in Settings → Members, where they cannot be changed. A sign-in never changes a role an admin gave by hand; the effective role is the higher of the two, and removing the one given in nanobom leaves the other.
Sessions
A successful sign-in starts a session, stored in the database, so restarts and upgrades do not
sign anyone out. The session cookie, nanobom_session, holds only a random session identifier,
and is HttpOnly, SameSite=Lax, and Secure when NANOBOM_PUBLIC_URL starts with https://.
A session ends after NANOBOM_SESSION_INACTIVITY_DAYS (7 by default) without a request, when
the user signs out, when their password changes, or when they are disabled. Expired sessions are
deleted every hour.
A disabled user cannot sign in, and their current sessions stop working at their next request. Their memberships are kept, so enabling them again restores their access.
Metrics, health and logs
/healthz
GET /healthz answers 200 {"status": "ok"} when the database answers, and
503 {"status": "unavailable"} otherwise. It does not check OSV, CISA or FIRST. It needs no
authentication.
/metrics
GET /metrics serves Prometheus metrics, without authentication. Labels are instance-wide, never
per organization or project, so the number of series stays small and the endpoint reveals nothing
about a particular organization.
| Metric | Type | |
|---|---|---|
nanobom_open_findings{severity} | gauge | Open findings of the active project versions across the instance, by severity (critical, high, medium, low, unknown); ignored findings and inactive versions are not counted |
nanobom_open_findings_known_exploited | gauge | Open findings of the active project versions with a CVE in CISA’s KEV catalog |
nanobom_stale_projects | gauge | Projects whose SBOM stopped coming |
nanobom_last_successful_run_timestamp_seconds | gauge | Unix time at which the last successful run started |
nanobom_runs_total{status} | counter | Runs, by status (succeeded, failed) |
nanobom_run_failures_total | counter | Runs that could not complete |
nanobom_run_duration_seconds | histogram | Duration of runs |
nanobom_osv_request_errors_total{kind} | counter | Failed requests to OSV, retries included; kind is status (an error status) or request (network error or unreadable answer) |
nanobom_exploitation_refresh_failures_total | counter | Refreshes of exploitation data that failed or were abandoned, including those where only one of KEV and EPSS failed; a refresh counts once even when both failed |
nanobom_webhook_deliveries_total{channel, outcome} | counter | Delivery attempts, by channel (webhook or email, where each recipient of an email is a delivery of its own) and outcome: delivered, retried (the attempt failed and another is scheduled) or abandoned (the attempt failed and no retry follows: refused by the receiver, or the last retry) |
Gauges are computed from the database at startup and after each run. nanobom_stale_projects
is also recomputed on each scrape, since projects go stale with time alone (with
NANOBOM_SCHEDULE=off and few uploads, runs can be rare); if that fails, the scrape serves the
last value. nanobom_last_successful_run_timestamp_seconds only appears after the first
successful run.
Counters start at zero at each start, and appear only once something has been counted: a missing
nanobom_run_failures_total means no run failed since the start.
Logs
nanobom writes one JSON object per line on standard error (NANOBOM_LOG_FORMAT=text for
humans; standard output is kept for command results), with the event’s fields at the top level:
{"timestamp":"2026-11-08T03:00:41.120Z","level":"INFO","message":"run succeeded","run":42,"scope":"all","components":1834,"vulnerabilities":97,"new":2,"fixed":5,"seconds":38.2,"target":"nanobom_domain::evaluation"}
Every request is logged once answered, with its method, path, status and duration. Query strings
are left out, since they can carry search terms; requests to /healthz, /metrics,
badges, public pages and static assets are logged at debug level
only. Badge and public page paths are logged as /badges/… and /public/…: their key is their
authorization. NANOBOM_LOG_LEVEL=info,nanobom=debug shows
them, and more detail from nanobom’s own crates.
Log messages
| Message | Level | Meaning |
|---|---|---|
run failed; findings left unchanged | error | A run could not complete; error says why |
OSV request failed, retrying | warn | A request to OSV failed and is retried |
notification delivery failed | warn | A webhook (an organization’s, or the failure webhook) did not answer with a 2xx, or an SMTP server did not accept an email; channel, attempt and status say which channel, which attempt and why. See Delivery for retries |
test email failed | warn | The Send a test email button of an organization’s settings got no 2xx from the SMTP server for at least one recipient; status gives each refused address and why |
a stage of a run panicked; the worker continues | error | A bug stopped a run, or the work after it; the run is recorded as failed |
a run interrupted by a restart is recorded as failed | warn | nanobom was stopped during a run; the run is closed at startup and sent to the failure webhook |
refreshing exploitation data failed | warn | KEV or EPSS could not be downloaded, or did not answer within its 25 seconds; feed names it when the other feed was still stored |
the KEV catalog could not be downloaded; using the copy in memory | warn | A KEV outage: the catalog downloaded hours ago is used instead |
cross-site request refused | warn | A form submission came from another origin, often a wrong NANOBOM_PUBLIC_URL |
OpenID Connect sign-in refused | warn | A single sign-on attempt failed; error says why |
starting the OpenID Connect sign-in failed | error | The sign-in could not start, for example because discovery failed; error says why |
database error | error | An unexpected database failure |
Languages
The web interface is available in English and French. Each request is answered in:
- the language chosen in the account menu of the page header, remembered in the
nanobom_localecookie of that browser (it holds only the chosen language); - otherwise, the best match among the browser’s preferred languages (
Accept-Language); - otherwise, English.
The choice is per browser, not per account: signing in elsewhere starts from the browser’s preferences again. The choice works without JavaScript, like the rest of the interface.
Error messages of the interface are translated too. Some texts stay in English whatever the language:
- the upload API’s messages, since they end up in CI logs read by whoever maintains the pipeline;
- webhook payloads and logs, which are meant for programs, and the Slack and Microsoft Teams messages, since the language of a channel’s readers is unknown (emails are in the language chosen in the organization’s email settings);
- vulnerability descriptions, which come from OSV as published;
- the label of the single sign-on button, which is set by
NANOBOM_OIDC_BUTTON_LABEL.
Dates are shown in UTC.
Translations live in crates/app/locales/ (interface) and crates/domain/locales/ (messages of
the domain, such as validation errors), one JSON file per language. A message missing from a
language fails the build, so a release never shows a half-translated page. Adding a language is
described in Develop and contribute.
Concepts
Organizations
An organization owns projects, API tokens, a webhook, email recipients and members. Organizations are isolated: a member of one sees nothing of the others, and an organization you do not belong to answers “not found” rather than “forbidden”, so its name does not leak.
Each organization has a slug, which appears in addresses and upload URLs
(/organizations/acme, /api/organizations/acme/projects/web/sbom), and a display name. Slugs
are case-insensitive: Acme and acme are the same organization (the rules are in the
reference).
Members have one of four roles: viewer, member, admin or owner. Instance administrators act as owners of every organization.
By default every new user also gets a personal organization named after their username, which they own. It is an ordinary organization; the setting only saves a step for people working alone.
Projects
A project is one thing you ship: a service, a library, a container image. Admins create it on the organization page, or an organization-wide token creates it with its first upload (a project token never does: see tokens). Either way it comes with an upload token of its own, for its CI. Its slug follows the same rules as organization slugs.
A project holds the components of the last SBOM of each of its versions only. The history of uploads (when, to which version, from which commit or image tag, how many components) is kept; the components of older uploads are not.
Versions
A product often ships several releases at once: 3.x is current while 2.x still gets
security fixes. A version of a project is one of them. Each version has its own
components, findings and triage, so fixing lodash on the main branch does not hide that the
2.4 maintenance branch still ships the vulnerable one, and ignoring a finding in 2.4 does
not ignore it in 3.0, where the code may have changed.
CI names the version with each upload (version); a
project that never names one has a single, unnamed version and works as if versions did not
exist. One version is the latest: the project page, the read API and the VEX export show it
unless asked for another. A new version becomes the latest unless the upload says otherwise,
which is what a maintenance branch does (latest=false).
When an upload creates a version, the new version inherits the open and ignored findings of
the latest version, as Dependency-Track copies the audit trail when it clones a version: a
release branched from main has the same dependencies and the same reasons to ignore a
finding, and nobody should have to triage them again. Each inherited finding keeps its
status, its ignore (reason, justification, expiry) and its first-seen date, and its history
starts with one event naming the version it came from. The run after the upload then treats
inherited findings like any other: those whose component the new SBOM no longer has are fixed.
Inherited findings are not announced: they are not news, and announcing every finding of the latest version each time a release branch is cut would bury the findings that are. A vulnerability that appears in several versions at once (a new advisory against a dependency they share) is announced once per affected component, with the list of versions it affects (payloads). Fixed findings are not inherited: an ignore ends when its finding is fixed, so they carry nothing the new version needs, and a vulnerability fixed in the latest version but present in the new one is announced as new for it.
Organization pages count a vulnerability of a package once per project, at its highest
severity, however many versions have it; the gate of an upload (fail_on) judges the version
uploaded only. A finding’s page lists every version of its project with where it stands with
the vulnerability (open, ignored, fixed or not affected), which answers “which of our releases
need the fix?” without opening each one.
A version that is no longer shipped can be made inactive, Dependency-Track’s “active” flag: runs stop evaluating it, and it no longer counts, shows up in searches or sends notifications, while its findings and triage stay readable and exportable as they were. A release that went out of support is history worth keeping, not something to be alerted about. An upload to an inactive version makes it active again, since something still builds it. A version can also be deleted with everything it holds, which is never done automatically.
Inactive versions keep the database and the runs small: a project has at most 50 active versions. Rather than refusing the upload of a 51st, nanobom makes the version uploaded to the longest ago inactive. Dependency-Track has no cap, and its clients often send a build number as the version; refusing uploads would break those pipelines at the 51st build, while retiring the oldest version keeps them working and only puts aside builds nobody uploads anymore. The latest version is never retired that way, and is always active: it is the version everything shows by default (rules).
Uploads
An upload is one SBOM sent by CI. It replaces the components of one version of the project entirely: a component missing from the new SBOM is gone, and its findings in that version are fixed at the next run. Upload one SBOM per project, version and build, describing everything the version ships.
Components are identified by their package URL. Components without one are counted and listed in the upload’s response but cannot be checked. The SBOM’s dependency graph, when it has one, is kept with the components and tells which direct dependency of the project pulls in each one (Dependency paths). So is each component’s license, as the SBOM states it: one SPDX license expression, shown on findings and in search results (how licenses are read). An organization’s license policy allows, warns about or forbids licenses; the components that break it are computed from the last SBOM of a version whenever they are shown (License policies).
Runs
A run matches the components of a scope against OSV and updates the findings. Runs start:
- after each upload, for that project (
uploadtrigger); - on the schedule, for every project of the instance (
scheduled, by default every night at 03:00 UTC); - on demand, with Check now on an organization or project page (
manual).
Runs execute one at a time. A run that cannot complete, because OSV is unreachable for example, changes nothing: findings stay as they were, and the run is recorded as failed. A failure never reads as “no vulnerabilities”. See How findings are kept up to date.
Findings
A finding is one vulnerability affecting one component of one version of a project. It has a status:
| Status | Meaning | Becomes |
|---|---|---|
| Open | The vulnerability affects a current component | ignored by a member; fixed when the component goes away or OSV stops reporting it |
| Ignored | A member decided it does not apply or is accepted, with a reason | open when restored or when its expiry date passes; fixed like an open one |
| Fixed | No longer affects the project | open again (reopened) if a run reports it again |
Every change is kept in the finding’s history, with who did it, why, and which run.
upload / run reports it
│
▼
┌──────────► OPEN ◄───────────────┐
│ │ │ │ restored, or
│ ignored │ │ component gone, │ ignore expired
│ (reason) ▼ │ or OSV stops │
│ IGNORED ─┼─ reporting it ───┘
│ ▼
└── reopened ── FIXED
One vulnerability often has several identifiers: a GitHub advisory (GHSA-…), a CVE, a RustSec
or PyPA advisory. OSV lists them as aliases, and nanobom merges identifiers that are aliases
of each other into one finding: a CVE published after the GHSA does not create a second finding
(aliases).
Each finding has a severity, critical, high, medium, low or unknown, from the CVSS scores of its advisories (severity). Severity says how bad a vulnerability could be, not whether anyone exploits it; that is what the exploitation signals are for.
How findings are kept up to date
A project’s findings change for two reasons: its SBOM changed, or what OSV knows changed. nanobom notices both with runs.
When runs happen
| Trigger | Scope | When |
|---|---|---|
upload | the project | right after each upload (unless NANOBOM_RUN_AFTER_UPLOAD=false), or when an upload waits for its evaluation |
scheduled | every project of the instance | on NANOBOM_SCHEDULE, by default 0 3 * * *: every day at 03:00 UTC |
manual | an organization or a project | Check now on the organization or project page (members and above) |
The nightly run is what catches advisories published after a project’s last build: new
advisories appear for old versions all the time. Turning it off (NANOBOM_SCHEDULE=off) means a
project that is not rebuilt is never re-checked, and stale projects are never notified. It is
also why a CI gate can fail without a code change.
One run at a time
Runs execute one after the other, in the order requested. A request for a scope that is already
waiting in the queue is merged with it: twenty uploads to the same project during a long run
cause one more run, not twenty. Since runs share one queue, a manual check or a waiting upload
can sit behind the nightly run of a large instance; the run’s duration is in the
nanobom_run_duration_seconds metric.
Failed runs
A run fails when OSV cannot be reached (after three attempts per request, for network errors,
rate limiting and server errors) or answers something unexpected. Apart from returning expired
ignores to open, a failed run changes no finding: they stay as the last successful run left them,
so a failure never reads as “no vulnerabilities”. It is listed as Failed under Recent
runs, counted by nanobom_run_failures_total, and sent to NANOBOM_FAILURE_WEBHOOK_URL if set.
Recent runs on an organization page lists the runs of that organization and its projects, and the instance-wide scheduled runs. The error message of an instance-wide run can name other organizations’ packages, and its counts of new and fixed findings span every organization, so only instance administrators see them; others read “the run could not complete” and no counts.
A run that stops before it can record its end is recorded as failed with the error “the run stopped unexpectedly”, counted and sent to the failure webhook like any failed run. That happens right away when a bug makes the run panic (the queue goes on with the next run), and at the next start when nanobom was stopped or crashed during the run. Such a run is not resumed; the next run of the same scope does its work.
Matching against OSV
A run:
- returns findings whose ignore has expired to open;
- collects the components of its scope that have a version, and queries OSV’s batch API once per distinct package URL (qualifiers and subpath removed), up to 1,000 per request;
- downloads the details of each reported vulnerability it does not have yet, or that OSV modified since; details are cached in the database, so a nightly run of an unchanged instance downloads little more than the batch answers;
- updates the findings of each project in one transaction.
OSV gathers advisories from many databases (GitHub, PyPI, Go, RustSec and others), each under its own license, listed on OSV’s data sources page. The About page of the interface links to it, and shows when this instance last completed a run for you.
After a successful run, exploitation data is refreshed for the run’s scope (Prioritization), then webhooks are sent.
How findings change
For each component and each group of reported vulnerabilities that are aliases of each other:
- if the project has no finding for it, a finding is opened;
- if it has a fixed one, it is reopened;
- if it has an open or ignored one, it stays as it is, and its severity is updated if the advisory changed.
Then every open or ignored finding of the project that was not reported is fixed: its component left the SBOM, was upgraded to an unaffected version, or OSV withdrew or changed the advisory.
A finding belongs to one component, identified by its full package URL: upgrading lodash from
4.17.20 to 4.17.21 fixes the findings of pkg:npm/lodash@4.17.20 and opens findings for the
new version, if it has any.
Aliases
OSV records list the identifiers of the same vulnerability in other databases: a
GHSA-35jh-r3h4-6jhm record has CVE-2021-23337 as alias. When OSV reports several identifiers
for one component, nanobom groups those that share an alias (directly or through others), and
makes one finding per group:
- a new finding is named after the smallest reported identifier of its group;
- later runs find it through any identifier of the group, so a CVE assigned after the GHSA was published, or a new RustSec advisory for the same issue, updates the existing finding instead of opening another;
- the finding page and webhooks list the other identifiers as aliases.
Severity
The severity of each record comes from its CVSS vectors, scored by nanobom:
- the vector of the most recent CVSS version the record has (4.0, then 3.1, 3.0, 2.0) gives a base score, rated critical from 9.0, high from 7.0, medium from 4.0, low below (0.0 included);
- without a usable vector, the qualitative rating of the advisory database
(
database_specific.severity, as GitHub advisories give:CRITICAL,HIGH,MODERATE,LOW); - otherwise unknown.
A finding takes the highest severity among the records of its group, so a GitHub advisory and the CVE it aliases that rate the same issue differently show the higher. Severity is recomputed at every run, so a re-scored advisory moves the finding.
Unknown is not “harmless”: it means no score was published yet, which is common for fresh advisories of some ecosystems. Unknown findings are listed after low ones and never trip a severity gate.
Ignored findings
An ignored finding:
- is left out of the open counts, of the CI gate (
fail_on) and of the metrics; - does not trigger webhooks;
- is still tracked: if its component goes away it becomes fixed, and it still gets exploitation data, so you can see if an ignored vulnerability becomes known exploited.
Its expiry is midnight UTC at the start of the given date. It takes effect at the next run
covering the project, which is the nightly run at the latest: the finding returns to open, with an
Ignore expired entry in its history, and is then counted again. It is not notified as new;
only as exploited, if it became known exploited while ignored.
Stale projects
A project is stale when its last upload, or its creation if it never received an SBOM, is
older than NANOBOM_STALE_AFTER_DAYS (30 by default). It usually means its CI job broke or was
removed, and its inventory no longer describes what runs in production.
Stale projects are:
- flagged Stale on the organization page, with an alert on the project page;
- counted by the
nanobom_stale_projectsmetric; - sent to the organization’s webhook as
projects.stale, after a scheduled run, once per stale period.
A stale project keeps being checked by the nightly run: its old inventory still gets new advisories.
Prioritization
Severity tells how bad a vulnerability could be. Most critical vulnerabilities are never exploited, and some medium ones are exploited widely. A project with a few hundred dependencies easily has dozens of findings, so severity alone does not say where to start. nanobom adds two public signals of actual exploitation to each finding that has a CVE, and lists findings by them first.
The signals
Known exploited (CISA KEV). The US Cybersecurity and Infrastructure Security Agency keeps the Known Exploited Vulnerabilities catalog: vulnerabilities with reliable evidence of exploitation in the wild. A finding with a CVE in it is known exploited, and shows:
- the date CISA added it;
- its due date, the deadline CISA sets for US federal agencies to remediate it;
- whether it is known to be used in ransomware campaigns.
Someone exploits these in the wild, which makes them the most urgent; CISA’s due date is a fair deadline for anyone.
EPSS. FIRST’s Exploit Prediction Scoring System estimates the probability that a CVE is exploited in the next 30 days, from 0 to 1, and its percentile among all scored CVEs. An EPSS of 0.0149 with a percentile of 0.78 means “1.5% chance, higher than 78% of CVEs”. It is a ranking aid, not a verdict.
Both are public data: CISA distributes the KEV catalog under the Creative Commons 0 1.0 license, and FIRST publishes EPSS freely, asking products that use it for credit (the interface says “EPSS scores by FIRST.org” on its About page, along with when each was last read).
Only CVE identifiers are looked up: those among the finding’s identifier and its aliases. A finding known only by a GHSA or RustSec identifier, with no CVE alias, has neither signal. When a finding has several CVEs, it takes the most alarming value of each signal: known exploited if any of them is, the earliest due date, the highest EPSS score.
Ordering
On the project page, findings are listed:
- known exploited first;
- then by severity, critical first;
- within a severity, by EPSS score, highest first; findings without a score last;
- then by CVSS score.
The upload response’s evaluation.findings is ordered by severity first (its 100 entries keep
the most severe), and within a severity in the order above.
The project page tags them KEV, counts them in its summary of open findings, and its filter
Only known exploited vulnerabilities keeps them alone; the organization page counts them per
project in its KEV column, and the nanobom_open_findings_known_exploited metric counts
them across the instance. A CI gate with fail_on=exploited fails on them whatever their
severity.
When the data is refreshed
After each successful run, nanobom refreshes the data of the CVEs of the run’s scope (those of open and ignored findings):
- the KEV catalog is downloaded and kept in memory for 12 hours, so most runs reuse it;
- EPSS scores are fetched, 100 CVEs per request, for the CVEs whose score is older than 24 hours.
The two feeds fail separately:
- when the KEV catalog cannot be downloaded, the copy in memory is used even if it is older than 12 hours, and without one (just after a restart) the KEV data stored for each CVE is kept as it was; EPSS scores are refreshed either way;
- when EPSS cannot be reached, the KEV data is still written from a freshly downloaded catalog,
so a newly exploited CVE is notified and fails
fail_on=exploitedgates during an EPSS outage; the EPSS scores stored for each CVE are kept as they were; - when both fail, nothing is written: the previous data is kept for every CVE.
The run itself is not affected by a failed refresh. Failures, including a failure of one feed
while the other was stored, are logged (refreshing exploitation data failed) and counted once
per refresh by nanobom_exploitation_refresh_failures_total.
Three bounds keep an outage of those services from slowing nanobom down:
- the KEV download and the EPSS requests each get 25 seconds, retries included; a feed that does not answer in time has failed, and the other is still refreshed and stored;
- a refresh taking more than 60 seconds is abandoned (and counted as failed), because uploads waiting for their evaluation are answered only after it;
- after a failed download of the KEV catalog, it is not asked again for 5 minutes, so a series of uploads during an outage does not wait for the retries each time.
The refresh comes before waiting uploads are answered so that fail_on=exploited sees the CVEs
first reported by that very run.
A vulnerability added to the KEV catalog after it was first reported is noticed at the next
refresh of a run covering it, at the latest the nightly run, and is notified once with the
exploited reason (see findings.new).
Limits
- The signals only cover CVEs; ecosystems whose advisories rarely get a CVE get few signals.
- EPSS predicts, it does not observe; KEV lists only what CISA has evidence for. Neither says whether the vulnerable code is reachable in your project: that is what triage records.
- Instances that cannot reach CISA and FIRST can use mirrors or turn the data off (Run without internet access); with it off, no finding is known exploited.
Dependency paths
A finding names the vulnerable component, which is often deep in the dependency tree: lodash 4.17.20, required by a template engine, required by the web framework the project uses. The
project’s manifest names the web framework, not lodash, so that is what a developer upgrades.
When the SBOM describes its dependency graph, nanobom shows that link: the finding was
introduced via the web framework.
Where the graph comes from
A CycloneDX document describes the project itself in metadata.component, and its dependency
graph in dependencies: one entry per component, by bom-ref, listing the components it
depends on directly.
{
"metadata": { "component": { "name": "shop", "bom-ref": "shop" } },
"components": [
{ "name": "web-framework", "bom-ref": "framework", "purl": "pkg:npm/web-framework@2.1.0" },
{ "name": "template-engine", "bom-ref": "engine", "purl": "pkg:npm/template-engine@0.9.0" },
{ "name": "lodash", "bom-ref": "lodash", "purl": "pkg:npm/lodash@4.17.20" }
],
"dependencies": [
{ "ref": "shop", "dependsOn": ["framework"] },
{ "ref": "framework", "dependsOn": ["engine"] },
{ "ref": "engine", "dependsOn": ["lodash"] }
]
}
An SPDX document gives the same information as relationships between packages (DEPENDS_ON,
DEPENDENCY_OF), the project being the package the document describes; generators fill them
less consistently (see SPDX documents).
The components the project’s own entry lists are its direct dependencies. Each upload stores the graph between the components it keeps, and replaces the previous graph along with the components: like the components, the graph is always the latest SBOM’s.
How paths are chosen
For a vulnerable component, nanobom finds every direct dependency that leads to it and, for each, the shortest path from it to the component. They are shown shortest first:
- on the finding’s page, under Introduced via:
web-framework 2.1.0 → template-engine 0.9.0 → lodash 4.17.20. A component that is itself a direct dependency is a path of its own, marked direct dependency. At most 5 paths are shown; the others are counted. - on the project page, in the Introduced via column: the direct dependencies, the first two by name (with their versions only when several versions of one lead to the component) and how many more, or direct when the component is one itself; the column is left out when no finding listed has one to show;
- in webhooks and in the
evaluation returned to CI, as
introduced_via: the names of the direct dependencies.
When several paths of the same length lead from a direct dependency, one of them is shown. Paths longer than 32 components are not followed. The graph may have cycles; they do not change the result.
A component that is a direct dependency and is also required by other direct dependencies lists them all: they may keep requiring the vulnerable version after you upgrade your own.
Limits
A path may be missing, and with several copies of a package it may combine them, but every link in it is in the SBOM: nanobom shows no path rather than a guess.
- No graph, or no project in it. Without any dependency of the project itself, nothing is derived, and the finding’s page says the SBOM does not tell which components the project depends on directly. nanobom does not take the components nothing depends on for the direct dependencies: in an environment, a package the project requires directly is often required by another one too, and the guess would hide it.
- Components that are not stored. The graph is kept between the components nanobom stores, those with a package URL. An edge to or from a component without one, or a file, is dropped rather than bridged, so a path never skips a component: a component reached only through one is not linked to the project. When the graph enters and leaves such a component, the finding’s page adds that some links could not be followed, and other paths may exist.
- References shared by several packages. A
bom-ref(anSPDXIDin SPDX) is meant to be unique. When two components with different package URLs carry the same one, nanobom cannot tell which one an edge means, so it drops every edge that names it, and says so like above. The note is the same for both formats and is stored with each upload. - Copies of a package. Paths are between packages, identified by package URL, not between
installed copies of them. Components with the same package URL are stored once, with the
edges of all their copies: if two nested copies of
foo 1.0.0in an npm tree resolvedepto different versions,foo 1.0.0leads to both, and a path throughfoo 1.0.0may combine the link of one copy with a link into the other. Each link exists in the SBOM, but the whole path may not match one installation. - Gone components. A finding whose component is no longer in the latest SBOM has no path, and its page does not show the card.
Generators fill the graph unevenly. With the versions nanobom is tested with:
| Generator | Graph | Paths |
|---|---|---|
| cargo-cyclonedx 0.5.9 | complete, from the crate | yes |
| cyclonedx-npm 6.0.1 | complete, from the package | yes |
cyclonedx-py 8.0.1, environment | between installed packages; no metadata.component | no |
| Syft 1.57.0, CycloneDX, on an image | between packages; the image is in metadata.component, but nothing links it to them | no |
| Syft 1.33.0, SPDX, on an image or a lock file | between packages; the image or directory only contains them | no |
| Trivy 0.76.2, SPDX, on a lock file | through the lock file’s entry, which has no package URL | no |
GitHub dependency graph export (SPDX), package-lock.json | complete, from the repository | yes, except for direct dependencies that have no dependency and that no other package depends on (why) |
GitHub dependency graph export (SPDX), Cargo.lock | the repository depends on every crate, none on another | no |
Whether your generator links the project to its dependencies shows in its output: the entry of
dependencies whose ref is the bom-ref of metadata.component in CycloneDX, the
DEPENDS_ON relationships of the described package in SPDX.
A path says how a package gets installed, not that its vulnerable code is called: that is still what triage decides (Triage findings). The graph is the one the generator resolved, with the same options: development dependencies left out of the SBOM are left out of the paths.
SPDX documents
nanobom was built around CycloneDX, and reads SPDX by mapping it onto the same inventory: the same components, identified by the same package URLs, matched against OSV the same way. What a project shows does not depend on the format, except for the dependency graph, which SPDX generators describe less consistently. The exact mapping is in the upload API reference; this page explains its choices and what is lost.
Packages and the project
An SPDX document lists packages, and says which of them it is about with a DESCRIBES
relationship. nanobom keeps the packages that have a package URL, like CycloneDX components, and
treats the described package as the project, like the CycloneDX metadata.component. A
package without a package URL is skipped and reported to CI the same way in both formats. A
package with several package URLs (several purl references) gets the first one: CycloneDX
gives a component one package URL, and the others usually name the same package in another
ecosystem’s terms.
Generators also disagree on which fields they fill. nanobom reads a null or missing field as
absent rather than refusing the document, even for fields SPDX requires: a package without a
name is still matched by its package URL, a relationship missing one of its ends is ignored.
Two packages with the same SPDXID break the document’s own rules. If they have the same
package URL, nothing is lost; otherwise a relationship naming that identifier cannot be traced
to one of them, so it is ignored rather than attributed to either, and the graph is marked
incomplete.
Generators do not describe the same thing. Syft and Trivy describe what they scanned (a
directory or an image), GitHub describes the repository. None of these is a package of an
ecosystem OSV covers, so leaving the described package out loses nothing; but a package of your
own (pkg:cargo/your-crate@0.1.0, found in the scanned lock file) stays a component, as it does
in their CycloneDX output.
SPDX files and snippets are ignored: OSV matches packages, not files.
Dependency graph
A CycloneDX document names the project’s direct dependencies in one place: the dependencies
entry of metadata.component. SPDX expresses dependencies with relationships (DEPENDS_ON,
DEPENDENCY_OF and its variants, CONTAINS), and generators use them differently:
- Syft writes
DEPENDENCY_OFbetween packages when the lock file gives them, and makes the scanned directory or imageCONTAINSevery package, direct dependency or not. Containment is therefore not read as a dependency of the project: it would make every package direct.CONTAINSbetween two packages (an archive bundling a library) is read as a dependency. - Trivy hangs the direct dependencies from an entry for the lock file, which has no package URL. nanobom does not bridge edges through packages it does not store, so the project’s direct dependencies are not known, as with Trivy’s CycloneDX output.
- GitHub’s dependency graph export makes the repository
DEPENDS_ONits dependencies. Forpackage-lock.jsonthese are the direct dependencies, development ones included, withDEPENDS_ONbetween packages below them. ForCargo.lockthe repository depends on every crate, transitive ones included, with no edge between crates.
The last case would show every crate as a direct dependency, and a repository can hold such a flat list next to a graphed lock file of the same ecosystem (two npm projects in one repository, for example). Nothing in the document tells the two apart, so nanobom keeps an edge from the project to a package only when that package is also linked to another package, as a dependency or a dependent. A flat list is then ignored: the path is missing rather than wrong, the rule of Dependency paths. The price is a direct dependency that depends on nothing and that no other package depends on, such as a small utility library: it gets no path, even from a complete graph. A project whose only dependencies are such packages gets no path at all.
In practice, introduced via is shown less often for SPDX uploads than for CycloneDX ones from the ecosystem’s own generator. If you rely on it, prefer a CycloneDX generator that describes the project (cargo-cyclonedx, cyclonedx-npm).
Versions and serializations
- SPDX 2.2 and 2.3 JSON share the fields nanobom reads; SPDX 2.2 spells the purl category
PACKAGE_MANAGERand may name the project indocumentDescribes, both accepted. - Tag-value and RDF are other serializations of the same model. Every generator that writes them also writes JSON, so nanobom refuses them with a message saying so rather than carrying three parsers.
- SPDX 3.0 is a different model (a JSON-LD graph of elements), and no maintained Rust library reads it. It is refused with a message naming the supported versions; generators still default to SPDX 2.3.
What else is lost
Nothing nanobom uses for CycloneDX is missing from SPDX, with two differences besides the graph:
- Version requirements. GitHub’s export gives the manifest’s requirement (
^6.1.2) for packages no lock file pins. A requirement is not a version: OSV would match it against the wrong releases, so such packages are skipped and reported inskipped. The same rule applies to CycloneDX documents, where generators rarely write requirements. - Serial number. SPDX has none; the document namespace, a URI unique to each document, is recorded in its place.
VEX
An SBOM lists what a product contains; matched against vulnerability databases, it yields every vulnerability of every component. Most do not affect the product: the vulnerable function is never called, the feature is not compiled in, the attack needs a configuration nobody uses. A customer or an auditor who receives the SBOM finds the same long list and cannot tell.
VEX (Vulnerability Exploitability eXchange) is the answer to that list: a statement, per
vulnerability and component, of whether the product is affected, and why not when it is not. In
CycloneDX, it is the analysis of each entry of vulnerabilities: a state (not_affected,
exploitable, in_triage, resolved…), a justification for not_affected, and free text.
Why it matters now
Customers increasingly ask for one, and regulation is following. The EU Cyber Resilience Act requires manufacturers of products with digital elements to identify and document the components and vulnerabilities of their products, with an SBOM, and to handle vulnerabilities without delay. A VEX document is the usual way to show that handling for each vulnerability the SBOM reveals, in a form tools can read.
What nanobom says, and what it does not
nanobom’s triage already holds the information: an ignored finding has a reason. What a reason lacks is a form a machine can read, and a distinction between “does not affect us” and “we accept the risk”. Hence the justification of an ignore, from the CycloneDX vocabulary, and these choices in exports:
- Only a justification makes a
not_affected. An ignore with just a reason is often an accepted risk or a postponed fix. Telling a customer it does not affect the product would be a claim nobody made, so it is exported asin_triage, with the reason as detail. - Open is
in_triage, neverexploitable. nanobom knows when a vulnerability is exploited in the wild (CISA KEV), not whether this product exposes it. Being exploited somewhere does not make it exploitable here, and statingexploitablewould be as unfounded as statingnot_affected. - Fixed is
resolved. A fixed finding’s component is often gone or upgraded, so the statement is about a version the product no longer contains. It stays in the document as the record of what was handled. - False positive is kept apart. CycloneDX has a
false_positivestate for a vulnerability wrongly associated with a component. nanobom offers it alongside the justifications so an ignore can say it, and an import offalse_positiveround-trips.
Importing statements
Imports turn others’ statements, or your own kept in a repository, into ignores, so the same
decision is not made twice and the CI gate stops failing on what was already analysed. Only
not_affected and false_positive act; the other states inform and change nothing, since
reopening or prioritizing a finding on someone else’s word is a decision for a member.
Matching is deliberately strict. A statement must name the vulnerability (by any alias) and the
component’s exact version: a statement written for lodash 4.17.20 says nothing about
4.17.21, which may contain other code. Version ranges (affects[].versions) are not read for
the same reason.
An import is attributed to the upload token that sent it, not to a person: tokens are how CI acts, and whoever reads the history sees where the decision came from. Restoring an imported ignore works as for any other; a later import of the same statement ignores the finding again, so fix the statement rather than the finding.
Limits
- CycloneDX only. OpenVEX, CSAF VEX and SPDX security information are not read or written.
OpenVEX describes the same idea with other justifications
(
vulnerable_code_not_in_execute_path,inline_mitigations_already_exist…) that map only partly onto CycloneDX’s; nanobom is CycloneDX-native throughout, so it stays with one vocabulary rather than translate lossily. Converters exist between the formats. - The export describes the current state of the project, with the findings of its latest SBOM; nanobom keeps no history of exports or per-release VEX documents.
- References to elements of another document (BOM-Links whose fragment is a
bom-refrather than a package URL) cannot be resolved, since nanobom does not keep thebom-refs of uploaded SBOMs. - Responses (
can_not_fix,update…) andaffects[].versionsare neither read nor written.
License policies
A component’s license is rarely one identifier. npm packages declare (MIT OR Apache-2.0),
Rust crates MIT OR Apache-2.0, firmware bundles GPL-2.0-only AND BSD-3-Clause. A policy
written as a list of identifiers (allowed, warned, forbidden) has to say what such an
expression means. This page explains the choices nanobom makes; the rules themselves are in the
license policy reference.
OR is a choice, AND is an obligation
SPDX gives the two operators precise meanings. A OR B means the licensor offers both, and
whoever redistributes the component picks one: a dual-licensed MIT OR GPL-3.0-only library
can be shipped under MIT, and the GPL never applies. A AND B means both apply at once,
usually because parts of the component come under different licenses: shipping
MIT AND GPL-3.0-only means complying with the GPL.
So nanobom keeps the least severe side of OR, the choice you would make, and the most
severe side of AND, the obligation you cannot avoid. Nested expressions follow the same
rule from the inside out, with SPDX’s precedence (AND binds tighter than OR). The verdict
also names the licenses that decided it: on MIT AND (GPL-3.0-only OR LGPL-2.1-only) with
GPL forbidden and LGPL warned, the verdict is a warning because of LGPL-2.1-only, which is
what to look at.
Choosing the least severe side assumes you do choose it. Shipping a dual-licensed component under MIT is a decision your notices and attributions must reflect; nanobom records the licenses, not the decision.
Several license entries are combined with AND
A CycloneDX component may list several license entries without saying whether they are
alternatives. nanobom joins them with AND when it reads the SBOM
(how): reading two licenses as two obligations can
only produce a warning you then review, while reading them as a choice could hide a forbidden
license. Generators that mean a choice can write one expression with OR.
Unknown is never better than what it names
An expression that is not valid SPDX (a free-text name such as Apache License 2.0, an
identifier outside the SPDX list, broken parentheses) is unknown: judging the valid part alone
would be guessing, since in MIT AND Some-Custom-License the unrecognized part might be the one
that matters. So it gets at least the action for unknown licenses, even when every identifier it
names is allowed.
It can get more. Invalid text often still names real licenses, for instance when a CycloneDX
component lists a free-text name next to an SPDX identifier and nanobom joins them, giving
(GNU Affero General Public License v3) AND AGPL-3.0-only. Taking the action for unknown
licenses alone would let a forbidden AGPL-3.0-only through only because the text next to it
is not SPDX. nanobom therefore also reads the identifiers in the text and keeps the most
severe action, as if they were all joined with AND: without a valid expression, an OR
cannot be trusted to offer a choice. The result errs on the side of a warning or a block you
then review, never on a forbidden license passing. nanobom does not guess identifiers either
(Apache is not taken for Apache-2.0), for the same reason. Identifiers and operators are
compared without case, since SPDX says case does not matter, and SBOMs in the wild write mit
and Apache-2.0 or MIT.
Reading prose for identifiers has a cost of its own: close to 200 SPDX identifiers are
letters only, many of them ordinary words such as Intel, Ruby, JSON or MIT (the German
“mit”). With an allowlist, every such word would be a forbidden license, and
Intel Simplified Software License would fail the gate. So an identifier made of letters only
counts when it stands alone between separators (parentheses, operators, ,, ;, /), the way
generators write a license next to free text, while an identifier with a digit, -, . or
+, which prose does not produce by accident, counts anywhere, even glued to punctuation
(Licensed under AGPL-3.0-only.).
Computed when read, not stored
Violations are not a table that runs fill in, unlike findings. They depend only on the project’s latest SBOM and the current policy, so they are computed each time a page, the API or an upload asks. Changing the policy applies to every project at once, without a run, and the policy cannot drift from what was evaluated. The cost is small: each distinct license of a project is evaluated once, and the database counts the components.
The trade-off is history: nanobom keeps no record of past verdicts, and no webhook reports a new violation. The upload gate is where a new forbidden license is caught, at the moment it enters the project.
Only forbid fails the gate
warn exists for licenses that need a look but not a block: weak copyleft such as MPL-2.0,
or unknown licenses while generators are being fixed. fail_on=license fails only on forbid,
so warnings can be added without breaking pipelines. Licenses are read from the uploaded SBOM,
not found by the run, so a failed or slow run does not stop the license gate from answering.
What this is not
A license policy here is a list of SPDX identifiers with three actions. nanobom does not detect licenses from source files, does not track obligations such as attribution or source distribution, and does not produce notices. It answers one question at the point where code ships: does this project contain a license we decided not to accept?
Tokens and scopes
CI pipelines, scripts and dashboards talk to nanobom without a person behind them, so they authenticate with tokens rather than user accounts. This page explains how a token’s reach and scope combine, and which token to give to what. The facts (headers, endpoints, commands) are in the upload API, read API and MCP endpoint references.
Two independent choices
A token is created with two answers:
- Reach: the whole organization, or one project of it. It bounds what the token sees and touches.
- Scope: what the token may do within its reach.
| Scope | Uploads SBOMs | Imports VEX documents | Creates projects | Reads (read API, VEX export, MCP) |
|---|---|---|---|---|
upload | ✓ | ✓ | organization tokens only | ✓ |
read | ✓ |
Whatever its scope, a token reads like a viewer of what it reaches: the same checks as the
interface decide, in the same place, so a token never sees more than a viewer of its
organization would, and a project token sees one project. Anything out of reach looks missing
(404), so a token cannot learn which other organizations or projects exist.
Why upload tokens also read
An upload token already receives the project’s open findings when CI waits for the evaluation, and its VEX export lists every finding. Refusing it the read API would protect nothing while forcing CI to hold two secrets. The scope that matters is the reverse one: a token that can only read.
Why read tokens exist
An upload token can change what nanobom reports. It replaces a project’s components, so an SBOM that leaves out a vulnerable package fixes its findings; it imports VEX statements, which ignore findings. A leaked upload token can therefore hide vulnerabilities.
A dashboard, a spreadsheet export or an issue-tracker integration needs none of that. Giving it
a read token means a leak exposes the findings, which is serious, but cannot change them: the
upload, VEX import and Dependency-Track routes refuse read tokens with 403, and the check is
made again in the domain layer, so a future route cannot forget it.
Every project comes with a token
A project created in the interface could not receive anything until someone created a token for it, and a token shown once must be copied at once, or created again. So every project comes with an upload token of its own, shown on its page to admins and owners for as long as it is in use, next to a workflow step ready to paste: create the project, copy two lines into CI, done. This is how CI services such as Codecov enroll a repository.
The price is that nanobom keeps that token’s value, where other tokens keep only a digest (security model). The token is renewed rather than revoked, so a project never lacks one; named tokens stay for everything else: a second pipeline that should be revoked on its own, a read-only integration, CI that creates projects.
Choosing a token
| Tool | Token |
|---|---|
| CI of one repository | the project’s upload token, or another upload token reaching that project |
| CI that creates projects on the fly (a monorepo, a fleet of images) | upload, reaching the organization |
| A dashboard or report over the organization | read, reaching the organization |
| An integration about one project (its own issue tracker) | read, reaching that project |
Prefer the narrowest reach that works: a project token limits a leak to one project.
Tokens and people
Tokens are not user accounts. They do not sign in to the interface, belong to no user, and keep
working when the admin who created them leaves; revoke them in Settings → API tokens or with
nanobom token revoke, and renew a project’s upload token on its page or with
nanobom project token --renew. A person who wants to call the API from a browser does not need a token:
pages of the instance can call the read API with the session, and then read what that person
sees, with their role.
Security model
This page explains what protects what, and why, for whoever reviews a deployment.
Organization isolation
Every operation on organization data goes through one access check, in the domain layer that
both the interface and the API use, not in the pages. It resolves the user’s role in the
organization (the higher of the role given in nanobom and the one from identity provider groups)
and compares it with the permission the operation needs (see
Roles and permissions). Organizations a user does
not belong to answer “not found”, so their existence does not leak; the upload API answers 404
for an organization that is not the token’s for the same reason. Instance administrators act as
owners everywhere.
Shared data is limited to what is not organization-specific: cached OSV records and exploitation data per CVE. The error message of a failed instance-wide run can name packages of any organization, and its counts of new and fixed findings span all of them, so both are shown to instance administrators only, and the failure webhook should reach operators rather than an organization’s channel.
API tokens
- 256 bits of randomness, prefixed with
nanobom_so secret scanners (and you) can recognize them in logs and repositories. - Stored as a SHA-256 digest. A slow password hash is unnecessary for random values of that length, and would slow every upload down.
- Except each project’s own upload token, whose clear value is also stored, so that the project page can show it again and a new project is ready for CI without a token to create and copy at once. This is the trade-off CI services such as Codecov make for their upload tokens, and the one nanobom already makes for webhook URLs (which may embed a secret) and badge keys: whoever reads the database, or a backup of it, can upload SBOMs and import VEX documents to every project, and so hide their vulnerabilities. They could already read every finding and change any row, so the database is the boundary either way. Only admins and owners see the value; it is never in a token list, an API response or the page of a member or viewer. It cannot be revoked, only renewed, which stops the old value at once.
- Limited to an organization or one project; they reach the upload, VEX and read APIs and the MCP endpoint only, never the interface. A project token limits a leak to one project, and cannot create projects. Every token reads the findings of the projects it reaches, as a viewer, through the same checks as the interface.
- An
uploadtoken can also replace components and ignore findings by importing VEX statements: a leaked upload token can hide vulnerabilities, so treat it like the SBOM pipeline it belongs to. Areadtoken cannot change anything: every write path refuses it, in the server and again in the domain layer. Give tools that only read a read token (Tokens and scopes). - Shown once (except the project’s upload token); revocable (the project’s upload token is renewed instead); their last use is recorded, to the minute: a token used again within a minute does not write to the database, so reads stay reads.
The upload API is not exposed to cross-site request forgery: it is authenticated by the
Authorization header (X-Api-Key for the Dependency-Track API), which browsers never add on
their own. The read API also accepts the session cookie, so the interface’s pages can use it;
it only answers GET requests and changes nothing, and since it sends no CORS headers, a page
of another site cannot read its answers. Its responses are Cache-Control: private, no-cache
and vary on the cookie and token headers, so a shared proxy cannot serve what one caller
obtained to another.
The MCP endpoint is driven by POST requests, so it accepts tokens only,
never the session cookie, and refuses any request with an Origin header: a browser cannot
send it a request with the user’s credentials, and no web page can drive it. It reads what the
read API reads, through the same checks, and has no tool that writes. Advisory text it returns
comes from third parties and could try to steer the assistant reading it; nanobom marks it as
data, and a read token keeps a misled assistant from changing anything
(Query nanobom from an assistant).
Sessions and cookies
The session cookie, nanobom_session, holds only a random session identifier; sessions are
stored in the database, so they survive restarts and can be ended from the server. It is:
HttpOnly, out of reach of scripts;SameSite=Lax, not sent with cross-site form submissions;SecurewhenNANOBOM_PUBLIC_URLishttps, so it is only sent over TLS.
Sessions end after NANOBOM_SESSION_INACTIVITY_DAYS without activity, on sign-out, on a password
change and when the user is disabled.
The language cookie, nanobom_locale, only holds the chosen language.
Cross-site request forgery
State-changing requests from the interface (form submissions, which all use POST) are refused
with 403 when:
- the browser reports them as cross-site (
Sec-Fetch-Siteother thansame-originornone), or - their
Originheader differs from the origin ofNANOBOM_PUBLIC_URL.
Together with SameSite=Lax cookies, which browsers do not send with cross-site POST requests,
this covers current and older browsers without a token in every form. Requests carrying an
Authorization header are not checked, since they do not rely on cookies, and neither are
requests carrying neither Sec-Fetch-Site nor Origin: browsers send at least one of them on a
cross-site POST, so such requests come from other clients, which a cookie-based attack cannot
use. This is why NANOBOM_PUBLIC_URL must match the browser’s address bar exactly.
Passwords and sign-in
- Local passwords are hashed with Argon2id. The minimum length is configurable, with no composition rules: length is what makes a password strong, and a password manager is the way to get one.
- Password sign-in is rate limited per client address (a burst of 5, then one attempt every 4
seconds). Behind a proxy, nanobom sees the proxy’s address as the client of every request, so
all users would share one budget;
NANOBOM_TRUST_FORWARDED_HEADERSreads the address from the proxy’s headers instead. It must stay off unless a proxy you control sets them: otherwise any client can send a made-up header and escape the limit. - Redirects after sign-in only go to paths of the same site.
Single sign-on
- OpenID Connect uses the authorization code flow with PKCE, a
stateand a nonce, and verifies the ID token’s signature, issuer, audience and expiry, and the access token hash when present. - Users are matched by issuer and subject, never by email address: an attacker who can set an arbitrary email address at a provider cannot take over an account. The price is that a local account and a single sign-on identity with the same address stay two users.
- The discovery and token requests do not follow redirects, so the issuer cannot be used to make nanobom request other addresses.
- The provider is the authority for its users: with an administrator claim configured, it grants and removes instance administration at each sign-in, and roles from groups follow the user’s groups. A user who loses a group keeps its role until their next sign-in; disabling the user cuts access at once.
HTTP headers
Every response carries X-Content-Type-Options: nosniff, Referrer-Policy: same-origin,
X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none', which prevent
nanobom from being framed by another site. HSTS is left to the TLS-terminating proxy.
Advisory text
Advisories come from OSV and their description is Markdown written by third parties. A finding’s page shows it formatted, and treats it as untrusted:
- HTML in the description is shown as text, never interpreted.
- A link is kept only when it leads to an
http,httpsormailtoaddress, and carriesrel="noopener noreferrer nofollow". Any other link, relative ones included, is reduced to its text. So is an address made to mislead: a web address with user information before its host, amailtoaddress that fills in a subject or a body, an address holding characters that change the direction of text. - An image is never shown, so opening a finding makes the browser request nothing from a third party: it is replaced by a link to its address when that address is allowed, by its alternative text otherwise.
- A description that is very long (over 256 KiB), or built to grow out of proportion once formatted, is shown as plain text.
The addresses listed under References follow the same rule: one that is not allowed is shown without a link. The read API returns the description as published.
Outbound requests
nanobom makes requests to:
- OSV (
NANOBOM_OSV_URL), during runs; - CISA and FIRST (
NANOBOM_KEV_URL,NANOBOM_EPSS_URL), after runs, unless exploitation data is off; - the OpenID Connect provider, at sign-in;
- webhooks: organization webhooks set by organization admins, and the failure webhook;
- the SMTP server (
NANOBOM_SMTP_URL), for emails to the recipients organization admins set. Recipients are not verified and any signed-in user can create an organization, so test emails are rate limited per organization, per user and for the instance, and name the organization by its slug rather than its free-text display name.
Organization admins can make nanobom POST to any http or https address they choose,
including addresses on its own network. If nanobom runs next to services that trust their
network, restrict its outbound traffic with a firewall or an egress proxy.
Webhook requests are not signed: receivers should treat them as a hint to look at nanobom, not as an authority, and keep their URL secret.
Unauthenticated endpoints
/healthz, /metrics, the sign-in page and static assets need no session; the upload API needs a
token. Metrics are instance-wide counts; restrict /metrics at the proxy if even those should
stay private. None of them names the running release, so that an anonymous visitor cannot tell which
instances run a release with a known flaw. Signed-in users see it at the bottom of each page and
on the About page; holders of a token see it in the report and VEX documents and in the MCP
server’s information.
Project badges (/badges/…) need no session either: the random key in
their address is their authorization, and it unlocks only the open finding counts of one project.
They are off until an admin turns them on, and a new address or turning them off revokes the old
one at once. To serve badges to the internet while keeping the rest of nanobom private, expose
only /badges/ at the proxy. nanobom keeps the key out of its own logs, but the proxy’s access
log records it with each request.
Public pages (/public/…) work the same way, with a key of
their own, and unlock more: a version’s open and ignored findings, with the justification of
each ignore, and its VEX document. They are built from an allowlist of fields, so the reasons
members write, who triaged, the organization and anything else added to the interface later stay
private. They never read the session, send no Referer to the sites they link to, and ask
search engines not to index them. Expose /public/ at the proxy to serve them.
Data at rest
Everything, password hashes, token digests and the clear upload tokens of projects included, is
in the database (SQLite or PostgreSQL): treat it and its backups as sensitive. On PostgreSQL, the connection carries that
data too: use sslmode=verify-full when the database is on another host
(PostgreSQL URLs).
Dependency-Track compatibility
Many build tools and pipelines already upload SBOMs to OWASP Dependency-Track. nanobom answers the part of Dependency-Track’s API they use to upload, so those pipelines work against nanobom without being rewritten, and a team moving from Dependency-Track changes a URL and a key rather than every pipeline. The requests are listed in the upload API reference; this page explains how Dependency-Track’s model maps onto nanobom’s, and where it stops.
What maps, and how
Dependency-Track identifies a project by a UUID, or by a name and a version, and keeps one project per version. nanobom identifies a project by its slug within an organization, and keeps one inventory per version of the project: each upload replaces the previous one of its version.
- The organization comes from the token. Dependency-Track has no organizations; a nanobom upload token belongs to one, so the token alone tells where the SBOM goes.
- The project name is the slug. It is normalized as in the native API, trimmed and folded to lower case, but not rewritten further: a name with a space or an accent is refused rather than silently mapped to a slug nobody chose, which could merge two projects into one.
- The version is a project version.
projectVersionnames the version of the project the SBOM goes to, as in Dependency-Track: uploads of1.4.0and1.5.0of the same project are two versions, each with its own findings, and a new version starts with the triage of the latest one, as Dependency-Track’s clone with audit history does. A blankprojectVersionis the unnamed version. Dependency-Track’s latest-version flag (isLatest) is nanobom’slatest. Before nanobom had versions,projectVersionwas only recorded as the upload’s image tag, and uploads of every version replaced each other; pipelines that send a newprojectVersionwith every build (a build number) now create a version each time. They keep working: past 50 active versions per project, each new build makes the version uploaded to the longest ago inactive (the cap), so the latest 50 builds are checked. A release or branch name is still the better version: it keeps one version per line of development instead of one per build. - Versions differ in two ways. nanobom accepts a narrower set of version names (letters,
digits,
.,_,+,/and-, up to 64 characters) and refuses others with a400, rather than mapping them to a name nobody chose. And a new version becomes the latest unless the upload saysisLatest: false, where Dependency-Track leaves the flag alone unless asked: with nanobom, the version most recently created is the one the project page shows. - UUIDs cannot be resolved. A client configured with a project UUID refers to a project that only exists in Dependency-Track; nanobom refuses it with a message asking for the name, rather than guessing.
autoCreatekeeps its meaning. Without it, a missing project is a404, as in Dependency-Track. With it, an organization token creates the project; a project token never does, whatever the request says (Security model).- The rest is ignored. Tags and parent projects have no equivalent; they are accepted so that
clients sending them still work. So is the active flag (
isActive): nanobom versions can be inactive, but an upload always makes its version active, as something still builds it.
Processing status
Dependency-Track processes an upload in the background and returns a token; clients that wait
poll the token until it is no longer processing, then usually fetch results. nanobom’s work after
an upload is the project’s run, so a token is processing until that run has finished, exploitation
data included. That is what a client polling before reading results needs: once processing is
false after a run that completed, the project’s findings are those of this SBOM. It is not a
guarantee when the wait ended at NANOBOM_UPLOAD_WAIT_SECONDS before the run finished, when the
run failed, or when runs after uploads are off: the token then reads as not processing although
the findings may still be those of the previous SBOM.
The tokens are kept in memory only. Persisting them would add a table for state that matters for
a few minutes, and a restart already abandons the run they wait for. Like Dependency-Track, an
unknown token reads as not processing, so a client polling across a restart, or polling an
upload made when runs after uploads are off, stops waiting instead of hanging. The wait is
bounded by NANOBOM_UPLOAD_WAIT_SECONDS, the same bound as native uploads that wait.
Where compatibility stops
Only uploading and its processing status are implemented. Clients that go further after the upload call endpoints nanobom does not have:
- reading findings, metrics or policy violations (the Jenkins plugin in synchronous mode, the
Maven plugin’s
upload-bomgoal after the upload); - looking projects up or changing their properties (project tags or description in the Jenkins plugin);
- uploading VEX documents.
Those answer 404. Upload with Dependency-Track clients
says how to configure each client to stay within uploads. Failing a build on vulnerabilities is
done with the native API’s fail_on (Fail CI on vulnerabilities),
which answers in the same request.
The answers follow Dependency-Track’s shapes where clients read them: 200 with a token,
plain-text error messages that clients print to the build log, and an RFC 9457 problem for an
invalid document. Messages are nanobom’s, in English, as for the native API.
Architecture
nanobom is one process and one database, a SQLite file by default or PostgreSQL. There is no worker to scale, no cache to warm and no queue to drain: running it well comes down to a reverse proxy in front, a backup of the database, and a few alerts.
It is a Rust workspace. The web interface is written with Leptos, rendered on the server, and works without JavaScript; a small WebAssembly bundle adds interactivity where the browser runs it.
Crates
| Crate | Role |
|---|---|
domain | Everything with business rules: SBOM parsing and the inventory, runs and findings, exploitation data, notifications, organizations, memberships, tokens, users. All database access goes through it, and every function touching organization data takes an Actor (a Reader, user or token, for reads) and checks its permission (access.rs). |
osv | The OSV client (batch queries, record details, retries) and CVSS-based severity. |
authentication | Sessions stored in the database, password and OpenID Connect sign-in, claims and group mapping, cross-site request checks. |
entity | SeaORM entities, generated from the migrations by mise run entities; never edited by hand. |
migration | The database schema, as SeaORM migrations. |
app | The Leptos interface: pages, components, server functions, translations. |
frontend | The WebAssembly entry point of the interface. |
server | The nanobom binary: command line, HTTP server, upload and read APIs, MCP endpoint, badges, public pages, run queue, metrics. |
┌──────────────────── server: the nanobom binary ───────────────────┐
CI ─ PUT SBOM ──►│ api ──────────────► domain::inventory (parse, replace components) │
│ │ │
│ └── run request ─► runner ◄── schedule, "Check now" (app) │
│ │ │
browser ─────────►│ authentication ─► app (pages, server functions) ─► domain │
│ (sessions, CSRF, (access checks)│
│ OIDC) │
Prometheus ──────►│ /metrics, /healthz │
README image ────►│ badges ───────────► domain::badges (key, open finding counts) │
visitor ─────────►│ public_pages ─────► domain::public_pages (key, allowlisted page) │
└─────────────────────────────────────┬─────────────────────────────┘
│
SQLite or PostgreSQL (SeaORM entities, migrations)
The run pipeline
run request (upload, schedule, manual)
└─► runner queue: one run at a time; requests for a scope already waiting are merged
└─► domain::evaluation::Evaluator::run
1. ignored findings whose expiry passed return to open
2. components of the scope that have a package version are collected
3. osv: one batch query per 1,000 distinct package URLs,
then the records that are new or modified since they were cached
4. per project version, in one transaction: identifiers are grouped by alias,
severity is computed, findings are opened, reopened or fixed, events recorded
5. the run is recorded as succeeded or failed (a failure changes no finding)
└─► if it succeeded: exploitation data (KEV, EPSS) refreshed for the scope (≤ 60 s)
└─► uploads waiting for this run are answered
└─► gauges updated; webhook documents and emails queued and sent (findings.new;
projects.stale after scheduled runs), or run.failed to the failure webhook
delivery retry loop (every 30 s): due webhook posts and emails sent again, a few at a time;
delivered and abandoned ones deleted after 30 days
Exploitation data comes before the waiting uploads so that fail_on=exploited sees the CVEs of
this run; notifications come after, so slow webhooks never hold CI. Webhook documents and emails
are stored before their first attempt, so a receiver that is down gets them once it is back (see
Delivery). A run that panics, or that a restart interrupts,
is recorded as failed and notified like any failed run; at startup the failure document is only
queued, and the retry loop posts it, so the server listens without waiting for the receiver. The
rules each step applies are described in How findings are kept up to date.
One process per database
Runs are serialized inside the process, and the schedule runs in it. Two servers on the same
database would each run the schedule and send every webhook twice: one instance runs one
process. The startup also assumes it: it closes every run still running in the database as
interrupted, so a rolling deploy that starts a new instance while the old one is still running a
check would record the old instance’s live run as failed.
SQLite or PostgreSQL
Both hold the same schema and run the same code, and the test suite runs on both. The choice is about operations, not features.
SQLite is the default because it needs nothing: the database is a file next to the process, it
is created on the first start, and nanobom backup copies it while nanobom runs. One nanobom
process is the only writer anyway, and its load (bursts after uploads and at night) is far from
what a single SQLite file handles. Pick it unless something below applies.
PostgreSQL fits when the database should live outside the nanobom host:
- You already run PostgreSQL, with its monitoring, its backups (
pg_dump, continuous archiving, point-in-time recovery) and the people who look after them, and want nanobom’s data covered by the same routine instead of a file with its own backup job. - A managed database (from a cloud provider or a platform team) takes backups, replication and upgrades off your hands, and lets the nanobom container stay stateless, which suits platforms where containers have no durable volume.
- A shared database server gathers the data of several services in one place, with access control, encryption in transit and auditing set once.
PostgreSQL does not make nanobom scale out: there is still one process per database. It adds a server to run (or pay for), a network hop, and a password to keep. nanobom has no tool to move data between the two, so choose at installation; see Run on PostgreSQL.
On SQLite, timestamps are stored as text and compared as text, which is correct because nanobom
writes every timestamp in UTC; PostgreSQL stores them as timestamp with time zone. Queries
whose result order matters state it (ORDER BY), since PostgreSQL, unlike SQLite, returns rows
in no particular order otherwise.
SQLite lets one connection write at a time. Every transaction that writes takes the write lock
when it starts (BEGIN IMMEDIATE), and a connection waits up to 10 seconds for it while another
holds it, so concurrent writes (an upload during a run, a form, the webhook retries) queue up
instead of failing. A transaction that took the lock only at its first write could fail at once
if another connection had written since it started reading. PostgreSQL locks rows, not the
database, and needs none of this.
Resources
nanobom does its work in short bursts, after uploads and at night, and is idle the rest of the time. What makes it grow:
- Memory peaks during uploads: each request body is held in memory, and parsing an SBOM takes
a few times its size, with two SBOMs parsed at a time at most. Raise
NANOBOM_MAXIMUM_SBOM_SIZEwith that in mind. - Disk holds the components of each project’s latest SBOM, the findings and their history, and the cached vulnerability records. Old uploads only keep their metadata (date, commit, tag, counts), not their components, so the database grows with the number of projects and findings, not with the number of uploads.
- Run duration depends on the number of distinct package URLs (one OSV request per 1,000) and
on how many vulnerability records are new or modified (fetched 8 at a time). The first run of a
large instance takes the longest; later ones reuse the cache. Watch
nanobom_run_duration_seconds, and keepNANOBOM_UPLOAD_WAIT_SECONDSabove the usual duration of a project’s run plus the time it may wait behind the nightly run.