O assistente de IA divide isto em chamadas de ferramentas:```
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 módulos)

O diretório `reversecore_mcp/core/` contém a infraestrutura compartilhada sobre a qual todas as ferramentas são construídas:

| Módulo | Finalidade |
|---|---|
| `config.py` | Pydantic BaseSettings com 34+ variáveis de ambiente |
| `security.py` | Sanitização de entrada, validação de argumentos de comando |
| `validators.py` | Validação de caminhos de arquivo e binário com mitigação TOCTOU, resolução de symlinks |
| `r2_pool.py` | Pool de conexões Radare2 thread-safe com tamanho configurável |
| `r2_helpers.py` | Análise estruturada de saída do Radare2 |
| `metrics.py` | Tempos de execução por ferramenta, contagens de chamadas, taxas de erro, estatísticas de cache |
| `memory.py` | Armazenamento de memória de IA baseado em SQLite assíncrono para persistir descobertas de análise entre sessões |
| `mitre_mapper.py` | Mecanismo de mapeamento de IDs de técnicas MITRE ATT&CK |
| `evidence.py` | Sistema de classificação de evidências: `OBSERVED`, `INFERRED`, `POSSIBLE` |
| `resilience.py` | Padrões de decoradores de retry, circuit-breaker e timeout |
| `task_queue.py` | Fila de tarefas em segundo plano via Redis + arq |
| `extension_registry.py` | Registro de plugins e gerenciamento de ciclo de vida |
| `arch_registry.py` | Mapeamento multi-arquitetura (x86, x86_64, ARM32, ARM64, MIPS, RISC-V, PPC → arch/bits/registradores do r2) |
| `result_cache.py` | Decorador de cache de resultados de ferramentas baseado em SHA256 (`@cache_tool_result`) |
| `analysis_cache.py` | Cache de descompilação em vários níveis (L1: Redis, L2: SQLite) |
| `result.py` | Modelos Pydantic `ToolSuccess` / `ToolError` |
| `exceptions.py` | 17 classes de exceção com códigos de erro `RCMCP-E*` |
| `decorators.py` | `@log_execution`, `@track_metrics` |
| `error_handling.py` | Decorador `@handle_tool_errors` |
| `error_formatting.py` | Formatação estruturada de respostas de erro |
| `execution.py` | Execução segura de subprocessos com timeout e limites de saída |
| `command_spec.py` | Especificação de comandos para chamadas de subprocesso |
| `loader.py` | Carregador dinâmico de módulos de ferramentas |
| `plugin.py` | Classe base de plugin |
| `extension.py` | Classe base de extensão |
| `container.py` | Suporte à execução em container/sandbox |
| `audit.py` | Registro de auditoria |
| `binary_cache.py` | Cache de arquivos binários |
| `json_utils.py` | Serialização JSON via orjson (3-5x mais rápida que o json da stdlib) |
| `logging_config.py` | Registro estruturado baseado em Loguru |
| `report_generator.py` | Mecanismo de renderização de relatórios (Markdown, PDF via xhtml2pdf) |
| `resource_manager.py` | Gerenciamento do ciclo de vida de recursos MCP |
| `sast/python_ast_scanner.py` | Scanner de vulnerabilidades baseado em AST Python |
| `sast/regex_scanner.py` | Scanner de vulnerabilidades baseado em regex para C/C++ |
| `sast/rule_manager.py` | Carregamento e gerenciamento de regras SAST |

---

## Catálogo de Ferramentas (120 ferramentas)

Cada ferramenta retorna um `ToolResult` estruturado — seja um `ToolSuccess` com `data` tipado ou um `ToolError` com um código de erro `RCMCP-E*`. As ferramentas estão organizadas em 8 plugins.

---

### 🔍 Plugin de Análise Estática (24 ferramentas)

| # | Ferramenta | Backend | Descrição |
|---|---|---|---|
| 1 | `run_strings` | `strings` CLI | Extração de strings ASCII/Unicode com comprimento mínimo configurável |
| 2 | `run_binwalk` | Binwalk | Varredura profunda de firmware em busca de assinaturas e sistemas de arquivos embutidos |
| 3 | `run_binwalk_extract` | Binwalk | Extrai arquivos embutidos descobertos pelo binwalk |
| 4 | `parse_binary_with_lief` | LIEF | Análise completa de cabeçalho, seções, imports/exports e TLS de PE/ELF/Mach-O |
| 5 | `detect_packer` | DIE | Detecção rápida de packer/compilador |
| 6 | `detect_packer_deep` | DIE (`diec`) | Análise profunda de packer/protetor via Detect It Easy |
| 7 | `run_capa` | CAPA (Mandiant FLARE) | Detecção de capacidades — "criptografa dados", "cria persistência", etc. |
| 8 | `run_capa_quick` | CAPA | Varredura rápida de capacidades com um subconjunto de regras |
| 9 | `generate_signature` | Radare2 | Gera assinaturas de binário para identificação |
| 10 | `generate_yara_rule` | Radare2 + YARA | Gera regras de detecção YARA a partir de padrões de binário |
| 11 | `generate_advanced_yara_rule` | Radare2 + YARA | Regras YARA avançadas com indicadores comportamentais |
| 12 | `scan_for_versions` | LIEF + strings | Varre o binário em busca de strings de versão embutidas |
| 13 | `extract_rtti_info` | Radare2 | Extrai RTTI de C++ (Run-Time Type Information) |
| 14 | `diff_binaries` | Radare2 | Diff semântico de binários entre duas versões de arquivo |
| 15 | `analyze_variant_changes` | Radare2 | Analisa alterações entre variantes de binário |
| 16 | `match_libraries` | Radare2 | Identifica bibliotecas vinculadas estaticamente por impressão digital de função |
| 17 | `patch_diff_1day` | Radare2 + heurísticas | Análise automatizada de diff de patches para pesquisa de vulnerabilidades 1-day |
| 18 | `analyze_patch_diff_auto` | Radare2 + inferência | Inferência automatizada de vulnerabilidades em patches |
| 19 | `emulate_binary` | Radare2 ESIL | Emulação de código com rastreamento de registradores/memória |
| 20 | `generate_fuzzing_harness` | Qiling + AFL++ | Gera um harness de fuzzing direcionado a uma função específica |
| 21 | `run_fuzzing_campaign` | AFL++ | Executa uma campanha completa de fuzzing com coleta de crashes |
| 22 | `triage_crash` | GDB | Análise de crashes e avaliação de explorabilidade |
| 23 | `verify_path_and_get_args` | angr | Execução simbólica — prova a alcançabilidade de caminhos e calcula entradas concretas |
| 24 | `taint_trace` | Radare2 + angr | Análise de taint no fluxo de dados de fontes para sumidouros (sinks) |

---

### 🔐 Plugin de Auditoria de Código-Fonte (1 ferramenta)

| # | Ferramenta | Backend | Descrição |
|---|---|---|---|
| 25 | `audit_source_code` | AST + Regex | Varredura AST Python + varredura regex C/C++ para padrões perigosos |

---

### 🛠️ Plugin de Utilitários Comuns (20 ferramentas)

**Operações de Arquivo (5 ferramentas)**

| # | Ferramenta | Descrição |
|---|---|---|
| 26 | `run_file` | Identificação de tipo de arquivo, arquitetura e compilador |
| 27 | `copy_to_workspace` | Copia um arquivo para o espaço de trabalho de análise |
| 28 | `create_directory` | Cria um diretório no espaço de trabalho |
| 29 | `list_workspace` | Lista todos os arquivos no espaço de trabalho |
| 30 | `scan_workspace` | Varredura completa do espaço de trabalho com metadados de arquivos |

**Explicação de Patches (1 ferramenta)**

| # | Ferramenta | Descrição |
|---|---|---|
| 31 | `explain_patch` | Explica um patch de binário em linguagem natural |

**Montador (1 ferramenta)**

| # | Ferramenta | Backend | Descrição |
|---|---|---|---|
| 32 | `assemble_instructions` | Keystone | Monta instruções em código de máquina (x86, ARM, MIPS, etc.) |

**Gerenciamento de Memória de IA (11 ferramentas)**

Estas ferramentas permitem que a IA persista e recupere descobertas entre sessões de análise usando um banco de dados SQLite assíncrono:

| # | Ferramenta | Descrição |
|---|---|---|
| 33 | `create_memory_session` | Inicia uma nova sessão de memória para uma análise |
| 34 | `store_analysis_finding` | Persiste uma descoberta de análise com tags |
| 35 | `query_analysis_memories` | Busca descobertas passadas por consulta |
| 36 | `get_binary_analysis_context` | Recupera todo o contexto de um binário específico |
| 37 | `tag_analysis_session` | Adiciona tags a uma sessão para organização |
| 38 | `search_memories_by_tag` | Encontra sessões/descobertas por tag |
| 39 | `delete_analysis_session` | Remove uma sessão e suas descobertas |
| 40 | `cleanup_expired_sessions` | Remove sessões mais antigas que um limite |
| 41 | `list_analysis_sessions` | Lista todas as sessões ativas |
| 42 | `export_memory_store` | Exporta todas as memórias para um formato portátil |
| 43 | `import_memory_store` | Importa memórias de um arquivo de exportação |

**Monitoramento de Servidor (2 ferramentas)**

| # | Ferramenta | Descrição |
|---|---|---|
| 44 | `get_server_health` | Tempo de atividade, uso de memória, ferramentas carregadas, versão do Python |
| 45 | `get_tool_metrics` | Contagens de chamadas por ferramenta, tempos médios de execução, taxas de erro, acertos/erros de cache |

---

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

Todas as ferramentas Radare2 usam um pool de conexões thread-safe (`r2_pool.py`) que gerencia automaticamente as sessões r2pipe.

| # | Ferramenta | Descrição |
|---|---|---|
| 46 | `Radare2_open_file` | Abre um arquivo binário no Radare2 |
| 47 | `Radare2_close_file` | Fecha uma sessão do Radare2 |
| 48 | `Radare2_list_open_files` | Lista arquivos atualmente abertos |
| 49 | `Radare2_analyze_binary` | Executa análise automática completa (`aaa`) |
| 50 | `Radare2_list_functions` | Lista todas as funções detectadas |
| 51 | `Radare2_disassemble_function` | Desmonta uma função específica |
| 52 | `Radare2_disassemble_address` | Desmonta em um endereço específico |
| 53 | `Radare2_decompile_function` | Descompila via r2ghidra (mecanismo Ghidra embutido no r2, sem necessidade de JVM) |
| 54 | `Radare2_list_exports` | Lista símbolos exportados |
| 55 | `Radare2_list_imports` | Lista funções importadas |
| 56 | `Radare2_list_sections` | Lista seções do binário com entropia |
| 57 | `Radare2_list_strings` | Lista strings encontradas no binário |
| 58 | `Radare2_find_cross_references` | Rastreia chamadas de função e referências de dados |
| 59 | `Radare2_search_bytes` | Busca padrões de bytes no binário |
| 60 | `Radare2_get_binary_info` | Obtém metadados do binário (arch, formato, endianness) |
| 61 | `Radare2_execute_command` | Executa um comando Radare2 bruto |
| 62 | `Radare2_esil_emulate` | Emulação ESIL em um endereço específico |
| 63 | `Radare2_get_hexdump` | Hex dump em um endereço virtual |
| 64 | `Radare2_get_cfg_data` | Extrai dados do grafo de fluxo de controle |
| 65 | `Radare2_generate_cfg_png` | Gera o CFG como imagem PNG |
| 66 | `Radare2_generate_callgraph` | Gera grafo de chamadas de funções |
| 67 | `Radare2_recover_structures` | Recupera automaticamente structs C e persiste no banco de dados de anotações |
| 68 | `Radare2_decompile_with_r2ghidra` | Descompilação C de alta qualidade com cache |
| 69 | `Radare2_annotate_binary` | Adiciona anotações ao binário |
| 70 | `Radare2_get_annotations` | Recupera anotações |
| 71 | `Radare2_export_annotations` | Exporta anotações para arquivo |
| 72 | `Radare2_import_annotations` | Importa anotações de arquivo |
| 73 | `Radare2_detect_crypto_constants` | Detecta constantes criptográficas (S-box AES, etc.) |
| 74 | `Radare2_find_gadgets` | Encontra gadgets ROP/JOP |
| 75 | `Radare2_calculate_entropy` | Calcula entropia por seção |

---

### 🦠 Plugin de Análise de Malware (9 ferramentas)

| # | Ferramenta | Backend | Descrição |
|---|---|---|---|
| 76 | `dormant_detector` | Radare2 + heurísticas | Encontra backdoors ocultos, funções órfãs, time-bombs, logic bombs |
| 77 | `adaptive_vaccine` | YARA + Radare2 | Gera regras YARA de detecção + patches de binário para neutralizar ameaças |
| 78 | `vulnerability_hunter` | Radare2 + análise | Detecta padrões perigosos de API (strcpy, sprintf) e cadeias de gadgets ROP |
| 79 | `extract_iocs` | Regex + LIEF | Extrai IPs, URLs, domínios, hashes, chaves de registro, endereços de criptomoedas |
| 80 | `run_yara` | YARA | Varre com arquivos de regras personalizados e conjuntos de regras integrados |
| 81 | `generate_poc_exploit` | pwntools | Gera código de exploit proof-of-concept |
| 82 | `build_rop_chain` | ROPgadget + pwntools | Construção automatizada de cadeias ROP |
| 83 | `autonomous_vuln_hunt` | Radare2 + angr | Pipeline autônomo de caça a vulnerabilidades |
| 84 | `analyze_heap_exploit` | Radare2 + heurísticas | Análise de exploração de heap (UAF, double-free, overflow) |

---

### 🕵️ Plugin de Perícia Digital (22 ferramentas)

**Perícia de Memória (6 ferramentas)**

| # | Ferramenta | Backend | Descrição |
|---|---|---|---|
| 85 | `memory_analyze` | Volatility3 | Análise completa de dump de memória |
| 86 | `memory_list_processes` | Volatility3 | Lista processos em execução a partir do dump de memória |
| 87 | `memory_detect_injections` | Volatility3 | Detecta injeção de código na memória de processos |
| 88 | `memory_extract_strings` | Volatility3 | Extrai strings da memória de processos |
| 89 | `memory_dump_module` | Volatility3 | Despeja um módulo carregado da memória |
| 90 | `memory_list_symbols` | Volatility3 | Lista símbolos da memória |

**Perícia de Disco (6 ferramentas)**

| # | Ferramenta | Backend | Descrição |
|---|---|---|---|
| 91 | `disk_list_partition` | Sleuth Kit | Lista partições de disco |
| 92 | `disk_list_files` | Sleuth Kit | Lista arquivos em uma imagem de disco |
| 93 | `disk_recover_deleted` | Sleuth Kit | Recupera arquivos excluídos |
| 94 | `disk_analyze_mft` | Sleuth Kit | Analisa a Master File Table do NTFS |
| 95 | `disk_extract_file` | Sleuth Kit | Extrai um arquivo de imagem de disco |
| 96 | `disk_hash_verify` | Sleuth Kit | Verifica a integridade do arquivo via hash |

**Perícia de Rede (5 ferramentas)**

| # | Ferramenta | Backend | Descrição |
|---|---|---|---|
| 97 | `pcap_analyze` | Scapy | Análise de PCAP: detalhamento de protocolos, anomalias |
| 98 | `pcap_list_connections` | Scapy | Lista todas as conexões de rede |
| 99 | `pcap_extract_dns` | Scapy | Extrai consultas e respostas DNS |
| 100 | `pcap_extract_c2` | Scapy | Identifica comunicação C2 potencial |
| 101 | `pcap_reconstruct_stream` | Scapy | Reconstrói fluxos TCP |

**Análise de Artefatos (5 ferramentas)**

| # | Ferramenta | Backend | Descrição |
|---|---|---|---|
| 102 | `artifact_collect` | Parsers personalizados | Coleta histórico de navegador, hives de registro, logs de eventos, prefetch |
| 103 | `artifact_correlate_ioc` | Parsers personalizados | Correlaciona artefatos com IOCs conhecidos |
| 104 | `artifact_generate_yara` | YARA | Gera regras YARA a partir de padrões de artefatos |
| 105 | `artifact_timeline` | Parsers personalizados | Constrói linha do tempo a partir de múltiplas fontes de artefatos |
| 106 | `artifact_report` | Parsers personalizados | Gera relatório de análise de artefatos |

---

### 📝 Plugin de Geração de Relatórios (14 ferramentas)

| # | Ferramenta | Descrição |
|---|---|---|
| 107 | `get_system_time` | Obtém o timestamp do servidor (impede que a IA alucine datas) |
| 108 | `set_timezone` | Define o fuso horário do relatório |
| 109 | `get_timezone_info` | Obtém informações do fuso horário atual |
| 110 | `start_report_session` | Inicia uma sessão de análise cronometrada com ID exclusivo |
| 111 | `end_report_session` | Finaliza a sessão: calcula a duração, bloqueia listas de IOC/ATT&CK |
| 112 | `get_report_session_status` | Verifica o status da sessão |
| 113 | `list_report_sessions` | Lista todas as sessões ativas/concluídas |
| 114 | `add_ioc` | Coleta e etiqueta IOCs durante uma sessão ativa |
| 115 | `add_analysis_note` | Adiciona notas categorizadas (descoberta, aviso, comportamento) |
| 116 | `add_mitre_technique` | Documenta IDs de técnicas MITRE ATT&CK |
| 117 | `set_severity` | Define a gravidade da sessão (baixa/média/alta/crítica) |
| 118 | `create_analysis_report` | Renderiza o relatório em 4 modos: `full_analysis`, `quick_triage`, `ioc_summary`, `executive_brief` |
| 119 | `generate_vex_report` | Gera um relatório VEX (Vulnerability Exploitability eXchange) |
| 120 | `generate_sigma_rule` | Gera regras de detecção SIGMA |

---

## Prompts de Análise Guiada (22 modos)

Os prompts são fluxos de trabalho de análise pré-construídos que preparam a IA com uma persona estruturada, sequências de uso de ferramentas passo a passo e regras de classificação de evidências. Você os ativa referenciando o nome do prompt no seu cliente de IA.

### Análise de Malware (9 prompts)

| Prompt | Caso de uso |
|---|---|
| `full_analysis_mode` | Análise abrangente em 6 fases: triagem → desmontagem → comportamento → rede → persistência → relatório |
| `malware_analysis_mode` | Análise focada de malware com classificação de ameaças |
| `basic_analysis_mode` | Triagem rápida para avaliação inicial e veredictos rápidos |
| `apt_hunting_mode` | Caça específica a APTs: movimento lateral, persistência, exfiltração de dados |
| `malware_defense_mode` | Orientado à defesa: gera regras de detecção e mitigações |
| `unpacking_mode` | Analisa e contorna packing/ofuscação (Themida, VMProtect, UPX) |
| `c2_extraction_mode` | Extrai e analisa a infraestrutura de comunicação C2 |
| `ransomware_triage_mode` | Triagem específica de ransomware: análise de criptografia, avaliação de recuperação de chaves |
| `code_similarity_mode` | Compara binários quanto à similaridade de código e linhagem compartilhada |

### Pesquisa de Segurança (6 prompts)

| Prompt | Caso de uso |
|---|---|
| `vulnerability_research_mode` | Caça a bugs: buffer overflows, UAF, injeção de comandos |
| `crypto_analysis_mode` | Análise de implementações criptográficas e detecção de fraquezas |
| `firmware_analysis_mode` | Firmware IoT/embarcado: extração com binwalk, strings UART, credenciais codificadas |
| `patch_analysis_mode` | Análise de patches de segurança e testes de regressão |
| `source_code_audit_mode` | Auditoria de segurança de código-fonte (Python, C, C++) |
| `autonomous_vuln_hunt_mode` | Pipeline autônomo de caça a vulnerabilidades |

### Pesquisa de CVE e Desenvolvimento de Exploits (5 prompts)

| Prompt | Caso de uso |
|---|---|
| `taint_analysis_mode` | Análise de taint no fluxo de dados: descoberta automatizada de caminhos fonte→sumidouro |
| `heap_exploit_mode` | Análise de exploração de heap e geração de PoC |
| `fuzzing_mode` | Configuração de campanhas de fuzzing e triagem de crashes |
| `patch_diff_auto_mode` | Diff automatizado de patches para pesquisa de vulnerabilidades 1-day |
| `cve_discovery_pipeline_mode` | Pipeline completo de descoberta de CVEs: do diff de patches ao exploit funcional |

### Outros (2 prompts)

| Prompt | Caso de uso |
|---|---|
| `game_analysis_mode` | Análise de clientes de jogos: detecção de anti-cheat, RE de protocolos, inspeção de memória |
| `report_generation_mode` | Fluxo de trabalho de sessão estruturado com mapeamento de técnicas MITRE ATT&CK |

> **Como os prompts funcionam:** Cada prompt prepara a IA com uma persona de análise estruturada. Inclui checkpoints de raciocínio Chain-of-Thought (onde a IA deve parar e avaliar antes de prosseguir) e regras de classificação de evidências que impedem a IA de apresentar especulação como fato. Cada descoberta deve ser rotulada como `OBSERVED` (verificada diretamente), `INFERRED` (derivada logicamente da análise estática) ou `POSSIBLE` (requer verificação adicional).

---

## Recursos MCP (11 URIs)

Os recursos são endpoints de dados somente leitura que os clientes de IA podem acessar por meio de modelos de URI. Eles complementam as ferramentas fornecendo dados estruturados sem exigir chamadas explícitas de ferramentas.

### Recursos Estáticos

| URI | Descrição |
|---|---|
| `reversecore://guide` | Guia de uso de ferramentas com regras de caminhos de arquivo e melhores práticas |
| `reversecore://guide/structures` | Guia técnico de recuperação de estruturas e análise de referências cruzadas |
| `reversecore://tools` | Documentação completa de todas as 120 ferramentas registradas |
| `reversecore://logs` | Logs do aplicativo (últimas 100 linhas) |

