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

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.