L'assistant IA décompose cela en appels d'outils :```
r2_decompile("sample.exe", "main")
  → extract_iocs("sample.exe")
    → add_mitre_technique(technique_id="T1071.001", ...)
      → create_analysis_report(template_type="quick_triage")

### Core Infrastructure (37 modules)

Le répertoire `reversecore_mcp/core/` contient l'infrastructure partagée sur laquelle tous les outils s'appuient :

| Module | Rôle |
|---|---|
| `config.py` | Pydantic BaseSettings avec 34+ variables d'environnement |
| `security.py` | Assainissement des entrées, validation des arguments de commande |
| `validators.py` | Validation des chemins de fichiers et de binaires avec atténuation TOCTOU, résolution des liens symboliques |
| `r2_pool.py` | Pool de connexions Radare2 thread-safe avec taille configurable |
| `r2_helpers.py` | Analyse structurée des sorties Radare2 |
| `metrics.py` | Temps d'exécution par outil, nombres d'appels, taux d'erreur, statistiques de cache |
| `memory.py` | Stockage de mémoire IA asynchrone basé sur SQLite pour persister les résultats d'analyse entre les sessions |
| `mitre_mapper.py` | Moteur de correspondance des ID de techniques MITRE ATT&CK |
| `evidence.py` | Système de classification des preuves : `OBSERVED`, `INFERRED`, `POSSIBLE` |
| `resilience.py` | Modèles de décorateurs pour la relance (retry), le disjoncteur (circuit-breaker) et le délai d'expiration (timeout) |
| `task_queue.py` | File de tâches en arrière-plan via Redis + arq |
| `extension_registry.py` | Enregistrement des plugins et gestion du cycle de vie |
| `arch_registry.py` | Correspondance multi-architectures (x86, x86_64, ARM32, ARM64, MIPS, RISC-V, PPC → arch/bits/registres r2) |
| `result_cache.py` | Décorateur de mise en cache des résultats d'outils basé sur SHA256 (`@cache_tool_result`) |
| `analysis_cache.py` | Cache de décompilation multi-niveaux (L1 : Redis, L2 : SQLite) |
| `result.py` | Modèles Pydantic `ToolSuccess` / `ToolError` |
| `exceptions.py` | 17 classes d'exceptions avec codes d'erreur `RCMCP-E*` |
| `decorators.py` | `@log_execution`, `@track_metrics` |
| `error_handling.py` | Décorateur `@handle_tool_errors` |
| `error_formatting.py` | Formatage structuré des réponses d'erreur |
| `execution.py` | Exécution sécurisée de sous-processus avec délai d'expiration et limites de sortie |
| `command_spec.py` | Spécification de commande pour les appels de sous-processus |
| `loader.py` | Chargeur dynamique de modules d'outils |
| `plugin.py` | Classe de base des plugins |
| `extension.py` | Classe de base des extensions |
| `container.py` | Prise en charge de l'exécution en conteneur/sandbox |
| `audit.py` | Journalisation d'audit |
| `binary_cache.py` | Mise en cache des fichiers binaires |
| `json_utils.py` | Sérialisation JSON via orjson (3 à 5 fois plus rapide que json de la bibliothèque standard) |
| `logging_config.py` | Journalisation structurée basée sur Loguru |
| `report_generator.py` | Moteur de rendu de rapports (Markdown, PDF via xhtml2pdf) |
| `resource_manager.py` | Gestion du cycle de vie des ressources MCP |
| `sast/python_ast_scanner.py` | Analyseur de vulnérabilités basé sur l'AST Python |
| `sast/regex_scanner.py` | Analyseur de vulnérabilités C/C++ basé sur des expressions régulières |
| `sast/rule_manager.py` | Chargement et gestion des règles SAST |

---

## Catalogue d'outils (120 outils)

Chaque outil renvoie un `ToolResult` structuré — soit un `ToolSuccess` avec des `data` typées, soit un `ToolError` avec un code d'erreur `RCMCP-E*`. Les outils sont organisés en 8 plugins.

---

### 🔍 Plugin d'analyse statique (24 outils)

| # | Outil | Backend | Description |
|---|---|---|---|
| 1 | `run_strings` | `strings` CLI | Extraction de chaînes ASCII/Unicode avec longueur minimale configurable |
| 2 | `run_binwalk` | Binwalk | Analyse approfondie de firmware pour signatures et systèmes de fichiers intégrés |
| 3 | `run_binwalk_extract` | Binwalk | Extraire les fichiers intégrés découverts par binwalk |
| 4 | `parse_binary_with_lief` | LIEF | Analyse complète des en-têtes, sections, importations/exports et TLS des formats PE/ELF/Mach-O |
| 5 | `detect_packer` | DIE | Détection rapide de packer/compilateur |
| 6 | `detect_packer_deep` | DIE (`diec`) | Analyse approfondie de packer/protecteur via Detect It Easy |
| 7 | `run_capa` | CAPA (Mandiant FLARE) | Détection de capacités — « chiffre les données », « crée une persistance », etc. |
| 8 | `run_capa_quick` | CAPA | Analyse rapide des capacités avec un sous-ensemble de règles |
| 9 | `generate_signature` | Radare2 | Générer des signatures binaires pour l'identification |
| 10 | `generate_yara_rule` | Radare2 + YARA | Générer des règles de détection YARA à partir de motifs binaires |
| 11 | `generate_advanced_yara_rule` | Radare2 + YARA | Règles YARA avancées avec indicateurs comportementaux |
| 12 | `scan_for_versions` | LIEF + strings | Analyser le binaire à la recherche de chaînes de version intégrées |
| 13 | `extract_rtti_info` | Radare2 | Extraire les informations RTTI C++ (Run-Time Type Information) |
| 14 | `diff_binaries` | Radare2 | Différence binaire sémantique entre deux versions de fichiers |
| 15 | `analyze_variant_changes` | Radare2 | Analyser les changements entre variantes binaires |
| 16 | `match_libraries` | Radare2 | Identifier les bibliothèques liées statiquement par empreinte de fonction |
| 17 | `patch_diff_1day` | Radare2 + heuristics | Analyse automatisée de diff de patchs pour la recherche de vulnérabilités 1-day |
| 18 | `analyze_patch_diff_auto` | Radare2 + inference | Inférence automatisée de vulnérabilités de patch |
| 19 | `emulate_binary` | Radare2 ESIL | Émulation de code avec suivi des registres/mémoire |
| 20 | `generate_fuzzing_harness` | Qiling + AFL++ | Générer un harnais de fuzzing ciblant une fonction spécifique |
| 21 | `run_fuzzing_campaign` | AFL++ | Exécuter une campagne de fuzzing complète avec collecte des crashes |
| 22 | `triage_crash` | GDB | Analyse de crash et évaluation de l'exploitabilité |
| 23 | `verify_path_and_get_args` | angr | Exécution symbolique — prouver l'accessibilité d'un chemin et calculer des entrées concrètes |
| 24 | `taint_trace` | Radare2 + angr | Analyse de flux de données (taint) des sources vers les puits (sinks) |

---

### 🔐 Plugin d'audit de code source (1 outil)

| # | Outil | Backend | Description |
|---|---|---|---|
| 25 | `audit_source_code` | AST + Regex | Analyse AST Python + analyse par expressions régulières C/C++ pour motifs dangereux |

---

### 🛠️ Plugin d'utilitaires courants (20 outils)

**Opérations sur les fichiers (5 outils)**

| # | Outil | Description |
|---|---|---|
| 26 | `run_file` | Identification du type de fichier, de l'architecture et du compilateur |
| 27 | `copy_to_workspace` | Copier un fichier dans l'espace de travail d'analyse |
| 28 | `create_directory` | Créer un répertoire dans l'espace de travail |
| 29 | `list_workspace` | Lister tous les fichiers de l'espace de travail |
| 30 | `scan_workspace` | Analyse complète de l'espace de travail avec métadonnées de fichiers |

**Explication de patch (1 outil)**

| # | Outil | Description |
|---|---|---|
| 31 | `explain_patch` | Expliquer un patch binaire en langage naturel |

**Assembleur (1 outil)**

| # | Outil | Backend | Description |
|---|---|---|---|
| 32 | `assemble_instructions` | Keystone | Assembler des instructions en code machine (x86, ARM, MIPS, etc.) |

**Gestion de la mémoire IA (11 outils)**

Ces outils permettent à l'IA de persister et de rappeler des résultats entre les sessions d'analyse à l'aide d'une base de données SQLite asynchrone :

| # | Outil | Description |
|---|---|---|
| 33 | `create_memory_session` | Démarrer une nouvelle session mémoire pour une analyse |
| 34 | `store_analysis_finding` | Persister un résultat d'analyse avec des balises |
| 35 | `query_analysis_memories` | Rechercher des résultats antérieurs par requête |
| 36 | `get_binary_analysis_context` | Récupérer tout le contexte d'un binaire spécifique |
| 37 | `tag_analysis_session` | Ajouter des balises à une session pour l'organisation |
| 38 | `search_memories_by_tag` | Trouver des sessions/résultats par balise |
| 39 | `delete_analysis_session` | Supprimer une session et ses résultats |
| 40 | `cleanup_expired_sessions` | Supprimer les sessions plus anciennes qu'un seuil |
| 41 | `list_analysis_sessions` | Lister toutes les sessions actives |
| 42 | `export_memory_store` | Exporter toutes les mémoires dans un format portable |
| 43 | `import_memory_store` | Importer des mémoires depuis un fichier d'exportation |

**Surveillance du serveur (2 outils)**

| # | Outil | Description |
|---|---|---|
| 44 | `get_server_health` | Temps de fonctionnement (uptime), utilisation mémoire, outils chargés, version de Python |
| 45 | `get_tool_metrics` | Nombre d'appels par outil, temps d'exécution moyens, taux d'erreur, succès/échec du cache |

---

### ⚙️ Plugin Radare2 et r2ghidra (30 outils)

Tous les outils Radare2 utilisent un pool de connexions thread-safe (`r2_pool.py`) qui gère automatiquement les sessions r2pipe.

| # | Outil | Description |
|---|---|---|
| 46 | `Radare2_open_file` | Ouvrir un fichier binaire dans Radare2 |
| 47 | `Radare2_close_file` | Fermer une session Radare2 |
| 48 | `Radare2_list_open_files` | Lister les fichiers actuellement ouverts |
| 49 | `Radare2_analyze_binary` | Exécuter l'auto-analyse complète (`aaa`) |
| 50 | `Radare2_list_functions` | Lister toutes les fonctions détectées |
| 51 | `Radare2_disassemble_function` | Désassembler une fonction spécifique |
| 52 | `Radare2_disassemble_address` | Désassembler à une adresse spécifique |
| 53 | `Radare2_decompile_function` | Décompiler via r2ghidra (moteur Ghidra intégré à r2, aucune JVM requise) |
| 54 | `Radare2_list_exports` | Lister les symboles exportés |
| 55 | `Radare2_list_imports` | Lister les fonctions importées |
| 56 | `Radare2_list_sections` | Lister les sections du binaire avec l'entropie |
| 57 | `Radare2_list_strings` | Lister les chaînes trouvées dans le binaire |
| 58 | `Radare2_find_cross_references` | Suivre les appels de fonctions et les références de données |
| 59 | `Radare2_search_bytes` | Rechercher des motifs d'octets dans le binaire |
| 60 | `Radare2_get_binary_info` | Obtenir les métadonnées du binaire (arch, format, endianness) |
| 61 | `Radare2_execute_command` | Exécuter une commande Radare2 brute |
| 62 | `Radare2_esil_emulate` | Émulation ESIL à une adresse spécifique |
| 63 | `Radare2_get_hexdump` | Hex dump à une adresse virtuelle |
| 64 | `Radare2_get_cfg_data` | Extraire les données du graphe de flux de contrôle |
| 65 | `Radare2_generate_cfg_png` | Générer le CFG sous forme d'image PNG |
| 66 | `Radare2_generate_callgraph` | Générer le graphe d'appels de fonctions |
| 67 | `Radare2_recover_structures` | Récupérer automatiquement les structures C et les persister dans la base de données d'annotations |
| 68 | `Radare2_decompile_with_r2ghidra` | Décompilation C de haute qualité avec mise en cache |
| 69 | `Radare2_annotate_binary` | Ajouter des annotations au binaire |
| 70 | `Radare2_get_annotations` | Récupérer les annotations |
| 71 | `Radare2_export_annotations` | Exporter les annotations vers un fichier |
| 72 | `Radare2_import_annotations` | Importer des annotations depuis un fichier |
| 73 | `Radare2_detect_crypto_constants` | Détecter les constantes cryptographiques (S-box AES, etc.) |
| 74 | `Radare2_find_gadgets` | Trouver des gadgets ROP/JOP |
| 75 | `Radare2_calculate_entropy` | Calculer l'entropie par section |

---

### 🦠 Plugin d'analyse de malwares (9 outils)

| # | Outil | Backend | Description |
|---|---|---|---|
| 76 | `dormant_detector` | Radare2 + heuristics | Trouver des portes dérobées cachées, des fonctions orphelines, des bombes à retardement, des bombes logiques |
| 77 | `adaptive_vaccine` | YARA + Radare2 | Générer des règles de détection YARA + des patchs binaires pour neutraliser les menaces |
| 78 | `vulnerability_hunter` | Radare2 + analysis | Détecter les motifs d'API dangereux (strcpy, sprintf) et les chaînes de gadgets ROP |
| 79 | `extract_iocs` | Regex + LIEF | Extraire les IP, URL, domaines, hashs, clés de registre, adresses crypto |
| 80 | `run_yara` | YARA | Analyser avec des fichiers de règles personnalisés et des ensembles de règles intégrés |
| 81 | `generate_poc_exploit` | pwntools | Générer un code d'exploit de preuve de concept |
| 82 | `build_rop_chain` | ROPgadget + pwntools | Construction automatisée de chaînes ROP |
| 83 | `autonomous_vuln_hunt` | Radare2 + angr | Pipeline autonome de chasse aux vulnérabilités |
| 84 | `analyze_heap_exploit` | Radare2 + heuristics | Analyse d'exploitation du tas (UAF, double-free, overflow) |

---

### 🕵️ Plugin de forensique numérique (22 outils)

**Forensique mémoire (6 outils)**

| # | Outil | Backend | Description |
|---|---|---|---|
| 85 | `memory_analyze` | Volatility3 | Analyse complète d'un dump mémoire |
| 86 | `memory_list_processes` | Volatility3 | Lister les processus en cours d'exécution depuis le dump mémoire |
| 87 | `memory_detect_injections` | Volatility3 | Détecter l'injection de code dans la mémoire des processus |
| 88 | `memory_extract_strings` | Volatility3 | Extraire les chaînes de la mémoire des processus |
| 89 | `memory_dump_module` | Volatility3 | Extraire (dumper) un module chargé depuis la mémoire |
| 90 | `memory_list_symbols` | Volatility3 | Lister les symboles depuis la mémoire |

**Forensique disque (6 outils)**

| # | Outil | Backend | Description |
|---|---|---|---|
| 91 | `disk_list_partition` | Sleuth Kit | Lister les partitions du disque |
| 92 | `disk_list_files` | Sleuth Kit | Lister les fichiers d'une image disque |
| 93 | `disk_recover_deleted` | Sleuth Kit | Récupérer les fichiers supprimés |
| 94 | `disk_analyze_mft` | Sleuth Kit | Analyser la Master File Table NTFS |
| 95 | `disk_extract_file` | Sleuth Kit | Extraire un fichier d'une image disque |
| 96 | `disk_hash_verify` | Sleuth Kit | Vérifier l'intégrité des fichiers via hash |

**Forensique réseau (5 outils)**

| # | Outil | Backend | Description |
|---|---|---|---|
| 97 | `pcap_analyze` | Scapy | Analyse PCAP : répartition des protocoles, anomalies |
| 98 | `pcap_list_connections` | Scapy | Lister toutes les connexions réseau |
| 99 | `pcap_extract_dns` | Scapy | Extraire les requêtes et réponses DNS |
| 100 | `pcap_extract_c2` | Scapy | Identifier les communications C2 potentielles |
| 101 | `pcap_reconstruct_stream` | Scapy | Reconstruire les flux TCP |

**Analyse des artefacts (5 outils)**

| # | Outil | Backend | Description |
|---|---|---|---|
| 102 | `artifact_collect` | Custom parsers | Collecter l'historique du navigateur, les ruches de registre, les journaux d'événements, prefetch |
| 103 | `artifact_correlate_ioc` | Custom parsers | Corréler les artefacts avec des IOC connus |
| 104 | `artifact_generate_yara` | YARA | Générer des règles YARA à partir de motifs d'artefacts |
| 105 | `artifact_timeline` | Custom parsers | Construire une chronologie à partir de multiples sources d'artefacts |
| 106 | `artifact_report` | Custom parsers | Générer un rapport d'analyse des artefacts |

---

### 📝 Plugin de génération de rapports (14 outils)

| # | Outil | Description |
|---|---|---|
| 107 | `get_system_time` | Obtenir l'horodatage du serveur (empêche l'IA d'inventer des dates) |
| 108 | `set_timezone` | Définir le fuseau horaire des rapports |
| 109 | `get_timezone_info` | Obtenir les informations du fuseau horaire actuel |
| 110 | `start_report_session` | Démarrer une session d'analyse chronométrée avec un ID unique |
| 111 | `end_report_session` | Finaliser la session : calculer la durée, verrouiller les listes IOC/ATT&CK |
| 112 | `get_report_session_status` | Vérifier l'état de la session |
| 113 | `list_report_sessions` | Lister toutes les sessions actives/terminées |
| 114 | `add_ioc` | Collecter et baliser les IOC pendant une session en direct |
| 115 | `add_analysis_note` | Ajouter des notes catégorisées (résultat, avertissement, comportement) |
| 116 | `add_mitre_technique` | Documenter les ID de techniques MITRE ATT&CK |
| 117 | `set_severity` | Définir la sévérité de la session (faible/moyenne/élevée/critique) |
| 118 | `create_analysis_report` | Générer le rapport en 4 modes : `full_analysis`, `quick_triage`, `ioc_summary`, `executive_brief` |
| 119 | `generate_vex_report` | Générer un rapport VEX (Vulnerability Exploitability eXchange) |
| 120 | `generate_sigma_rule` | Générer des règles de détection SIGMA |

---

## Invites d'analyse guidée (22 modes)

Les invites sont des flux de travail d'analyse préconstruits qui préparent l'IA avec une personnalité structurée, des séquences d'utilisation d'outils étape par étape et des règles de classification des preuves. Vous les activez en référençant le nom de l'invite dans votre client IA.

### Analyse de malwares (9 invites)

| Invite | Cas d'utilisation |
|---|---|
| `full_analysis_mode` | Analyse complète en 6 phases : triage → désassemblage → comportement → réseau → persistance → rapport |
| `malware_analysis_mode` | Analyse de malware ciblée avec classification des menaces |
| `basic_analysis_mode` | Triage rapide pour l'évaluation initiale et des verdicts rapides |
| `apt_hunting_mode` | Chasse spécifique aux APT : mouvement latéral, persistance, exfiltration de données |
| `malware_defense_mode` | Orienté défense : générer des règles de détection et des mesures d'atténuation |
| `unpacking_mode` | Analyser et contourner le packing/l'obfuscation (Themida, VMProtect, UPX) |
| `c2_extraction_mode` | Extraire et analyser l'infrastructure de communication C2 |
| `ransomware_triage_mode` | Triage spécifique aux ransomwares : analyse du chiffrement, évaluation de la récupération des clés |
| `code_similarity_mode` | Comparer les binaires pour la similarité de code et la lignée partagée |

### Recherche en sécurité (6 invites)

| Invite | Cas d'utilisation |
|---|---|
| `vulnerability_research_mode` | Chasse aux bugs : dépassements de tampon, UAF, injection de commandes |
| `crypto_analysis_mode` | Analyse des implémentations cryptographiques et détection de faiblesses |
| `firmware_analysis_mode` | Firmware IoT/embarqué : extraction binwalk, chaînes UART, identifiants codés en dur |
| `patch_analysis_mode` | Analyse de patchs de sécurité et tests de régression |
| `source_code_audit_mode` | Audit de sécurité du code source (Python, C, C++) |
| `autonomous_vuln_hunt_mode` | Pipeline autonome de chasse aux vulnérabilités |

### Recherche CVE et développement d'exploits (5 invites)

| Invite | Cas d'utilisation |
|---|---|
| `taint_analysis_mode` | Analyse de flux de données (taint) : découverte automatisée des chemins source→puits |
| `heap_exploit_mode` | Analyse d'exploitation du tas et génération de PoC |
| `fuzzing_mode` | Configuration de campagne de fuzzing et triage des crashes |
| `patch_diff_auto_mode` | Diff de patch automatisé pour la recherche de vulnérabilités 1-day |
| `cve_discovery_pipeline_mode` | Pipeline complet de découverte de CVE : du diff de patch à l'exploit fonctionnel |

### Autres (2 invites)

| Invite | Cas d'utilisation |
|---|---|
| `game_analysis_mode` | Analyse de client de jeu : détection anti-triche, rétro-ingénierie (RE) de protocole, inspection mémoire |
| `report_generation_mode` | Flux de travail de session structuré avec correspondance des techniques MITRE ATT&CK |

> **Comment fonctionnent les invites :** Chaque invite prépare l'IA avec une personnalité d'analyse structurée. Elle inclut des points de contrôle de raisonnement Chain-of-Thought (où l'IA doit s'arrêter et évaluer avant de continuer) et des règles de classification des preuves qui empêchent l'IA de présenter des spéculations comme des faits. Chaque résultat doit être étiqueté `OBSERVED` (vérifié directement), `INFERRED` (dérivé logiquement de l'analyse statique) ou `POSSIBLE` (nécessite une vérification supplémentaire).

---

## Ressources MCP (11 URI)

Les ressources sont des points de terminaison de données en lecture seule accessibles aux clients IA via des modèles d'URI. Elles complètent les outils en fournissant des données structurées sans nécessiter d'appels d'outils explicites.

### Ressources statiques

| URI | Description |
|---|---|
| `reversecore://guide` | Guide d'utilisation des outils avec règles de chemins de fichiers et bonnes pratiques |
| `reversecore://guide/structures` | Guide technique de récupération de structures et d'analyse de références croisées |
| `reversecore://tools` | Documentation complète des 120 outils enregistrés |
| `reversecore://logs` | Journaux d'application (100 dernières lignes) |

