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

구현된 기능

• 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에 대해 여섯 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를 한 화면에 정리한다.

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는 항상 필요하다. 기본 정책에서는 여섯 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는 구현하지 않았다.

다음 구현 우선순위

1. 실제 ProFuzzBench/AFLNet target adapter
2. protocol message sequence와 state trace collector
3. CodeQL 선택 adapter 및 C/C++ source/sink model emitter
4. ASan/UBSan/MSan과 architecture matrix 실행
5. 정상 corpus 기반 differential protocol oracle
6. AutoPatchBench runner와 정량 benchmark report

조사 근거와 설계 결정은 docs/research에 정리되어 있다 (Korean).

License

MIT