El asistente de IA divide esto en llamadas a herramientas:```
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)

The `reversecore_mcp/core/` directory contains the shared infrastructure that all tools build on:

| Module | Purpose |
|---|---|
| `config.py` | Pydantic BaseSettings con 34+ variables de entorno |
| `security.py` | Saneamiento de entrada, validación de argumentos de comando |
| `validators.py` | Validación de rutas de archivos y binarios con mitigación TOCTOU, resolución de enlaces simbólicos |
| `r2_pool.py` | Pool de conexiones Radare2 seguro para subprocesos con tamaño configurable |
| `r2_helpers.py` | Análisis estructurado de salida de Radare2 |
| `metrics.py` | Tiempos de ejecución por herramienta, contadores de llamadas, tasas de error, estadísticas de caché |
| `memory.py` | Almacén de memoria de IA basado en SQLite asíncrono para persistir hallazgos de análisis entre sesiones |
| `mitre_mapper.py` | Motor de mapeo de IDs de técnicas MITRE ATT&CK |
| `evidence.py` | Sistema de clasificación de evidencia: `OBSERVED`, `INFERRED`, `POSSIBLE` |
| `resilience.py` | Patrones de decorador de reintento, circuit-breaker y timeout |
| `task_queue.py` | Cola de tareas en segundo plano mediante Redis + arq |
| `extension_registry.py` | Registro de plugins y gestión del ciclo de vida |
| `arch_registry.py` | Mapeo multiarquitectura (x86, x86_64, ARM32, ARM64, MIPS, RISC-V, PPC → r2 arch/bits/registers) |
| `result_cache.py` | Decorador de caché de resultados de herramientas basado en SHA256 (`@cache_tool_result`) |
| `analysis_cache.py` | Caché de descompilación multinivel (L1: Redis, L2: SQLite) |
| `result.py` | Modelos Pydantic `ToolSuccess` / `ToolError` |
| `exceptions.py` | 17 clases de excepción con códigos de error `RCMCP-E*` |
| `decorators.py` | `@log_execution`, `@track_metrics` |
| `error_handling.py` | Decorador `@handle_tool_errors` |
| `error_formatting.py` | Formato estructurado de respuestas de error |
| `execution.py` | Ejecución segura de subprocesos con timeout y límites de salida |
| `command_spec.py` | Especificación de comandos para llamadas a subprocesos |
| `loader.py` | Cargador dinámico de módulos de herramientas |
| `plugin.py` | Clase base de plugin |
| `extension.py` | Clase base de extensión |
| `container.py` | Soporte de ejecución en contenedor/sandbox |
| `audit.py` | Registro de auditoría |
| `binary_cache.py` | Caché de archivos binarios |
| `json_utils.py` | Serialización JSON mediante orjson (3-5x más rápido que el json de la stdlib) |
| `logging_config.py` | Registro estructurado basado en Loguru |
| `report_generator.py` | Motor de renderizado de informes (Markdown, PDF vía xhtml2pdf) |
| `resource_manager.py` | Gestión del ciclo de vida de recursos MCP |
| `sast/python_ast_scanner.py` | Escáner de vulnerabilidades basado en AST de Python |
| `sast/regex_scanner.py` | Escáner de vulnerabilidades basado en expresiones regulares para C/C++ |
| `sast/rule_manager.py` | Carga y gestión de reglas SAST |

---

## Tool Catalog (120 Tools)

Every tool returns a structured `ToolResult` — either a `ToolSuccess` with typed `data` or a `ToolError` with an `RCMCP-E*` error code. Tools are organized into 8 plugins.

---

### 🔍 Static Analysis Plugin (24 tools)

| # | Tool | Backend | Description |
|---|---|---|---|
| 1 | `run_strings` | `strings` CLI | Extracción de cadenas ASCII/Unicode con longitud mínima configurable |
| 2 | `run_binwalk` | Binwalk | Escaneo profundo de firmware para firmas y sistemas de archivos embebidos |
| 3 | `run_binwalk_extract` | Binwalk | Extraer archivos embebidos descubiertos por binwalk |
| 4 | `parse_binary_with_lief` | LIEF | Análisis completo de cabeceras PE/ELF/Mach-O, secciones, import/export y TLS |
| 5 | `detect_packer` | DIE | Detección rápida de empaquetadores/compiladores |
| 6 | `detect_packer_deep` | DIE (`diec`) | Análisis profundo de empaquetadores/protectores mediante Detect It Easy |
| 7 | `run_capa` | CAPA (Mandiant FLARE) | Detección de capacidades — "encrypts data", "creates persistence", etc. |
| 8 | `run_capa_quick` | CAPA | Escaneo rápido de capacidades con un subconjunto de reglas |
| 9 | `generate_signature` | Radare2 | Generar firmas binarias para identificación |
| 10 | `generate_yara_rule` | Radare2 + YARA | Generar reglas de detección YARA a partir de patrones binarios |
| 11 | `generate_advanced_yara_rule` | Radare2 + YARA | Reglas YARA avanzadas con indicadores de comportamiento |
| 12 | `scan_for_versions` | LIEF + strings | Escanear binarios en busca de cadenas de versión embebidas |
| 13 | `extract_rtti_info` | Radare2 | Extraer RTTI de C++ (Run-Time Type Information) |
| 14 | `diff_binaries` | Radare2 | Diff binario semántico entre dos versiones de archivos |
| 15 | `analyze_variant_changes` | Radare2 | Analizar cambios entre variantes de binarios |
| 16 | `match_libraries` | Radare2 | Identificar bibliotecas enlazadas estáticamente mediante huella de funciones |
| 17 | `patch_diff_1day` | Radare2 + heurísticas | Análisis automatizado de patch diff para investigación de vulnerabilidades 1-day |
| 18 | `analyze_patch_diff_auto` | Radare2 + inferencia | Inferencia automatizada de vulnerabilidades de parches |
| 19 | `emulate_binary` | Radare2 ESIL | Emulación de código con seguimiento de registros/memoria |
| 20 | `generate_fuzzing_harness` | Qiling + AFL++ | Generar un harness de fuzzing dirigido a una función específica |
| 21 | `run_fuzzing_campaign` | AFL++ | Ejecutar una campaña completa de fuzzing con recopilación de crashes |
| 22 | `triage_crash` | GDB | Análisis de crashes y evaluación de explotabilidad |
| 23 | `verify_path_and_get_args` | angr | Ejecución simbólica — demostrar alcanzabilidad de rutas y calcular entradas concretas |
| 24 | `taint_trace` | Radare2 + angr | Análisis de flujo de datos (taint) desde fuentes hasta sumideros |

---

### 🔐 Source Code Audit Plugin (1 tool)

| # | Tool | Backend | Description |
|---|---|---|---|
| 25 | `audit_source_code` | AST + Regex | Escaneo AST de Python + escaneo regex de C/C++ para patrones peligrosos |

---

### 🛠️ Common Utilities Plugin (20 tools)

**File Operations (5 tools)**

| # | Tool | Description |
|---|---|---|
| 26 | `run_file` | Identificación del tipo de archivo, arquitectura y compilador |
| 27 | `copy_to_workspace` | Copiar un archivo al espacio de trabajo de análisis |
| 28 | `create_directory` | Crear un directorio en el espacio de trabajo |
| 29 | `list_workspace` | Listar todos los archivos del espacio de trabajo |
| 30 | `scan_workspace` | Escaneo completo del espacio de trabajo con metadatos de archivos |

**Patch Explanation (1 tool)**

| # | Tool | Description |
|---|---|---|
| 31 | `explain_patch` | Explicar un parche binario en lenguaje natural |

**Assembler (1 tool)**

| # | Tool | Backend | Description |
|---|---|---|---|
| 32 | `assemble_instructions` | Keystone | Ensamblar instrucciones a código máquina (x86, ARM, MIPS, etc.) |

**AI Memory Management (11 tools)**

These tools let the AI persist and recall findings across analysis sessions using an async SQLite database:

| # | Tool | Description |
|---|---|---|
| 33 | `create_memory_session` | Iniciar una nueva sesión de memoria para un análisis |
| 34 | `store_analysis_finding` | Persistir un hallazgo de análisis con etiquetas |
| 35 | `query_analysis_memories` | Buscar hallazgos previos mediante consulta |
| 36 | `get_binary_analysis_context` | Recuperar todo el contexto de un binario específico |
| 37 | `tag_analysis_session` | Añadir etiquetas a una sesión para organización |
| 38 | `search_memories_by_tag` | Encontrar sesiones/hallazgos por etiqueta |
| 39 | `delete_analysis_session` | Eliminar una sesión y sus hallazgos |
| 40 | `cleanup_expired_sessions` | Eliminar sesiones más antiguas que un umbral |
| 41 | `list_analysis_sessions` | Listar todas las sesiones activas |
| 42 | `export_memory_store` | Exportar todas las memorias a un formato portátil |
| 43 | `import_memory_store` | Importar memorias desde un archivo de exportación |

**Server Monitoring (2 tools)**

| # | Tool | Description |
|---|---|---|
| 44 | `get_server_health` | Tiempo de actividad, uso de memoria, herramientas cargadas, versión de Python |
| 45 | `get_tool_metrics` | Contadores de llamadas por herramienta, tiempos medios de ejecución, tasas de error, aciertos/fallos de caché |

---

### ⚙️ Radare2 & r2ghidra Plugin (30 tools)

All Radare2 tools use a thread-safe connection pool (`r2_pool.py`) that automatically manages r2pipe sessions.

| # | Tool | Description |
|---|---|---|
| 46 | `Radare2_open_file` | Abrir un archivo binario en Radare2 |
| 47 | `Radare2_close_file` | Cerrar una sesión de Radare2 |
| 48 | `Radare2_list_open_files` | Listar archivos actualmente abiertos |
| 49 | `Radare2_analyze_binary` | Ejecutar análisis automático completo (`aaa`) |
| 50 | `Radare2_list_functions` | Listar todas las funciones detectadas |
| 51 | `Radare2_disassemble_function` | Desensamblar una función específica |
| 52 | `Radare2_disassemble_address` | Desensamblar en una dirección específica |
| 53 | `Radare2_decompile_function` | Descompilar mediante r2ghidra (motor Ghidra integrado en r2, sin necesidad de JVM) |
| 54 | `Radare2_list_exports` | Listar símbolos exportados |
| 55 | `Radare2_list_imports` | Listar funciones importadas |
| 56 | `Radare2_list_sections` | Listar secciones del binario con entropía |
| 57 | `Radare2_list_strings` | Listar cadenas encontradas en el binario |
| 58 | `Radare2_find_cross_references` | Rastrear llamadas a funciones y referencias a datos |
| 59 | `Radare2_search_bytes` | Buscar patrones de bytes en el binario |
| 60 | `Radare2_get_binary_info` | Obtener metadatos del binario (arquitectura, formato, endianness) |
| 61 | `Radare2_execute_command` | Ejecutar un comando Radare2 sin procesar |
| 62 | `Radare2_esil_emulate` | Emulación ESIL en una dirección específica |
| 63 | `Radare2_get_hexdump` | Volcado hexadecimal en una dirección virtual |
| 64 | `Radare2_get_cfg_data` | Extraer datos del grafo de flujo de control |
| 65 | `Radare2_generate_cfg_png` | Generar CFG como imagen PNG |
| 66 | `Radare2_generate_callgraph` | Generar grafo de llamadas de funciones |
| 67 | `Radare2_recover_structures` | Recuperar automáticamente structs de C y persistirlos en la base de datos de anotaciones |
| 68 | `Radare2_decompile_with_r2ghidra` | Descompilación C de alta calidad con caché |
| 69 | `Radare2_annotate_binary` | Añadir anotaciones al binario |
| 70 | `Radare2_get_annotations` | Recuperar anotaciones |
| 71 | `Radare2_export_annotations` | Exportar anotaciones a un archivo |
| 72 | `Radare2_import_annotations` | Importar anotaciones desde un archivo |
| 73 | `Radare2_detect_crypto_constants` | Detectar constantes criptográficas (AES S-box, etc.) |
| 74 | `Radare2_find_gadgets` | Encontrar gadgets ROP/JOP |
| 75 | `Radare2_calculate_entropy` | Calcular entropía por sección |

---

### 🦠 Malware Analysis Plugin (9 tools)

| # | Tool | Backend | Description |
|---|---|---|---|
| 76 | `dormant_detector` | Radare2 + heurísticas | Encontrar backdoors ocultos, funciones huérfanas, bombas de tiempo y bombas lógicas |
| 77 | `adaptive_vaccine` | YARA + Radare2 | Generar reglas YARA de detección + parches binarios para neutralizar amenazas |
| 78 | `vulnerability_hunter` | Radare2 + análisis | Detectar patrones de API peligrosos (strcpy, sprintf) y cadenas de gadgets ROP |
| 79 | `extract_iocs` | Regex + LIEF | Extraer IPs, URLs, dominios, hashes, claves de registro y direcciones de criptomonedas |
| 80 | `run_yara` | YARA | Escanear con archivos de reglas personalizados y conjuntos de reglas integrados |
| 81 | `generate_poc_exploit` | pwntools | Generar código de exploit de prueba de concepto |
| 82 | `build_rop_chain` | ROPgadget + pwntools | Construcción automatizada de cadenas ROP |
| 83 | `autonomous_vuln_hunt` | Radare2 + angr | Pipeline autónomo de búsqueda de vulnerabilidades |
| 84 | `analyze_heap_exploit` | Radare2 + heurísticas | Análisis de explotación de heap (UAF, double-free, overflow) |

---

### 🕵️ Digital Forensics Plugin (22 tools)

**Memory Forensics (6 tools)**

| # | Tool | Backend | Description |
|---|---|---|---|
| 85 | `memory_analyze` | Volatility3 | Análisis completo de volcados de memoria |
| 86 | `memory_list_processes` | Volatility3 | Listar procesos en ejecución desde el volcado de memoria |
| 87 | `memory_detect_injections` | Volatility3 | Detectar inyección de código en la memoria de procesos |
| 88 | `memory_extract_strings` | Volatility3 | Extraer cadenas de la memoria de procesos |
| 89 | `memory_dump_module` | Volatility3 | Volcar un módulo cargado desde la memoria |
| 90 | `memory_list_symbols` | Volatility3 | Listar símbolos desde la memoria |

**Disk Forensics (6 tools)**

| # | Tool | Backend | Description |
|---|---|---|---|
| 91 | `disk_list_partition` | Sleuth Kit | Listar particiones de disco |
| 92 | `disk_list_files` | Sleuth Kit | Listar archivos en una imagen de disco |
| 93 | `disk_recover_deleted` | Sleuth Kit | Recuperar archivos eliminados |
| 94 | `disk_analyze_mft` | Sleuth Kit | Analizar la Master File Table de NTFS |
| 95 | `disk_extract_file` | Sleuth Kit | Extraer un archivo de la imagen de disco |
| 96 | `disk_hash_verify` | Sleuth Kit | Verificar la integridad de archivos mediante hash |

**Network Forensics (5 tools)**

| # | Tool | Backend | Description |
|---|---|---|---|
| 97 | `pcap_analyze` | Scapy | Análisis de PCAP: desglose de protocolos, anomalías |
| 98 | `pcap_list_connections` | Scapy | Listar todas las conexiones de red |
| 99 | `pcap_extract_dns` | Scapy | Extraer consultas y respuestas DNS |
| 100 | `pcap_extract_c2` | Scapy | Identificar comunicación C2 potencial |
| 101 | `pcap_reconstruct_stream` | Scapy | Reconstruir flujos TCP |

**Artifact Analysis (5 tools)**

| # | Tool | Backend | Description |
|---|---|---|---|
| 102 | `artifact_collect` | Parsers personalizados | Recopilar historial del navegador, colmenas de registro, registros de eventos y prefetch |
| 103 | `artifact_correlate_ioc` | Parsers personalizados | Correlacionar artefactos con IOCs conocidos |
| 104 | `artifact_generate_yara` | YARA | Generar reglas YARA a partir de patrones de artefactos |
| 105 | `artifact_timeline` | Parsers personalizados | Construir línea de tiempo a partir de múltiples fuentes de artefactos |
| 106 | `artifact_report` | Parsers personalizados | Generar informe de análisis de artefactos |

---

### 📝 Report Generation Plugin (14 tools)

| # | Tool | Description |
|---|---|---|
| 107 | `get_system_time` | Obtener la marca de tiempo del servidor (evita que la IA alucine fechas) |
| 108 | `set_timezone` | Establecer la zona horaria para los informes |
| 109 | `get_timezone_info` | Obtener información de la zona horaria actual |
| 110 | `start_report_session` | Iniciar una sesión de análisis cronometrada con ID único |
| 111 | `end_report_session` | Finalizar la sesión: calcular duración, bloquear listas de IOC/ATT&CK |
| 112 | `get_report_session_status` | Comprobar el estado de la sesión |
| 113 | `list_report_sessions` | Listar todas las sesiones activas/completadas |
| 114 | `add_ioc` | Recopilar y etiquetar IOCs durante una sesión en vivo |
| 115 | `add_analysis_note` | Añadir notas categorizadas (hallazgo, advertencia, comportamiento) |
| 116 | `add_mitre_technique` | Documentar IDs de técnicas MITRE ATT&CK |
| 117 | `set_severity` | Establecer la severidad de la sesión (baja/media/alta/crítica) |
| 118 | `create_analysis_report` | Renderizar informe en 4 modos: `full_analysis`, `quick_triage`, `ioc_summary`, `executive_brief` |
| 119 | `generate_vex_report` | Generar un informe VEX (Vulnerability Exploitability eXchange) |
| 120 | `generate_sigma_rule` | Generar reglas de detección SIGMA |

---

## Guided Analysis Prompts (22 Modes)

Prompts are pre-built analysis workflows that prime the AI with a structured persona, step-by-step tool usage sequences, and evidence classification rules. You activate them by referencing the prompt name in your AI client.

### Malware Analysis (9 prompts)

| Prompt | Use Case |
|---|---|
| `full_analysis_mode` | Análisis integral en 6 fases: triage → desensamblado → comportamiento → red → persistencia → informe |
| `malware_analysis_mode` | Análisis de malware enfocado con clasificación de amenazas |
| `basic_analysis_mode` | Triage rápido para evaluación inicial y veredictos rápidos |
| `apt_hunting_mode` | Búsqueda específica de APT: movimiento lateral, persistencia, exfiltración de datos |
| `malware_defense_mode` | Orientado a la defensa: generar reglas de detección y mitigaciones |
| `unpacking_mode` | Analizar y evadir empaquetado/ofuscación (Themida, VMProtect, UPX) |
| `c2_extraction_mode` | Extraer y analizar infraestructura de comunicación C2 |
| `ransomware_triage_mode` | Triage específico de ransomware: análisis de cifrado, evaluación de recuperación de claves |
| `code_similarity_mode` | Comparar binarios para similitud de código y linaje compartido |

### Security Research (6 prompts)

| Prompt | Use Case |
|---|---|
| `vulnerability_research_mode` | Caza de bugs: desbordamientos de búfer, UAF, inyección de comandos |
| `crypto_analysis_mode` | Análisis de implementaciones criptográficas y detección de debilidades |
| `firmware_analysis_mode` | Firmware IoT/embebido: extracción con binwalk, cadenas UART, credenciales hardcodeadas |
| `patch_analysis_mode` | Análisis de parches de seguridad y pruebas de regresión |
| `source_code_audit_mode` | Auditoría de seguridad de código fuente (Python, C, C++) |
| `autonomous_vuln_hunt_mode` | Pipeline autónomo de búsqueda de vulnerabilidades |

### CVE Research & Exploit Development (5 prompts)

| Prompt | Use Case |
|---|---|
| `taint_analysis_mode` | Análisis de flujo de datos (taint): descubrimiento automatizado de rutas fuente→sumidero |
| `heap_exploit_mode` | Análisis de explotación de heap y generación de PoC |
| `fuzzing_mode` | Configuración de campañas de fuzzing y triage de crashes |
| `patch_diff_auto_mode` | Patch diff automatizado para investigación de vulnerabilidades 1-day |
| `cve_discovery_pipeline_mode` | Pipeline completo de descubrimiento de CVE: desde patch diff hasta exploit funcional |

### Other (2 prompts)

| Prompt | Use Case |
|---|---|
| `game_analysis_mode` | Análisis de clientes de juegos: detección de anti-cheat, RE de protocolos, inspección de memoria |
| `report_generation_mode` | Flujo de trabajo de sesión estructurado con mapeo de técnicas MITRE ATT&CK |

> **How prompts work:** Each prompt primes the AI with a structured analysis persona. It includes Chain-of-Thought reasoning checkpoints (where the AI must stop and evaluate before proceeding) and evidence classification rules that prevent the AI from stating speculation as fact. Every finding must be labeled as `OBSERVED` (directly verified), `INFERRED` (logically derived from static analysis), or `POSSIBLE` (requires further verification).

---

## MCP Resources (11 URIs)

Resources are read-only data endpoints that AI clients can access through URI templates. They complement tools by providing structured data without requiring explicit tool calls.

### Static Resources

| URI | Description |
|---|---|
| `reversecore://guide` | Guía de uso de herramientas con reglas de rutas de archivos y mejores prácticas |
| `reversecore://guide/structures` | Guía técnica de recuperación de estructuras y análisis de referencias cruzadas |
| `reversecore://tools` | Documentación completa de las 120 herramientas registradas |
| `reversecore://logs` | Registros de la aplicación (últimas 100 líneas) |

