protocol-remediator

An MVP that normalizes vulnerability findings in C/C++ protocol/platform code into reproducible evidence and validates candidate patches in isolated copies. code-shield was a working name with a confirmed name-collision risk, so a neutral internal name is used for the public package and CLI.

The focus of the current implementation is not a patch-generation model but the verification closed loop below.

sanitizer 또는 SARIF
  -> Finding + EvidenceBundle
  -> source context
  -> manual/external-agent patch
  -> 원본 재현
  -> build
  -> patched reproducer
  -> tests
  -> static rescan
  -> bounded refuzz
  -> protocol oracle
  -> verified report

Implemented features

• versioned Finding, EvidenceBundle, PatchProposal, VerificationReport JSON models
• detected → reproducible → contextualized → proposed → plausible → verified state transitions
• AddressSanitizer, MemorySanitizer, UndefinedBehaviorSanitizer report ingestion
• SARIF 2.1 finding ingestion
• SARIF 2.1 export of normalized findings
• auditable context JSON generation around the source location
• TOML-based target/build/gate configuration
• Docker executor with network-off, capability-drop, and resource limits
• local executor requiring explicit opt-in
• reproduces the finding in a copy of the original target, then verifies the patch in a separate copy
• patch checksum, reproducer checksum, path escape, symlink, and file/line limit checks
• rejects patches to protected paths such as tests/fuzz harness/reproducer
• external patch agent command adapter
• preserves each command's exit code, stdout/stderr, timing, and gate results

Requirements

• Python 3.11 or later
• Git for patch verification
• Docker for default isolated execution
• Clang for running the examples

There are no runtime Python dependencies.

Installation and Testing

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

To run without installing:

PYTHONPATH=src python3 -m protocol_remediator --help
PYTHONPATH=src python3 -m unittest discover -s tests -v

The dynamic end-to-end suite is a C/C++ fixture matrix under examples. It actually reproduces CWE-121, CWE-190, CWE-416, CWE-787, and CWE-476 with Clang ASan/UBSan, then runs all six gates against a patch that restores each invariant. Per-fixture inputs and verification scope are documented in examples/README.md.

To run only the real matrix without a unit-test framework:

PYTHONPATH=src python3 examples/run_fixture_matrix.py

To auto-generate and run more C/C++ variant examples:

PYTHONPATH=src python3 examples/run_generated_corpus.py --count 50

This runner does not use unittest; it passes each generated project through the same VerificationPipeline. The result summary is written to artifacts/generated-corpus-summary.json by default.

Frontend console

A Vite + React + TypeScript frontend that lets you inspect the current implementation state as an operational dashboard lives in frontend. This console brings the fixture matrix, generated corpus, Hermes API server connectivity, verification gates, and evidence safety invariants together on one screen.

cd frontend
npm install
npm run dev

The default dev server is http://127.0.0.1:5173. Verify a production build with:

cd frontend
npm run build

CLI

sanitizer finding ingestion

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

SARIF ingestion

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

SARIF export

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

model-neutral context generation

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

existing patch verification

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 is 0 on verified, 1 on verification failure, and 2 on configuration or input errors.

Hermes agent API server

Starting the Hermes API server lets remediate request patches via HTTP API instead of a local command. The default endpoint is POST /v1/patches; it accepts finding/evidence/context and a target workspace archive and returns a unified diff.

Example server run:

PYTHONPATH=src python3 -m protocol_remediator.hermes_server \
  --host 127.0.0.1 \
  --port 8765

After installation, the console script is also available.

hermes-agent-server --host 127.0.0.1 --port 8765

To attach an operational backend command, repeat --backend-command for each argument. The {context}, {workspace}, and {patch_output} placeholders are supported.

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, specify Hermes mode like this:

[agent]
mode = "hermes"
url = "http://127.0.0.1:8765"
timeout_seconds = 30

Then use the existing remediate command as-is.

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

For a development end-to-end check, run the following runner. It starts a temporary Hermes server, obtains a patch via the API client, and runs the verification closed loop to completion.

PYTHONPATH=src python3 examples/run_hermes_demo.py

external command agent creation and verification

To call a local command directly without Hermes, specify the agent command as a string array in target.toml.

[agent]
mode = "command"
command = [
  "my-patch-agent",
  "--context",
  "{context}",
  "--workspace",
  "{workspace}",
  "--output",
  "{patch_output}",
]
timeout_seconds = 900

Then run:

protocol-remediator remediate \
  --config /path/to/target/target.toml \
  --finding intake/parser-crash/finding.json \
  --evidence intake/parser-crash/evidence.json \
  --artifacts artifacts

The core does not directly call any particular LLM API. The contract is that a Hermes backend or an external command reads the context and generates a unified diff. Agent work runs on a temporary copy, not the original target.

target configuration

A complete example is 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",
]