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

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