protocol-remediator

É 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

Funcionalidades implementadas

• Modelos JSON versionados de Finding, EvidenceBundle, PatchProposal, VerificationReport
• Transição de estado detected → reproducible → contextualized → proposed → plausible → verified
• Coleta de relatórios AddressSanitizer, MemorySanitizer, UndefinedBehaviorSanitizer
• Coleta de findings SARIF 2.1
• Exportação SARIF 2.1 de findings normalizados
• Geração de contexto JSON auditável ao redor da localização de origem
• Configuração de target/build/gate baseada em TOML
• Executor Docker com network-off, capability-drop e resource-limit
• Executor local que exige opt-in explícito
• Reprodução do finding em uma cópia do target original e validação do patch em uma cópia separada
• Verificações de checksum do patch, checksum do reprodutor, escape de caminho, symlink e limites de arquivo/linha
• Rejeição de patches em caminhos protegidos, como test/fuzz harness/reproducer
• Adaptador de comando para agente de patch externo
• Preservação do exit code, stdout/stderr, tempo e resultados de gate de cada comando

Requisitos

• Python 3.11 ou superior
• Git para validação de patches
• Docker para a execução isolada padrão
• Clang para executar os exemplos

Não há dependências Python em tempo de execução.

Instalação e testes

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.

Console frontend

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

CLI

Coleta de findings do sanitizer

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

Coleta de SARIF

protocol-remediator ingest-sarif \
  --sarif results.sarif \
  --output intake/sarif

Exportação de SARIF

protocol-remediator export-sarif \
  --finding intake/parser-crash/finding.json \
  --finding intake/another/finding.json \
  --output artifacts/findings.sarif

Geração de contexto neutro em relação ao modelo

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

Validação de patch existente

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.

Servidor de API do agente Hermes

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

Criação e validação de agente de comando externo

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.

Configuração do target

Um exemplo completo está em target.toml.

[project]
name = "my-protocol"
language = "c++"
root = "."