kos2001/code-shieldEvidenzgesteuerte C/C++-Schwachstellenbehebungspipeline + http-parser Fallstudie (CVE-2024-22019-class). Python-Kern, React 19-Konsole, 17-Test-Verifikationssuite.
MVP, das Schwachstellen-Findings in C/C++-Protokoll-/Plattform-Code in reproduzierbare Beweise normalisiert und Kandidaten-Patches in isolierten Kopien validiert. code-shield war ein Arbeitstitel, bei dem ein Namenskonfliktrisiko festgestellt wurde, daher werden für öffentliche Pakete und CLI neutrale interne Namen verwendet.
Der Schwerpunkt der aktuellen Implementierung liegt nicht auf dem Patch-Erzeugungsmodell, sondern auf der folgenden Verifikations-Rückkopplungsschleife.
Sanitizer oder SARIF
-> Finding + EvidenceBundle
-> Quellkontext
-> manueller/externer Agenten-Patch
-> Original reproduzieren
-> Build
-> gepatchter Reproducer
-> Tests
-> statischer Rescan
-> begrenztes Refuzz
-> Protokoll-Orakel
-> verifizierter Report
Finding, EvidenceBundle, PatchProposal, VerificationReportdetected → reproducible → contextualized → proposed → plausible → verifiedEs gibt keine Python-Laufzeitabhängigkeiten.
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v
Ohne Installation ausführen:
PYTHONPATH=src python3 -m protocol_remediator --help
PYTHONPATH=src python3 -m unittest discover -s tests -v
Das dynamische End-to-End-Suite ist die C/C++-Fixture-Matrix in examples. Es reproduziert tatsächlich CWE-121, CWE-190, CWE-416, CWE-787, CWE-476 mit Clang ASan/UBSan und führt dann alle sechs Gates für Patches aus, die die jeweiligen Invarianten wiederherstellen. Eingaben und Validierungsumfang pro Fixture sind in examples/README.md dokumentiert.
Um nur die reale Matrix ohne Unit-Test-Framework auszuführen:
PYTHONPATH=src python3 examples/run_fixture_matrix.py
Um mehr automatisch generierte C/C++-Varianten zu erstellen und auszuführen:
PYTHONPATH=src python3 examples/run_generated_corpus.py --count 50
Dieser Runner verwendet kein unittest, sondern übergibt jedes generierte Projekt an dieselbe VerificationPipeline. Die Ergebniszusammenfassung landet standardmäßig in artifacts/generated-corpus-summary.json.
Ein Vite + React + TypeScript-Frontend, das den aktuellen Implementierungsstatus als betriebsfähiges Dashboard anzeigt, befindet sich in frontend. Diese Konsole fasst die Fixture-Matrix, den generierten Corpus, die Hermes-API-Server-Verbindung, die Verifikations-Gates und die Evidence-Safety-Invarianten auf einem Bildschirm zusammen.
cd frontend
npm install
npm run dev
Der Standard-Entwicklungsserver läuft unter http://127.0.0.1:5173. Der Production-Build wird wie folgt erstellt:
cd frontend
npm run build
protocol-remediator ingest-sanitizer \
--log asan.log \
--reproducer crash.input \
--target-name parser \
--revision 0123456789abcdef \
--variant asan-x86_64 \
--output intake/parser-crash
Ausgabe:
intake/parser-crash/finding.json
intake/parser-crash/evidence.json
protocol-remediator ingest-sarif \
--sarif results.sarif \
--output intake/sarif
protocol-remediator export-sarif \
--finding intake/parser-crash/finding.json \
--finding intake/another/finding.json \
--output artifacts/findings.sarif
protocol-remediator context \
--finding intake/parser-crash/finding.json \
--evidence intake/parser-crash/evidence.json \
--target-root /path/to/target \
--output intake/parser-crash/context.json
protocol-remediator verify \
--config /path/to/target/target.toml \
--finding intake/parser-crash/finding.json \
--evidence intake/parser-crash/evidence.json \
--patch candidate.patch \
--artifacts artifacts
Exit-Code: 0 bei erfolgreicher Verifikation, 1 bei fehlgeschlagener Verifikation, 2 bei Konfigurations- oder Eingabefehlern.
Wird der Hermes-API-Server gestartet, kann remediate Patches über eine HTTP-API anstelle eines lokalen Befehls anfordern. Der Standard-Endpoint ist POST /v1/patches, der Finding/Evidence/Context und ein Target-Workspace-Archiv entgegennimmt und einen Unified Diff zurückgibt.
Beispiel-Serverstart:
PYTHONPATH=src python3 -m protocol_remediator.hermes_server \
--host 127.0.0.1 \
--port 8765
Nach der Installation kann auch das Console-Script verwendet werden:
hermes-agent-server --host 127.0.0.1 --port 8765
Um einen operativen Backend-Befehl anzuhängen, wird --backend-command pro Argument wiederholt. Die Platzhalter {context}, {workspace} und {patch_output} werden unterstützt.
hermes-agent-server \
--backend-command my-patch-agent \
--backend-command --context \
--backend-command {context} \
--backend-command --workspace \
--backend-command {workspace} \
--backend-command --output \
--backend-command {patch_output}
In target.toml wird der Hermes-Modus wie folgt angegeben:
[agent]
mode = "hermes"
url = "http://127.0.0.1:8765"
timeout_seconds = 30
Anschließend wird der vorhandene remediate-Befehl wie gewohnt verwendet:
protocol-remediator remediate \
--config examples/length-prefixed-parser/target.hermes.toml \
--finding artifacts/hermes-cli-input/finding.json \
--evidence artifacts/hermes-cli-input/evidence.json \
--artifacts artifacts/hermes-cli
Für eine End-to-End-Überprüfung während der Entwicklung wird der folgende Runner verwendet, der einen temporären Hermes-Server startet, Patches über den API-Client empfängt und die gesamte Verifikations-Rückkopplungsschleife durchläuft:
PYTHONPATH=src python3 examples/run_hermes_demo.py
Ohne Hermes kann ein lokaler Befehl direkt aufgerufen werden, indem der Agent-Befehl als String-Array in target.toml angegeben wird:
[agent]
mode = "command"
command = [
"my-patch-agent",
"--context",
"{context}",
"--workspace",
"{workspace}",
"--output",
"{patch_output}",
]
timeout_seconds = 900
Dann wird der folgende Befehl ausgeführt:
protocol-remediator remediate \
--config /path/to/target/target.toml \
--finding intake/parser-crash/finding.json \
--evidence intake/parser-crash/evidence.json \
--artifacts artifacts
Der Kern ruft keine bestimmte LLM-API direkt auf. Der Vertrag ist, dass der Hermes-Backend oder der externe Befehl den Kontext liest und einen Unified Diff erzeugt. Die Agentenarbeit wird in einer temporären Kopie des Original-Targets ausgeführt.
Ein vollständiges Beispiel befindet sich in target.toml:
[project]
name = "my-protocol"
language = "c++"
root = "."
[executor]
mode = "docker"
image = "my-frozen-toolchain@sha256:..."
timeout_seconds = 300
network = false
[reproduction]
failure_regex = "AddressSanitizer|heap-buffer-overflow"
[verification]
required_gates = [
"build",
"reproducer",
"tests",
"rescan",
"refuzz",
"protocol",
]
[gates]
build = [["cmake", "-S", ".", "-B", "build"], ["cmake", "--build", "build"]]
reproducer = [["./build/fuzz_target", "{reproducer}"]]
tests = [["ctest", "--test-dir", "build", "--output-on-failure"]]
rescan = [["./tools/run-sast", "--fail-on-new"]]
refuzz = [["./tools/refuzz", "--seconds", "60"]]
protocol = [["./tools/protocol-oracle"]]
Jeder Befehl ist ein Argument-Array, kein Shell-String. Unterstützte Platzhalter:
{workspace}: vom Executor sichtbarer temporärer Target-Pfad{reproducer}: Pfad des Reproducers im temporären Target nach Prüfsummenvalidierungbuild und reproducer sind immer erforderlich. Die Standardrichtlinie macht alle sechs Gates obligatorisch. Falls ein Gate aufgrund der Target-Eigenschaften nicht verfügbar ist, muss es explizit in required_gates angepasst werden; es bleibt im Bericht sichtbar.
Jeder Verifikationslauf erhält Folgendes:
artifacts/run_<id>/
candidate.patch
context.json
evidence.input.json
finding.input.json
finding.final.json
patch-proposal.json
patch-stats.json
verification-report.json
verification-report.json enthält die Ausgaben der Basis- und der gepatchten Befehle. Da PoCs oder Logs Geheimnisse enthalten können, müssen separate Zugriffs- und Aufbewahrungsrichtlinien für das Artefakt-Repository gelten.
network=false.allow_local=true und darf nicht für nicht vertrauenswürdige Targets verwendet werden.plausible ist der Zustand, in dem nur Build und Original-Reproducer bestanden wurden.verified ist kein Beweis für Programmäquivalenz und ersetzt keine menschliche Freigabe.Forschungsergebnisse und Designentscheidungen sind in docs/research dokumentiert.