Zum Inhalt springen
Craftifact

MCP für KI-gestützte Evidence-Sammlung nutzen

Verbinde deinen eigenen MCP-fähigen KI-Agenten, um technische Evidence-Snapshots für explizite Paketartefakt- und OCI-Subject-Sets zu sammeln und als Review-Bundle zu exportieren.

Kurzpfad

  1. Nutze eine Pro- oder Team-Instanz, bei der Evidence-Snapshots und die MCP-Schnittstelle aktiviert sind.
  2. Lege ein API- oder Robot-Token mit engem Repository-Family-Scope und den Leseberechtigungen an, die dein Agent braucht.
  3. Identifiziere die exakten Paketartefakt-IDs oder OCI-Digests, die zur Review-Menge gehören.
  4. Hinterlege den Craftifact-MCP-Endpunkt mit mode=evidence_review in deinem Agenten oder MCP-Client.
  5. Lass den Agenten mit craftifact_collect_evidence_snapshot starten und Evidence nur für das explizite Subject-Set sammeln.
  6. Prüfe den resultierenden Snapshot in Craftifact und exportiere das technische Bundle über den REST-Endpunkt, wenn du eine portable Kopie brauchst.
  7. Bewahre produktbezogene Entscheidungen, rechtliche Schlussfolgerungen, Meldezustand und Release-Freigaben in deinem eigenen Review-System auf.

Was der Workflow tut

Craftifact stellt den MCP-Endpunkt unter INSTANZ_URL/mcp bereit. Für Evidence-Sammlung nutzt du den Endpunkt mit mode=evidence_review. Dieser Modus ist für deinen eigenen KI-Agenten gedacht; Craftifact betreibt dabei kein KI-Modell für dich und trifft keine Compliance-Entscheidung.

Der Agent hilft, einen technischen Evidence-Snapshot für ein begrenztes Subject-Set zu sammeln. Jedes Subject muss explizit sein: eine Paketartefakt-ID oder ein OCI-Subject mit Repository und Digest. Diese Grenze ist wichtig, weil ein Artefakt-Repository deine Produkt-Release-Zuordnung, Support-Zeiträume, Nutzerexposition, rechtlichen Status oder Release-Freigabe nicht ableiten kann.

Der resultierende Export ist ein technisches Evidence-Bundle. Es kann Snapshot-Metadaten und kompakte Zusammenfassungen zu Subjects, SBOM-Status, Schwachstellenstatus, Suppressions, Lizenz- und Policy-Decision-Kontext sowie Provenance-Werten enthalten, die Craftifact vorliegen. Diese Werte werden beim Erfassen eingefroren, sodass der Snapshot weiterhin aus erfassten Daten gelesen und exportiert werden kann, wenn das ursprüngliche Paketartefakt oder OCI-Subject später verschwindet, ungetaggt wird oder anderweitig nicht verfügbar ist. Es ist kein Compliance-Paket und ersetzt keine Produktrisikobewertung, keine Vulnerability-Disclosure-Verantwortung, keine gesetzlichen Meldeprozesse, keine Update-Auslieferung, keine CE-Kennzeichnung und keine finale Release-Freigabe.

MCP-Modus und Prompt

Nutze den Query-Parameter mode:

evidence_review-MCP-Endpunkt 
https://packages.example.com/mcp?mode=evidence_review

Starte mit dem MCP-Prompt:

Evidence-Prompt-Name 
craftifact_collect_evidence_snapshot

Gib dem Prompt ein explizites Subject-Set. Für Paketartefakte gibst du artifact_id-Werte an. Für OCI-Inhalte gibst du Repository und Digest an. Bitte den Agenten nicht, Evidence für ein ganzes Repository zu sammeln, solange du den Release-Scope nicht vorher in explizite Paketartefakt- oder OCI-Subject-Einträge übersetzt hast.

Exportpfade

Craftifact unterstützt zwei Exportpfade für technische Evidence-Bundles, aber sie gehören zu unterschiedlichen Workflows:

  • REST-Export für vorhandene Snapshots: GET /api/evidence/snapshots/{snapshot_id}/export/
  • UI-Erfassung für das aktuell ausgewählte UI-Subject: POST /ui/api/evidence/snapshots/export/

Nutze den REST-Endpunkt, wenn Automation oder MCP bereits eine snapshot_id aus dem Evidence-Snapshot-Workflow hat. Das ist der Exportpfad für Multi-Subject-Snapshots. Der Export basiert auf erfassten Werten, nicht auf Live-Neuberechnung, und bleibt deshalb nutzbar, wenn das Quell-Artefakt oder OCI-Subject nicht mehr erreichbar ist; die aktuelle Repository-Sichtbarkeit steuert weiterhin, wer den Snapshot lesen oder exportieren darf.

Nutze die UI-Aktion, wenn eine prüfende Person in Browse oder Dependencies arbeitet und einen frischen Snapshot für das aktuell ausgewählte Paketartefakt oder OCI-Subject braucht. Die UI-Aktion erstellt einen neuen Single-Subject-Snapshot und öffnet ihn in der Evidence-Ansicht, wo die prüfende Person das Bundle herunterladen kann; sie exportiert keinen vorhandenen Snapshot per ID direkt.

