SBOM API

15 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.

Endpoints

GET /.well-known/openartifact/attestation-key.pem

Attestation public key

The PEM (PKIX) public key that verifies SBOM and VEX attestations, for cosign verify-blob-attestation --key. Unauthenticated.

Authentication: none (public endpoint).

Responses

Status	Description	Body
200	PEM public key	application/x-pem-file: string
501	Attestations are not enabled	-

GET /api/v1/admin/attestation

Describe the attestation signing key

Admin only. The key signs ?attest= SBOM and VEX downloads; its public half is also served unauthenticated at public_key_url.

Responses

Status	Description	Body
200	Success	application/json: AttestationKey
501	Attestations are not enabled	-
default	Error	application/json: Error

GET /api/v1/repositories/{name}/attestation-attach

Get the referrer-attach setting

Admin only. Whether SBOM and VEX attestations are attached to the repository's docker images automatically.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Responses

Status	Description	Body
200	Success	application/json: AttestationAttachSettings
404	Repository not found	-
default	Error	application/json: Error

PUT /api/v1/repositories/{name}/attestation-attach

Set the referrer-attach setting

Admin only; hosted docker repositories only. When on, a generated SBOM and a finished vulnerability scan attach a signed SBOM and VEX attestation to the image as OCI referrers. Off by default.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Request body (required)

application/json: AttestationAttachSettings

Responses

Status	Description	Body
200	Saved	application/json: AttestationAttachSettings
400	Not a hosted docker repository	-
404	Repository not found	-
501	Attestations are not enabled	-
default	Error	application/json: Error

GET /api/v1/repositories/{name}/sbom

List SBOM reports

List SBOM reports for a repository

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Responses

Status	Description	Body
200	List of SBOM reports	application/json: object
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	Repository or addressed resource not found	application/json: Error

Fields of the 200 response (application/json):

Field	Type	Required	Description
reports	array of SBOMReport	no	-

POST /api/v1/repositories/{name}/sbom/generate

Generate SBOM

Generate a Software Bill of Materials for a repository artifact. Components are the dependencies declared by the stored package file (manifest and lockfile) merged with the artifact's dependencies property.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Request body (required)

application/json: object

Field	Type	Required	Description
artifact_id	string (uuid)	yes	-
format	string	yes	cyclonedx (JSON), spdx (2.3 tag-value), spdx-json (2.3 JSON) or spdx3-json (SPDX 3.0.1 JSON-LD). One of: cyclonedx, spdx, spdx-json, spdx3-json.
metadata	object	no	-
spec_version	string	no	CycloneDX 1.4, 1.5 (default) or 1.6; SPDX 2.3; SPDX 3 3.0.1. Optional.

Responses

Status	Description	Body
201	SBOM generation started	-
400	Invalid request	application/json: Error
403	Forbidden	application/json: Error
404	Repository or addressed resource not found	application/json: Error
422	The artifact's package file is too large or ambiguous to be read safely (unsafe_artifact)	-

GET /api/v1/repositories/{name}/sbom/{id}

Get SBOM report

Get details of a specific SBOM report

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
id	path	string (uuid)	yes	-

Responses

Status	Description	Body
200	SBOM report details	application/json: SBOMReport
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	SBOM report not found	-

DELETE /api/v1/repositories/{name}/sbom/{id}

Delete SBOM report

Delete a specific SBOM report

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
id	path	string (uuid)	yes	-

Responses

Status	Description	Body
204	SBOM report deleted	-
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	SBOM report not found	-

POST /api/v1/repositories/{name}/sbom/{id}/attach

Attach a signed SBOM to its docker image

Admin only. Signs the stored SBOM (JSON formats only) and attaches the Sigstore bundle to the image manifest as an OCI referrer; an earlier attachment of the same predicate is replaced.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
id	path	string	yes	-

Responses

Status	Description	Body
200	An identical attestation was already attached	application/json: AttestationAttachResult
201	Attached	application/json: AttestationAttachResult
400	Not a hosted docker repository, or not a JSON SBOM	-
403	Admin access required	-
404	Repository, report or image not found	-
507	Repository storage quota exceeded	-
default	Error	application/json: Error

GET /api/v1/repositories/{name}/sbom/{id}/download

Download SBOM report