### Ressources dynamiques (Système de fichiers virtuel par binaire)

Ces URI se résolvent par binaire et invoquent les outils d'analyse correspondants à la demande :

| Modèle d'URI | Description |
|---|---|
| `reversecore://{filename}/strings` | Extraire toutes les chaînes d'un binaire |
| `reversecore://{filename}/iocs` | Extraire les IOC (IP, URL, e-mails, hashs) |
| `reversecore://{filename}/func/{address}/code` | Code pseudo-C décompilé pour une fonction |
| `reversecore://{filename}/func/{address}/asm` | Désassemblage pour une fonction |
| `reversecore://{filename}/func/{address}/cfg` | Graphe de flux de contrôle au format Mermaid |
| `reversecore://{filename}/functions` | Liste de toutes les fonctions du binaire |
| `reversecore://{filename}/dormant_detector` | Résultats de l'analyse du dormant detector |

---

## Démarrage rapide

### Option 1 — PyPI (La plus simple)```bash
pip install reversecore-mcp
reversecore-mcp

### Option 3 — Compiler depuis les sources (Docker Compose)```bash
git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
./scripts/run-docker.sh        # auto-detects Intel / Apple Silicon

### Option 4 — Python (Développement local)```bash
git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python -m reversecore_mcp.server

> Remplacez `reversecore-mcp-arm64` par `reversecore-mcp` si vous êtes sur Intel/AMD.

