Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

  1. Under New organization, enter Acme as the name and acme as the slug, then Create.
  2. On the page of Acme, under New project, enter demo as the slug, leave the name empty, and Create project.
  3. You land on the project demo, which says No SBOM yet. Under Upload token, copy the token: it starts with nanobom_. It stays on this page, for admins and owners, and so do a GitHub Actions step and a curl command 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:

  1. In Reason, write Tutorial: the vulnerable function is not used.
  2. In Ignore until, pick a date a month from now.
  3. 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

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:

  1. On the Secrets tab, add a repository secret NANOBOM_TOKEN with the project’s upload token.
  2. On the Variables tab, add a repository variable NANOBOM_URL with the instance’s address, such as https://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:

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_URL is its https address: 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 wait NANOBOM_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.
  • /metrics is 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_URL reaches 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.gov and api.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

  1. 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;
    
  2. Point nanobom at it, with the URL form:

    NANOBOM_DATABASE_URL=postgres://nanobom:a-long-random-password@db.example.org:5432/nanobom?sslmode=verify-full
    

    sslmode=verify-full encrypts the connection and checks the server’s certificate and name against the public certificate authorities; add sslrootcert=/path/to/ca.pem when the server’s certificate comes from a private one, as with most managed databases. Avoid verify-ca, which accepts any publicly trusted certificate whatever the host.

  3. 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 same NANOBOM_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.

EcosystemCommandNotes
Rustcargo cyclonedx --format json --override-filename sbomcargo-cyclonedx; one file per crate of a workspace (see below)
npmnpx @cyclonedx/cyclonedx-npm --omit dev --output-file sbom.jsoncyclonedx-npm; run after npm ci
Yarn (berry)yarn cyclonedx --output-file sbom.jsonyarn-plugin-cyclonedx
Pythoncyclonedx-py environment --output-file sbom.jsoncyclonedx-py; run inside the project’s virtual environment
Mavenmvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBomwrites target/bom.json
Gradlethe org.cyclonedx.bom plugin, task cyclonedxBomwrites to build/reports/
Gocyclonedx-gomod app -json -output sbom.jsoncyclonedx-gomod
Container images, binaries, anythingsyft <image or directory> -o cyclonedx-json=sbom.jsonSyft

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.

GeneratorCommandNotes
Syftsyft <image or directory> -o spdx-json=sbom.spdx.jsonSPDX 2.3; -o spdx-json@2.2=… for 2.2. Not -o spdx, which is tag-value
Trivytrivy image --format spdx-json --output sbom.spdx.json <image>, or trivy fs on a directoryNot --format spdx, which is tag-value
GitHub dependency graphInsights → Dependency graph → Export SBOM, or gh api repos/OWNER/REPO/dependency-graph/sbom --jq .sbom > sbom.spdx.jsonSPDX 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 poetry and cyclonedx-py pipenv read 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.

  1. 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.
  2. The project page opens on Upload token: the token, a GitHub Actions step and a curl command, 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:

