MCP für KI-gestützte Schwachstellen-Triage nutzen

Kurzpfad

1. Nutze eine Pro- oder Team-Instanz, bei der die MCP-Schnittstelle aktiviert ist.
2. Lege ein API- oder Robot-Token mit den eng begrenzten Repository-Rechten an, die dein Agent braucht.
3. Lege vor dem ersten Lauf fest, welche Repositorys oder exakten Subjects der Agent prüfen soll; Triage über alle Repositorys kann abgelehnt werden.
4. Hinterlege den Craftifact-MCP-Endpunkt in einem Agenten oder MCP-Client, der Remote-MCP per HTTP unterstützt, zum Beispiel Codex oder Claude Code.
5. Starte mit recommend_only; wechsle erst zu draft_proposals, wenn der Workflow passt.
6. Aktiviere direct_write erst für bewusst freigegebene Workflows und prüfe die resultierenden Suppressions regelmäßig.

Was die Schnittstelle tut

Craftifact stellt den MCP-Endpunkt unter INSTANZ_URL/mcp bereit. Das ist eine Schnittstelle für deinen eigenen KI-Agenten; Craftifact betreibt dabei kein KI-Modell für dich und führt keine automatische Triage aus. Der Agent authentifiziert sich mit dem hinterlegten Zugriffs-Token, sieht nur die Repositorys aus diesem Scope und kann Tools für Schwachstellen-Queues, Suppressions und Triage-Vorschläge nutzen. Der eigentliche Vorteil dieses Designs: Der Agent kann Findings aus Craftifact mit Kontext auf der ausführenden Workstation verbinden, etwa mit lokalem Quellcode, Build-Dateien oder dem aktuellen Branch. So kann er besser bewerten, welche Schwachstelle in deinem konkreten Repository relevant ist und welche eher nicht; ein Artifact-Repository allein könnte diesen Abgleich nicht leisten.

Modi

Mit dem Query-Parameter mode kontrollierst du die Autonomie in drei Stufen:

• recommend_only: Queues, Prompts und Redundanzprüfungen lesen. Das ist der Standard und der konservativste Modus.
• draft_proposals: erlaubt zusätzlich, Entwürfe für Triage-Vorschläge anzulegen, die ein Mensch prüft.
• direct_write: erlaubt zusätzlich, Schwachstellen-Suppressions direkt zu erstellen, wenn dafür die nötige Berechtigung vorhanden ist.

Für die meisten Teams ist draft_proposals der beste Arbeitsmodus. So bleibt die Ausgabe prüfbar, ohne den Agenten auf reine Empfehlungen zu begrenzen. direct_write passt für klar abgegrenzte Workflows, wenn du die erzeugten Suppressions regelmäßig unter Findings -> Suppressions prüfst.

Direkte Suppressions mit direct_write

Nutze den Direct-Write-Endpunkt nur für bewusst freigegebene Workflows:

https://packages.example.com/mcp?mode=direct_write

Führe die erste Session interaktiv aus. Nicht-interaktive MCP-Hosts können Tool-Aufrufe abbrechen, bevor du Repository-Lesezugriffe oder Schreibzugriffe freigeben kannst. Prüfe deshalb Queue, Token-Scope und Freigabe-Prompts, bevor du den Workflow automatisierst.

Im Modus direct_write muss der Agent check_vulnerability_suppression aufrufen, bevor er create_vulnerability_suppression nutzt. Der Check muss dieselben Findings und denselben Scope verwenden, die anschließend geschrieben werden sollen. Jede direkte Suppression braucht:

• scope_kind: einen unterstützten Suppression-Scope, zum Beispiel repository, artifact oder oci_repo.
• scope_key: den konkreten Scope-Identifier. Repository-Scope nutzt repository:<name>. Artifact-Scope nutzt artifact:<uuid> oder einen OCI-Digest-Scope.
• expires_at: ein ISO-8601-Datum mit Uhrzeit in der Zukunft.
• justification: eine kurze gespeicherte Begründung mit maximal 256 Zeichen.

Längere Begründungen, Advisory-Notizen und Evidenz aus lokalem Code gehören in den Abschlussbericht des Agenten. Für OCI-Artifact-Suppressions nutzt du oci_digest:sha256:<digest> als kanonischen Scope-Key. Agenten dürfen bei scope_kind="artifact" auch rohes sha256:<digest> senden; Craftifact normalisiert den Wert zu oci_digest:sha256:<digest>.