### Recursos Dinâmicos (Sistema de Arquivos Virtual por Binário)

Estes URIs são resolvidos por binário e invocam as ferramentas de análise correspondentes sob demanda:

| Modelo de URI | Descrição |
|---|---|
| `reversecore://{filename}/strings` | Extrai todas as strings de um binário |
| `reversecore://{filename}/iocs` | Extrai IOCs (IPs, URLs, e-mails, hashes) |
| `reversecore://{filename}/func/{address}/code` | Código pseudo-C descompilado de uma função |
| `reversecore://{filename}/func/{address}/asm` | Desmontagem de uma função |
| `reversecore://{filename}/func/{address}/cfg` | Grafo de fluxo de controle no formato Mermaid |
| `reversecore://{filename}/functions` | Lista de todas as funções no binário |
| `reversecore://{filename}/dormant_detector` | Resultados da análise do dormant detector |

---

## Início Rápido

### Opção 1 — PyPI (Mais simples)```bash
pip install reversecore-mcp
reversecore-mcp

### Opção 3 — Compilar a partir do código-fonte (Docker Compose)```bash
git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
./scripts/run-docker.sh        # auto-detects Intel / Apple Silicon

### Opção 4 — Python (Desenvolvimento 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

> Substitua `reversecore-mcp-arm64` por `reversecore-mcp` se você estiver em Intel/AMD.

