kos2001/code-shieldPipeline di remediation delle vulnerabilità C/C++ basata sulle evidenze + caso di studio su http-parser (CVE-2024-22019-class). Core Python, console React 19, suite di verifica con 17 test.
È una MVP che normalizza i finding di vulnerabilità del codice C/C++ di protocolli/piattaforme in prove riproducibili e verifica le patch candidate su una copia isolata. Poiché code-shield era un nome di lavoro con un rischio accertato di conflitto di denominazione, per il package pubblico e la CLI è stato adottato un nome interno neutro.
Il fulcro dell'implementazione attuale non è un modello di generazione di patch, ma il seguente ciclo chiuso di verifica.
sanitizer o SARIF
-> Finding + EvidenceBundle
-> source context
-> manual/external-agent patch
-> riproduzione originale
-> build
-> patched reproducer
-> tests
-> static rescan
-> bounded refuzz
-> protocol oracle
-> verified report
Finding, EvidenceBundle, PatchProposal, VerificationReportdetected → reproducible → contextualized → proposed → plausible → verifiedNon ci sono dependency Python a runtime.
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v
Per eseguire senza installare:
PYTHONPATH=src python3 -m protocol_remediator --help
PYTHONPATH=src python3 -m unittest discover -s tests -v
La suite end-to-end dinamica è rappresentata dalla matrice di fixture C/C++ in examples. Dopo aver riprodotto realmente CWE-121, CWE-190, CWE-416, CWE-787 e CWE-476 con Clang ASan/UBSan, esegue tutti e sei i gate per ogni patch che ripristina l'invariante corrispondente. Gli input e l'ambito di verifica per ciascuna fixture sono descritti in examples/README.md.
Per eseguire solo la matrice reale, senza framework di unit test:
PYTHONPATH=src python3 examples/run_fixture_matrix.py
Per generare automaticamente ed eseguire più esempi di varianti C/C++:
PYTHONPATH=src python3 examples/run_generated_corpus.py --count 50
Questo runner non usa unittest; fa passare ogni progetto generato attraverso la stessa VerificationPipeline. Il riepilogo dei risultati viene salvato per impostazione predefinita in artifacts/generated-corpus-summary.json.
Il frontend Vite + React + TypeScript, che permette di osservare lo stato dell'implementazione attuale come dashboard operativa, si trova in frontend. Questa console riunisce in un'unica schermata la fixture matrix, il corpus generato, gli aspetti di connessione al server API Hermes, i gate di verifica e gli invariant di sicurezza delle evidenze.
cd frontend
npm install
npm run dev
Il server di sviluppo predefinito è http://127.0.0.1:5173. La build di produzione si verifica con:
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
Output:
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
Il codice di uscita è 0 in caso di verified, 1 in caso di verifica fallita e 2 in caso di errori di configurazione o input.
Avviando il server API Hermes, remediate può richiedere le patch tramite HTTP API invece che con un comando locale. L'endpoint predefinito è POST /v1/patches; riceve finding/evidence/context e un archivio del workspace target e restituisce un unified diff.
Avvio del server di esempio:
PYTHONPATH=src python3 -m protocol_remediator.hermes_server \
--host 127.0.0.1 \
--port 8765
Dopo l'installazione è disponibile anche un console script.
hermes-agent-server --host 127.0.0.1 --port 8765
Per collegare il backend command di produzione, si ripete --backend-command per ogni singolo argomento. Sono supportati i placeholder {context}, {workspace}, {patch_output}.
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 la modalità Hermes si specifica così:
[agent]
mode = "hermes"
url = "http://127.0.0.1:8765"
timeout_seconds = 30
Quindi si utilizza il comando remediate esistente così com'è.
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
La verifica end-to-end per lo sviluppo si esegue con il runner seguente. Questo runner avvia un server Hermes temporaneo, riceve la patch tramite il client API e poi porta a termine l'intero ciclo chiuso di verifica.
PYTHONPATH=src python3 examples/run_hermes_demo.py
Per chiamare direttamente un comando locale senza usare Hermes, si imposta il comando dell'agente come array di stringhe in target.toml.
[agent]
mode = "command"
command = [
"my-patch-agent",
"--context",
"{context}",
"--workspace",
"{workspace}",
"--output",
"{patch_output}",
]
timeout_seconds = 900
Quindi si esegue il comando seguente:
protocol-remediator remediate \
--config /path/to/target/target.toml \
--finding intake/parser-crash/finding.json \
--evidence intake/parser-crash/evidence.json \
--artifacts artifacts
Il core non invoca direttamente alcuna API LLM specifica. Il contratto è che il backend Hermes o un comando esterno legga il context e generi l'unified diff. Il lavoro dell'agente viene eseguito su una copia temporanea, non sul target originale.
Un esempio completo è disponibile 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"]]
Ogni comando è un array di argomenti, non una stringa di shell. Placeholder supportati:
{workspace}: percorso del target temporaneo come visibile dall'executor{reproducer}: percorso del reproducer copiato nel target temporaneo dopo la verifica del checksumbuild e reproducer sono sempre necessari. La policy predefinita rende obbligatori tutti e sei i gate. Se un gate non è utilizzabile per la natura del target, va rimosso esplicitamente da required_gates; la cosa resta comunque tracciata nel report.
Ogni run di verifica conserva quanto segue:
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 include l'output dei comandi baseline e patched. Poiché PoC e log possono contenere segreti, all'archivio degli artifact va applicata una policy separata di accesso e conservazione.
network=false.allow_local=true e non va usato con target non affidabili.plausible è lo stato che ha superato solo la build e il reproducer originale.verified non è una prova di equivalenza dei programmi e non sostituisce l'approvazione umana.Le motivazioni della ricerca e le decisioni di progettazione sono documentate in docs/research.