Evidence-Snapshots-API

Zweck

• ein explizites Set aus Paketartefakten und OCI-Subjects einfrieren
• kompakte SBOM-, Schwachstellen-, Lizenz-, Suppression-, Policy-Decision- und Provenance-Zusammenfassungen erfassen
• Automation einen stabilen technischen Review-Datensatz geben, ohne ein Compliance-Paket zu exportieren

Request

Sende name und mindestens ein Subject. Jedes Subject muss repository und genau einen Selektor enthalten.

Paketartefakt-Subject

• artifact_id: vorhandene Paketartefakt-ID

OCI-Subject

• oci_digest: vorhandener sichtbarer OCI-Manifest- oder Index-Digest

Für Least Privilege erfordert Snapshot-Erzeugung aktuellen Paketartefakt-Lesezugriff, Composition-Lesezugriff für SBOM-Daten, Findings-Lesezugriff, Lizenz-Policy-Lesezugriff, Pull-Gate-Inspect-Zugriff und Token-Scope für jede referenzierte Repository-Familie. Bereits vorhandene Findings-Suppress-Berechtigungen oder Lizenz-Policy-Konfigurationsberechtigungen erfüllen die entsprechenden Sichtbarkeitsprüfungen ebenfalls, sind für read-only Evidence-Sammlung aber nicht nötig.

capture_options lässt privilegierte Suppression-Details standardmäßig weg. Setze include_suppression_actor_rationale, um created_by und justification aus Suppressions zu erfassen, und include_suppression_scope_details, um scope_key und scope_label zu erfassen. Jede dieser Optionen erfordert findings:suppress auf allen ausgewählten Repositorys. Einbezogene Werte werden im Snapshot eingefroren und sind für alle sichtbar, die diesen Snapshot später lesen oder herunterladen können.

{
  "name": "Release 1.0 review",
  "description": "Technical review inputs for release 1.0.",
  "capture_options": {
    "include_suppression_actor_rationale": false,
    "include_suppression_scope_details": false
  },
  "subjects": [
    {
      "repository": "libs-release",
      "artifact_id": "4fd75091-2d3a-48b7-9e35-85a5edfa1d92"
    },
    {
      "repository": "containers",
      "oci_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}

Create-Responses

Häufige Statuscodes:

• 201 Created: der Snapshot wurde angelegt und mit den erfassten Subjects zurückgegeben.
• 400 Bad Request: das Subject-Set ist leer, doppelt, zu groß oder nutzt ungültige Selektoren.
• 401 Unauthorized: es wurden keine gültigen programmgesteuerten Credentials mitgegeben.
• 403 Forbidden: der Aufrufer kann auf das Repository zugreifen, aber ihm fehlt eine erforderliche Evidence-Summary-Berechtigung.
• 404 Not Found: ein Repository oder ausgewähltes Subject kann nicht aufgelöst werden oder wird durch Repository-Lesezugriff oder Token-Scope verborgen.

Snapshots Listen

Die Liste enthält nur Snapshots, bei denen du noch auf jedes erfasste Repository zugreifen kannst. Teilweise unzugängliche Snapshots werden ausgelassen, statt ihre Existenz offenzulegen. Snapshots können sichtbar bleiben, wenn ein erfasstes Artefakt oder OCI-Subject nicht mehr live verfügbar ist, solange das erfasste Repository weiterhin zugänglich ist.

Snapshot Lesen

Nutze die Snapshot-ID aus Create- oder List-Responses. Die Response enthält die erfassten Subjects und die beim Anlegen eingefrorenen Zusammenfassungen. Diese eingefrorenen Werte bleiben lesbar, auch wenn das ursprüngliche Artefakt, Tag, Manifest oder der Index später gelöscht, verborgen, ungetaggt oder anderweitig nicht verfügbar ist. Live-Detail-Links sind nur verfügbar, solange das Quell-Subject noch aufgelöst werden kann.

Snapshot Exportieren

Nutze den Export, wenn du eine portable Kopie des Snapshot-Bundles brauchst. Die ZIP-Datei enthält manifest.json mit SHA-256-Hashes, evidence.json mit dem erfassten Snapshot-Payload, summary.md mit einer kompakten Markdown-Zusammenfassung sowie die subjectbezogenen Detaildateien subjects/<subject-id>/vulnerabilities.json und subjects/<subject-id>/suppressions.json. Craftifact nutzt die eingefrorenen Snapshot-Werte und berechnet beim Export keine Live-SBOM-, Schwachstellen-, Lizenz-, Suppression-, Policy-Decision- oder Provenance-Daten neu. Exporte bleiben auf erfasste Werte gestützt, auch wenn das Quell-Subject nicht mehr verfügbar ist. Wenn privilegierte Suppression-Felder beim Erfassen eingeschlossen wurden, enthalten die exportierten Detaildateien diese eingefrorenen Werte auch für spätere Betrachter mit reinem Lesezugriff auf den Snapshot.

Beispiele

curl \
  -X POST \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Release 1.0 review","subjects":[{"repository":"libs-release","artifact_id":"ARTIFACT_ID"},{"repository":"containers","oci_digest":"sha256:DIGEST"}]}' \
  "https://packages.example.com/api/evidence/snapshots/"

curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  "https://packages.example.com/api/evidence/snapshots/"

curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  "https://packages.example.com/api/evidence/snapshots/SNAPSHOT_ID/"

curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  -o evidence-snapshot.zip \
  "https://packages.example.com/api/evidence/snapshots/SNAPSHOT_ID/export/"

Grenzen

Ein Evidence-Snapshot ist ein technischer Review-Datensatz. Er bestätigt keine rechtliche Compliance, keinen Konformitätsbewertungsstatus, keine CE-Kennzeichnung, keinen gesetzlichen Meldezustand und keine finale Release-Freigabe.

Verwandte Seiten

• Um Paketartefakt-IDs zuerst aufzulösen, siehe Artefakt-Suche API.
• Um zuerst SBOM-Daten anzuhängen, siehe SBOM-Upload-API.
• Um Live-Schwachstellendetails für ein Subject zu lesen, siehe SBOM-Schwachstellenbericht-API.