kos2001/code-shieldPipeline de remediação de vulnerabilidades C/C++ orientado por evidências + estudo de caso do http-parser (classe CVE-2024-22019). Núcleo em Python, console React 19, suíte de verificação com 17 testes.
É um MVP que normaliza findings de vulnerabilidades em código de protocolo/plataforma C/C++ como evidência reproduzível e valida patches candidatos em uma cópia isolada. code-shield era um nome de trabalho com risco de conflito de nomes identificado, portanto um nome interno neutro foi usado para o pacote público e a CLI.
O núcleo da implementação atual não é um modelo de geração de patches, mas o seguinte loop fechado de verificação.
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 → verifiedNão há dependências Python em tempo de execução.
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v
Para executar sem instalar:
PYTHONPATH=src python3 -m protocol_remediator --help
PYTHONPATH=src python3 -m unittest discover -s tests -v
A suíte dinâmica de ponta a ponta é uma matriz de fixtures C/C++ em examples. Depois de reproduzir de fato CWE-121, CWE-190, CWE-416, CWE-787 e CWE-476 com Clang ASan/UBSan, executa todos os seis gates para um patch que restaura cada invariante. As entradas e o escopo de verificação por fixture estão documentados em examples/README.md.
Para executar apenas a matriz real, sem framework de testes unitários:
PYTHONPATH=src python3 examples/run_fixture_matrix.py
Para gerar e executar automaticamente mais exemplos de variações C/C++:
PYTHONPATH=src python3 examples/run_generated_corpus.py --count 50
Este runner não usa unittest; ele passa cada projeto gerado pelo mesmo VerificationPipeline. O resumo dos resultados é salvo por padrão em artifacts/generated-corpus-summary.json.
O frontend Vite + React + TypeScript, que permite visualizar o estado atual da implementação como um dashboard operacional, está em frontend. Este console reúne em uma única tela a matriz de fixtures, o corpus gerado, a superfície de conexão com o servidor de API Hermes, os gates de verificação e os invariantes de segurança de evidência.
cd frontend
npm install
npm run dev
O servidor de desenvolvimento padrão é http://127.0.0.1:5173. A build de produção é verificada com:
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
Saída:
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
O código de saída é 0 se verificado, 1 se a validação falhar e 2 para erro de configuração ou entrada.
Com o servidor de API Hermes ativo, remediate pode solicitar patches por meio da API HTTP em vez de um comando local. O endpoint padrão é POST /v1/patches, que recebe finding/evidence/context e o arquivo do workspace do target e retorna um diff unificado.
Execução do servidor de exemplo:
PYTHONPATH=src python3 -m protocol_remediator.hermes_server \
--host 127.0.0.1 \
--port 8765
Após a instalação, o console script também está disponível.
hermes-agent-server --host 127.0.0.1 --port 8765
Para anexar um comando de backend de produção, repita --backend-command por argumento. São suportados os placeholders {context}, {workspace} e {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}
No target.toml, especifique o modo Hermes da seguinte forma:
[agent]
mode = "hermes"
url = "http://127.0.0.1:8765"
timeout_seconds = 30
Em seguida, use o comando remediate existente normalmente.
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
Para uma verificação ponta a ponta de desenvolvimento, execute o runner a seguir. Ele inicia um servidor Hermes temporário, recebe o patch via client de API e executa o loop fechado de verificação até o fim.
PYTHONPATH=src python3 examples/run_hermes_demo.py
Para chamar diretamente um comando local em vez de usar Hermes, especifique o comando do agente como uma matriz de strings no target.toml.
[agent]
mode = "command"
command = [
"my-patch-agent",
"--context",
"{context}",
"--workspace",
"{workspace}",
"--output",
"{patch_output}",
]
timeout_seconds = 900
Em seguida, execute o seguinte comando:
protocol-remediator remediate \
--config /path/to/target/target.toml \
--finding intake/parser-crash/finding.json \
--evidence intake/parser-crash/evidence.json \
--artifacts artifacts
O núcleo não chama diretamente APIs específicas de LLM. O contrato é que o backend Hermes ou o comando externo leia o contexto e gere um diff unificado. O trabalho do agente é executado em uma cópia temporária, não no target original.
Um exemplo completo está em 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"]]
Cada comando é uma matriz de argumentos, não uma string de shell. Placeholders suportados:
{workspace}: caminho temporário do target visível para o executor{reproducer}: caminho do reprodutor copiado para o target temporário após a verificação de checksumbuild e reproducer são sempre necessários. Na política padrão, os seis gates são todos obrigatórios. Se algum gate não puder ser usado devido às características do alvo, isso deve ser ajustado explicitamente em required_gates e permanece registrado no relatório.
Cada execução de verificação preserva o seguinte:
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
O verification-report.json inclui as saídas dos comandos de baseline e patched. Como PoCs ou logs podem conter segredos, políticas separadas de acesso e retenção devem ser aplicadas ao repositório de artefatos.
network=false.allow_local=true e não deve ser usado com targets não confiáveis.plausible é o estado em que apenas a build e o reprodutor original passaram.verified também não é uma prova de equivalência de programa e não substitui a aprovação humana.A fundamentação da pesquisa e as decisões de design estão organizadas em docs/research.