L'assistente AI scompone questo in chiamate di strumenti:```
r2_decompile("sample.exe", "main")
  → extract_iocs("sample.exe")
    → add_mitre_technique(technique_id="T1071.001", ...)
      → create_analysis_report(template_type="quick_triage")

### Infrastruttura principale (37 moduli)

La directory `reversecore_mcp/core/` contiene l'infrastruttura condivisa su cui si basano tutti gli strumenti:

| Modulo | Scopo |
|---|---|
| `config.py` | Pydantic BaseSettings con 34+ variabili d'ambiente |
| `security.py` | Sanificazione degli input, validazione degli argomenti dei comandi |
| `validators.py` | Validazione dei percorsi di file e binari con mitigazione TOCTOU, risoluzione dei symlink |
| `r2_pool.py` | Pool di connessioni Radare2 thread-safe con dimensione configurabile |
| `r2_helpers.py` | Parsing strutturato dell'output di Radare2 |
| `metrics.py` | Tempi di esecuzione per strumento, conteggi delle chiamate, tassi di errore, statistiche della cache |
| `memory.py` | Archivio di memoria AI basato su SQLite asincrono per persistere i risultati dell'analisi tra sessioni diverse |
| `mitre_mapper.py` | Motore di mappatura degli ID delle tecniche MITRE ATT&CK |
| `evidence.py` | Sistema di classificazione delle evidenze: `OBSERVED`, `INFERRED`, `POSSIBLE` |
| `resilience.py` | Decorator pattern per retry, circuit-breaker e timeout |
| `task_queue.py` | Coda di task in background tramite Redis + arq |
| `extension_registry.py` | Registrazione dei plugin e gestione del ciclo di vita |
| `arch_registry.py` | Mappatura multi-architettura (x86, x86_64, ARM32, ARM64, MIPS, RISC-V, PPC → arch/bits/registri r2) |
| `result_cache.py` | Decorator di caching dei risultati degli strumenti basato su SHA256 (`@cache_tool_result`) |
| `analysis_cache.py` | Cache di decompilazione multilivello (L1: Redis, L2: SQLite) |
| `result.py` | Modelli Pydantic `ToolSuccess` / `ToolError` |
| `exceptions.py` | 17 classi di eccezione con codici di errore `RCMCP-E*` |
| `decorators.py` | `@log_execution`, `@track_metrics` |
| `error_handling.py` | Decorator `@handle_tool_errors` |
| `error_formatting.py` | Formattazione strutturata delle risposte di errore |
| `execution.py` | Esecuzione sicura di subprocess con timeout e limiti di output |
| `command_spec.py` | Specifica dei comandi per le chiamate a subprocess |
| `loader.py` | Caricatore dinamico dei moduli degli strumenti |
| `plugin.py` | Classe base dei plugin |
| `extension.py` | Classe base delle estensioni |
| `container.py` | Supporto all'esecuzione in container/sandbox |
| `audit.py` | Registrazione delle attività di audit |
| `binary_cache.py` | Caching dei file binari |
| `json_utils.py` | Serializzazione JSON tramite orjson (3-5 volte più veloce del json della libreria standard) |
| `logging_config.py` | Logging strutturato basato su Loguru |
| `report_generator.py` | Motore di rendering dei report (Markdown, PDF tramite xhtml2pdf) |
| `resource_manager.py` | Gestione del ciclo di vita delle risorse MCP |
| `sast/python_ast_scanner.py` | Scanner di vulnerabilità basato su AST Python |
| `sast/regex_scanner.py` | Scanner di vulnerabilità C/C++ basato su regex |
| `sast/rule_manager.py` | Caricamento e gestione delle regole SAST |

---

## Catalogo degli strumenti (120 strumenti)

Ogni strumento restituisce un `ToolResult` strutturato — o un `ToolSuccess` con `data` tipizzato o un `ToolError` con un codice di errore `RCMCP-E*`. Gli strumenti sono organizzati in 8 plugin.