### Dynamic Resources (Per-Binary Virtual Filesystem)

These URIs resolve per-binary and invoke the corresponding analysis tools on demand:

| URI Template | Description |
|---|---|
| `reversecore://{filename}/strings` | Extraer todas las cadenas de un binario |
| `reversecore://{filename}/iocs` | Extraer IOCs (IPs, URLs, correos electrónicos, hashes) |
| `reversecore://{filename}/func/{address}/code` | Código pseudo-C descompilado para una función |
| `reversecore://{filename}/func/{address}/asm` | Desensamblado de una función |
| `reversecore://{filename}/func/{address}/cfg` | Grafo de flujo de control en formato Mermaid |
| `reversecore://{filename}/functions` | Lista de todas las funciones del binario |
| `reversecore://{filename}/dormant_detector` | Resultados del análisis de Dormant detector |

---

## Quick Start

### Option 1 — PyPI (Simplest)```bash
pip install reversecore-mcp
reversecore-mcp

### Opción 3 — Compilar desde el código fuente (Docker Compose)```bash
git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
./scripts/run-docker.sh        # auto-detects Intel / Apple Silicon

### Opción 4 — Python (Desarrollo 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

> Reemplaza `reversecore-mcp-arm64` por `reversecore-mcp` si estás en Intel/AMD.