---

### 🌐 Opção 2: Modo HTTP SSE

Para streaming baseado em rede (Server-Sent Events):```json
{
  "mcpServers": {
    "Reversecore_MCP": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

### Testes```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 pré-commit

Os seguintes hooks são executados automaticamente a cada commit:

1. **Ruff** — lint com auto-correção + verificação de formatação
2. **trailing-whitespace** — remove espaços em branco no final das linhas
3. **end-of-file-fixer** — garante que os arquivos terminem com uma nova linha
4. **check-yaml / check-json** — valida a sintaxe de YAML/JSON
5. **check-added-large-files** — bloqueia arquivos > 1 MB
6. **check-merge-conflict** — detecta marcadores de merge não resolvidos
7. **detect-private-key** — evita commits acidentais de chaves
8. **Bandit** — varredura de segurança em Python

---

## Pipeline de CI/CD

Cada push para `main` dispara 11 jobs do pipeline. Todos devem passar antes do deploy.```
 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 imagem é reconstruída apenas quando as versões das ferramentas mudam. Tempo de build: ~12 minutos.

### Camada 2: Imagem da Aplicação (`Dockerfile`)

Herda da imagem base e copia o código da aplicação:```
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"]

**Outros diretórios:**```
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.",
    )

Em seguida, registe-o no `__init__.py` do plugin apropriado e adicione testes em `tests/unit/`.

---

## Como Contribuir

1. Crie um fork do repositório
2. Crie uma branch de funcionalidade: `git checkout -b feat/my-feature`
3. Escreva testes juntamente com o seu código — a cobertura não deve cair abaixo de 80%
4. Garanta que todos os gateways passem: `pytest`, `ruff check`, `mypy`, `bandit`
5. Abra um pull request com uma descrição clara

Consulte o [Guia de Contribuição](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md) para conhecer os padrões de código, as convenções de docstrings (estilo Google) e a lista de verificação para pull requests.

---

## Documentação

| Documento | Descrição |
|---|---|
| [Guia de Instalação](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/getting-started/installation.md) | Configuração detalhada para todos os ambientes |
| [Guia de Arquitetura](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/architecture.md) | Design do sistema e detalhes dos componentes |
| [Guia de Contribuição](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md) | Padrões de código, docstrings, fluxo de trabalho de PR |
| [Guia de Testes](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/testing.md) | Padrões de teste, fixtures e cobertura |
| [Referência da API](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/api/) | Referência de ferramentas e módulos |
| [Guia do Utilizador](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/user-guide/) | Fluxos de trabalho de análise |

---

## Exemplos de Utilização

### Exemplo 1: Triagem Básica 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..."

### Exemplo 3: Investigação 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

---

## Suporte a Múltiplas Arquiteturas

O módulo `arch_registry.py` mapeia nomes de arquiteturas para parâmetros de configuração do Radare2, permitindo que as ferramentas funcionem em diferentes arquiteturas de CPU sem configuração manual:

| Arquitetura | Chave | r2 Arch | Larguras de Bits | Registrador PC | Registrador 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` |

