code-shield

한국어 · English

Normaliza achados de vulnerabilidade em código de protocolo·plataforma C/C++ como evidência reproduzível, e verifica patches candidatos em cópias isoladas — este é o MVP. O nome do repositório é code-shield, e o pacote Python público e a CLI usam o nome interno neutro protocol-remediator para evitar conflitos de nome.

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

Telas

Dashboard de visão geral — fixture matrix 5/5, generated corpus 50/50, CWE coverage, resumo dos gates de verificação	Fixture matrix — resultados dos gates reproducer·build·tests·rescan·refuzz·protocol por target CWE-121/190/416/787/476
Estudo de caso (nodejs/http-parser) — informações do reproducer, resultados de probe antes e depois do patch, lista de achados CWE/CVE	Evidence — diff do patch proposto e caminhos JSON de evidence/context, lista de safety invariant

O console exibe como dados estáticos os resultados de fixture matrix·generated corpus·estudo de caso incluídos no repositório.

O centro da implementação atual não é o modelo de geração de patch, mas o seguinte ciclo 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 Finding, EvidenceBundle, PatchProposal, VerificationReport
• transições de estado detected → reproducible → contextualized → proposed → plausible → verified
• coleta de relatórios AddressSanitizer, MemorySanitizer, UndefinedBehaviorSanitizer
• coleta de achados SARIF 2.1
• exportação de achados normalizados em SARIF 2.1
• geração de context JSON auditável em torno da source location
• configuração de target/build/gate baseada em TOML
• executor Docker com network-off, capability-drop, resource-limit aplicados
• executor local que exige opt-in explícito
• reprodução do achado em cópia do target original e verificação do patch em cópia separada
• verificação de patch checksum, reproducer checksum, escape de caminho, symlink, limites de arquivo·linha
• rejeição de patch em caminhos protegidos como test/fuzz harness/reproducer
• adaptador de comando de agente de patch externo
• preservação de exit code, stdout/stderr, tempo e resultado de gate de cada comando

Requisitos

• Python 3.11 ou superior
• Git para verificação de patch
• Docker para execução isolada padrão
• Clang para execução dos exemplos

Não há dependências Python de runtime.

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 end-to-end é a fixture matrix C/C++ em examples. Reproduz de fato CWE-121, CWE-190, CWE-416, CWE-787, CWE-476 com Clang ASan/UBSan e, em seguida, executa todos os seis gates para o patch que restaura cada invariant. As entradas por fixture e o escopo de verificação estão organizados em examples/README.md.

Para executar apenas a matrix real sem o framework de unit-test:

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 e passa cada projeto gerado pelo mesmo VerificationPipeline. O summary de resultados é gravado por padrão em artifacts/generated-corpus-summary.json.

Frontend console

O frontend Vite + React + TypeScript que permite verificar o estado atual da implementação como um dashboard operacional está em frontend. Este console organiza em uma única tela a fixture matrix, o generated corpus, a interface de conexão do Hermes API server, os gates de verificação e os evidence safety invariant.

cd frontend
npm install
npm run dev

O servidor de desenvolvimento padrão é http://127.0.0.1:5173. O production build é verificado com:

cd frontend
npm run build

CLI

Coleta de achados de 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 context 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

Verificaçã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 verificação falhar, 2 se houver erro de configuração·entrada.

Hermes agent API server

Ao subir o Hermes API server, o remediate pode solicitar patch via HTTP API em vez de comando local. O endpoint padrão é POST /v1/patches, que recebe finding/evidence/context e o target workspace archive e retorna um unified diff.

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 pode ser usado.

hermes-agent-server --host 127.0.0.1 --port 8765

Ao conectar um backend command de produção, repita --backend-command por argumento. Os placeholders {context}, {workspace}, {patch_output} são suportados.