---

### 🌐 Opción 2: Modo HTTP SSE

Para transmisión por red (Server-Sent Events):```json
{
  "mcpServers": {
    "Reversecore_MCP": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

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

Los siguientes hooks se ejecutan automáticamente en cada commit:

1. **Ruff** — lint con auto-corrección + comprobación de formato
2. **trailing-whitespace** — elimina los espacios en blanco al final
3. **end-of-file-fixer** — garantiza que los archivos terminen con una nueva línea
4. **check-yaml / check-json** — valida la sintaxis de YAML/JSON
5. **check-added-large-files** — bloquea archivos de más de 1 MB
6. **check-merge-conflict** — detecta marcadores de merge sin resolver
7. **detect-private-key** — evita commits accidentales de claves
8. **Bandit** — escaneo de seguridad de Python

---

## Pipeline de CI/CD

Cada push a `main` activa 11 trabajos del pipeline. Todos deben pasar antes del despliegue.```
 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

Esta imagen se reconstruye solo cuando cambian las versiones de las herramientas. Tiempo de compilación: ~12 minutos.

### Capa 2: Imagen de aplicación (`Dockerfile`)

Hereda de la imagen base y copia el código de la aplicación:```
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"]

**Otros directorios:**```
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.",
    )

Luego regístralo en el `__init__.py` del plugin correspondiente y añade pruebas en `tests/unit/`.

