Zum Inhalt springen
Craftifact

SBOM-Upload-API

Referenz für den Upload-Endpunkt für CycloneDX-SBOMs, inklusive Eingaben, Zielauswahl und Response-Formaten.

POST /api/sbom/upload/

Zweck

  • genau ein CycloneDX-JSON-Dokument annehmen
  • es genau einem bestehenden Ziel zuordnen
  • es zur Verarbeitung einplanen

Request

Query-Parameter

Nutze genau einen Zielmodus.

Paketartefakt-Modus

  • artifact_id : erforderlich

Nutze diesen Modus, wenn die SBOM zu einem bestehenden Paketartefakt wie einem Python-Wheel oder npm-Tarball gehört. Kopiere die artifact_id aus der Zeile Artifact ID im Detailbereich des Artefakts in Craftifact oder löse sie zuerst über die Artefakt-Suche API auf. Der Upload-Endpunkt legt nicht zuerst ein neues Paketartefakt für dich an.

OCI-Modus

  • oci_digest: erforderlich
  • repository: erforderlich

Nutze diesen Modus, wenn die SBOM zu bestehendem OCI-Inhalt gehört, der per Digest identifiziert wird.

Name Erforderlich Typ
artifact_id Optional string · uuid
oci_digest Optional string · pattern: ^sha256:[a-f0-9]{64}$
repository Optional string

Header-Aliasse

Nutze diese, wenn deine Automation lieber Header statt Query-Parameter setzt.

Name Erforderlich Typ
X-Sbom-Artifact-Id Optional string · uuid
X-Sbom-Oci-Digest Optional string · pattern: ^sha256:[a-f0-9]{64}$
X-Sbom-Repository Optional string

Request-Body

Der Body muss genau ein JSON-Objekt im CycloneDX-Format sein.

Minimale praktische Form:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6"
}

Validierungsregeln:

  • der Body muss gültiges JSON sein
  • der Top-Level-Wert muss ein Objekt sein
  • bomFormat muss CycloneDX sein
  • specVersion muss ein String sein

JSON-Payload

Erforderlich
bomFormat Erforderlich

string · const: CycloneDX

Must be CycloneDX.
specVersion Erforderlich

string

CycloneDX specification version string.

Zusätzliche Objektfelder sind erlaubt.

Beispiel-JSON 
{
  "bomFormat": "CycloneDX",
  "specVersion": "1.6"
}

Responses

Häufige Statuscodes:

  • 201 Created: die SBOM wurde angenommen und zur Verarbeitung eingeplant.
  • 400 Bad Request: die Zielauswahl ist ungültig oder der Body ist kein gültiges CycloneDX-JSON.
  • 401 Unauthorized: es wurden keine gültigen programmgesteuerten Credentials mitgegeben.
  • 403 Forbidden: dem Aufrufer fehlt der nötige Scope oder die nötige Repository-Berechtigung.
  • 404 Not Found: das referenzierte Artefakt oder der OCI-Inhalt existiert nicht.
  • 413 Payload Too Large: das konfigurierte Größenlimit oder die Repository-Quota würde überschritten.
201

Created

The SBOM was accepted and queued for parsing.
document_id Erforderlich

string · uuid

UUID of the queued SBOM document.
status Erforderlich

string · enum: pending

Initial processing state after the upload was accepted.
201 Beispiel-JSON 
{
  "document_id": "3f5d0a9d-4cbe-4e6a-b5b1-1b4c3930d9a1",
  "status": "pending"
}
400

Bad Request

Bad request. Typical causes include:

  • Neither artifact_id nor oci_digest was provided.
  • Both target modes were provided at once.
  • repository is missing in OCI mode.
  • The body is invalid JSON.
  • The body is not a JSON object.
  • The body is not valid CycloneDX JSON.
error Erforderlich

string

Human-readable error message for the rejected upload.
400 Beispiel-JSON 
{
  "error": "one of artifact_id or oci_digest is required"
}
401

Unauthorized

Authentication failed or no programmatic credentials were provided.
error Erforderlich

string

Human-readable error message for the rejected upload.
401 Beispiel-JSON 
{
  "error": "authentication required"
}
403

Forbidden

Forbidden. Typical causes include:

  • The token scope does not allow this repository family.
  • The caller lacks write or redeploy permission.
  • Redeploy is disabled for the target repository.
error Erforderlich

string

Human-readable error message for the rejected upload.
403 Beispiel-JSON 
{
  "error": "token scope does not permit this operation"
}
404

Not Found

Not found. Typical causes include:

  • artifact_id does not resolve to an uploaded artifact.
  • oci_digest together with repository does not resolve to uploaded OCI content.
error Erforderlich

string

Human-readable error message for the rejected upload.
404 Beispiel-JSON 
{
  "error": "artifact not found"
}
413

Payload Too Large

Payload too large. Typical causes include:

  • The SBOM exceeds the configured maximum size.
  • Repository quota would be exceeded by storing the uploaded SBOM blob.
error Erforderlich

string

Human-readable error message for the rejected upload.
413 Beispiel-JSON 
{
  "error": "document exceeds maximum size (10485760 bytes)"
}

Beispiele

curl: hochladen und an Artefakt binden 
curl \
  -X POST \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @dist/example-cyclonedx.json \
  "https://packages.example.com/api/sbom/upload/?artifact_id=ARTIFACT_ID"
curl: OCI-Inhalt 
curl \
  -X POST \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @image-cyclonedx.json \
  "https://packages.example.com/api/sbom/upload/?oci_digest=sha256:DIGEST&repository=libs-release"

Verwandte Seiten