---

### 🌐 Option 2 : Mode HTTP SSE

Pour le streaming réseau (Server-Sent Events) :```json
{
  "mcpServers": {
    "Reversecore_MCP": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

### Tests```bash
# Full test suite with coverage report
pytest tests/ -v

# Unit tests only (fast, no external dependencies)
pytest tests/unit/ -v

# Integration tests (requires Docker)
pytest tests/integration/ -v

# Run with coverage threshold enforcement
pytest tests/unit/ --cov=reversecore_mcp --cov-fail-under=80

# Run a specific test
pytest tests/unit/test_cli_tools.py::TestRunFile::test_success -v

# Security boundary tests
pytest tests/ -m security -v

# Benchmarks
pytest tests/ -m benchmark -v

### Hooks de pre-commit

Les hooks suivants s'exécutent automatiquement à chaque commit :

1. **Ruff** — lint avec correction automatique + vérification du format
2. **trailing-whitespace** — supprime les espaces en fin de ligne
3. **end-of-file-fixer** — garantit que les fichiers se terminent par un saut de ligne
4. **check-yaml / check-json** — valide la syntaxe YAML/JSON
5. **check-added-large-files** — bloque les fichiers > 1 Mo
6. **check-merge-conflict** — détecte les marqueurs de fusion non résolus
7. **detect-private-key** — empêche les commits accidentels de clés
8. **Bandit** — analyse de sécurité Python

