Zum Inhalt springen
Craftifact

SBOM-Schwachstellenbericht-API

Referenz zum Lesen des gespeicherten Trivy-Schwachstellenberichts für ein SBOM-gestütztes Paketartefakt oder OCI-Subject.

GET /api/sbom/vulnerabilities/report/

Zweck

  • den effektiven Schwachstellenbericht für ein bestehendes Subject lesen
  • denselben subject-spezifischen Bericht nutzen, den Craftifact in Findings -> Vulnerabilities zeigt
  • Automation unterstützen, die gespeicherte Findings braucht, ohne das UI auszulesen

Request

Query-Parameter

Sende immer repository. Nutze danach genau einen Zielmodus.

Paketartefakt-Modus

  • artifact_id : erforderlich

Nutze diesen Modus, wenn der Bericht zu einem bestehenden Paketartefakt gehört.

OCI-Modus

  • oci_digest: erforderlich

Nutze diesen Modus, wenn der Bericht zu bestehendem OCI-Inhalt gehört, der im ausgewählten Repository per Digest identifiziert wird.

Optionale Filter

  • severity_min: gibt nur Findings ab dem ausgewählten Schweregrad zurück.
  • severity: gibt nur Findings mit einem exakten Schweregrad zurück. Wiederhole den Parameter, um mehrere Schweregrade einzuschließen.
  • q: filtert die zurückgegebenen Findings nach Schwachstellen- und Pakettext.
  • hide_suppressed=1: blendet aktiv unterdrückte Findings in der zurückgegebenen Liste aus.
  • limit und offset: blättern durch die zurückgegebene Findings-Liste.
Name Erforderlich Typ
repository Optional string
artifact_id Optional string · uuid
oci_digest Optional string · pattern: ^sha256:[a-f0-9]{64}$
severity_min Optional string · enum: critical, high, medium, low, unknown
limit Optional integer
offset Optional integer

Response

Die Response ist subject-spezifisch. Craftifact wählt die effektive SBOM für das angefragte Subject und führt Findings aus mehreren SBOM-Dokumenten für dasselbe Artefakt oder Image nicht zusammen.

Prüfe scan_state und summary, bevor du auf Basis von results handelst. Pending-, Failed- oder Invalid-Zustände solltest du nicht als sauberes Ergebnis behandeln. Prüfe außerdem summary.stale, bevor du einen fertigen Bericht als aktuell behandelst.

Häufige Statuscodes:

  • 200 OK: das ausgewählte Subject wurde aufgelöst und der Berichtszustand wird zurückgegeben.
  • 400 Bad Request: Zielauswahl, Paging oder Schweregrad-Filter ist ungültig.
  • 401 Unauthorized: es wurden keine gültigen programmgesteuerten Credentials mitgegeben.
  • 403 Forbidden: dem Aufrufer fehlt Lesezugriff oder Token-Scope für diese Repository-Familie.
  • 404 Not Found: Repository oder ausgewähltes Subject wird nicht zu einem zugänglichen Ziel aufgelöst.
200

OK

Effective vulnerability report for the selected subject.
target Erforderlich

object

document_id Erforderlich

object

scan_state Erforderlich

object

summary Optional

object

results Erforderlich

array

total Erforderlich

integer

limit Erforderlich

integer

offset Erforderlich

integer

200 Beispiel-JSON 
{
  "target": {
    "kind": "artifact",
    "artifact_id": "3f5d0a9d-4cbe-4e6a-b5b1-1b4c3930d9a1",
    "oci_digest": null,
    "repository": "libs-release"
  },
  "document_id": "11111111-2222-3333-4444-555555555555",
  "scan_state": "ready",
  "summary": {
    "scan_state": "ready",
    "finding_count": 1,
    "max_severity": "critical",
    "db_version": "1",
    "db_updated_at": "2026-04-23T09:15:00Z",
    "by_severity": {
      "critical": 1,
      "high": 0,
      "medium": 0,
      "low": 0,
      "unknown": 0
    }
  },
  "results": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "vulnerability_id": "CVE-2026-0001",
      "severity": "critical",
      "package_type": "maven",
      "package_name": "log4j-core",
      "package_path": "pkg:maven/com.example/demo@1.0.0",
      "package_purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.17.0",
      "component_name": "lang-pkgs",
      "component_version": "2.17.0",
      "component_purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.17.0",
      "installed_version": "2.17.0",
      "fixed_version": "2.17.1",
      "advisory_url": "https://example.test/CVE-2026-0001",
      "title": "Remote code execution"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
400

Bad Request

Bad request. Typical causes include:

  • repository is missing.
  • neither or both target selectors were provided.
  • limit, offset, or severity_min is invalid.
error Erforderlich

string

Human-readable error message for the rejected upload.
401

Unauthorized

Authentication failed or no programmatic credentials were provided.
error Erforderlich

string

Human-readable error message for the rejected upload.
403

Forbidden

The caller lacks read access or the token scope does not permit this repository family.
error Erforderlich

string

Human-readable error message for the rejected upload.
404

Not Found

The selected repository or subject does not resolve to an accessible uploaded target.
error Erforderlich

string

Human-readable error message for the rejected upload.

Beispiele

curl: Schwachstellenbericht für Paketartefakt 
curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  "https://packages.example.com/api/sbom/vulnerabilities/report/?repository=libs-release&artifact_id=ARTIFACT_ID"
curl: OCI-Schwachstellenbericht 
curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  "https://packages.example.com/api/sbom/vulnerabilities/report/?repository=containers&oci_digest=sha256:DIGEST&severity_min=high"

Verwandte Seiten