kos2001/code-shield증거 기반 C/C++ 취약점 수정 파이프라인 + http-parser 사례 연구 (CVE-2024-22019-class). Python 코어, React 19 콘솔, 17-테스트 검증 스위트.
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
Finding, EvidenceBundle, PatchProposal,
VerificationReport JSON 모델detected → reproducible → contextualized → proposed → plausible → verified 상태 전이런타임 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에 남는다.
현재 구현 상태를 운영형 대시보드로 확인할 수 있는 Vite + React + TypeScript
프론트엔드는 frontend에 있다. 이 콘솔은 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
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
protocol-remediator ingest-sarif \
--sarif results.sarif \
--output intake/sarif
protocol-remediator export-sarif \
--finding intake/parser-crash/finding.json \
--finding intake/another/finding.json \
--output artifacts/findings.sarif
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
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 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
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.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는 항상 필요하다. 기본 정책에서는 여섯 gate가 모두
필수다. 대상 특성상 사용할 수 없는 gate가 있다면 required_gates에서 명시적으로
조정해야 하며, 보고서에 그대로 남는다.
각 검증 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 저장소에는 별도 접근·보존 정책을
적용해야 한다.
network=false다.allow_local=true를 직접 선언해야 하며 신뢰할 수 없는
target에는 사용하면 안 된다.plausible은 build와 원 reproducer만 통과한 상태다.verified도 program equivalence의 증명은 아니며 사람 승인을 대체하지 않는다.조사 근거와 설계 결정은 docs/research에 정리되어 있다.