---

### 🔍 Plugin di analisi statica (24 strumenti)

| # | Strumento | Backend | Descrizione |
|---|---|---|---|
| 1 | `run_strings` | CLI `strings` | Estrazione di stringhe ASCII/Unicode con lunghezza minima configurabile |
| 2 | `run_binwalk` | Binwalk | Scansione approfondita del firmware per firme e filesystem incorporati |
| 3 | `run_binwalk_extract` | Binwalk | Estrae i file incorporati scoperti da binwalk |
| 4 | `parse_binary_with_lief` | LIEF | Parsing completo di intestazioni PE/ELF/Mach-O, sezioni, import/export, TLS |
| 5 | `detect_packer` | DIE | Rilevamento rapido di packer/compilatori |
| 6 | `detect_packer_deep` | DIE (`diec`) | Analisi approfondita di packer/protector tramite Detect It Easy |
| 7 | `run_capa` | CAPA (Mandiant FLARE) | Rilevamento delle capacità — «cifra i dati», «crea persistenza», ecc. |
| 8 | `run_capa_quick` | CAPA | Scansione rapida delle capacità con un sottoinsieme di regole |
| 9 | `generate_signature` | Radare2 | Genera firme binarie per l'identificazione |
| 10 | `generate_yara_rule` | Radare2 + YARA | Genera regole di rilevamento YARA dai pattern binari |
| 11 | `generate_advanced_yara_rule` | Radare2 + YARA | Regole YARA avanzate con indicatori comportamentali |
| 12 | `scan_for_versions` | LIEF + strings | Scansiona il binario alla ricerca di stringhe di versione incorporate |
| 13 | `extract_rtti_info` | Radare2 | Estrae le informazioni RTTI (Run-Time Type Information) C++ |
| 14 | `diff_binaries` | Radare2 | Diff binario semantico tra due versioni di file |
| 15 | `analyze_variant_changes` | Radare2 | Analizza le modifiche tra varianti binarie |
| 16 | `match_libraries` | Radare2 | Identifica le librerie collegate staticamente tramite impronte delle funzioni |
| 17 | `patch_diff_1day` | Radare2 + euristiche | Analisi automatica del diff di patch per la ricerca di vulnerabilità 1-day |
| 18 | `analyze_patch_diff_auto` | Radare2 + inferenza | Inferenza automatica delle vulnerabilità dalle patch |
| 19 | `emulate_binary` | Radare2 ESIL | Emulazione del codice con tracciamento di registri/memoria |
| 20 | `generate_fuzzing_harness` | Qiling + AFL++ | Genera un harness di fuzzing mirato a una funzione specifica |
| 21 | `run_fuzzing_campaign` | AFL++ | Esegue una campagna di fuzzing completa con raccolta dei crash |
| 22 | `triage_crash` | GDB | Parsing dei crash e valutazione della sfruttabilità |
| 23 | `verify_path_and_get_args` | angr | Esecuzione simbolica — dimostra la raggiungibilità dei percorsi e calcola input concreti |
| 24 | `taint_trace` | Radare2 + angr | Analisi del flusso dati con taint dalle sorgenti ai sink |

---

### 🔐 Plugin di audit del codice sorgente (1 strumento)

| # | Strumento | Backend | Descrizione |
|---|---|---|---|
| 25 | `audit_source_code` | AST + Regex | Scansione AST Python + scansione regex C/C++ per pattern pericolosi |

---

### 🛠️ Plugin di utilità comuni (20 strumenti)

**Operazioni sui file (5 strumenti)**

| # | Strumento | Descrizione |
|---|---|---|
| 26 | `run_file` | Identificazione del tipo di file, dell'architettura e del compilatore |
| 27 | `copy_to_workspace` | Copia un file nello spazio di lavoro di analisi |
| 28 | `create_directory` | Crea una directory nello spazio di lavoro |
| 29 | `list_workspace` | Elenca tutti i file nello spazio di lavoro |
| 30 | `scan_workspace` | Scansione completa dello spazio di lavoro con metadati dei file |