---

## Pipeline CI/CD

Chaque push vers `main` déclenche 11 jobs de pipeline. Tous doivent réussir avant le déploiement.```
 Lint & Security Gate              Unit Tests (Python Matrix)
   ├─ Gitleaks (secret scan)         ├─ pytest 3.10 --cov-fail-under=80
   ├─ Hadolint (Dockerfile lint)     ├─ pytest 3.11 --cov-fail-under=80
   ├─ Ruff check + format            └─ pytest 3.12 --cov-fail-under=80
   ├─ Mypy type check (108 files)
   ├─ Bandit (all severities)      Wheel Smoke Test
   ├─ pip-audit (no CVEs)            └─ Build wheel → install in /tmp
   └─ Security boundary tests            → verify plugin discovery
                                          → assert __file__ under sys.prefix
 CodeQL Analysis
   └─ Python SAST                  Docker Verification
                                     ├─ Build reversecore-mcp:ci
 Exploit Safety Gate                 ├─ Trivy container scan
   ├─ Bandit on POC templates        ├─ Image size check (< 5 GB)
   ├─ Hypothesis DAST fuzzing        ├─ CLI tool verification
   ├─ Performance benchmarks         ├─ Integration tests in container
   └─ Container isolation test       └─ E2E tool invocation

 In-Container Smoke Test           Build Base Image (amd64 + arm64)
   ├─ Copy test ELF into container   ├─ Compile YARA 4.3.1
   └─ Run scripts/smoke_test.py     ├─ Compile Radare2 6.0.4
                                     ├─ Compile r2ghidra
 Deploy (amd64 + arm64)             └─ Push to GHCR
   ├─ Build app image
   ├─ Push to GHCR                 Merge Manifests
   └─ Trivy rescan on published     └─ Multi-arch manifest → :latest

Cette image n'est reconstruite que lorsque les versions des outils changent. Durée de construction : ~12 minutes.

### Couche 2 : Image d'application (`Dockerfile`)

Hérite de l'image de base et copie le code de l'application :```
FROM base image
    ├── COPY reversecore_mcp/ (application code)
    ├── COPY scripts/ (smoke test, benchmarks)
    ├── pip install any new requirements
    ├── Security package upgrades
    └── CMD ["python", "-m", "reversecore_mcp.server"]