**Resolução de aliases** é tratada automaticamente:
- `amd64` → `x86_64`
- `aarch64` → `arm64`
- `arm` com `bits=64` → `arm64`
- `arm` com `bits=16` ou `bits=32` → `arm32`

Ferramentas como `Radare2_esil_emulate`, `assemble_instructions` e `r2_simulate_patch` usam este registro para configurar corretamente o ambiente de análise para qualquer binário alvo.

---

## Sistema de Cache de Resultados

Duas camadas de cache minimizam a computação redundante:

### Cache de Resultados de Ferramenta (`result_cache.py`)

O decorador `@cache_tool_result` armazena em cache a saída de qualquer ferramenta com base em um hash SHA256 do arquivo binário e nos argumentos de palavra-chave da ferramenta:```
Cache key = SHA256( "<tool_name>::{sorted_json_kwargs}" )

**Storage:** Banco de dados SQLite assíncrono no caminho configurado por `MEMORY_DB_PATH` (padrão: `~/.reversecore_mcp/memory.db`).

**Portabilidade:** Use `export_memory_store` e `import_memory_store` para transferir todo o banco de dados de memória entre ambientes.

---

## Painel Web

Ao executar no modo HTTP (`MCP_TRANSPORT=http`), um painel web está disponível em `http://localhost:8000/dashboard`. Ele fornece:

