Prototype de recherche VulnAgent-X

VulnAgent-X est un prototype de détection de vulnérabilités/défauts multi-agent destiné à la reproduction d'articles. Il prend en entrée un dépôt local ou un diff, et produit des résultats structurés, des chaînes de preuves, des localisations, des niveaux de confiance et des journaux d'expérience.

Capacités principales

• Entrée : chemin du dépôt ou diff unifié
• Flux de travail : screening -> expansion de contexte -> ordonnanceur -> routeur -> experts -> sceptique -> vérification (maquette) -> fusion des preuves
• Champs de sortie :
  • type_de_problème
  • emplacement (fichier + plage de lignes)
  • résumé_des_preuves
  • confiance
  • sévérité
  • cwe_optionnel
  • indice_de_correction
  • chaîne_de_preuves
  • contre-preuves
• Interface : CLI + FastAPI
• Expériences reproductibles : pytest / mypy / ruff + support Docker

Aperçu du flux de travail

1. screening : filtrage rapide des zones suspectes (règles + signaux de métadonnées)
2. expansion_de_contexte : extraction du « contexte minimal suffisant » (fenêtres autour des localisations suspectes)
3. ordonnanceur : stratégie d'escalade selon la confiance et le risque (early_exit / expert_review / vérification)
4. agent_routeur : sélection d'un agent expert pour chaque zone suspecte
5. sémantique/sécurité/logique : formulations structurées et preuves selon différents points de vue
6. agent_sceptique : génération de contre-preuves et signaux de pénalité
7. vérification : vérification dynamique optionnelle (actuellement une implémentation de sécurité factice)
8. fusion_des_preuves : fusion unifiée et sortie des constats finaux

Guide d'installation et d'exécution

1) Préparation de l'environnement

Prérequis : Python 3.11+ (fonctionne également avec des versions plus récentes)

cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

2) Utilisation en CLI

Analyser un dépôt complet :

.venv/bin/vulnagentx analyze --repo /chemin/vers/depot --output json

Analyser un fichier diff :

.venv/bin/vulnagentx analyze --diff-file /chemin/vers/patch.diff --output json

Sortie condensée :

.venv/bin/vulnagentx analyze --repo /chemin/vers/depot --output summary

3) Utilisation via API

Démarrer le service :

.venv/bin/uvicorn vulnagentx.app.api:app --reload

Vérification de l'état de santé :

curl http://127.0.0.1:8000/health

Lancer une analyse :

curl -X POST http://127.0.0.1:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"repo_path":"/chemin/vers/depot"}'

4) Exécution avec Docker

docker compose -f docker/docker-compose.yml up --build

5) Contrôle qualité et tests

.venv/bin/ruff check src tests
.venv/bin/mypy src
.venv/bin/pytest

Exemple de sortie

{
  "run_id": "...",
  "findings": [
    {
      "issue_type": "injection_de_commande",
      "location": {"file_path": "app.py", "start_line": 42, "end_line": 42},
      "evidence_summary": "Surface d'exécution de commande détectée...",
      "confidence": 0.87,
      "severity": "critique",
      "optional_cwe": "CWE-78",
      "fix_hint": "Éviter la composition de commandes shell...",
      "source_agents": ["security_agent", "semantic_agent"],
      "evidence_chain": [],
      "counter_evidence": []
    }
  ],
  "metrics": {
    "runtime_seconds": 0.07
  },
  "logs": []
}

Description des fichiers (fichier par fichier)

Répertoire racine et fichiers projet

Fichier	Description
.env.example	Modèle de variables d'environnement (niveau de journalisation, etc. paramètres optionnels).
pyproject.toml	Construction du projet, dépendances, points d'entrée des scripts, configuration pytest/ruff/mypy.
README.md	README principal (avec bouton de changement de langue, par défaut en chinois).
README.zh.md	Documentation complète en chinois.
README.en.md	Documentation complète en anglais.
docker/Dockerfile	Fichier de construction de l'image conteneur du service API.
docker/docker-compose.yml	Démarrage local en un clic du service conteneurisé.
rules/semgrep/vulnagentx-rules.yml	Ensemble de règles Semgrep intégrées (injection de commande / injection SQL / désérialisation / API C non sécurisée).
scripts/run_experiment.py	Script d'exécution d'expériences par lots sur un jeu de données, sortie JSONL de prédictions.
scripts/evaluate.py	Lecture des sorties d'expériences et calcul des métriques de détection/localisation/efficacité.
scripts/run_ablation.py	Script d'expérience d'ablation (no_semgrep/no_treesitter/no_sceptic/no_verification).

Code source principal (src/vulnagentx)