**Autres répertoires :**```
tests/
├── unit/                          # 1,957 unit tests
├── integration/                   # Docker-based integration tests
├── fixtures/                      # Test binaries, YARA rules, sample data
└── conftest.py                    # Shared pytest fixtures

scripts/
├── smoke_test.py                  # Multi-layer in-container smoke test
├── check_release_metadata.py      # Version consistency validation
├── fetch_test_binaries.py         # Download test fixtures
├── run-docker.sh                  # Auto-detect architecture and start
└── ...                            # Benchmarks, analysis scripts

docs/
├── getting-started/               # Installation guide
├── development/                   # Architecture, contributing, testing guides
├── api/                           # Tool and module reference
└── user-guide/                    # Analysis workflows

Args:
    file_path: Path to the binary file (relative to workspace).
    option: Optional analysis option.

Returns:
    ToolResult with status='success' and structured content.
"""
try:
    safe_path = validate_file_path(file_path)
    result = await perform_analysis(safe_path)
    return success({"result": result})
except Exception as e:
    return failure(
        error_code="RCMCP-E100",
        message=str(e),
        hint="Check that the file exists and is a valid binary.",
    )

Ensuite, enregistrez-le dans le `__init__.py` du plugin approprié et ajoutez des tests dans `tests/unit/`.

---

## Contribuer

1. Forkez le dépôt
2. Créez une branche de fonctionnalité : `git checkout -b feat/my-feature`
3. Écrivez des tests en parallèle de votre code — la couverture ne doit pas descendre en dessous de 80 %
4. Assurez-vous que toutes les vérifications passent : `pytest`, `ruff check`, `mypy`, `bandit`
5. Ouvrez une pull request avec une description claire

Veuillez lire le [Guide de contribution](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md) pour les normes de code, les conventions de docstring (style Google) et la liste de contrôle des pull requests.

---

## Documentation

| Document | Description |
|---|---|
| [Guide d'installation](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/getting-started/installation.md) | Configuration détaillée pour tous les environnements |
| [Guide d'architecture](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/architecture.md) | Conception du système et détails des composants |
| [Guide de contribution](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md) | Normes de code, docstrings, workflow des PR |
| [Guide des tests](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/testing.md) | Modèles de test, fixtures et couverture |
| [Référence de l'API](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/api/) | Référence des outils et modules |
| [Guide utilisateur](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/user-guide/) | Workflows d'analyse |

---

## Exemples d'utilisation

### Exemple 1 : Tri de base des malwares```
User: "Analyze this suspicious file sample.exe"