OCI-Subject-Namen sind nicht immer verfügbar. Wenn ein Work Item keinen Subject-Namen hat, nutze den zurückgegebenen Digest, subject.oci_locations oder subject.display_label, zum Beispiel OCI digest sha256:..., als stabile Kennung in Prompts, Berichten und Review-Notizen zu Suppressions.

Für exakte Schwachstellen-Triage auf einem Subject ruft der Agent das Work-Item-Tool mit repository und genau einem Wert aus artifact_id oder oci_digest auf. Bei OCI-Tags aus der UI löst du den Tag zuerst zum Digest auf und übergibst diesen Digest als oci_digest. Der Parameter q sucht in Finding-, Paket- und Scanner-Target-Texten; er ist nicht der bevorzugte Weg, um ein OCI-Image-Tag oder eine Version auszuwählen.

Token-Anforderungen

Lege für die Session ein API- oder Robot-Token an, das nur die Repositorys abdeckt, die der Agent prüfen darf. Für persönliche Triage-Sessions ist ein eigenes API-Token mit engem Scope oft passend. Für geteilte oder wiederholbare Automatisierung kann ein dediziertes Robot-Token sauberer sein. Unabhängig vom Typ arbeitet der Agent im Namen der Person, die die Session startet; diese Person trägt auch die Verantwortung für die Bewertung. Für reine Lese-Triage braucht es Repository-Lesezugriff und Findings-Lesezugriff. Für Entwürfe oder direkte Suppressions braucht es die Findings-Suppression-Berechtigung nur auf den Repositorys, für die der Agent diese Aktion vorbereiten oder ausführen darf.

Vermeide unnötig breite Scopes. Wenn ein Token nur für ein Repository oder einen Vorfall gedacht ist, halte den Scope so eng und rotiere es 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:

[mcp_servers.craftifact-vulnerability-triage]
url = "https://packages.example.com/mcp?mode=recommend_only"
bearer_token_env_var = "CRAFTIFACT_MCP_TOKEN"

Ersetze INSTANZ_HOST durch die Domain, unter der deine Craftifact-Instanz erreichbar ist. Wenn du Craftifact zum Beispiel unter https://craftifact.example.com/ öffnest, nutzt du craftifact.example.com in den Snippets.

Starte Codex danach aus dem Source-Checkout, den der Agent prüfen soll:

read -rsp "Craftifact MCP token: " CRAFTIFACT_MCP_TOKEN
printf "\n"
export CRAFTIFACT_MCP_TOKEN
codex --no-alt-screen -s workspace-write -a on-request

So landet das Token nicht in der Shell-History und nicht in der Codex-Konfiguration. Wenn du das Token bereits in einem Secret Manager oder einer Umgebungsvariable verwaltest, setze CRAFTIFACT_MCP_TOKEN stattdessen aus dieser Quelle, ohne den Wert auszugeben.

Nutze für den ersten Lauf interaktives Codex, damit du MCP-Tool-Aufrufe freigeben und sehen kannst, welche Repositorys der Agent liest. Nicht-interaktive Codex-Läufe müssen MCP-Tool-Aufrufe vorab erlauben; sonst kann der Host die Aufrufe abbrechen, bevor der Agent die Queue liest. Für Review-Entwürfe änderst du die URL auf ?mode=draft_proposals. Für direkte Suppressions änderst du die URL erst nach Freigabe von Workflow und Token-Scope auf ?mode=direct_write. Halte Repository-Namen und erwartete Grenzen in AGENTS.md fest, damit der Agent weiß, welche Findings er prüfen soll und wann er für menschliche Prüfung stoppen muss.

Gib dem Agenten eine konkrete Triage-Aufgabe, nicht nur eine Aufgabe zum Auflisten der Queue:

Nutze das Craftifact-Vulnerability-Triage-MCP im Modus recommend_only.
Grenze die Arbeit auf diese Repositorys oder exakten Subjects ein: REPOSITORY_OR_SUBJECT_NAMES.
Löse bei OCI-Image-Subjects zuerst den Tag zum Digest auf und rufe das Work-Item-Tool dann mit repository und oci_digest auf.
Liste nur für diese Ziele offene, nicht unterdrückte Findings.
Öffne für jedes Finding mit hoher oder wichtiger Priorität die Advisory-URL, prüfe lokalen Quellcode und Build-Dateien auf erreichbare Nutzung des betroffenen Pakets oder Features und erkläre, ob das Finding anwendbar ist.
Nenne Finding-IDs, Pakete, Versionen, Repository oder Subject, Priority, Severity, Advisory-Evidenz und lokale Evidenz.
Empfiehl zuerst eine Behebung oder den engsten sicheren Suppression-Scope, wenn eine Behebung nicht die richtige unmittelbare Maßnahme ist.
Erstelle keine Suppressions, außer der MCP-Server läuft im Modus direct_write und die Evidenz trägt die Entscheidung klar.
Rufe im Modus direct_write zuerst check_vulnerability_suppression mit dem exakt vorgesehenen Scope auf. Halte die gespeicherte justification unter 256 Zeichen und schreibe ausführlichere Begründungen in den Abschlussbericht.