Privilegierte Suppression-Felder werden standardmäßig nicht einbezogen. API und UI können Suppression-created_by, justification, scope_key und scope_label einschließen; dafür ist findings:suppress auf allen ausgewählten Repositorys nötig, und die enthaltenen Werte sind später für alle sichtbar, die den Snapshot lesen oder herunterladen können.

Nutze heruntergeladene Bundles, wenn ein externes Release-Archiv, ein Audit-Unterstützungs-Workflow oder eine prüfende Person eine portable Kopie des Snapshots braucht.

Token-Anforderungen

Nutze ein eng begrenztes API- oder Robot-Token. Das Token muss jede Repository-Familie im Subject-Set abdecken. Für Least Privilege gibst du Paketartefakt-Lesezugriff, Composition-Lesezugriff für SBOM-Daten, Findings-Lesezugriff, Lizenz-Policy-Lesezugriff und Pull-Gate-Inspect-Zugriff für jedes referenzierte Repository. 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.

Vermeide breite organisationsweite Tokens für einen einzelnen Release-Review. Wenn die Evidence-Aufgabe zu einem Incident oder Release Candidate gehört, halte den Scope auf diese Menge begrenzt und rotiere das Token nach der Session.

Remote-MCP-Client einrichten

Jeder Agent oder MCP-Client, der Remote-MCP per HTTP mit konfigurierbaren Headern unterstützt, kann den Craftifact-Endpunkt nutzen. Übergib das Zugriffs-Token über eine Umgebungsvariable oder einen Secret Store, nicht über committete Dateien.

Beispiel: Codex

Trage den MCP-Server in die Codex-Konfiguration ein:

~/.codex/config.toml 
[mcp_servers.craftifact-evidence-review]
url = "https://packages.example.com/mcp?mode=evidence_review"
bearer_token_env_var = "CRAFTIFACT_MCP_TOKEN"

Ersetze INSTANZ_HOST durch die Domain, unter der deine Craftifact-Instanz erreichbar ist. Starte Codex danach aus dem Source-Checkout oder Release-Workspace, dessen Kontext der Agent berücksichtigen soll:

Erster Codex-Lauf (Bash) 
read -rsp "Craftifact MCP token: " CRAFTIFACT_MCP_TOKEN
printf "\n"
export CRAFTIFACT_MCP_TOKEN
codex --no-alt-screen -s workspace-write -a on-request

Nutze für den ersten Lauf interaktives Codex, damit du MCP-Lesezugriffe freigeben und das Subject-Set bestätigen kannst, bevor der Agent einen Snapshot sammelt.

Gib dem Agenten eine begrenzte Aufgabe:

Prompt für Evidence-Sammlung 
Nutze das Craftifact-Evidence-Review-MCP im Modus evidence_review.
Starte mit dem Prompt craftifact_collect_evidence_snapshot.
Grenze die Arbeit auf diese Paketartefakt-IDs und OCI-Subjects ein: SUBJECT_SET.
Sammle genau einen technischen Evidence-Snapshot für exakt diese Menge.
Berichte die Snapshot-ID, alle enthaltenen Subjects, SBOM-Abdeckung, Schwachstellen- und Freshness-Status, aktive Suppressions, Lizenz- und Policy-Decision-Zusammenfassungen, Provenance-Notizen und fehlende oder veraltete Eingaben.
Wenn ein Export-Bundle für den erstellten Snapshot nötig ist, nutze den REST-Export-Endpunkt für die Snapshot-ID: GET /api/evidence/snapshots/{snapshot_id}/export/.
Für einen frischen Single-Subject-Snapshot aus der aktuellen `Browse`- oder `Dependencies`-Auswahl nutze die UI-Erfassung in Craftifact.
Lade das Bundle anschließend aus der Evidence-Ansicht herunter.
Erweitere das Subject-Set nicht, leite keine Release-Vollständigkeit ab und triff keine Aussagen zu rechtlicher Compliance, Konformität, Meldepflichten, CE-Kennzeichnung oder Release-Freigabe.

Sichere Nutzung

Behandle den Agenten als Sammler und Prüfer technischer Eingaben. Lass ihn die Snapshot-ID nennen, alle enthaltenen Subjects auflisten und Einschränkungen wie fehlende SBOMs, veraltete Schwachstellendaten, fehlgeschlagene Verarbeitung oder unzugängliche Repositorys markieren.

Lass den Agenten keinen Repository-Namen in eine Release-Grenze umdeuten. Release-Zuordnung, Support-Zeiträume, Nutzerexposition, Produktrisiko-Entscheidungen, rechtliche Bewertung, Meldepflichten, Nutzerkommunikation und Release-Freigabe bleiben außerhalb von Craftifact.

Fehlerbehebung

Wenn der Agent einen breiten Repository-Review anfragt, formuliere die Aufgabe erneut mit expliziten Paketartefakt-IDs oder OCI-Digests. Wenn der REST-Export fehlschlägt, prüfe, ob die snapshot_id existiert und das Token weiterhin Zugriff auf jedes vom Snapshot erfasste Repository hat. Wenn Codex MCP-Tool-Aufrufe in einem nicht-interaktiven Lauf abbricht, starte den ersten Lauf interaktiv mit -a on-request, damit du MCP-Lesezugriffe freigeben kannst.

Verwandte Seiten