code-shield

한국어 · English

An MVP that normalizes vulnerability findings in C/C++ protocol and platform code into reproducible evidence and verifies candidate patches in isolated copies of the target. The repository is named code-shield; the public Python package and CLI use the neutral internal name protocol-remediator to avoid a name clash.

Quick start

# Python core (no runtime dependencies)
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

# React console
cd frontend
npm install
npm run dev   # http://127.0.0.1:5173

Screens

Overview dashboard: fixture matrix 5/5, generated corpus 50/50, CWE coverage and verification gate summary	Fixture matrix: reproducer, build, tests, rescan, refuzz and protocol gate results for the CWE-121/190/416/787/476 targets
Case study (nodejs/http-parser): reproducer details, probe result before and after the patch, CWE/CVE finding list	Evidence: proposed patch diff with evidence/context JSON paths, and the safety invariants

The console renders the fixture matrix, generated corpus and case study results shipped in the repository as static data.

The centre of the current implementation is not a patch generation model but the following verification loop:

sanitizer or SARIF
  -> Finding + EvidenceBundle
  -> source context
  -> manual/external-agent patch
  -> original reproduction
  -> build
  -> patched reproducer
  -> tests
  -> static rescan
  -> bounded refuzz
  -> protocol oracle
  -> verified report

Implemented features

• Versioned Finding, EvidenceBundle, PatchProposal and VerificationReport JSON models
• detected → reproducible → contextualized → proposed → plausible → verified state transitions
• Ingestion of AddressSanitizer, MemorySanitizer and UndefinedBehaviorSanitizer reports
• SARIF 2.1 finding ingestion
• SARIF 2.1 export of normalized findings
• Auditable context JSON generated around the source location
• TOML-based target/build/gate configuration
• Docker executor with network-off, capability-drop and resource-limit settings
• Local executor that requires an explicit opt-in
• Reproduce the finding in a copy of the original target, then verify the patch in a separate copy
• Patch checksum, reproducer checksum, path escape, symlink and file/line limit checks
• Rejection of patches touching protected paths such as tests, fuzz harnesses and reproducers
• Adapter for external patch agent commands
• Preservation of each command's exit code, stdout/stderr, timing and gate result

Requirements

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

There are no runtime Python dependencies.

Install and test

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 the C/C++ fixture matrix in examples. It reproduces CWE-121, CWE-190, CWE-416, CWE-787 and CWE-476 for real with Clang ASan/UBSan, then runs all six gates against a patch that restores each invariant. Inputs and verification scope per fixture are listed in examples/README.md (Korean).

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

PYTHONPATH=src python3 examples/run_fixture_matrix.py

To auto-generate and run more C/C++ variants:

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 presents the current implementation state as an operations-style dashboard lives in frontend. The console brings the fixture matrix, generated corpus, Hermes API server integration surface, verification gates and evidence safety invariants onto one screen.

cd frontend
npm install
npm run dev

The default dev server is http://127.0.0.1:5173. Check the production build with:

cd frontend
npm run build

CLI

Ingest sanitizer findings

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

Ingest SARIF

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

Export SARIF

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

Generate model-neutral context

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

Verify an existing patch

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

The exit code is 0 when verified, 1 when verification fails and 2 on configuration or input errors.

Hermes agent API server

With a Hermes API server running, remediate can request patches over HTTP instead of a local command. The default endpoint is POST /v1/patches; it receives the finding/evidence/context plus a target workspace archive and returns a unified diff.

Run the example server:

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 a production backend command, repeat --backend-command once per 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, select Hermes mode like this:

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