Beispiel: Claude Code

Hinterlege denselben Remote-MCP-Endpunkt in deinen Claude-Code-Projekt- oder Nutzereinstellungen. Nutze zuerst recommend_only und danach draft_proposals, wenn du Prompt und Token-Scope geprüft hast.

{
  "mcpServers": {
    "craftifact-vulnerability-triage": {
      "url": "https://packages.example.com/mcp?mode=recommend_only",
      "headers": {
        "Authorization": "Bearer ${CRAFTIFACT_MCP_TOKEN}"
      }
    }
  }
}

Claude Code unterstützt Header an Remote-MCP-Servern; das Beispiel oben nutzt diesen Weg direkt. Wenn du stattdessen einen Client ohne konfigurierbare Header einsetzt, nutze den mcp-remote-Fallback unten und übergib den Authorization-Header dort.

mcp-remote-Fallback

Nutze mcp-remote, wenn dein Agent einen lokalen stdio-MCP-Server erwartet oder dein gewählter Client keine konfigurierbaren HTTP-Header für Remote-MCP bietet.

npx mcp-remote https://packages.example.com/mcp?mode=recommend_only \
  --header "Authorization: Bearer ${CRAFTIFACT_MCP_TOKEN}"

Pinne die mcp-remote-Version in gemeinsamer Automatisierung, wenn Reproduzierbarkeit wichtig ist. Lass den Fallback-Befehl in Umgebungen mit Paket-Policy keine Pakete direkt aus öffentlichen Registrys laden; leite solche Installationen über Craftifact-Proxys.

Sichere Nutzung

Behandle Agent-Triage als Entscheidungshilfe. Fordere Finding-IDs, betroffene Pakete, Zielumgebungen, Prioritätssignale und den vorgeschlagenen Suppression-Scope ein. Verlange außerdem Evidenz aus dem Advisory und aus lokalem Code oder Build-Dateien, bevor du eine Suppression-Empfehlung akzeptierst. Gute Suppressions erklären, warum der betroffene Codepfad für das konkrete Artifact nicht erreichbar oder irrelevant ist; sie verweisen nicht nur darauf, dass ein Scanner ein wahrscheinlich geringes Risiko gemeldet hat. Bevor du einen Vorschlag akzeptierst oder direct_write nutzt, prüfe, dass der Scope nicht breiter als nötig ist und die Begründung die aktuelle Risikoentscheidung erklärt.

Für wiederkehrende Findings sind Entwürfe mit explizitem Ablaufdatum meist die bessere Wahl. Wenn du direct_write für einen eng abgegrenzten Vorfall oder einen gut verstandenen Routine-Workflow aktivierst, nutze kurze Laufzeiten und prüfe danach das Suppression-Ledger unter Findings -> Suppressions. Rufe vor jeder direkten Suppression check_vulnerability_suppression auf und halte justification kurz genug für das 256-Zeichen-Limit. Ausführlichere Begründungen gehören in den Bericht, nicht in das gespeicherte Suppression-Feld.

Fehlerbehebung

Wenn eine Queue-Abfrage über alle Repositorys abgelehnt wird, lass den Agenten repository angeben oder eine ausreichend spezifische q-Abfrage nutzen. Craftifact kann engere MCP-Abfragen verlangen, damit ein Agent nicht mehr Findings liest, als er für die aktuelle Triage-Aufgabe braucht. Wenn die UI ein OCI-Tag wie namespace:tag zeigt, löse es zum Digest auf und rufe das Work-Item-Tool mit repository und oci_digest auf; verlasse dich nicht darauf, dass q den Tag findet. Wenn ein OCI-Subject keinen Namen hat, nutze den zurückgegebenen Digest, subject.oci_locations oder subject.display_label als stabile Kennung.