protocol-remediator

C/C++ protocol・platformコードの脆弱性findingを再現可能な証拠として正規化し、候補パッチを隔離されたコピーで検証するMVPである。code-shieldは名前衝突のリスクが確認された作業名であるため、公開packageとCLIには中立的な内部名を使用した。

現在の実装の中心はパッチ生成モデルではなく、次の検証クローズドループである。

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

実装済みの機能

versioned 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に対して6つの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

現在の実装状態を運用型ダッシュボードとして確認できるVite + React + TypeScript フロントエンドはfrontendにある。このコンソールはfixture matrix、generated corpus、Hermes API serverとの接続面、検証gate、evidence safety invariantを1つの画面にまとめている。

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がローカルcommandの代わりにHTTP APIで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",
]

[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"]]

各commandはshell文字列ではなくargument配列である。サポートされるplaceholder:

{workspace}: executorから見える一時targetパス
{reproducer}: checksum検証後に一時targetへコピーしたreproducerパス

buildとreproducerは常に必要である。デフォルトのポリシーでは6つのgateがすべて必須である。対象の特性上使用できないgateがある場合は、required_gatesで明示的に調整する必要があり、レポートにそのまま残る。

artifact

各検証runは次を保存する。

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にはbaselineとpatched commandの出力が含まれる。 PoCやログに秘密情報が含まれる可能性があるため、artifactリポジトリには別途のアクセス・保存ポリシーを適用する必要がある。

安全境界

デフォルトの推奨はpinned Docker imageとnetwork=falseである。
local executorはallow_local=trueを明示的に宣言する必要があり、信頼できない targetには使用してはならない。
外部へ送信されるLLM commandのデータポリシーは運用者が決定する。coreは自動アップロードしない。
plausibleはbuildと元のreproducerのみを通過した状態である。
verifiedもprogram equivalenceの証明ではなく、人間の承認を代替しない。
自動mergeは実装していない。

次の実装優先順位

実際のProFuzzBench/AFLNet target adapter
protocol message sequenceとstate trace collector
CodeQL選択adapterおよびC/C++ source/sink model emitter
ASan/UBSan/MSanとarchitecture matrixの実行
正常corpusベースのdifferential protocol oracle
AutoPatchBench runnerと定量的benchmark report

調査根拠と設計決定はdocs/researchにまとめられている。

code-shield

人気