---

## Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de características: `git checkout -b feat/my-feature`
3. Escribe pruebas junto con tu código: la cobertura no debe bajar del 80%
4. Asegúrate de que todas las verificaciones pasen: `pytest`, `ruff check`, `mypy`, `bandit`
5. Abre un pull request con una descripción clara

Por favor, lee la [Guía de Contribución](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md) para conocer los estándares de código, las convenciones de docstrings (estilo Google) y la lista de verificación para pull requests.

---

## Documentación

| Documento | Descripción |
|---|---|
| [Guía de Instalación](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/getting-started/installation.md) | Configuración detallada para todos los entornos |
| [Guía de Arquitectura](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/architecture.md) | Diseño del sistema y detalles de componentes |
| [Guía de Contribución](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md) | Estándares de código, docstrings, flujo de trabajo de PR |
| [Guía de Pruebas](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/testing.md) | Patrones de prueba, fixtures y cobertura |
| [Referencia de la API](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/api/) | Referencia de herramientas y módulos |
| [Guía de Usuario](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/user-guide/) | Flujos de trabajo de análisis |

---

## Ejemplos de Uso

### Ejemplo 1: Triaje básico de 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..."

### Ejemplo 3: Investigación Forense Digital```
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

---

## Soporte Multi-Arquitectura