Download an SBOM report file

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
id	path	string (uuid)	yes	-
attest	query	string	no	true returns the document as a signed in-toto attestation in a DSSE envelope; bundle returns a Sigstore bundle, the input of cosign verify-blob-attestation. Verify with the key from /.well-known/openartifact/attestation-key.pem. One of: true, bundle.

Responses

Status	Description	Body
200	SBOM file, or its attestation with attest	application/octet-stream: string (binary); application/vnd.dev.sigstore.bundle.v0.3+json: object; application/vnd.dsse.envelope.v1+json: object
400	Invalid attest value, or the SBOM is not a JSON document (SPDX tag-value cannot be attested)	-
403	Forbidden	application/json: Error
404	SBOM report not found	-
501	Attestations are not enabled	-

GET /api/v1/repositories/{name}/vex

Download a VEX document

Build an OpenVEX 0.2.0 (default) or CycloneDX VEX document from the latest vulnerability scans and the recorded VEX decisions. With artifact_id it covers one artifact, otherwise every scanned artifact of the repository. Status per vulnerability: the recorded decision; else fixed when the scan's fixed_in is at or below the artifact version; else affected when the scan quarantined the artifact; else under_investigation. not_affected only comes from a recorded decision. Admin only.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
format	query	string	no	One of: openvex, cyclonedx. Default: openvex.
spec_version	query	string	no	CycloneDX spec version (1.4, 1.5 or 1.6; default 1.5). CycloneDX only.
artifact_id	query	string	no	Restrict the document to one artifact (name@version).
attest	query	string	no	true returns the document as a signed in-toto attestation in a DSSE envelope; bundle returns a Sigstore bundle, the input of cosign verify-blob-attestation. Verify with the key from /.well-known/openartifact/attestation-key.pem. One of: true, bundle.

Responses

Status	Description	Body
200	VEX document, or its attestation with attest	application/json: object; application/vnd.dev.sigstore.bundle.v0.3+json: object; application/vnd.dsse.envelope.v1+json: object
400	Invalid format, spec_version or artifact_id	-
403	Forbidden	application/json: Error
404	Repository not found	-
501	Attestations are not enabled	-

POST /api/v1/repositories/{name}/vex/attach

Attach a signed VEX document to its docker image

Admin only. Builds the artifact's VEX document, signs it and attaches the Sigstore bundle to the image manifest as an OCI referrer; an earlier attachment of the same predicate is replaced.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Request body (required)

application/json: object

Field	Type	Required	Description
artifact_id	string	yes	-
format	string	no	One of: openvex, cyclonedx.

Responses

Status	Description	Body
200	An identical attestation was already attached	application/json: AttestationAttachResult
201	Attached	application/json: AttestationAttachResult
400	Not a hosted docker repository, or not a JSON SBOM	-
403	Admin access required	-
404	Repository, report or image not found	-
507	Repository storage quota exceeded	-
default	Error	application/json: Error

GET /api/v1/repositories/{name}/vex/statements

List VEX decisions

List the VEX decisions recorded for a repository, optionally for one artifact. Admin only.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
artifact_id	query	string	no	-

Responses

Status	Description	Body
200	VEX decisions	application/json: object
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	Repository not found	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
statements	array of VEXStatement	no	-

PUT /api/v1/repositories/{name}/vex/statements

Record a VEX decision

Record (or replace) the decision for one vulnerability of one artifact. not_affected requires a justification; other statuses must not carry one. Admin only.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-

Request body (required)

application/json: object

Field	Type	Required	Description
action_statement	string	no	-
artifact_id	string	yes	-
impact_statement	string	no	-
justification	string	no	One of: component_not_present, vulnerable_code_not_present, vulnerable_code_not_in_execute_path, vulnerable_code_cannot_be_controlled_by_adversary, inline_mitigations_already_exist.
status	string	yes	One of: affected, not_affected, fixed, under_investigation.
vuln_id	string	yes	e.g. CVE-2024-1234 or GHSA-xxxx

Responses

Status	Description	Body
200	Recorded decision	application/json: VEXStatement
400	Validation failed	-
403	Forbidden	application/json: Error
404	Repository not found	-

DELETE /api/v1/repositories/{name}/vex/statements/{id}

Delete a VEX decision

Delete a recorded VEX decision; the vulnerability falls back to its derived status. Admin only.

Parameters

Name	In	Type	Required	Description
name	path	string	yes	-
id	path	string (uuid)	yes	-

Responses

Status	Description	Body
204	Decision deleted	-
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	Repository or decision not found	-