**Spiegazione delle patch (1 strumento)**

| # | Strumento | Descrizione |
|---|---|---|
| 31 | `explain_patch` | Spiega una patch binaria in linguaggio naturale |

**Assembler (1 strumento)**

| # | Strumento | Backend | Descrizione |
|---|---|---|---|
| 32 | `assemble_instructions` | Keystone | Assembla istruzioni in codice macchina (x86, ARM, MIPS, ecc.) |

**Gestione della memoria AI (11 strumenti)**

Questi strumenti consentono all'AI di persistere e recuperare i risultati tra sessioni di analisi utilizzando un database SQLite asincrono:

| # | Strumento | Descrizione |
|---|---|---|
| 33 | `create_memory_session` | Avvia una nuova sessione di memoria per un'analisi |
| 34 | `store_analysis_finding` | Persiste un risultato di analisi con tag |
| 35 | `query_analysis_memories` | Cerca risultati passati tramite query |
| 36 | `get_binary_analysis_context` | Recupera tutto il contesto per un binario specifico |
| 37 | `tag_analysis_session` | Aggiunge tag a una sessione per l'organizzazione |
| 38 | `search_memories_by_tag` | Trova sessioni/risultati per tag |
| 39 | `delete_analysis_session` | Rimuove una sessione e i suoi risultati |
| 40 | `cleanup_expired_sessions` | Rimuove le sessioni più vecchie di una soglia |
| 41 | `list_analysis_sessions` | Elenca tutte le sessioni attive |
| 42 | `export_memory_store` | Esporta tutte le memorie in un formato portabile |
| 43 | `import_memory_store` | Importa le memorie da un file di esportazione |

**Monitoraggio del server (2 strumenti)**

| # | Strumento | Descrizione |
|---|---|---|
| 44 | `get_server_health` | Uptime, utilizzo della memoria, strumenti caricati, versione di Python |
| 45 | `get_tool_metrics` | Conteggi delle chiamate per strumento, tempi medi di esecuzione, tassi di errore, hit/miss della cache |

---

### ⚙️ Plugin Radare2 e r2ghidra (30 strumenti)

Tutti gli strumenti Radare2 utilizzano un pool di connessioni thread-safe (`r2_pool.py`) che gestisce automaticamente le sessioni r2pipe.