- Upload de binários com arrastar e soltar
- Status de análise em tempo real
- Lista de funções interativa e visão de desmontagem
- Resultados de extração de IOCs
- Monitoramento da saúde do servidor

**Stack de tecnologia:** FastAPI + templates Jinja2 + HTMX (carregados localmente de `dashboard/static/`, sem dependência de CDN para conformidade com CSP).

**Recursos de segurança:**
- Tokens CSRF em todos os formulários que alteram estado
- Auto-escape Jinja2 habilitado
- Toda entrada do usuário é sanitizada via `html.escape()` antes da exibição
- Proteção contra path traversal via `validate_file_path()`

---

## Implantação

### Checklist de Produção

Antes de implantar em produção:

| Item | Como |
|---|---|
| Definir chave de API | `MCP_API_KEY=<strong-random-key>` |
| Usar usuário não root | Embutido: o container executa como `appuser` (UID 1000) |
| Definir limites de recursos | Padrão: 2 CPUs / 4 GB de RAM em `docker-compose.yml` |
| Habilitar logging estruturado | `LOG_FORMAT=json` para agregação de logs |
| Configurar Redis | `REDIS_URL=redis://<host>:6379/0` para fila de tarefas e cache |
| Definir caminho do workspace | `REVERSECORE_WORKSPACE=/path/to/isolated/directory` |
| Revisar limites de taxa | `REVERSECORE_RATE_LIMIT=60` (requisições/min, ajuste conforme necessário) |
| Habilitar sandbox | `REVERSECORE_SANDBOX_ENABLED=true` para isolamento de análise dinâmica |

### Verificações de Saúde

O servidor fornece endpoints HTTP de verificação de saúde para orquestração:```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