AI calls:
  1. run_file("sample.exe")           → PE32 executable, x86, MSVC
  2. detect_packer("sample.exe")      → Not packed
  3. extract_iocs("sample.exe")       → 3 IPs, 2 URLs, 1 mutex
  4. run_capa("sample.exe")           → "creates persistence", "encrypts data"
  5. dormant_detector("sample.exe")   → 2 orphan functions with network calls
  6. generate_yara_rule("sample.exe") → Detection rule generated

AI response: "This PE32 binary shows ransomware-like behavior. CAPA detected
encryption and persistence capabilities. I found 2 hidden network functions
that may serve as a backup C2 channel. Here's a YARA rule for detection..."

### Exemple 3: Enquête de criminalistique numérique```
User: "Analyze this memory dump from a compromised server"

AI calls:
  1. memory_list_processes("memdump.raw")
     → 47 processes, 2 with suspicious names

  2. memory_detect_injections("memdump.raw")
     → Code injection detected in PID 1842 (svchost.exe)

  3. memory_extract_strings("memdump.raw", pid=1842)
     → C2 domain strings extracted

  4. artifact_correlate_ioc(artifacts={"domains": ["evil-c2.com"]})
     → Matches known APT group IOCs

  5. create_analysis_report(template_type="full_analysis")
     → PDF report with timeline and MITRE ATT&CK mapping