| # | Strumento | Descrizione |
|---|---|---|
| 46 | `Radare2_open_file` | Apre un file binario in Radare2 |
| 47 | `Radare2_close_file` | Chiude una sessione Radare2 |
| 48 | `Radare2_list_open_files` | Elenca i file attualmente aperti |
| 49 | `Radare2_analyze_binary` | Esegue l'auto-analisi completa (`aaa`) |
| 50 | `Radare2_list_functions` | Elenca tutte le funzioni rilevate |
| 51 | `Radare2_disassemble_function` | Disassembla una funzione specifica |
| 52 | `Radare2_disassemble_address` | Disassembla a un indirizzo specifico |
| 53 | `Radare2_decompile_function` | Decompila tramite r2ghidra (motore Ghidra integrato in r2, nessuna JVM necessaria) |
| 54 | `Radare2_list_exports` | Elenca i simboli esportati |
| 55 | `Radare2_list_imports` | Elenca le funzioni importate |
| 56 | `Radare2_list_sections` | Elenca le sezioni del binario con entropia |
| 57 | `Radare2_list_strings` | Elenca le stringhe trovate nel binario |
| 58 | `Radare2_find_cross_references` | Traccia le chiamate di funzione e i riferimenti ai dati |
| 59 | `Radare2_search_bytes` | Cerca pattern di byte nel binario |
| 60 | `Radare2_get_binary_info` | Ottiene i metadati del binario (arch, formato, endianness) |
| 61 | `Radare2_execute_command` | Esegue un comando Radare2 grezzo |
| 62 | `Radare2_esil_emulate` | Emulazione ESIL a un indirizzo specifico |
| 63 | `Radare2_get_hexdump` | Hex dump a un indirizzo virtuale |
| 64 | `Radare2_get_cfg_data` | Estrae i dati del grafo di flusso di controllo |
| 65 | `Radare2_generate_cfg_png` | Genera il CFG come immagine PNG |
| 66 | `Radare2_generate_callgraph` | Genera il grafo delle chiamate di funzione |
| 67 | `Radare2_recover_structures` | Recupera automaticamente le struct C e le persiste nel database delle annotazioni |
| 68 | `Radare2_decompile_with_r2ghidra` | Decompilazione C di alta qualità con caching |
| 69 | `Radare2_annotate_binary` | Aggiunge annotazioni al binario |
| 70 | `Radare2_get_annotations` | Recupera le annotazioni |
| 71 | `Radare2_export_annotations` | Esporta le annotazioni in un file |
| 72 | `Radare2_import_annotations` | Importa le annotazioni da un file |
| 73 | `Radare2_detect_crypto_constants` | Rileva costanti crittografiche (S-box AES, ecc.) |
| 74 | `Radare2_find_gadgets` | Trova gadget ROP/JOP |
| 75 | `Radare2_calculate_entropy` | Calcola l'entropia per sezione |

---

### 🦠 Plugin di analisi malware (9 strumenti)

| # | Strumento | Backend | Descrizione |
|---|---|---|---|
| 76 | `dormant_detector` | Radare2 + euristiche | Trova backdoor nascoste, funzioni orfane, time-bomb, logic bomb |
| 77 | `adaptive_vaccine` | YARA + Radare2 | Genera regole YARA di rilevamento + patch binarie per neutralizzare le minacce |
| 78 | `vulnerability_hunter` | Radare2 + analisi | Rileva pattern API pericolosi (strcpy, sprintf) e catene di gadget ROP |
| 79 | `extract_iocs` | Regex + LIEF | Estrae IP, URL, domini, hash, chiavi di registro, indirizzi crypto |
| 80 | `run_yara` | YARA | Scansiona con file di regole personalizzati e set di regole integrati |
| 81 | `generate_poc_exploit` | pwntools | Genera codice exploit proof-of-concept |
| 82 | `build_rop_chain` | ROPgadget + pwntools | Costruzione automatica di catene ROP |
| 83 | `autonomous_vuln_hunt` | Radare2 + angr | Pipeline autonoma di caccia alle vulnerabilità |
| 84 | `analyze_heap_exploit` | Radare2 + euristiche | Analisi dello sfruttamento dell'heap (UAF, double-free, overflow) |

---

### 🕵️ Plugin di digital forensics (22 strumenti)

**Analisi forense della memoria (6 strumenti)**

| # | Strumento | Backend | Descrizione |
|---|---|---|---|
| 85 | `memory_analyze` | Volatility3 | Analisi completa del dump di memoria |
| 86 | `memory_list_processes` | Volatility3 | Elenca i processi in esecuzione dal dump di memoria |
| 87 | `memory_detect_injections` | Volatility3 | Rileva l'iniezione di codice nella memoria dei processi |
| 88 | `memory_extract_strings` | Volatility3 | Estrae le stringhe dalla memoria dei processi |
| 89 | `memory_dump_module` | Volatility3 | Esegue il dump di un modulo caricato dalla memoria |
| 90 | `memory_list_symbols` | Volatility3 | Elenca i simboli dalla memoria |

**Analisi forense del disco (6 strumenti)**

