kos2001/code-shieldКонвейер устранения уязвимостей C/C++ на основе фактических данных + тематическое исследование http-parser (класс CVE-2024-22019). Ядро на Python, консоль React 19, набор из 17 проверочных тестов.
Это MVP, который нормализует findings об уязвимостях в коде C/C++ protocol·platform в воспроизводимые доказательства и проверяет кандидатные патчи в изолированной копии. code-shield — рабочее название, для которого подтверждён риск конфликта имён, поэтому в публичном пакете и 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, VerificationReportdetected → reproducible → contextualized → proposed → plausible → verifiedРантайм-зависимостей Python нет.
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 — это матрица C/C++ fixture из examples. С помощью Clang ASan/UBSan реально воспроизводятся CWE-121, CWE-190, CWE-416, CWE-787, CWE-476, после чего для патча, восстанавливающего каждый invariant, выполняются все шесть gate. Входные данные и объём проверки для каждой fixture описаны в examples/README.md.
Чтобы запустить только саму матрицу без unit-test framework:
PYTHONPATH=src python3 examples/run_fixture_matrix.py
Чтобы автоматически сгенерировать и запустить больше вариантов примеров C/C++:
PYTHONPATH=src python3 examples/run_generated_corpus.py --count 50
Этот runner не использует unittest и прогоняет каждый сгенерированный проект через один и тот же VerificationPipeline. Сводка результатов по умолчанию сохраняется в artifacts/generated-corpus-summary.json.
Фронтенд на Vite + React + TypeScript, позволяющий наблюдать текущее состояние реализации в виде операционного дашборда, находится в frontend. Эта консоль объединяет на одном экране матрицу fixture, сгенерированный корпус, состояние подключения к Hermes API server, gate верификации и evidence safety invariant.
cd frontend
npm install
npm run dev
Сервер разработки по умолчанию — http://127.0.0.1:5173. Production-сборка проверяется следующей командой:
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
Код выхода: 0 при verified, 1 при неудачной проверке, 2 при ошибке конфигурации или входных данных.
Запуск Hermes API server позволяет remediate запрашивать патчи через HTTP API вместо локальной команды. Endpoint по умолчанию — POST /v1/patches: он принимает finding/evidence/context и архив target workspace и возвращает 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, указывайте --backend-command по одному аргументу за раз. Поддерживаются плейсхолдеры {context}, {workspace}, {patch_output}.
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 задаётся следующим образом:
[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. Он поднимает временный Hermes server, получает патч через API client и доводит замкнутый цикл верификации до конца.
PYTHONPATH=src python3 examples/run_hermes_demo.py
Чтобы вызывать локальную команду напрямую, без Hermes, укажите agent command в target.toml в виде массива строк.
[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
Ядро не вызывает напрямую API конкретной LLM. Контракт таков: Hermes backend или внешняя команда читает context и формирует unified diff. Работа агента выполняется во временной копии, а не в исходном 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"]]
Каждая команда — это массив аргументов, а не shell-строка. Поддерживаемые плейсхолдеры:
{workspace}: путь к временному target, видимый из executor{reproducer}: путь к reproducer, скопированному во временный target после проверки checksumbuild и reproducer требуются всегда. Политика по умолчанию делает все шесть gate обязательными. Если какой-то gate неприменим из-за особенностей target, его необходимо явно скорректировать в required_gates; это останется в отчёте.
Каждый запуск верификации сохраняет следующее:
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 и логи могут содержать секреты, к хранилищу артефактов следует применять отдельную политику доступа и хранения.
network=false.allow_local=true; его нельзя использовать с недоверенными target.plausible — состояние, в котором пройдены только build и исходный reproducer.verified также не является доказательством program equivalence и не заменяет одобрение человеком.Обоснование исследований и проектные решения собраны в docs/research.