protocol-remediator

È 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

Funzionalità implementate

• modelli JSON versionati Finding, EvidenceBundle, PatchProposal, VerificationReport
• transizioni di stato detected → reproducible → contextualized → proposed → plausible → verified
• raccolta di report AddressSanitizer, MemorySanitizer, UndefinedBehaviorSanitizer
• raccolta di finding SARIF 2.1
• esportazione SARIF 2.1 dei finding normalizzati
• generazione di un context JSON verificabile attorno alla posizione della sorgente
• configurazione target/build/gate basata su TOML
• executor Docker con network disattivato, capability ridotte e limiti di risorse applicati
• executor locale che richiede opt-in esplicito
• riproduzione del finding su una copia del target originale e successiva verifica della patch su una copia separata
• controlli su checksum della patch, checksum del reproducer, path escape, symlink e limiti di file/riga
• rifiuto di patch su percorsi protetti come test, fuzz harness e reproducer
• adapter per comandi di agenti di patch esterni
• preservazione di exit code, stdout/stderr, tempi e risultati dei gate per ogni comando

Requisiti

• Python 3.11 o successivo
• Git per la verifica delle patch
• Docker per l'esecuzione isolata predefinita
• Clang per l'esecuzione degli esempi

Non ci sono dependency Python a runtime.

Installazione e test

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.

Console frontend

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

CLI

Ingestione di finding da sanitizer

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

Ingestione SARIF

protocol-remediator ingest-sarif \
  --sarif results.sarif \
  --output intake/sarif

Esportazione SARIF

protocol-remediator export-sarif \
  --finding intake/parser-crash/finding.json \
  --finding intake/another/finding.json \
  --output artifacts/findings.sarif

Generazione di un context agnostico rispetto al modello

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

Verifica di una patch esistente

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.

Server API dell'agente Hermes

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

Creazione e verifica di un agente a comando esterno

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.

Configurazione del target

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 checksum

build 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.

Artifact

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.

Confini di sicurezza

• La raccomandazione predefinita è un'immagine Docker pinnata con network=false.
• L'executor locale richiede la dichiarazione esplicita di allow_local=true e non va usato con target non affidabili.
• La policy sui dati inviati ai comandi LLM esterni è decisa dall'operatore. Il core non carica nulla automaticamente.
• plausible è lo stato che ha superato solo la build e il reproducer originale.
• Anche verified non è una prova di equivalenza dei programmi e non sostituisce l'approvazione umana.
• Non è implementato un merge automatico.

Prossime priorità di implementazione

1. Adapter per target reali ProFuzzBench/AFLNet
2. Collector per sequenze di messaggi di protocollo e state trace
3. Adapter opzionale per CodeQL ed emitter di modelli source/sink C/C++
4. Esecuzione di ASan/UBSan/MSan e matrice delle architetture
5. Oracolo di protocollo differenziale basato su un corpus di input normali
6. Runner AutoPatchBench e report benchmark quantitativo

Le motivazioni della ricerca e le decisioni di progettazione sono documentate in docs/research.