| # | Strumento | Backend | Descrizione |
|---|---|---|---|
| 91 | `disk_list_partition` | Sleuth Kit | Elenca le partizioni del disco |
| 92 | `disk_list_files` | Sleuth Kit | Elenca i file in un'immagine disco |
| 93 | `disk_recover_deleted` | Sleuth Kit | Recupera i file eliminati |
| 94 | `disk_analyze_mft` | Sleuth Kit | Analizza la Master File Table NTFS |
| 95 | `disk_extract_file` | Sleuth Kit | Estrae un file dall'immagine disco |
| 96 | `disk_hash_verify` | Sleuth Kit | Verifica l'integrità dei file tramite hash |

**Analisi forense della rete (5 strumenti)**

| # | Strumento | Backend | Descrizione |
|---|---|---|---|
| 97 | `pcap_analyze` | Scapy | Analisi PCAP: ripartizione dei protocolli, anomalie |
| 98 | `pcap_list_connections` | Scapy | Elenca tutte le connessioni di rete |
| 99 | `pcap_extract_dns` | Scapy | Estrae le query e le risposte DNS |
| 100 | `pcap_extract_c2` | Scapy | Identifica potenziali comunicazioni C2 |
| 101 | `pcap_reconstruct_stream` | Scapy | Ricostruisce i flussi TCP |

**Analisi degli artefatti (5 strumenti)**

| # | Strumento | Backend | Descrizione |
|---|---|---|---|
| 102 | `artifact_collect` | Parser personalizzati | Raccoglie cronologia del browser, hive di registro, log eventi, prefetch |
| 103 | `artifact_correlate_ioc` | Parser personalizzati | Correla gli artefatti con IOC noti |
| 104 | `artifact_generate_yara` | YARA | Genera regole YARA dai pattern degli artefatti |
| 105 | `artifact_timeline` | Parser personalizzati | Costruisce una timeline da più fonti di artefatti |
| 106 | `artifact_report` | Parser personalizzati | Genera un report di analisi degli artefatti |

---

### 📝 Plugin di generazione dei report (14 strumenti)