El módulo `arch_registry.py` asigna nombres de arquitectura a parámetros de configuración de Radare2, lo que permite que las herramientas funcionen en distintas arquitecturas de CPU sin configuración manual:

| 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 resolución de alias** se maneja automáticamente:
- `amd64` → `x86_64`
- `aarch64` → `arm64`
- `arm` con `bits=64` → `arm64`
- `arm` con `bits=16` o `bits=32` → `arm32`

Herramientas como `Radare2_esil_emulate`, `assemble_instructions` y `r2_simulate_patch` usan este registro para configurar correctamente el entorno de análisis para cualquier binario objetivo.

---

## Sistema de caché de resultados

Dos capas de caché minimizan el cálculo redundante:

### Caché de resultados de herramientas (`result_cache.py`)

El decorador `@cache_tool_result` almacena en caché la salida de cualquier herramienta basándose en un hash SHA256 del archivo binario y los argumentos de palabra clave de la herramienta:```
Cache key = SHA256( "<tool_name>::{sorted_json_kwargs}" )

**Almacenamiento:** Base de datos SQLite asíncrona en la ruta configurada por `MEMORY_DB_PATH` (por defecto: `~/.reversecore_mcp/memory.db`).

**Portabilidad:** Use `export_memory_store` e `import_memory_store` para transferir la base de datos de memoria completa entre entornos.

---

## Panel web

Cuando se ejecuta en modo HTTP (`MCP_TRANSPORT=http`), hay un panel web disponible en `http://localhost:8000/dashboard`. Proporciona:

- Subida de binarios con arrastrar y soltar
- Estado del análisis en tiempo real
- Lista de funciones interactiva y vista de desensamblado
- Resultados de extracción de IOC
- Monitorización del estado del servidor

**Stack tecnológico:** FastAPI + plantillas Jinja2 + HTMX (cargado localmente desde `dashboard/static/`, sin dependencia de CDN para cumplir con CSP).

**Características de seguridad:**
- Tokens CSRF en todos los formularios que cambian el estado
- Autoescapado de Jinja2 habilitado
- Toda la entrada del usuario se sanitiza mediante `html.escape()` antes de mostrarse
- Protección contra path traversal mediante `validate_file_path()`

---

## Despliegue

### Lista de comprobación para producción

Antes de desplegar en producción:

| Elemento | Cómo |
|---|---|
| Establecer clave de API | `MCP_API_KEY=<strong-random-key>` |
| Usar usuario no root | Integrado: el contenedor se ejecuta como `appuser` (UID 1000) |
| Establecer límites de recursos | Por defecto: 2 CPU / 4 GB de RAM en `docker-compose.yml` |
| Habilitar registro estructurado | `LOG_FORMAT=json` para agregación de registros |
| Configurar Redis | `REDIS_URL=redis://<host>:6379/0` para cola de tareas y caché |
| Establecer ruta del espacio de trabajo | `REVERSECORE_WORKSPACE=/path/to/isolated/directory` |
| Revisar límites de tasa | `REVERSECORE_RATE_LIMIT=60` (peticiones/min, ajuste según sea necesario) |
| Habilitar sandbox | `REVERSECORE_SANDBOX_ENABLED=true` para aislamiento del análisis dinámico |

### Comprobaciones de estado

El servidor proporciona endpoints HTTP de comprobación de estado para la orquestación:```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