---

## Prise en charge multi-architecture

Le module `arch_registry.py` fait correspondre les noms d'architectures aux paramètres de configuration de Radare2, permettant ainsi aux outils de fonctionner sur différentes architectures CPU sans configuration manuelle :

| Architecture | Clé | Architecture r2 | Largeurs de bits | Registre PC | Registre SP |
|---|---|---|---|---|---|
| Intel 32-bit | `x86` | `x86` | 32 | `eip` | `esp` |
| Intel/AMD 64-bit | `x86_64` | `x86` | 64 | `rip` | `rsp` |
| ARM 32-bit / Thumb | `arm32` | `arm` | 16, 32 | `r15` | `r13` |
| ARM 64-bit (AArch64) | `arm64` | `arm` | 64 | `pc` | `sp` |
| MIPS | `mips` | `mips` | 32, 64 | `pc` | `sp` |
| RISC-V | `riscv` | `riscv` | 32, 64 | `pc` | `sp` |
| PowerPC | `ppc` | `ppc` | 32, 64 | `pc` | `r1` |

**La résolution d'alias** est gérée automatiquement :
- `amd64` → `x86_64`
- `aarch64` → `arm64`
- `arm` avec `bits=64` → `arm64`
- `arm` avec `bits=16` ou `bits=32` → `arm32`