| # | Strumento | Descrizione |
|---|---|---|
| 107 | `get_system_time` | Ottiene il timestamp del server (impedisce all'AI di inventare date) |
| 108 | `set_timezone` | Imposta il fuso orario per i report |
| 109 | `get_timezone_info` | Ottiene le informazioni sul fuso orario corrente |
| 110 | `start_report_session` | Avvia una sessione di analisi temporizzata con ID univoco |
| 111 | `end_report_session` | Finalizza la sessione: calcola la durata, blocca le liste IOC/ATT&CK |
| 112 | `get_report_session_status` | Verifica lo stato della sessione |
| 113 | `list_report_sessions` | Elenca tutte le sessioni attive/completate |
| 114 | `add_ioc` | Raccoglie e tagga gli IOC durante una sessione live |
| 115 | `add_analysis_note` | Aggiunge note categorizzate (risultato, avviso, comportamento) |
| 116 | `add_mitre_technique` | Documenta gli ID delle tecniche MITRE ATT&CK |
| 117 | `set_severity` | Imposta la severità della sessione (bassa/media/alta/critica) |
| 118 | `create_analysis_report` | Genera il report in 4 modalità: `full_analysis`, `quick_triage`, `ioc_summary`, `executive_brief` |
| 119 | `generate_vex_report` | Genera un report VEX (Vulnerability Exploitability eXchange) |
| 120 | `generate_sigma_rule` | Genera regole di rilevamento SIGMA |

---

## Prompt di analisi guidata (22 modalità)

I prompt sono flussi di lavoro di analisi predefiniti che preparano l'AI con una persona strutturata, sequenze di utilizzo degli strumenti passo dopo passo e regole di classificazione delle evidenze. Li attivi facendo riferimento al nome del prompt nel tuo client AI.

### Analisi malware (9 prompt)

| Prompt | Caso d'uso |
|---|---|
| `full_analysis_mode` | Analisi completa in 6 fasi: triage → disassemblaggio → comportamento → rete → persistenza → report |
| `malware_analysis_mode` | Analisi malware mirata con classificazione delle minacce |
| `basic_analysis_mode` | Triage rapido per valutazione iniziale e verdetti rapidi |
| `apt_hunting_mode` | Caccia specifica per APT: movimento laterale, persistenza, esfiltrazione dei dati |
| `malware_defense_mode` | Orientato alla difesa: generare regole di rilevamento e mitigazioni |
| `unpacking_mode` | Analizza e aggira packing/offuscamento (Themida, VMProtect, UPX) |
| `c2_extraction_mode` | Estrai e analizza l'infrastruttura di comunicazione C2 |
| `ransomware_triage_mode` | Triage specifico per ransomware: analisi della cifratura, valutazione del recupero delle chiavi |
| `code_similarity_mode` | Confronta i binari per similarità del codice e lignaggio condiviso |

### Ricerca sulla sicurezza (6 prompt)

| Prompt | Caso d'uso |
|---|---|
| `vulnerability_research_mode` | Caccia ai bug: buffer overflow, UAF, command injection |
| `crypto_analysis_mode` | Analisi delle implementazioni crittografiche e rilevamento delle debolezze |
| `firmware_analysis_mode` | Firmware IoT/embedded: estrazione con binwalk, stringhe UART, credenziali hardcoded |
| `patch_analysis_mode` | Analisi delle patch di sicurezza e test di regressione |
| `source_code_audit_mode` | Audit di sicurezza del codice sorgente (Python, C, C++) |
| `autonomous_vuln_hunt_mode` | Pipeline autonoma di caccia alle vulnerabilità |

### Ricerca CVE e sviluppo exploit (5 prompt)

| Prompt | Caso d'uso |
|---|---|
| `taint_analysis_mode` | Analisi del flusso dati con taint: scoperta automatica dei percorsi sorgente→sink |
| `heap_exploit_mode` | Analisi dello sfruttamento dell'heap e generazione di PoC |
| `fuzzing_mode` | Configurazione di campagne di fuzzing e triage dei crash |
| `patch_diff_auto_mode` | Diff automatico delle patch per la ricerca di vulnerabilità 1-day |
| `cve_discovery_pipeline_mode` | Pipeline completa di scoperta CVE: dal diff delle patch all'exploit funzionante |

### Altri (2 prompt)

| Prompt | Caso d'uso |
|---|---|
| `game_analysis_mode` | Analisi dei client di gioco: rilevamento anti-cheat, reverse engineering dei protocolli, ispezione della memoria |
| `report_generation_mode` | Flusso di lavoro di sessione strutturato con mappatura delle tecniche MITRE ATT&CK |

> **Come funzionano i prompt:** Ogni prompt prepara l'AI con una persona di analisi strutturata. Include checkpoint di ragionamento Chain-of-Thought (in cui l'AI deve fermarsi e valutare prima di procedere) e regole di classificazione delle evidenze che impediscono all'AI di presentare speculazioni come fatti. Ogni risultato deve essere etichettato come `OBSERVED` (verificato direttamente), `INFERRED` (derivato logicamente dall'analisi statica) o `POSSIBLE` (richiede ulteriore verifica).

---

## Risorse MCP (11 URI)

Le risorse sono endpoint di dati di sola lettura a cui i client AI possono accedere tramite template URI. Complementano gli strumenti fornendo dati strutturati senza richiedere chiamate esplicite agli strumenti.

### Risorse statiche

| URI | Descrizione |
|---|---|
| `reversecore://guide` | Guida all'uso degli strumenti con regole sui percorsi dei file e best practice |
| `reversecore://guide/structures` | Guida tecnica al recupero delle strutture e all'analisi dei riferimenti incrociati |
| `reversecore://tools` | Documentazione completa per tutti i 120 strumenti registrati |
| `reversecore://logs` | Log dell'applicazione (ultime 100 righe) |