InputDefault
projectrepository nameProject slug
sbomAn existing CycloneDX or SPDX JSON file; without it, Syft generates one
scan-path.Directory Syft scans
scan-imageContainer image Syft scans instead
fail-oncritical, high, medium, low, exploited or license, or several separated by commas (high,license); see Fail CI
waittrueWait for the evaluation and report it
source-commit, image-tagthe commit; the Git tag, if anyShown in the upload history
summarytrueWrite 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-binary sends the file unchanged (--data would strip its line breaks); -F would wrap it in a multipart form, which nanobom does not read.
  • --fail-with-body makes curl exit with an error on any status from 400, so the job fails on 409 and 503 as 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 503 and a Retry-After header, before storing anything (limit). --retry 3 sends it again after that delay, but also after a 503 for 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; autoCreate is 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-App uploads to web-app, but Web App is 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. projectVersion is 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 leave projectVersion out 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.4 and 2.4.x are fine; a name with a space is refused with a 422. Encode / as %2F and + as %2B in 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 version keep 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 version to 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).

  1. Open the project page; the Versions table lists every version with its open findings.
  2. 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.

  1. On the version’s row, select Delete.
  2. 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_on counts 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.4 does not ignore it in main. 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: projectVersion is the version, and isLatest the 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 lodash fails 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, treat 503 as a warning in your script.
  • unknown severity never fails a severity gate. Findings whose advisory has no score or rating are only caught by exploited (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.readTimeout defaults to 60 seconds; raise it above the wait as a precaution, and keep forwardingTimeouts.responseHeaderTimeout unset (no limit) or above it;
  • Caddy does not limit how long a proxied response takes by default (unless response_header_timeout is 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 in evaluation.findings by 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

  1. Open the organization, then Settings, then License policy.

  2. 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
    
  3. 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.

  4. Keep Licenses not listed at Allow, and save.

Allow only some licenses

An allowlist forbids everything you did not approve:

  1. In Allowed licenses, list what you accept:

    MIT
    Apache-2.0
    BSD-2-Clause
    BSD-3-Clause
    ISC
    
  2. Set Licenses not listed to Forbid.

  3. Set Unknown licenses to Warn while you clean up, then to Forbid to require a license on every component.

  4. 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-Commercial for 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.0 is 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:

  1. 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.
  2. Critical and high findings with a high EPSS score.
  3. 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:

  1. A component marked direct dependency is yours: upgrade it to a version listed under Fixed in.
  2. 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.
  3. When no such release exists yet, force the transitive version with your package manager (npm overrides, Yarn resolutions, 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:

  1. 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.
  2. 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.
  3. Ignore until (optional): a date, YYYY-MM-DD, after which the finding opens again.
  4. Select Ignore finding.

Good reasons are specific and checkable:

  • “Only the sqlite feature 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:

QueryFinds
opensslcomponents whose name contains openssl (case-insensitive)
openssl 3.the same, with a version starting with 3.
lodash@4.17the 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.

  1. Open the project and, if the project has versions, choose the version in the filters.
  2. Select Report. The report opens for the version shown.
  3. Print the page from the browser (Ctrl+P, or Cmd+P on 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.

  1. 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.
  2. Store it as a secret of the repository (NANOBOM_TOKEN), and the address of nanobom as a variable (NANOBOM_URL).
  3. 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).

  1. 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.
  2. 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 exportQuery
Open and ignored findings, as the project page shows themremove status=open
Critical and high findings onlyadd &severity=critical,high
Known exploited findings onlyadd &exploited=true
Every finding, fixed ones includedstatus=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.

  1. 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.
  2. 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, then get_finding for 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

  1. Open the project’s page and find the Badge section, near the bottom. Only admins, owners and instance administrators see it.
  2. 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:

[![vulnerabilities](https://nanobom.example.com/badges/3f6c…e1.svg)](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:

![vulnerabilities](https://nanobom.example.com/badges/3f6c…e1.svg?version=2.4)

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:

![vulnerabilities](https://img.shields.io/endpoint?url=https%3A%2F%2Fnanobom.example.com%2Fbadges%2F3f6c…e1.json&style=for-the-badge)

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

  1. Open the project’s page and find the Public page section, near the bottom. Only admins, owners and instance administrators see it.
  2. 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.

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:

[![vulnerabilities](https://nanobom.example.com/badges/3f6c…e1.svg)](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 http or https address;
  • 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:

  1. Open api.slack.com/apps, choose Create New App, then From scratch; name it nanobom and pick your workspace.
  2. In the app’s Incoming Webhooks page, turn Activate Incoming Webhooks on.
  3. 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.
  4. 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.

  1. In Teams, open the channel that should receive the alerts, choose More options (…) next to its name, then Workflows.
  2. Choose the template Send webhook alerts to a channel, name the workflow and sign in the connections it asks for, then Next.
  3. Pick the team and the channel, then Add workflow.
  4. 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.
  5. 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.

  1. 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, use smtp://…:587?tls=required. nanobom refuses to start with a user or password in a smtp:// URL without tls=, 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 says email notifications are on at startup.

  2. 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.

  3. 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 failed for 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:

SettingValue
TypeWeb application, authorization code flow
Redirect URI<public URL>/auth/oidc/callback, e.g. https://nanobom.example.org/auth/oidc/callback
Client authenticationa client secret (confidential client), or none (public client, PKCE only)
Scopesopenid 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

  1. In the realm, Clients → Create client: OpenID Connect, client ID nanobom; Client authentication on, Standard flow on; Valid redirect URIs https://nanobom.example.org/auth/oidc/callback. Copy the secret from Credentials.
  2. 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

  1. 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 plain http, enable Development Mode on the application.
  2. 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

  1. Applications → Providers → Create → OAuth2/OpenID Provider: client type Confidential, redirect URI https://nanobom.example.org/auth/oidc/callback (strict).
  2. 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 the roles claim.

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 namePages 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 barForm 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 MiBNative 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-ForSign-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 internalIt 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

  1. Stop nanobom.
  2. Replace the database with the backup, and delete the -wal and -shm files next to it, which belong to the old database.
  3. 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:

  1. Stop nanobom.

  2. Empty the database. pg_restore --clean only 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;'
    
  3. 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
    
  4. 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.

ServiceSettingDefault
OSVNANOBOM_OSV_URLhttps://api.osv.dev/
CISA KEVNANOBOM_KEV_URLhttps://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json
FIRST EPSSNANOBOM_EPSS_URLhttps://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 Bearer with 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.json or -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 spdx and Trivy --format spdx write tag-value; use spdx-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_NAME are 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 for run failed in the logs, and check that the instance can reach https://api.osv.dev/.
  • timed_out: the run took longer than NANOBOM_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:

  1. 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.
  2. Did it succeed? A failed run leaves findings as they were, so a new project stays empty.
  3. 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.
  4. 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_total and look for refreshing exploitation data failed in the logs. The instance must reach www.cisa.gov and api.first.org.
  • NANOBOM_EXPLOITATION_DATA=false turns 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.new is only sent for new, reopened or newly exploited findings: a finding that was already open is not sent again.
  • projects.stale is 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 (and NANOBOM_SMTP_FROM); see Send them by email.
  • Send a test email shows the SMTP server’s reply for each address it refuses: 535 means the credentials in NANOBOM_SMTP_URL are wrong, 550 or 554 that 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=required port 587).
  • Recent deliveries lists one line per recipient, marked Email to and the address, with the SMTP server’s last reply. A 5xx reply is not retried.
  • nanobom does not start: a smtp:// URL with a user or password needs ?tls=required (or use smtps://), 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:

MessageCause
The identity provider could not sign you inDiscovery 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 againThe 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 automaticallyNANOBOM_OIDC_CREATE_USERS=false and the user never signed in
This account is disabledAn 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 (an http issuer redirected to https, for example), which nanobom does not follow;
  • unexpected issuer URI - the issuer in the discovery document differs from NANOBOM_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_CLAIM must name the claim exactly, as a top-level name or a dotted path (realm_access.roles).
  • Group names in NANOBOM_OIDC_GROUP_MAPPING must match the claim’s values exactly; Keycloak sends /developers with 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

MessageFix
no sign-in methodEnable local accounts or configure OpenID Connect
OpenID Connect needs both NANOBOM_OIDC_ISSUER and NANOBOM_OIDC_CLIENT_IDSet both, or neither
invalid NANOBOM_SCHEDULEUse a five-field cron expression, or off
invalid NANOBOM_OIDC_GROUP_MAPPINGFix 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 fileThe 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 in crates/domain/tests/fixtures/.
  • crates/server/tests/server/ drives the HTTP server end to end (uploads, sign-in, the interface, operations); common.rs starts 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

  1. Add a migration to crates/migration/src/ and list it in lib.rs. Never edit a migration that was released: instances have already applied it.
  2. Regenerate the entities with mise run entities (it applies the migrations to a temporary database and runs sea-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.

  1. Copy en.json to <tag>.json in both locale directories, and translate every message (language.name is the language’s name in itself, shown in the account menu).
  2. Add the tag to available_locales in the embedded_i18n::i18n! call at the root of both crates, crates/app/src/lib.rs and crates/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 on main, from which the version bump and the changelog are derived.
  • Run mise run check before pushing; CI runs the same checks, plus the release build and the container image.
  • main is protected: changes arrive through pull requests, which merge once the CI passed and Pull request title checks succeed. CI passed succeeds 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

VariableFlagDefault
NANOBOM_DATABASE_URL--database-urlsqlite:///data/nanobom.dbThe 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-formatjsonjson (one object per line, for collectors) or text.
NANOBOM_LOG_LEVEL--log-levelinfoA 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
sslmodedisable, 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.
sslrootcertA PEM file of authorities to trust in addition to the public ones, such as a managed database’s CA bundle.
sslcert, sslkeyA client certificate and its key, for servers that require one.
application_nameThe name shown in pg_stat_activity.

See Run on PostgreSQL.

Addresses and files

VariableFlagDefault
NANOBOM_PUBLIC_URL--public-urlhttp://localhost:8080The 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-address0.0.0.0:8080Address and port to listen on. 127.0.0.1:8080 keeps nanobom reachable only through a local reverse proxy.
NANOBOM_SITE_ROOT--site-rootsiteThe 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

VariableFlagDefault
NANOBOM_SCHEDULE--schedule0 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-uploadtrueEvaluate 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-seconds300Longest 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-uploads32Most 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-urlhttps://api.osv.dev/The OSV API, or a compatible mirror offering /v1/querybatch and /v1/vulns/{id}.
NANOBOM_MAXIMUM_SBOM_SIZE--maximum-sbom-size16Largest accepted SBOM, in MiB. Parsing takes a few times this much memory.
NANOBOM_STALE_AFTER_DAYS--stale-after-days30Days without an SBOM after which a project is stale; 0 turns the feature off.
NANOBOM_FAILURE_WEBHOOK_URL--failure-webhook-urlReceives a run.failed document when a run fails.

Email

VariableFlagDefault
NANOBOM_SMTP_URL--smtp-urlThe 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-fromThe 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

VariableFlagDefault
NANOBOM_EXPLOITATION_DATA--exploitation-datatrueDownload 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-urlhttps://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.jsonCISA’s Known Exploited Vulnerabilities catalog (JSON). A mirror must serve the catalog’s JSON as is.
NANOBOM_EPSS_URL--epss-urlhttps://api.first.org/data/v1/epssFIRST’s EPSS API. A mirror must answer GET <url>?cve=CVE-…,CVE-… like FIRST’s API.

Accounts and sessions

VariableFlagDefault
NANOBOM_LOCAL_ACCOUNTS--local-accountstrueSign-in with a username or email address and a password.
NANOBOM_PASSWORD_MINIMUM_LENGTH--password-minimum-length12Minimum length of local passwords.
NANOBOM_PERSONAL_ORGANIZATIONS--personal-organizationstrueGive each new user an organization of their own; applies to users created afterwards.
NANOBOM_SESSION_INACTIVITY_DAYS--session-inactivity-days7Sign users out after this many days without a request (at least 1).
NANOBOM_TRUST_FORWARDED_HEADERS--trust-forwarded-headersfalseRead 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.

VariableFlagDefault
NANOBOM_OIDC_ISSUER--oidc-issuerIssuer URL of the provider; its discovery document is read from it.
NANOBOM_OIDC_CLIENT_ID--oidc-client-idClient identifier.
NANOBOM_OIDC_CLIENT_SECRET--oidc-client-secretClient secret, for confidential clients; public clients rely on PKCE alone.
NANOBOM_OIDC_SCOPES--oidc-scopesopenid profile emailScopes to request, separated by spaces.
NANOBOM_OIDC_CREATE_USERS--oidc-create-userstrueCreate users at their first sign-in.
NANOBOM_OIDC_ADMINISTRATOR_CLAIM--oidc-administrator-claimClaim granting instance administration, applied at each sign-in (administrator claim). Dotted paths reach nested claims.
NANOBOM_OIDC_ADMINISTRATOR_VALUE--oidc-administrator-valueValue the administrator claim must contain; without it, the claim must be true.
NANOBOM_OIDC_GROUPS_CLAIM--oidc-groups-claimClaim listing the user’s groups or roles, for the group mapping.
NANOBOM_OIDC_GROUP_MAPPING--oidc-group-mappinggroup=organization:role entries separated by ; or line breaks (syntax).
NANOBOM_OIDC_BUTTON_LABEL--oidc-button-labelSign in with single sign-onLabel 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 serveApply pending migrations, then serve the web interface and the API.
nanobom migrateApply pending database migrations and exit.
nanobom backup <destination>Write a consistent copy of the live database to a new file.
nanobom create-administratorCreate a local instance administrator.
nanobom token create, list, revokeManage API tokens.
nanobom project create, tokenCreate projects and print their upload token.
nanobom healthcheckCheck 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

ArgumentVariable
<destination>NANOBOM_BACKUP_DESTINATIONThe 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

FlagVariable
--usernameNANOBOM_ADMINISTRATOR_USERNAMERequired.
--emailNANOBOM_ADMINISTRATOR_EMAILOptional; can then be used to sign in instead of the username.
--passwordNANOBOM_ADMINISTRATOR_PASSWORDRead from standard input when unset, as a plain line, shown as it is typed.
--personal-organizationsNANOBOM_PERSONAL_ORGANIZATIONSGive the user a personal organization (default true).
--password-minimum-lengthNANOBOM_PASSWORD_MINIMUM_LENGTHMinimum 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.

CommandFlags
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--idRevoke 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.

CommandFlags
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, --renewPrint 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

FlagVariableDefault
--listen-addressNANOBOM_LISTEN_ADDRESS0.0.0.0:8080The server’s listen address; its health endpoint is reached over loopback when it listens on every interface.
--urlNANOBOM_HEALTHCHECK_URLHealth endpoint to check instead of the one derived from the listen address.
--timeout-seconds5Seconds 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:

ReachCreated withMay
Organization tokenproject Whole organization in Settings → API tokens, or nanobom token create without --projectreach any project of its organization; with the upload scope, create projects by uploading to a new slug
Project tokena project chosen, or --project webreach that project only; it never creates one
ScopeCreated withMay
upload (default)scope Upload and read, or --scope uploadupload SBOMs, import VEX documents, and read
readscope Read only, or --scope readread 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 tokenOther tokens
Shownon the project page, under Upload token, at any time, and by nanobom project tokenonce, at creation
Storedits SHA-256 digest, and its clear valueits SHA-256 digest only
ReplacedRenew on the project page, or nanobom project token --renew: the old value stops working at oncecreate a new token, then revoke the old one
Revokednever, so a project always has one: the settings offer no Revoke for it, and nanobom token revoke refuses itRevoke in Settings → API tokens, or nanobom token revoke
Deletedwith its projectwith 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:

FormatRecognized byVersionsRecorded as
CycloneDX JSON"bomFormat": "CycloneDX"specVersion 1.3 to 1.71.6
SPDX JSONspdxVersionSPDX-2.2 and SPDX-2.3SPDX-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.*.*): its reason is version 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 components count (nested components included). The metadata.component, which describes the project itself, is not a component.
  • Components of type file and operating-system are skipped silently: they describe what was scanned, not packages.
  • The graph comes from dependencies; the entry of metadata.component gives 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 an expression, an SPDX license identifier (license.id) or a free-text name (license.name, kept as written). One entry gives the license. Several are joined with AND, sorted and without duplicates, with compound expressions in parentheses: an MIT identifier and a GPL-2.0-only OR BSD-3-Clause expression give (GPL-2.0-only OR BSD-3-Clause) AND MIT. CycloneDX does not say whether several entries are alternatives or all apply; AND is the conservative reading, since a component is then only as permissive as its most restrictive license. License text, url and evidence.licenses are not read.
  • Entries of vulnerabilities with an analysis.state are 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 packages count; files and snippets are ignored. A package’s package URL is its first externalRefs entry of type purl in the PACKAGE-MANAGER category (PACKAGE_MANAGER in SPDX 2.2, or no category).

  • A null or missing field counts as absent, even one SPDX requires: a package without a name is kept, a relationship missing one of its ends is ignored.

  • The package the document describes (a DESCRIBES relationship from the document, or documentDescribes) is the project, not a component.

  • Packages whose primaryPackagePurpose is FILE or OPERATING-SYSTEM are skipped silently.

  • The graph comes from relationships:

    RelationshipEdge
    A DEPENDS_ON BA depends on B
    B DEPENDENCY_OF A, and BUILD_, DEV_, OPTIONAL_, PROVIDED_, RUNTIME_, TEST_DEPENDENCY_OFA depends on B
    A CONTAINS B, B CONTAINED_BY A, between two packagesA depends on B
    CONTAINS from the projectnone: a scanned directory or image contains every package, direct dependency or not
    any othernone

    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 SPDXID given 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 its licenseDeclared when licenseConcluded is missing, NOASSERTION or NONE. NOASSERTION or NONE in 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

ParameterValueEffect
version1 to 64 characters among letters, digits, ., _, +, / and -The project version the SBOM describes; without it, the unnamed version
latesttrue or falsetrue makes the version the latest; false keeps a version this upload creates from becoming the latest
source_committext, up to 300 charactersThe commit the SBOM was built from, shown in the upload history
image_tagtext, up to 300 charactersThe container image tag the SBOM describes, shown in the upload history
waittrue or falseWait for the project’s evaluation and return it
fail_oncritical, high, medium, low, exploited or license, or several separated by commasFail 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 create starts 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=true makes the version uploaded to the latest, whether it is new or not. Without latest, an existing version keeps its flag, and latest=false on 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_onFails (409) when an open finding is
criticalcritical
highhigh or critical
mediummedium, high or critical
lowlow, medium, high or critical (anything but unknown)
exploitedknown exploited, whatever its severity
licensenot 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, projectThe slugs, normalized to lower case
project_id, upload_idIdentifiers in nanobom
project_createdWhether this upload created the project
versionThe version uploaded to; "" for the unnamed version
version_createdWhether this upload created the version (always true when it created the project)
component_countDistinct components stored (by package URL)
components_without_purlComponents skipped for a missing or invalid package URL
skippedThe first 100 of them, with name, version and reason
evaluationOnly with wait or fail_on, see below
vexOnly when the SBOM carries VEX statements: what importing them did, as in the VEX API
errorOnly when the upload fails, as {"error": "…"} alone or next to the fields above

The evaluation object

Field
statussucceeded; failed when the run could not complete (OSV unreachable, for example); timed_out when it did not finish within NANOBOM_UPLOAD_WAIT_SECONDS
run_idThe run’s identifier, null when timed out
openThe open findings of the version uploaded by severity (critical, high, medium, low, unknown); ignored findings are not counted
known_exploitedHow many open findings are known exploited
findingsThe 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_viaThe 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)
licensesOnly 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

StatusWhenWhat to do
200The SBOM replaced the components of the version
201The SBOM created the project
401No 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 renewedCheck the secret in CI; the response has a WWW-Authenticate: Bearer header
403A project token used for another existing project, or a read tokenUse that project’s slug, or an organization token; upload with a token of the upload scope
404The organization does not exist or is not the token’s; or a project token used for a project that does not existCheck the organization slug in the URL; create the project first, in the interface or with an organization token
409With fail_on: the evaluation succeeded and open findings reach a threshold, or, with license, a component has a forbidden licenseFix or triage the findings listed in evaluation.findings; replace the components listed in evaluation.licenses.violations, or change the policy
413The 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
422Invalid parameter, invalid project slug, or invalid document (not JSON, neither CycloneDX nor SPDX, unsupported version)Read error
500A database errorSee the server’s logs
503With a fail_on threshold other than license: the evaluation failed or timed out, so the findings are not up to dateRetry later; see Troubleshoot
503With 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 ….

Statuserror
401a valid upload token is required in the Authorization header (Bearer)
403this token does not allow uploads to this project
403this token is read-only: uploads need a token with the upload scope
404not found
422wait must be true or false (or latest must be …)
422the version must be 1 to 64 characters: letters, digits, '.', '_', '+', '/' or '-'
422fail_on must be critical, high, medium, low, exploited or license, or several of them separated by commas
422fail_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
422the source commit must be at most 300 printable characters (or the image tag …)
422the project slug must be 1 to 64 characters: letters, digits, '.', '_' or '-', starting with a letter or a digit
422the SBOM is not valid JSON: …
422XML SBOMs are not supported: generate the SBOM as CycloneDX JSON or SPDX JSON
422SPDX tag-value documents are not supported: generate the SBOM as SPDX JSON (SPDX 2.2 or 2.3) or CycloneDX JSON
422SPDX RDF documents are not supported: generate the SBOM as SPDX JSON (SPDX 2.2 or 2.3) or CycloneDX JSON
422the SBOM must be a CycloneDX JSON document (bomFormat "CycloneDX") or an SPDX JSON document (spdxVersion "SPDX-2.3")
422unsupported CycloneDX version "1.2"; supported versions are 1.3, 1.4, 1.5, 1.6, 1.7
422unsupported SPDX version "SPDX-3.0.1"; supported versions are SPDX-2.2, SPDX-2.3, in JSON
422invalid CycloneDX document: …
422invalid SPDX document: …
503the evaluation did not complete
503too 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.

FieldValueEffect
projectNametextThe 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
projectVersion1 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 falseLike the native latest: true makes the version the latest, false keeps a new version from becoming it; missing, a new version becomes the latest
autoCreatetrue or false (default)Create the project if it does not exist (organization tokens only). Without it, a missing project is a 404
bombase64 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
projectUUIDRefused with a 400 when projectName is missing; ignored otherwise
projectTags, parentUUID, parentName, parentVersion, isActiveAccepted 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: …" }
StatusWhenBody
200The SBOM replaced the components of the version{"token": …}
400No 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
400An invalid document: any document error of the native API, XML and SPDX tag-value includedProblem
401No X-Api-Key, or a token that is unknown or revokeda valid nanobom upload token is required in the X-Api-Key header
403A project token used for another existing projectAccess to the specified project is forbidden
403A read tokenThis nanobom token is read-only: uploads need a token with the upload scope.
404A missing project without autoCreate, or with a project tokenThe project could not be found.
409autoCreate and another upload created the same project first: send the upload againthe project "…" already exists
413An SBOM larger than NANOBOM_MAXIMUM_SBOM_SIZEPlain text
500A database errorinternal 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.

InputDefault
url$NANOBOM_URLAddress of the nanobom instance, such as https://nanobom.example.org
organizationSlug of the organization
project$CI_PROJECT_NAMESlug of the project; created by the first upload when the token covers the organization
sbomPath of an existing CycloneDX or SPDX JSON SBOM; empty, Syft generates one
scan-path.Directory Syft scans when sbom is empty
scan-imageContainer image Syft scans instead of scan-path when sbom is empty
fail-oncritical, 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
versionThe project version the SBOM describes; empty, the unnamed version
latest"true", "false" or empty: the upload’s latest parameter
source-commit$CI_COMMIT_SHACommit the SBOM was built from, shown in the upload history
image-tag$CI_COMMIT_TAGContainer image tag the SBOM describes, shown in the upload history; empty outside tag pipelines
stagetestStage of the job
job-namenanobomName of the job
imagealpine:3.24Image 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_TOKENRequired. 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_URLRead through the default of url only
CI_REGISTRY, CI_REGISTRY_USER, CI_REGISTRY_PASSWORDSet 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

NameThe job-name input
StageThe stage input
ImageThe image input, with an empty entrypoint
Rules, needsNone: the job runs in every pipeline, after the jobs of earlier stages
ArtifactsThe 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_STATUSHTTP status of the upload
NANOBOM_PROJECT_URLThe project’s page in nanobom
NANOBOM_EVALUATION_STATUSsucceeded, failed or timed_out
NANOBOM_CRITICAL, NANOBOM_HIGH, NANOBOM_MEDIUM, NANOBOM_LOWOpen findings of the version uploaded, by severity
NANOBOM_KNOWN_EXPLOITEDOpen findings known to be exploited
NANOBOM_FORBIDDEN_LICENSES, NANOBOM_WARNED_LICENSESComponents 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 answerJob
200, 201Succeeds
409: a fail-on threshold is crossedFails
503: with a severity or exploited threshold, the evaluation failed or timed out; or too many uploads are waitingFails
401, 403, 404, 413, 422, any other status, or no answerFails, 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
latestExactly 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
activeWhether 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 versionInactive 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

ChangeHowRefused when
Make a version inactiveMake inactive in the project page’s Versions tableIt is the latest: mark another version latest first
Make a version active againMake active, or any upload to the versionThrough the interface only: the project already has 50 active versions (an upload makes room instead, see the cap)
Mark a version latestMake latest, or an upload with latest=true; an upload creating a version also makes it the latest unless latest=falseIt is inactive: make it active first (an upload with latest=true makes it active)
Delete a versionDelete, then tick the confirmation box and select Delete versionIt 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:

RefusalMessage
Making the latest version inactivethe latest version cannot be made inactive: mark another version latest first
Marking an inactive version latestan inactive version cannot be the latest: make it active first
Deleting the latest versionthe latest version cannot be deleted: mark another version latest first
Deleting the only versiona project keeps at least one version: delete the project instead
Making a version active past the capthis 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 parameterMeaningDefault
versionThe name of a project version; an empty version= names the unnamed versionThe latest version
nameOnly components whose name contains this text, namespace included, ignoring case (% and _ match themselves)Every name
showopen: components with at least one open finding (ignored and fixed ones do not count). unlicensed: components whose SBOM entry gives no licenseEvery component
pageThe page, from 11

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.

ColumnContent
ComponentThe name, with its namespace (org.apache.logging.log4j/log4j-core), and the package URL
VersionThe package URL’s version
EcosystemThe package URL type: npm, cargo, maven…
LicenseThe license expression of the SBOM, or None declared
Open findingsThe 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
DependencyDirect 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
MethodAuthenticationDoes
GETA 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 APIReturns the findings of a project version as a CycloneDX 1.6 JSON document
PUTAuthorization: Bearer nanobom_… only, with a token of the upload scopeApplies 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 documentContent
specVersion1.6
serialNumberA new random urn:uuid: at each export
metadata.timestampThe time of the export, UTC
metadata.tools.componentsnanobom and its version
metadata.componentThe project: its name, bom-ref {organization}/{project}, and the version name in version (absent for the unnamed version)
componentsEach component that has a finding, with bom-ref and purl set to its package URL
vulnerabilitiesOne entry per finding, open, ignored or fixed, sorted by identifier then package URL

Each entry of vulnerabilities:

FieldContent
idThe finding’s vulnerability identifier (GHSA-…, CVE-…, RUSTSEC-…)
sourceWhere the identifier is published: NVD for CVE-, GitHub Advisories for GHSA-, OSV otherwise, with the URL of the record
referencesThe aliases, each with its source
ratingsThe severity, with the CVSS score, method (CVSSv2, CVSSv3, CVSSv31, CVSSv4) and vector when known
descriptionThe OSV summary
published, updatedThe OSV record’s dates
analysisSee 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

Findinganalysis.stateanalysis.justificationanalysis.detail
Openin_triage
Ignored with a justificationnot_affectedThe justificationThe reason
Ignored as False positivefalse_positiveThe reason
Ignored without a justificationin_triageThe reason
Fixedresolved

The justifications are those of CycloneDX:

ValueIn the interface
code_not_presentVulnerable code not present
code_not_reachableVulnerable code not reachable
requires_configurationRequires a configuration not in use
requires_dependencyRequires a dependency not present
requires_environmentRequires an environment not present
protected_by_compilerProtected by the compiler
protected_at_runtimeProtected at runtime
protected_at_perimeterProtected at the perimeter
protected_by_mitigating_controlProtected 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 the id of one of its references, equals the finding’s identifier or one of its aliases, ignoring case. A statement about CVE-2021-23337 covers a finding filed as GHSA-35jh-r3h4-6jhm with that alias.
  • Component: one of its affects[].ref resolves to the finding’s package URL, compared without qualifiers and subpath. A reference resolves when it is the bom-ref of a component of the same document with a purl, 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.stateEffect on covered findings
not_affectedOpen findings are ignored, with analysis.justification (if it is one of the values above)
false_positiveOpen findings are ignored, as False positive
resolved, resolved_with_pedigree, exploitable, in_triageNone; reported as informational

An ignore made by an import:

  • has analysis.detail as its reason, cut to 2,000 characters; without a detail, the reason is VEX statement: not_affected (code_not_reachable) or VEX 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
statementsStatements read (entries with an analysis.state)
ignoredFindings this import ignored
already_ignoredCovered findings that were already ignored
skippedStatement targets that changed nothing, for any result below except ignored and already_ignored
resultsOne entry per target (affects[].ref) of each statement, the first 500
results[].vulnerabilityThe statement’s id (or its first reference’s)
results[].componentThe affects[].ref as written; null when affects is empty
results[].findingsThe identifiers of the findings covered
resultMeaning
ignoredOpen findings were ignored
already_ignoredThe covered findings were already ignored
no_matching_findingNo open or ignored finding of the project version is covered
informationalThe state does not ignore findings
unresolved_referenceThe reference is neither a bom-ref of the document nor a package URL
no_versionThe package URL has no version
no_targetaffects 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 wait or fail_on, they are imported after the evaluation and before the gate: they also cover the findings this upload’s run opened, and fail_on does 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": "…"}.

StatusWhen
200Exported, or imported
401GET: neither a valid token nor a session; PUT: no valid token. The response has a WWW-Authenticate: Bearer header
403PUT with a read token
404The organization, project or version does not exist, or the token or member does not reach it
413The body is larger than NANOBOM_MAXIMUM_SBOM_SIZE
422Invalid document
500A database error
Statuserror
401a valid upload token is required in the Authorization header (Bearer)
401sign in, or send a token in the Authorization header (Bearer) or in X-Api-Key (GET without either)
403this token is read-only: uploads need a token with the upload scope
404not found
422the VEX document is not valid JSON: …
422the VEX document must be a CycloneDX JSON document (bomFormat "CycloneDX")
422unsupported CycloneDX version "1.3" for a VEX document; supported versions are 1.4, 1.5, 1.6, 1.7
422invalid 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.

PathReturnsPaginated
/api/organizationsThe organizations the caller sees, by name
/api/organizations/{organization}/projectsThe organization’s projects, by slug, with their open findings by severity
/api/organizations/{organization}/projects/{project}/versionsThe project’s versions, newest first
/api/organizations/{organization}/projects/{project}/findingsThe findings of a project version, filtered, in the project page’s order✓
/api/organizations/{organization}/projects/{project}/componentsThe components of a project version from its latest SBOM, by package URL✓
/api/organizations/{organization}/runsThe 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-policyThe organization’s license policy
/api/organizations/{organization}/projects/{project}/license-violationsThe components of a project version whose license the policy forbids or warns about, forbidden first✓
/api/openapi.jsonThe 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
nameThe version name; "" for the unnamed version
latestWhether it is the latest version, the one read when a request names none; exactly one version of a project is
activeWhether runs evaluate it; an inactive version is not counted, searched or notified, and stays readable (states)
last_upload_atThe version’s latest upload; null before the first
openThe version’s open findings by severity

Authentication

CallerSendsReads
A token of either scope, read or uploadAuthorization: Bearer nanobom_…, or X-Api-Key: nanobom_… as on the Dependency-Track APIIts organization, as a viewer; a project token, its project only
A signed-in userThe session cookie of the interfaceWhat 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:

ParameterDefault
limit100Items per page, from 1 to 500
offset0Items 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
ParameterValuesDefault
statusall, or a comma-separated list of open, ignored, fixedopen,ignored, as on the project page
severityA comma-separated list of critical, high, medium, low, unknownAny
exploitedtrue: only findings with a CVE in the CISA KEV catalogfalse
ecosystemThe package URL type: npm, cargo, pypi…Any
versionA version nameThe 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
versionThe project version the finding belongs to; "" for the unnamed version
component.licenseThe component’s license in the latest SBOM; null when it is not in it any more (components)
severityThe highest among the vulnerability’s aliases at the latest run that reported it
exploitationAggregated 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_viaThe project’s direct dependencies that lead to the component; empty when the SBOM’s dependency graph does not say (Dependency paths)
ignoreSet while the finding is ignored, null otherwise. justification is one of the VEX justifications or false_positive
urlThe 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
organizationThe organization’s slug
detailsThe advisory’s description, in Markdown
published, modifiedThe advisory’s dates
cvss_version, cvss_vectorThe CVSS vector the score comes from
fixed_versionsVersions of the package that fix the vulnerability, per the OSV record
referencesThe advisory’s links: {"type": "ADVISORY", "url": "…"}
ignored_by, ignored_by_tokenThe member, or the token of a VEX import, that ignored the finding, while it is ignored
eventsThe 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_componentsThe 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
versionsEvery 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

A project:

Field
slug, name
last_upload_atThe latest upload; null before the first
staleNo SBOM for longer than NANOBOM_STALE_AFTER_DAYS
openOpen issues by severity: critical, high, medium, low, unknown
ignoredIgnored issues
known_exploitedOpen 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):

  • q is 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;
  • license is matched anywhere in the component’s license, ignoring case: GPL finds GPL-3.0-only and MIT OR LGPL-2.1-or-later. Components without a license never match;
  • inactive=true also searches inactive versions, left out by default (true or false, anything else is 422).

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
activeWhether 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
unlistedThe action (allow, warn, forbid) for licenses no rule lists
unknownThe action for components whose license is missing or is not a valid SPDX expression
ruleslicense (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.

StatusWhenerror
304If-None-Match matches
401No token and no session, or a token that is unknown or revoked. The response has a WWW-Authenticate: Bearer headersign in, or send a token in the Authorization header (Bearer) or in X-Api-Key
400A path segment that is not valid percent-encoded UTF-8A description of the problem
404Missing (a project version included), or out of the caller’s reachnot found
422An invalid query parameterFor 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
500A database errorinternal 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
TransportStreamable 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 versions2024-11-05 to 2026-07-28
Server namenanobom, with the instance’s version
SettingNone: 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:

SendsReads
Authorization: Bearer nanobom_…, or X-Api-Key: nanobom_…, a token of either scopeIts 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.

StatusWhen
200A JSON-RPC answer, including tool errors (see Errors)
202A notification (notifications/initialized), which has no answer
400The body is not a JSON-RPC message, or MCP-Protocol-Version names an unknown version
401No token, or one that is not valid (revoked or mistyped): {"error": "…"} with WWW-Authenticate: Bearer
403The request has an Origin header
405Any method but POST
406Accept does not list both application/json and text/event-stream
413The body is larger than 64 KiB
415Content-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.

ToolInputsAnswers
list_projectsNoneThe 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_versionsprojectThe project’s versions, newest first: name ("" for the unnamed version), latest, active, created_at, last_upload_at, open findings by severity
list_findingsproject, version, status, minimum_severity, known_exploited_only, componentThe findings of a version, most urgent first (prioritization), with total, the number matching the filters
get_findingidOne 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_byvulnerability, any_status, include_inactiveThe findings of a vulnerability across the projects the token reaches, by project and version
search_componentsname, license, include_inactiveComponents by name (and version prefix), license or both, one match per project version, as the component search
license_violationsproject, versionThe components of a version that the license policy forbids or warns about, forbidden first, with policy_active and the forbidden and warned counts

Inputs

InputToolsValuesDefault
projectlist_versions, list_findings, license_violationsA project slug, case-insensitiveRequired
versionlist_findings, license_violationsA version name, case-sensitive; "" for the unnamed versionThe latest version
statuslist_findingsopen, ignored or fixedopen
minimum_severitylist_findingscritical, high, medium, low or unknown: that severity and above (unknown is the lowest)Every severity
known_exploited_onlylist_findingsOnly vulnerabilities in CISA’s KEV catalogfalse
componentlist_findingsText the component name contains, ignoring caseEvery component
idget_findingA finding identifier, from list_findings or affected_byRequired
vulnerabilityaffected_byAn identifier or alias, ignoring case: CVE-2021-23337 also finds findings filed under GHSA-35jh-r3h4-6jhm, which lists it as an aliasRequired
any_statusaffected_byAlso ignored and fixed findingsfalse: open ones
include_inactiveaffected_by, search_componentsAlso inactive versionsfalse
namesearch_componentsText the name contains, optionally followed by a space or @ and the start of the version: openssl 3., log4j-core@2.14
licensesearch_componentsText 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

LimitValue
Items in a list100; the answer has "truncated": true when there are more. list_findings also gives total
Advisory details4000 characters; details_truncated says when they were cut
Advisory references20; references_truncated says when there were more
Versions of a finding (get_finding)100; versions_truncated says when there were more
Request body64 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
AuthenticationA 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
versionThe name of a project version (?version=2.4; an empty version= names the unnamed version). Without it, the latest version
Accept-LanguageThe 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.

StatusWhen
200The 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)
401No token or session, or an invalid token
404Unknown organization, project or version, or one the token does not reach
422An 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.

SectionContent
TitleOrganization, project and version (or “Unnamed version”), the time of generation, the nanobom version and the host of NANOBOM_PUBLIC_URL
WarningsWhen 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 provenanceThe 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
SummaryA 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 vulnerabilitiesEach 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 productEach 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
LicensesWith 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
MethodWhat 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

PathReturns
GET /badges/{key}.svgThe badge as an SVG image
GET /badges/{key}.jsonThe 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.

ParameterMeaning
versionThe 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 findingsMessageColour
Nonenonegreen #1f883d
Some known exploited (CISA KEV)N exploited, then the counts belowred #cf222e
Worst is criticalthe counts, e.g. 1 critical, 2 highred #cf222e
Worst is highe.g. 2 high, 3 mediumorange #bc4c00
Worst is mediume.g. 3 mediumyellow #d4a72c, dark text
Worst is lowe.g. 1 lowyellow-green #a2b82c, dark text
Only unknown severitye.g. 1 unknowngrey #6e7781
The version never received an SBOMno SBOMgrey #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

StatusWhen
200The badge
304If-None-Match names the badge’s current ETag (or is *)
404The 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:

HeaderValue
Content-Typeimage/svg+xml; charset=utf-8 or application/json
Cache-Controlpublic, max-age=300: image proxies, such as GitHub’s, may serve a badge up to five minutes old
ETagA strong tag of the body; badges are never compressed, so it names the bytes sent
X-Content-Type-Optionsnosniff
Content-Security-PolicySVG 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

PathReturns
GET /public/{key}The page, as a complete HTML document
GET /public/{key}/vex.jsonThe 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.

ParameterMeaning
versionThe 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

StatusWhen
200The page or the document
404The 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:

HeaderValue
Content-Typetext/html; charset=utf-8 for the page, application/vnd.cyclonedx+json for the VEX document
Cache-Controlpublic, max-age=300: browsers and proxies may show a page up to five minutes old, including after it is turned off
VaryPage only: Accept-Language
Referrer-Policyno-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-Tagnoindex: search engines that find the address do not list it
X-Content-Type-Optionsnosniff
Content-Security-PolicyPage: 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:

SectionContent
HeaderThe 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)
WarningsWhether the project received no SBOM for longer than NANOBOM_STALE_AFTER_DAYS (Configuration), and whether the version is inactive
Scope and provenanceWhen 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
SummaryOpen findings by severity, how many are known exploited, how many are ignored, how many were fixed in the last 90 days
Open vulnerabilitiesFor 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 maintainersFor 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.state and analysis.justification remain;
  • metadata.component has no bom-ref, which names the organization in the members’ export; its name is the project’s name and its version the version’s name;
  • the nanobom entry of metadata.tools has no version.

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

SettingValuesDefault
Allowed licensesidentifiersnoneRules with the action allow
Licenses to warn aboutidentifiersnoneRules with the action warn
Forbidden licensesidentifiersnoneRules with the action forbid
Licenses not listedallow, warn, forbidallowThe action for a license no rule lists; forbid turns the allowed list into an allowlist
Unknown licensesallow, warn, forbidallowThe 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 (mit is stored as MIT); the deprecated GNU identifiers without a suffix (GPL-2.0, LGPL-2.1, AGPL-3.0) are stored as their -only variant, 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 -only variant of their license, eCos-2.0 as GPL-2.0-or-later and wxWindows as LGPL-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:

  1. A component without a license is unknown: it gets the action for unknown licenses, and the verdict names no identifier.
  2. The expression is parsed, ignoring the case of identifiers and operators. Deprecated identifiers, / for OR and + after an identifier are accepted.
  3. Each license of the expression gets its rule, or the action for licenses not listed. WITH exceptions are ignored: GPL-2.0-only WITH Classpath-exception-2.0 is judged as GPL-2.0-only. GPL-2.0 matches a rule on GPL-2.0-only, GPL-2.0+ one on GPL-2.0-or-later, GPL-2.0-with-classpath-exception one on GPL-2.0-only, eCos-2.0 one on GPL-2.0-or-later and wxWindows one on LGPL-2.0-or-later; + after another license is ignored (Apache-1.0+ is judged as Apache-1.0). DocumentRef-…:LicenseRef-… names a license of another document, which a rule on the LicenseRef-… alone does not match. NOASSERTION gets the action for unknown licenses.
  4. OR keeps the least severe side, AND the most severe. AND binds tighter than OR (A OR B AND C is A OR (B AND C)); parentheses group as written.
  5. 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.
  6. 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 or LicenseRef-… 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 with AND. 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:

LicenseVerdictBecause of
MITallow
GPL-3.0-onlyforbidGPL-3.0-only
MIT OR GPL-3.0-onlyallow
MIT AND GPL-3.0-onlyforbidGPL-3.0-only
GPL-3.0-only OR LGPL-2.1-onlywarnLGPL-2.1-only
(MIT OR GPL-3.0-only) AND LGPL-2.1-onlywarnLGPL-2.1-only
gpl-3.0-only with classpath-exception-2.0forbidGPL-3.0-only
nonewarn
Apache License 2.0warn
(GNU Affero General Public License v3) AND GPL-3.0-onlyforbidGPL-3.0-only
GPL-3.0-only WITH Some-Custom-exceptionforbidGPL-3.0-only
MIT AND Some-Custom-Licensewarn
Licensed under GPL-3.0-only.forbidGPL-3.0-only
Intel Simplified Software Licensewarn

Identifiers in invalid text

Words are runs of letters, digits, ., : and -; case does not matter. A word is matched, in order:

  1. as it is;
  2. without the ., : and - at its start and end (GPL-3.0-only. and GPL-3.0-only: are GPL-3.0-only);
  3. when it holds a : and is not a DocumentRef-…:LicenseRef-…, part by part, each without . and - at its ends (License:GPL-3.0-only names GPL-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 every LicenseRef-…, counts wherever it appears: Licensed under AGPL-3.0-only names AGPL-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 operators AND, OR and WITH in any case, ,, ; and /. Such words are common in prose: Intel Simplified Software License, SEE LICENSE IN doc/LICENSE and Lizenz mit Ausnahmen name no license, while MIT, Some proprietary thing and (Ruby) AND Foo bar name MIT and Ruby.

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

WhereWhat
The project pageA 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 pageA badge on each project with violations: the number of forbidden licenses, or of warnings when nothing is forbidden
Read APIGET /api/organizations/{organization}/license-policy and GET /api/organizations/{organization}/projects/{project}/license-violations
Upload APIevaluation.licenses in the response of an upload that waited: the counts and the first 20 violations
The upload gatefail_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

ViewerMemberAdminOwner
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:

EventSent toWhen
findings.newthe organization’s webhook and email recipientsafter a successful run that opened or reopened findings worth reporting, or found open findings newly known exploited
projects.stalethe organization’s webhook and email recipientsafter a successful scheduled run, when projects became stale
run.failedNANOBOM_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:

FormatPosted asFor
json (default)The JSON documents described belowYour own receiver, Home Assistant, n8n
slackA Slack message: text and Block Kit blocks (Slack messages)A Slack Incoming Webhook
teamsA 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:

BlockContent
headerAcme: 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
contextN 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 &amp;, &lt; and &gt;, 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 To header 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) and nanobom: 2 projects stopped sending SBOMs; in French, nanobom : 3 nouvelles vulnérabilités dans acme/web and nanobom : 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, or version sans nom in 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 POST per document, Content-Type: application/json, with the User-Agent nanobom/<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:

    AnswerOutcome
    2xx (200 ok from Slack, 202 Accepted from a Teams Workflows webhook, 204 from most receivers)Delivered
    4xx, except 408 and 429Failed 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:

    ReplyOutcome
    2xx (250 once 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 moreFailed 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 by nanobom_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.failed deliveries still waiting for a retry are abandoned at startup when NANOBOM_FAILURE_WEBHOOK_URL changed 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_URL was 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’s id for findings.new and run.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 exploited reason.

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
organizationSlug, display name and page of the organization
runThe run that found them: identifier, trigger (upload, scheduled or manual) and start time
countNumber of entries in findings, one per project, vulnerability and component
highest_severityThe highest severity among them
known_exploited_countHow many of them are known exploited
findings[].projectProject slug
findings[].componentThe component’s package URL
findings[].vulnerabilityThe finding’s identifier; aliases lists the others
findings[].severitycritical, high, medium, low or unknown
findings[].cvss_scoreCVSS base score of the finding’s record, or null
findings[].summaryOne-line summary from OSV, or null
findings[].reasonnew, reopened or exploited
findings[].reopenedtrue when reason is reopened
findings[].known_exploitedIn CISA’s KEV catalog
findings[].kev_due_dateCISA’s due date, or null
findings[].epss, epss_percentileEPSS score and percentile, from 0 to 1, or null
findings[].introduced_viaThe 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[].versionsThe 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[].urlThe 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
organizationSlug, display name and page of the organization
projects[].projectProject slug
projects[].last_upload_atTime of the project’s last upload; null for a project that never received an SBOM
projects[].urlThe 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_urlNANOBOM_PUBLIC_URL
runIdentifier, trigger (upload, scheduled or manual) and start time
scopeall (the scheduled run), organization or project
errorWhy 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:

PermissionViewerMemberAdminOwner
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, so Acme and acme are 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_LENGTH characters (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 from X-Forwarded-For, X-Real-IP or Forwarded only with NANOBOM_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 of email before @, 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:

  • group is a name as it appears in the groups claim; it may contain : but not =;
  • organization is an organization slug;
  • role is viewer, member, admin or owner.

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 owner in 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.

MetricType
nanobom_open_findings{severity}gaugeOpen 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_exploitedgaugeOpen findings of the active project versions with a CVE in CISA’s KEV catalog
nanobom_stale_projectsgaugeProjects whose SBOM stopped coming
nanobom_last_successful_run_timestamp_secondsgaugeUnix time at which the last successful run started
nanobom_runs_total{status}counterRuns, by status (succeeded, failed)
nanobom_run_failures_totalcounterRuns that could not complete
nanobom_run_duration_secondshistogramDuration of runs
nanobom_osv_request_errors_total{kind}counterFailed requests to OSV, retries included; kind is status (an error status) or request (network error or unreadable answer)
nanobom_exploitation_refresh_failures_totalcounterRefreshes 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}counterDelivery 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

MessageLevelMeaning
run failed; findings left unchangederrorA run could not complete; error says why
OSV request failed, retryingwarnA request to OSV failed and is retried
notification delivery failedwarnA 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 failedwarnThe 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 continueserrorA bug stopped a run, or the work after it; the run is recorded as failed
a run interrupted by a restart is recorded as failedwarnnanobom was stopped during a run; the run is closed at startup and sent to the failure webhook
refreshing exploitation data failedwarnKEV 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 memorywarnA KEV outage: the catalog downloaded hours ago is used instead
cross-site request refusedwarnA form submission came from another origin, often a wrong NANOBOM_PUBLIC_URL
OpenID Connect sign-in refusedwarnA single sign-on attempt failed; error says why
starting the OpenID Connect sign-in failederrorThe sign-in could not start, for example because discovery failed; error says why
database errorerrorAn unexpected database failure

Languages

The web interface is available in English and French. Each request is answered in:

  1. the language chosen in the account menu of the page header, remembered in the nanobom_locale cookie of that browser (it holds only the chosen language);
  2. otherwise, the best match among the browser’s preferred languages (Accept-Language);
  3. 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 (upload trigger);
  • 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:

StatusMeaningBecomes
OpenThe vulnerability affects a current componentignored by a member; fixed when the component goes away or OSV stops reporting it
IgnoredA member decided it does not apply or is accepted, with a reasonopen when restored or when its expiry date passes; fixed like an open one
FixedNo longer affects the projectopen 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

TriggerScopeWhen
uploadthe projectright after each upload (unless NANOBOM_RUN_AFTER_UPLOAD=false), or when an upload waits for its evaluation
scheduledevery project of the instanceon NANOBOM_SCHEDULE, by default 0 3 * * *: every day at 03:00 UTC
manualan organization or a projectCheck 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:

  1. returns findings whose ignore has expired to open;
  2. 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;
  3. 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;
  4. 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:

  1. 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);
  2. without a usable vector, the qualitative rating of the advisory database (database_specific.severity, as GitHub advisories give: CRITICAL, HIGH, MODERATE, LOW);
  3. 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_projects metric;
  • 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:

  1. known exploited first;
  2. then by severity, critical first;
  3. within a severity, by EPSS score, highest first; findings without a score last;
  4. 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=exploited gates 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 (an SPDXID in 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.0 in an npm tree resolve dep to different versions, foo 1.0.0 leads to both, and a path through foo 1.0.0 may 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:

GeneratorGraphPaths
cargo-cyclonedx 0.5.9complete, from the crateyes
cyclonedx-npm 6.0.1complete, from the packageyes
cyclonedx-py 8.0.1, environmentbetween installed packages; no metadata.componentno
Syft 1.57.0, CycloneDX, on an imagebetween packages; the image is in metadata.component, but nothing links it to themno
Syft 1.33.0, SPDX, on an image or a lock filebetween packages; the image or directory only contains themno
Trivy 0.76.2, SPDX, on a lock filethrough the lock file’s entry, which has no package URLno
GitHub dependency graph export (SPDX), package-lock.jsoncomplete, from the repositoryyes, except for direct dependencies that have no dependency and that no other package depends on (why)
GitHub dependency graph export (SPDX), Cargo.lockthe repository depends on every crate, none on anotherno

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_OF between packages when the lock file gives them, and makes the scanned directory or image CONTAINS every package, direct dependency or not. Containment is therefore not read as a dependency of the project: it would make every package direct. CONTAINS between 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_ON its dependencies. For package-lock.json these are the direct dependencies, development ones included, with DEPENDS_ON between packages below them. For Cargo.lock the 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_MANAGER and may name the project in documentDescribes, 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 in skipped. 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 as in_triage, with the reason as detail.
  • Open is in_triage, never exploitable. 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 stating exploitable would be as unfounded as stating not_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_positive state for a vulnerability wrongly associated with a component. nanobom offers it alongside the justifications so an ignore can say it, and an import of false_positive round-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-ref rather than a package URL) cannot be resolved, since nanobom does not keep the bom-refs of uploaded SBOMs.
  • Responses (can_not_fix, update…) and affects[].versions are 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.
ScopeUploads SBOMsImports VEX documentsCreates projectsReads (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

ToolToken
CI of one repositorythe 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 organizationread, 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 upload token 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. A read token 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;
  • Secure when NANOBOM_PUBLIC_URL is https, 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-Site other than same-origin or none), or
  • their Origin header differs from the origin of NANOBOM_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_HEADERS reads 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 state and 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, https or mailto address, and carries rel="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, a mailto address 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. projectVersion names the version of the project the SBOM goes to, as in Dependency-Track: uploads of 1.4.0 and 1.5.0 of 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 blank projectVersion is the unnamed version. Dependency-Track’s latest-version flag (isLatest) is nanobom’s latest. Before nanobom had versions, projectVersion was only recorded as the upload’s image tag, and uploads of every version replaced each other; pipelines that send a new projectVersion with 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 a 400, rather than mapping them to a name nobody chose. And a new version becomes the latest unless the upload says isLatest: 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.
  • autoCreate keeps its meaning. Without it, a missing project is a 404, 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-bom goal 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

CrateRole
domainEverything 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).
osvThe OSV client (batch queries, record details, retries) and CVSS-based severity.
authenticationSessions stored in the database, password and OpenID Connect sign-in, claims and group mapping, cross-site request checks.
entitySeaORM entities, generated from the migrations by mise run entities; never edited by hand.
migrationThe database schema, as SeaORM migrations.
appThe Leptos interface: pages, components, server functions, translations.
frontendThe WebAssembly entry point of the interface.
serverThe 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_SIZE with 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 keep NANOBOM_UPLOAD_WAIT_SECONDS above the usual duration of a project’s run plus the time it may wait behind the nightly run.