code-shield

한국어 · English

MVP qui normalise les findings de vulnérabilités dans le code de protocole/plateforme C/C++ en preuves reproductibles, et vérifie les correctifs candidats dans une copie isolée. Le nom du dépôt est code-shield, et le package Python public et le CLI utilisent le nom interne neutre protocol-remediator pour éviter les conflits de noms.

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

Écrans

Tableau de bord d'aperçu — matrice de fixtures 5/5, corpus généré 50/50, couverture CWE, résumé du portail de vérification	Matrice de fixtures — résultats des portails reproducer·build·tests·rescan·refuzz·protocol par cible CWE-121/190/416/787/476
Étude de cas (nodejs/http-parser) — informations du reproducer, résultats de sonde avant/après correctif, liste des findings CWE/CVE	Evidence — diff du correctif proposé et chemins JSON evidence/context, liste des invariants de sûreté

La console affiche en données statiques la matrice de fixtures, le corpus généré et les résultats d'étude de cas inclus dans le dépôt.

Le cœur de l'implémentation actuelle n'est pas le modèle de génération de correctifs, mais la boucle de vérification fermée suivante.

sanitizer 또는 SARIF
  -> Finding + EvidenceBundle
  -> source context
  -> manual/external-agent patch
  -> 원본 재현
  -> build
  -> patched reproducer
  -> tests
  -> static rescan
  -> bounded refuzz
  -> protocol oracle
  -> verified report

Fonctionnalités implémentées

• modèles JSON versionnés Finding, EvidenceBundle, PatchProposal, VerificationReport
• transitions d'état detected → reproducible → contextualized → proposed → plausible → verified
• collecte des rapports AddressSanitizer, MemorySanitizer, UndefinedBehaviorSanitizer
• collecte des findings SARIF 2.1
• export SARIF 2.1 des findings normalisés
• génération d'un JSON de contexte auditable autour de la source location
• configuration target/build/gate basée sur TOML
• exécuteur Docker avec network-off, capability-drop, resource-limit
• exécuteur local nécessitant un opt-in explicite
• reproduction du finding sur une copie de la cible originale, puis vérification du patch sur une copie séparée
• vérification du checksum de patch, du checksum de reproducer, de l'évasion de chemin, des symlinks, des limites de fichiers et de lignes
• rejet des patchs sur les chemins protégés comme test/fuzz harness/reproducer
• adaptateur de commande pour agent de patch externe
• préservation du code de sortie, stdout/stderr, du temps et des résultats de gate de chaque commande

Prérequis

• Python 3.11 ou supérieur
• Git pour la vérification des patchs
• Docker pour l'exécution isolée par défaut
• Clang pour l'exécution des exemples

Aucune dépendance Python à l'exécution.

Installation et tests

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

Pour exécuter sans installation :

PYTHONPATH=src python3 -m protocol_remediator --help
PYTHONPATH=src python3 -m unittest discover -s tests -v

La suite end-to-end dynamique est la matrice de fixtures C/C++ dans examples. Elle reproduit réellement CWE-121, CWE-190, CWE-416, CWE-787, CWE-476 avec Clang ASan/UBSan, puis exécute les six portails sur le patch qui restaure chaque invariant. Les entrées et la portée de vérification par fixture sont documentées dans examples/README.md.

Pour exécuter uniquement la matrice réelle sans framework de tests unitaires :

PYTHONPATH=src python3 examples/run_fixture_matrix.py

Pour générer et exécuter automatiquement davantage d'exemples de variantes C/C++ :

PYTHONPATH=src python3 examples/run_generated_corpus.py --count 50

Ce runner n'utilise pas unittest et fait passer chaque projet généré par le même VerificationPipeline. Le résumé des résultats est enregistré par défaut dans artifacts/generated-corpus-summary.json.

Console frontend

Le frontend Vite + React + TypeScript permettant de consulter l'état d'implémentation actuel sous forme de tableau de bord opérationnel se trouve dans frontend. Cette console regroupe sur un seul écran la matrice de fixtures, le corpus généré, l'interface de connexion au serveur API Hermes, les portails de vérification et les invariants de sûreté des preuves.

cd frontend
npm install
npm run dev

Le serveur de développement par défaut est http://127.0.0.1:5173. Le build de production se vérifie avec :

cd frontend
npm run build

CLI

Collecte des findings 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

Sortie :

intake/parser-crash/finding.json
intake/parser-crash/evidence.json

Collecte SARIF

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

Export SARIF

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

Génération de contexte neutre vis-à-vis du modèle

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

Vérification d'un patch existant

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

Le code de sortie est 0 si vérifié, 1 en cas d'échec de vérification, 2 en cas d'erreur de configuration ou d'entrée.

Serveur API de l'agent Hermes

En lançant le serveur API Hermes, remediate peut demander un patch via l'API HTTP au lieu d'une commande locale. L'endpoint par défaut est POST /v1/patches, qui reçoit finding/evidence/context et l'archive du workspace cible, puis renvoie un unified diff.

Exécution du serveur d'exemple :

PYTHONPATH=src python3 -m protocol_remediator.hermes_server \
  --host 127.0.0.1 \
  --port 8765

Après installation, le console script est également disponible.

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