### Risorse dinamiche (filesystem virtuale per binario)

Questi URI vengono risolti per binario e richiamano i corrispondenti strumenti di analisi su richiesta:

| Template URI | Descrizione |
|---|---|
| `reversecore://{filename}/strings` | Estrae tutte le stringhe da un binario |
| `reversecore://{filename}/iocs` | Estrae gli IOC (IP, URL, email, hash) |
| `reversecore://{filename}/func/{address}/code` | Codice pseudo-C decompilato per una funzione |
| `reversecore://{filename}/func/{address}/asm` | Disassemblaggio per una funzione |
| `reversecore://{filename}/func/{address}/cfg` | Grafo di flusso di controllo in formato Mermaid |
| `reversecore://{filename}/functions` | Elenco di tutte le funzioni nel binario |
| `reversecore://{filename}/dormant_detector` | Risultati dell'analisi del dormant detector |

---

## Avvio rapido

### Opzione 1 — PyPI (la più semplice)```bash
pip install reversecore-mcp
reversecore-mcp

### Opzione 3 — Build dal sorgente (Docker Compose)```bash
git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
./scripts/run-docker.sh        # auto-detects Intel / Apple Silicon

### Opzione 4 — Python (Sviluppo Locale)```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

> Sostituisci `reversecore-mcp-arm64` con `reversecore-mcp` se sei su Intel/AMD.

---

### 🌐 Opzione 2: Modalità SSE HTTP

Per lo streaming basato su rete (Server-Sent Events):```json
{
  "mcpServers": {
    "Reversecore_MCP": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

### Test```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

### Hook pre-commit

I seguenti hook vengono eseguiti automaticamente a ogni commit:

1. **Ruff** — lint con correzione automatica + controllo del formato
2. **trailing-whitespace** — rimuove gli spazi bianchi finali
3. **end-of-file-fixer** — garantisce che i file terminino con una nuova riga
4. **check-yaml / check-json** — valida la sintassi YAML/JSON
5. **check-added-large-files** — blocca i file > 1 MB
6. **check-merge-conflict** — rileva i marker di merge non risolti
7. **detect-private-key** — previene il commit accidentale di chiavi
8. **Bandit** — scansione della sicurezza Python

---

## Pipeline CI/CD

Ogni push su `main` attiva 11 job della pipeline. Tutti devono passare prima del deployment.```
 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

Questa immagine viene ricostruita solo quando cambiano le versioni dei tool. Tempo di build: ~12 minuti.

### Layer 2: Immagine dell'applicazione (`Dockerfile`)

Eredita dall'immagine di base e copia il codice dell'applicazione:```
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"]

**Altre directory:**```
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.",
    )

Quindi registralo nel `__init__.py` del plugin appropriato e aggiungi i test in `tests/unit/`.

---

## Come contribuire

1. Fai il fork del repository
2. Crea un branch per la funzionalità: `git checkout -b feat/my-feature`
3. Scrivi i test insieme al codice — la copertura non deve scendere sotto l'80%
4. Assicurati che tutti i gate vengano superati: `pytest`, `ruff check`, `mypy`, `bandit`
5. Apri una pull request con una descrizione chiara

Leggi la [Guida al contributo](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md) per gli standard del codice, le convenzioni per le docstring (stile Google) e la checklist per le pull request.

---

## Documentazione

| Documento | Descrizione |
|---|---|
| [Guida all'installazione](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/getting-started/installation.md) | Configurazione dettagliata per tutti gli ambienti |
| [Guida all'architettura](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/architecture.md) | Dettagli di progettazione del sistema e componenti |
| [Guida al contributo](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md) | Standard del codice, docstring, flusso di lavoro PR |
| [Guida ai test](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/testing.md) | Pattern di test, fixture e copertura |
| [Riferimento API](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/api/) | Riferimento di strumenti e moduli |
| [Guida utente](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/user-guide/) | Flussi di lavoro per l'analisi |

---

## Esempi di utilizzo

### Esempio 1: Triage di base del malware```
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..."