Des outils comme `Radare2_esil_emulate`, `assemble_instructions` et `r2_simulate_patch` utilisent ce registre pour configurer correctement l'environnement d'analyse pour n'importe quel binaire cible.

---

## Système de cache de résultats

Deux couches de cache minimisent les calculs redondants :

### Cache de résultats d'outil (`result_cache.py`)

Le décorateur `@cache_tool_result` met en cache la sortie de n'importe quel outil en fonction d'un hash SHA256 du fichier binaire et des arguments de mots-clés de l'outil :```
Cache key = SHA256( "<tool_name>::{sorted_json_kwargs}" )

**Stockage :** base de données SQLite asynchrone au chemin configuré par `MEMORY_DB_PATH` (par défaut : `~/.reversecore_mcp/memory.db`).

**Portabilité :** utilisez `export_memory_store` et `import_memory_store` pour transférer l'intégralité de la base de données mémoire entre environnements.

---

## Tableau de bord web

En mode HTTP (`MCP_TRANSPORT=http`), un tableau de bord web est disponible à l'adresse `http://localhost:8000/dashboard`. Il fournit :

- Téléversement de binaires par glisser-déposer
- Statut d'analyse en temps réel
- Liste interactive des fonctions et vue de désassemblage
- Résultats d'extraction des IOC
- Surveillance de l'état du serveur

**Pile technique :** FastAPI + templates Jinja2 + HTMX (chargé localement depuis `dashboard/static/`, aucune dépendance CDN pour la conformité CSP).

**Fonctionnalités de sécurité :**
- Jetons CSRF sur tous les formulaires modifiant l'état
- Échappement automatique de Jinja2 activé
- Toutes les entrées utilisateur sont assainies via `html.escape()` avant affichage
- Protection contre les traversées de chemin via `validate_file_path()`

---

## Déploiement

### Liste de contrôle pour la production

Avant de déployer en production :

| Élément | Comment |
|---|---|
| Définir la clé API | `MCP_API_KEY=<clé-robuste-aléatoire>` |
| Utiliser un utilisateur non root | Intégré : le conteneur s'exécute en tant qu'`appuser` (UID 1000) |
| Définir les limites de ressources | Par défaut : 2 CPU / 4 Go de RAM dans `docker-compose.yml` |
| Activer la journalisation structurée | `LOG_FORMAT=json` pour l'agrégation de journaux |
| Configurer Redis | `REDIS_URL=redis://<host>:6379/0` pour la file de tâches et la mise en cache |
| Définir le chemin de l'espace de travail | `REVERSECORE_WORKSPACE=/path/to/isolated/directory` |
| Réviser les limites de débit | `REVERSECORE_RATE_LIMIT=60` (requêtes/min, ajuster selon les besoins) |
| Activer le sandbox | `REVERSECORE_SANDBOX_ENABLED=true` pour l'isolation de l'analyse dynamique |

### Contrôles de santé

Le serveur fournit des endpoints HTTP de contrôle de santé pour l'orchestration :```bash
# Liveness (always 200 if process is running)
curl http://localhost:8000/health/live

# Readiness (checks tool availability)
curl http://localhost:8000/health/ready

# Full health (requires API key if configured)
curl -H "X-API-Key: <key>" http://localhost:8000/health