code-shield

한국어 · English

将 C/C++ protocol·platform 代码中的漏洞 finding 规范化为可复现的证据， 并在隔离副本中验证候选补丁的 MVP。仓库名为 code-shield， 公开的 Python package 和 CLI 为避免名称冲突，使用中立的内部名称 protocol-remediator。

Quick start

# Python core (런타임 dependency 없음)
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

界面

概览仪表盘 — fixture matrix 5/5、generated corpus 50/50、CWE coverage、验证 gate 摘要	Fixture matrix — CWE-121/190/416/787/476 target 各自的 reproducer·build·tests·rescan·refuzz·protocol gate 结果
Case study (nodejs/http-parser) — reproducer 信息、补丁前后 probe 结果、CWE/CVE finding 列表	Evidence — 建议补丁 diff 与 evidence/context JSON 路径、safety invariant 列表

控制台以静态数据展示仓库中包含的 fixture matrix·generated corpus·case study 结果。

当前实现的核心不是补丁生成模型，而是以下验证闭环。

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

已实现的功能

• 版本化的 Finding、EvidenceBundle、PatchProposal、 VerificationReport JSON 模型
• detected → reproducible → contextualized → proposed → plausible → verified 状态转移
• 收集 AddressSanitizer、MemorySanitizer、UndefinedBehaviorSanitizer 报告
• 收集 SARIF 2.1 finding
• 将 normalized finding 导出为 SARIF 2.1
• 生成 source location 周围可审计的 context JSON
• 基于 TOML 的 target/build/gate 配置
• 应用了 network-off、capability-drop、resource-limit 的 Docker 执行器
• 需要显式 opt-in 的 local 执行器
• 在原始 target 副本中复现 finding 后，在单独副本中验证 patch
• 检查 patch checksum、reproducer checksum、路径逃逸、symlink、文件·行数限制
• 拒绝针对 test/fuzz harness/reproducer 等受保护路径的 patch
• 外部 patch agent command 适配器
• 保留各 command 的 exit code、stdout/stderr、时间与 gate 结果

要求

• Python 3.11 以上
• 用于 patch 验证的 Git
• 默认隔离执行需要 Docker
• 运行示例需要 Clang

没有运行时 Python dependency。

安装与测试

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

不安装直接运行：

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

动态 end-to-end suite 是 examples 中的 C/C++ fixture matrix。 使用 Clang ASan/UBSan 实际复现 CWE-121、CWE-190、CWE-416、CWE-787、CWE-476， 然后针对恢复各 invariant 的 patch 执行全部六个 gate。 各 fixture 的输入与验证范围整理在 examples/README.md 中。

不使用 unit-test framework，仅运行实际 matrix：

PYTHONPATH=src python3 examples/run_fixture_matrix.py

自动生成并运行更多 C/C++ 变体示例：

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

该 runner 不使用 unittest，而是让生成的每个项目通过相同的 VerificationPipeline。结果 summary 默认保存在 artifacts/generated-corpus-summary.json。

Frontend console

可在 frontend 中找到以运维型仪表盘查看当前实现状态的 Vite + React + TypeScript 前端。该控制台将 fixture matrix、generated corpus、Hermes API server 连接面、验证 gate、evidence safety invariant 整理在同一界面中。

cd frontend
npm install
npm run dev

默认开发服务器为 http://127.0.0.1:5173。production build 可通过以下方式确认。

cd frontend
npm run build

CLI

收集 sanitizer finding

protocol-remediator ingest-sanitizer \
  --log asan.log \
  --reproducer crash.input \
  --target-name parser \
  --revision 0123456789abcdef \
  --variant asan-x86_64 \
  --output intake/parser-crash

输出：

intake/parser-crash/finding.json
intake/parser-crash/evidence.json

收集 SARIF

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

导出 SARIF

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

生成模型中立 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

验证现有 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

退出码为 verified 时 0，验证失败时 1，配置·输入错误时 2。

Hermes agent API server

启动 Hermes API server 后，remediate 可以通过 HTTP API 而非本地 command 请求 patch。 默认 endpoint 为 POST /v1/patches，接收 finding/evidence/context 与 target workspace archive，返回 unified diff。

运行示例服务器：

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

安装后也可以使用 console script。

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

接入运维 backend command 时，按 argument 单位重复 --backend-command。 支持 {context}、{workspace}、{patch_output} placeholder。

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}

在 target.toml 中如下指定 Hermes mode。

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

然后照常使用现有的 remediate 命令。

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

开发用 end-to-end 确认通过以下 runner 执行。该 runner 启动临时 Hermes server， 通过 API client 接收 patch，然后完整执行验证闭环。

PYTHONPATH=src python3 examples/run_hermes_demo.py

生成并验证外部 command agent

若不使用 Hermes 而直接调用本地 command，在 target.toml 中将 agent command 指定为字符串数组。

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

然后执行以下命令。

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

core 不直接调用特定 LLM API。契约是 Hermes backend 或外部 command 读取 context 并生成 unified diff。agent 工作不在原始 target 中执行， 而是在临时副本中执行。

target 配置

完整示例位于 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",
]