### Esempio 3: Indagine di Digital Forensics```
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

---

## Supporto Multi-Architettura

Il modulo `arch_registry.py` mappa i nomi delle architetture ai parametri di configurazione di Radare2, consentendo agli strumenti di funzionare su diverse architetture CPU senza configurazione manuale:

| Architecture | Key | r2 Arch | Bit Widths | PC Register | SP Register |
|---|---|---|---|---|---|
| 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 risoluzione degli alias** viene gestita automaticamente:
- `amd64` → `x86_64`
- `aarch64` → `arm64`
- `arm` con `bits=64` → `arm64`
- `arm` con `bits=16` o `bits=32` → `arm32`

Strumenti come `Radare2_esil_emulate`, `assemble_instructions` e `r2_simulate_patch` utilizzano questo registro per configurare correttamente l'ambiente di analisi per qualsiasi binario target.

---

## Sistema di Cache dei Risultati

Due livelli di cache riducono al minimo i calcoli ridondanti:

### Cache dei risultati degli strumenti (`result_cache.py`)

Il decoratore `@cache_tool_result` memorizza nella cache l'output di qualsiasi strumento in base a un hash SHA256 del file binario e agli argomenti keyword dello strumento:```
Cache key = SHA256( "<tool_name>::{sorted_json_kwargs}" )

**Storage:** Database SQLite asincrono nel percorso configurato da `MEMORY_DB_PATH` (predefinito: `~/.reversecore_mcp/memory.db`).

**Portabilità:** Usa `export_memory_store` e `import_memory_store` per trasferire l'intero database di memoria tra ambienti.

---

## Dashboard Web

Quando si esegue in modalità HTTP (`MCP_TRANSPORT=http`), una dashboard web è disponibile all'indirizzo `http://localhost:8000/dashboard`. Offre:

- Caricamento binario con trascinamento e rilascio
- Stato dell'analisi in tempo reale
- Elenco interattivo delle funzioni e vista disassembly
- Risultati dell'estrazione degli IOC
- Monitoraggio dello stato del server

**Stack tecnologico:** FastAPI + template Jinja2 + HTMX (caricati localmente da `dashboard/static/`, nessuna dipendenza CDN per conformità CSP).

**Funzionalità di sicurezza:**
- Token CSRF su tutti i moduli che modificano lo stato
- Auto-escaping Jinja2 abilitato
- Tutti gli input utente sanificati tramite `html.escape()` prima della visualizzazione
- Protezione da path traversal tramite `validate_file_path()`

---

## Distribuzione

### Checklist per la produzione

Prima di distribuire in produzione:

| Elemento | Come |
|---|---|
| Imposta la chiave API | `MCP_API_KEY=<strong-random-key>` |
| Usa un utente non root | Integrato: il container viene eseguito come `appuser` (UID 1000) |
| Imposta i limiti di risorse | Predefinito: 2 CPU / 4 GB RAM in `docker-compose.yml` |
| Abilita il logging strutturato | `LOG_FORMAT=json` per l'aggregazione dei log |
| Configura Redis | `REDIS_URL=redis://<host>:6379/0` per la coda di lavoro e la cache |
| Imposta il percorso del workspace | `REVERSECORE_WORKSPACE=/path/to/isolated/directory` |
| Rivedi i limiti di richiesta | `REVERSECORE_RATE_LIMIT=60` (richieste/min, regola secondo necessità) |
| Abilita la sandbox | `REVERSECORE_SANDBOX_ENABLED=true` per l'isolamento dell'analisi dinamica |

### Controlli di salute (Health Check)

Il server fornisce endpoint HTTP per i controlli di salute per l'orchestrazione:```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