ИИ-ассистент разбивает это на вызовы инструментов:```
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 модулей)

Каталог `reversecore_mcp/core/` содержит общую инфраструктуру, на которой построены все инструменты:

| Модуль | Назначение |
|---|---|
| `config.py` | Pydantic BaseSettings с 34+ переменными окружения |
| `security.py` | Санитизация входных данных, проверка аргументов команд |
| `validators.py` | Проверка путей к файлам и бинарным файлам с защитой от TOCTOU, разрешение символических ссылок |
| `r2_pool.py` | Потокобезопасный пул соединений Radare2 с настраиваемым размером |
| `r2_helpers.py` | Структурированный разбор вывода Radare2 |
| `metrics.py` | Время выполнения по каждому инструменту, счётчики вызовов, частота ошибок, статистика кэша |
| `memory.py` | Асинхронное хранилище AI-памяти на базе SQLite для сохранения результатов анализа между сеансами |
| `mitre_mapper.py` | Движок сопоставления идентификаторов техник MITRE ATT&CK |
| `evidence.py` | Система классификации доказательств: `OBSERVED`, `INFERRED`, `POSSIBLE` |
| `resilience.py` | Паттерны декораторов: повторные попытки, circuit-breaker и тайм-ауты |
| `task_queue.py` | Фоновая очередь задач через Redis + arq |
| `extension_registry.py` | Регистрация плагинов и управление жизненным циклом |
| `arch_registry.py` | Мультиархитектурное сопоставление (x86, x86_64, ARM32, ARM64, MIPS, RISC-V, PPC → r2 arch/bits/registers) |
| `result_cache.py` | Декоратор кэширования результатов инструментов на основе SHA256 (`@cache_tool_result`) |
| `analysis_cache.py` | Многоуровневый кэш декомпиляции (L1: Redis, L2: SQLite) |
| `result.py` | Pydantic-модели `ToolSuccess` / `ToolError` |
| `exceptions.py` | 17 классов исключений с кодами ошибок `RCMCP-E*` |
| `decorators.py` | `@log_execution`, `@track_metrics` |
| `error_handling.py` | Декоратор `@handle_tool_errors` |
| `error_formatting.py` | Форматирование структурированных ответов об ошибках |
| `execution.py` | Безопасное выполнение подпроцессов с тайм-аутом и ограничениями вывода |
| `command_spec.py` | Спецификация команд для вызовов подпроцессов |
| `loader.py` | Динамический загрузчик модулей инструментов |
| `plugin.py` | Базовый класс плагина |
| `extension.py` | Базовый класс расширения |
| `container.py` | Поддержка выполнения в контейнере/песочнице |
| `audit.py` | Аудит-логирование |
| `binary_cache.py` | Кэширование бинарных файлов |
| `json_utils.py` | Сериализация JSON через orjson (в 3–5 раз быстрее стандартного json) |
| `logging_config.py` | Структурированное логирование на основе Loguru |
| `report_generator.py` | Движок рендеринга отчётов (Markdown, PDF через xhtml2pdf) |
| `resource_manager.py` | Управление жизненным циклом ресурсов MCP |
| `sast/python_ast_scanner.py` | Сканер уязвимостей на основе AST Python |
| `sast/regex_scanner.py` | Сканер уязвимостей C/C++ на основе регулярных выражений |
| `sast/rule_manager.py` | Загрузка и управление правилами SAST |

---

## Каталог инструментов (120 инструментов)

Каждый инструмент возвращает структурированный `ToolResult` — либо `ToolSuccess` с типизированным `data`, либо `ToolError` с кодом ошибки `RCMCP-E*`. Инструменты сгруппированы в 8 плагинов.

---

### 🔍 Плагин статического анализа (24 инструмента)

| # | Инструмент | Бэкенд | Описание |
|---|---|---|---|
| 1 | `run_strings` | CLI `strings` | Извлечение ASCII/Unicode-строк с настраиваемой минимальной длиной |
| 2 | `run_binwalk` | Binwalk | Глубокое сканирование прошивок на наличие встроенных сигнатур и файловых систем |
| 3 | `run_binwalk_extract` | Binwalk | Извлечение встроенных файлов, обнаруженных binwalk |
| 4 | `parse_binary_with_lief` | LIEF | Полный разбор PE/ELF/Mach-O: заголовки, секции, импорт/экспорт, TLS |
| 5 | `detect_packer` | DIE | Быстрое определение упаковщика/компилятора |
| 6 | `detect_packer_deep` | DIE (`diec`) | Глубокий анализ упаковщика/протектора через Detect It Easy |
| 7 | `run_capa` | CAPA (Mandiant FLARE) | Определение возможностей — «шифрует данные», «создаёт персистентность» и т. д. |
| 8 | `run_capa_quick` | CAPA | Быстрое сканирование возможностей с подмножеством правил |
| 9 | `generate_signature` | Radare2 | Генерация сигнатур бинарных файлов для идентификации |
| 10 | `generate_yara_rule` | Radare2 + YARA | Генерация YARA-правил обнаружения по бинарным паттернам |
| 11 | `generate_advanced_yara_rule` | Radare2 + YARA | Продвинутые YARA-правила с поведенческими индикаторами |
| 12 | `scan_for_versions` | LIEF + strings | Поиск встроенных строк версий в бинарном файле |
| 13 | `extract_rtti_info` | Radare2 | Извлечение C++ RTTI (информации о типах во время выполнения) |
| 14 | `diff_binaries` | Radare2 | Семантическое сравнение двух версий бинарных файлов |
| 15 | `analyze_variant_changes` | Radare2 | Анализ изменений между вариантами бинарных файлов |
| 16 | `match_libraries` | Radare2 | Идентификация статически слинкованных библиотек по отпечаткам функций |
| 17 | `patch_diff_1day` | Radare2 + эвристики | Автоматический анализ patch diff для исследования 1-day уязвимостей |
| 18 | `analyze_patch_diff_auto` | Radare2 + логический вывод | Автоматический вывод уязвимостей из patch diff |
| 19 | `emulate_binary` | Radare2 ESIL | Эмуляция кода с трассировкой регистров и памяти |
| 20 | `generate_fuzzing_harness` | Qiling + AFL++ | Генерация фаззинг-харнеса, нацеленного на конкретную функцию |
| 21 | `run_fuzzing_campaign` | AFL++ | Запуск полной фаззинг-кампании со сбором крашей |
| 22 | `triage_crash` | GDB | Разбор крашей и оценка эксплуатируемости |
| 23 | `verify_path_and_get_args` | angr | Символьное выполнение — доказательство достижимости пути и вычисление конкретных входных данных |
| 24 | `taint_trace` | Radare2 + angr | Анализ потока данных от источников к стокам (taint analysis) |

---

### 🔐 Плагин аудита исходного кода (1 инструмент)

| # | Инструмент | Бэкенд | Описание |
|---|---|---|---|
| 25 | `audit_source_code` | AST + Regex | Сканирование AST Python + сканирование C/C++ по регулярным выражениям для поиска опасных паттернов |

---

### 🛠️ Плагин общих утилит (20 инструментов)

**Файловые операции (5 инструментов)**

| # | Инструмент | Описание |
|---|---|---|
| 26 | `run_file` | Определение типа файла, архитектуры и компилятора |
| 27 | `copy_to_workspace` | Копирование файла в рабочее пространство анализа |
| 28 | `create_directory` | Создание каталога в рабочем пространстве |
| 29 | `list_workspace` | Список всех файлов в рабочем пространстве |
| 30 | `scan_workspace` | Полное сканирование рабочего пространства с метаданными файлов |

**Объяснение патчей (1 инструмент)**

| # | Инструмент | Описание |
|---|---|---|
| 31 | `explain_patch` | Объяснение бинарного патча на естественном языке |

**Ассемблер (1 инструмент)**

| # | Инструмент | Бэкенд | Описание |
|---|---|---|---|
| 32 | `assemble_instructions` | Keystone | Ассемблирование инструкций в машинный код (x86, ARM, MIPS и др.) |

**Управление AI-памятью (11 инструментов)**

Эти инструменты позволяют AI сохранять и извлекать результаты анализа между сеансами с помощью асинхронной базы данных SQLite:

| # | Инструмент | Описание |
|---|---|---|
| 33 | `create_memory_session` | Начать новый сеанс памяти для анализа |
| 34 | `store_analysis_finding` | Сохранить результат анализа с тегами |
| 35 | `query_analysis_memories` | Поиск прошлых результатов по запросу |
| 36 | `get_binary_analysis_context` | Получить весь контекст для конкретного бинарного файла |
| 37 | `tag_analysis_session` | Добавить теги к сеансу для организации |
| 38 | `search_memories_by_tag` | Найти сеансы/результаты по тегу |
| 39 | `delete_analysis_session` | Удалить сеанс и его результаты |
| 40 | `cleanup_expired_sessions` | Удалить сеансы старше заданного порога |
| 41 | `list_analysis_sessions` | Список всех активных сеансов |
| 42 | `export_memory_store` | Экспорт всех воспоминаний в переносимый формат |
| 43 | `import_memory_store` | Импорт воспоминаний из файла экспорта |

**Мониторинг сервера (2 инструмента)**

| # | Инструмент | Описание |
|---|---|---|
| 44 | `get_server_health` | Время работы, использование памяти, загруженные инструменты, версия Python |
| 45 | `get_tool_metrics` | Счётчики вызовов по каждому инструменту, среднее время выполнения, частота ошибок, попадания/промахи кэша |

---

### ⚙️ Плагин Radare2 и r2ghidra (30 инструментов)

Все инструменты Radare2 используют потокобезопасный пул соединений (`r2_pool.py`), который автоматически управляет сеансами r2pipe.

| # | Инструмент | Описание |
|---|---|---|
| 46 | `Radare2_open_file` | Открыть бинарный файл в Radare2 |
| 47 | `Radare2_close_file` | Закрыть сеанс Radare2 |
| 48 | `Radare2_list_open_files` | Список текущих открытых файлов |
| 49 | `Radare2_analyze_binary` | Запустить полный автоматический анализ (`aaa`) |
| 50 | `Radare2_list_functions` | Список всех обнаруженных функций |
| 51 | `Radare2_disassemble_function` | Дизассемблировать конкретную функцию |
| 52 | `Radare2_disassemble_address` | Дизассемблировать по конкретному адресу |
| 53 | `Radare2_decompile_function` | Декомпиляция через r2ghidra (движок Ghidra, встроенный в r2, без JVM) |
| 54 | `Radare2_list_exports` | Список экспортируемых символов |
| 55 | `Radare2_list_imports` | Список импортируемых функций |
| 56 | `Radare2_list_sections` | Список секций бинарного файла с энтропией |
| 57 | `Radare2_list_strings` | Список строк, найденных в бинарном файле |
| 58 | `Radare2_find_cross_references` | Отслеживание вызовов функций и ссылок на данные |
| 59 | `Radare2_search_bytes` | Поиск байтовых паттернов в бинарном файле |
| 60 | `Radare2_get_binary_info` | Получить метаданные бинарного файла (архитектура, формат, порядок байтов) |
| 61 | `Radare2_execute_command` | Выполнить сырую команду Radare2 |
| 62 | `Radare2_esil_emulate` | Эмуляция ESIL по конкретному адресу |
| 63 | `Radare2_get_hexdump` | Шестнадцатеричный дамп по виртуальному адресу |
| 64 | `Radare2_get_cfg_data` | Извлечение данных графа потока управления |
| 65 | `Radare2_generate_cfg_png` | Генерация CFG в виде PNG-изображения |
| 66 | `Radare2_generate_callgraph` | Генерация графа вызовов функций |
| 67 | `Radare2_recover_structures` | Автоматическое восстановление C-структур и сохранение в базу данных аннотаций |
| 68 | `Radare2_decompile_with_r2ghidra` | Высококачественная декомпиляция на C с кэшированием |
| 69 | `Radare2_annotate_binary` | Добавить аннотации к бинарному файлу |
| 70 | `Radare2_get_annotations` | Получить аннотации |
| 71 | `Radare2_export_annotations` | Экспорт аннотаций в файл |
| 72 | `Radare2_import_annotations` | Импорт аннотаций из файла |
| 73 | `Radare2_detect_crypto_constants` | Обнаружение криптографических констант (AES S-box и т. д.) |
| 74 | `Radare2_find_gadgets` | Поиск ROP/JOP-гаджетов |
| 75 | `Radare2_calculate_entropy` | Расчёт энтропии по каждой секции |

---

### 🦠 Плагин анализа вредоносного ПО (9 инструментов)

| # | Инструмент | Бэкенд | Описание |
|---|---|---|---|
| 76 | `dormant_detector` | Radare2 + эвристики | Поиск скрытых бэкдоров, функций-сирот, таймеров и логических бомб |
| 77 | `adaptive_vaccine` | YARA + Radare2 | Генерация YARA-правил обнаружения + бинарных патчей для нейтрализации угроз |
| 78 | `vulnerability_hunter` | Radare2 + анализ | Обнаружение опасных API-паттернов (strcpy, sprintf) и цепочек ROP-гаджетов |
| 79 | `extract_iocs` | Regex + LIEF | Извлечение IP-адресов, URL, доменов, хэшей, ключей реестра, криптоадресов |
| 80 | `run_yara` | YARA | Сканирование с пользовательскими файлами правил и встроенными наборами правил |
| 81 | `generate_poc_exploit` | pwntools | Генерация кода PoC-эксплойта |
| 82 | `build_rop_chain` | ROPgadget + pwntools | Автоматическое построение ROP-цепочек |
| 83 | `autonomous_vuln_hunt` | Radare2 + angr | Автономный конвейер поиска уязвимостей |
| 84 | `analyze_heap_exploit` | Radare2 + эвристики | Анализ эксплойтов кучи (UAF, double-free, переполнение) |

---

### 🕵️ Плагин цифровой криминалистики (22 инструмента)

**Криминалистика памяти (6 инструментов)**

| # | Инструмент | Бэкенд | Описание |
|---|---|---|---|
| 85 | `memory_analyze` | Volatility3 | Полный анализ дампа памяти |
| 86 | `memory_list_processes` | Volatility3 | Список запущенных процессов из дампа памяти |
| 87 | `memory_detect_injections` | Volatility3 | Обнаружение инъекций кода в память процессов |
| 88 | `memory_extract_strings` | Volatility3 | Извлечение строк из памяти процессов |
| 89 | `memory_dump_module` | Volatility3 | Дамп загруженного модуля из памяти |
| 90 | `memory_list_symbols` | Volatility3 | Список символов из памяти |

**Криминалистика дисков (6 инструментов)**

| # | Инструмент | Бэкенд | Описание |
|---|---|---|---|
| 91 | `disk_list_partition` | Sleuth Kit | Список разделов диска |
| 92 | `disk_list_files` | Sleuth Kit | Список файлов в образе диска |
| 93 | `disk_recover_deleted` | Sleuth Kit | Восстановление удалённых файлов |
| 94 | `disk_analyze_mft` | Sleuth Kit | Анализ NTFS Master File Table |
| 95 | `disk_extract_file` | Sleuth Kit | Извлечение файла из образа диска |
| 96 | `disk_hash_verify` | Sleuth Kit | Проверка целостности файла по хэшу |

**Сетевая криминалистика (5 инструментов)**

| # | Инструмент | Бэкенд | Описание |
|---|---|---|---|
| 97 | `pcap_analyze` | Scapy | Анализ PCAP: разбивка по протоколам, аномалии |
| 98 | `pcap_list_connections` | Scapy | Список всех сетевых соединений |
| 99 | `pcap_extract_dns` | Scapy | Извлечение DNS-запросов и ответов |
| 100 | `pcap_extract_c2` | Scapy | Выявление потенциальной C2-коммуникации |
| 101 | `pcap_reconstruct_stream` | Scapy | Реконструкция TCP-потоков |

**Анализ артефактов (5 инструментов)**

| # | Инструмент | Бэкенд | Описание |
|---|---|---|---|
| 102 | `artifact_collect` | Пользовательские парсеры | Сбор истории браузера, кустов реестра, журналов событий, prefetch |
| 103 | `artifact_correlate_ioc` | Пользовательские парсеры | Сопоставление артефактов с известными IOC |
| 104 | `artifact_generate_yara` | YARA | Генерация YARA-правил по паттернам артефактов |
| 105 | `artifact_timeline` | Пользовательские парсеры | Построение таймлайна из нескольких источников артефактов |
| 106 | `artifact_report` | Пользовательские парсеры | Генерация отчёта по анализу артефактов |

---

### 📝 Плагин формирования отчётов (14 инструментов)

| # | Инструмент | Описание |
|---|---|---|
| 107 | `get_system_time` | Получить временную метку сервера (предотвращает выдумывание дат AI) |
| 108 | `set_timezone` | Установить часовой пояс для отчётов |
| 109 | `get_timezone_info` | Получить информацию о текущем часовом поясе |
| 110 | `start_report_session` | Начать сеанс анализа с замером времени и уникальным ID |
| 111 | `end_report_session` | Завершить сеанс: вычислить длительность, зафиксировать списки IOC/ATT&CK |
| 112 | `get_report_session_status` | Проверить статус сеанса |
| 113 | `list_report_sessions` | Список всех активных/завершённых сеансов |
| 114 | `add_ioc` | Сбор и тегирование IOC в ходе активного сеанса |
| 115 | `add_analysis_note` | Добавление категоризированных заметок (finding, warning, behavior) |
| 116 | `add_mitre_technique` | Фиксация идентификаторов техник MITRE ATT&CK |
| 117 | `set_severity` | Установка уровня серьёзности сеанса (low/medium/high/critical) |
| 118 | `create_analysis_report` | Рендеринг отчёта в 4 режимах: `full_analysis`, `quick_triage`, `ioc_summary`, `executive_brief` |
| 119 | `generate_vex_report` | Генерация отчёта VEX (Vulnerability Exploitability eXchange) |
| 120 | `generate_sigma_rule` | Генерация правил обнаружения SIGMA |

---

## Управляемые промпты для анализа (22 режима)

Промпты — это готовые рабочие процессы анализа, которые задают AI структурированную роль, пошаговые последовательности использования инструментов и правила классификации доказательств. Вы активируете их, указав имя промпта в вашем AI-клиенте.

### Анализ вредоносного ПО (9 промптов)

| Промпт | Вариант использования |
|---|---|
| `full_analysis_mode` | Полный 6-фазный анализ: триаж → дизассемблирование → поведение → сеть → персистентность → отчёт |
| `malware_analysis_mode` | Целенаправленный анализ вредоносного ПО с классификацией угроз |
| `basic_analysis_mode` | Быстрый триаж для первичной оценки и быстрых вердиктов |
| `apt_hunting_mode` | Поиск APT-специфичных активностей: горизонтальное перемещение, персистентность, эксфильтрация данных |
| `malware_defense_mode` | Ориентация на защиту: генерация правил обнаружения и мер противодействия |
| `unpacking_mode` | Анализ и обход упаковки/обфускации (Themida, VMProtect, UPX) |
| `c2_extraction_mode` | Извлечение и анализ инфраструктуры C2-коммуникации |
| `ransomware_triage_mode` | Триаж программ-вымогателей: анализ шифрования, оценка возможности восстановления ключей |
| `code_similarity_mode` | Сравнение бинарных файлов на предмет схожести кода и общего происхождения |

### Security Research (6 промптов)

| Промпт | Вариант использования |
|---|---|
| `vulnerability_research_mode` | Поиск ошибок: переполнения буфера, UAF, инъекции команд |
| `crypto_analysis_mode` | Анализ криптографических реализаций и выявление слабостей |
| `firmware_analysis_mode` | IoT/встраиваемые прошивки: извлечение binwalk, UART-строки, жёстко заданные учётные данные |
| `patch_analysis_mode` | Анализ исправлений безопасности и регрессионное тестирование |
| `source_code_audit_mode` | Аудит безопасности исходного кода (Python, C, C++) |
| `autonomous_vuln_hunt_mode` | Автономный конвейер поиска уязвимостей |

### CVE Research и разработка эксплойтов (5 промптов)

| Промпт | Вариант использования |
|---|---|
| `taint_analysis_mode` | Анализ потока данных: автоматическое обнаружение путей источник→сток |
| `heap_exploit_mode` | Анализ эксплойтов кучи и генерация PoC |
| `fuzzing_mode` | Настройка фаззинг-кампании и триаж крашей |
| `patch_diff_auto_mode` | Автоматический patch diff для исследования 1-day уязвимостей |
| `cve_discovery_pipeline_mode` | Полный конвейер обнаружения CVE: от patch diff до рабочего эксплойта |

### Прочие (2 промпта)

| Промпт | Вариант использования |
|---|---|
| `game_analysis_mode` | Анализ игровых клиентов: обнаружение анти-чита, реверс протоколов, инспекция памяти |
| `report_generation_mode` | Структурированный сеанс работы с сопоставлением техник MITRE ATT&CK |

> **Как работают промпты:** Каждый промпт задаёт AI структурированную роль аналитика. Он включает контрольные точки рассуждений по цепочке мыслей (chain-of-thought), где AI должен остановиться и оценить ситуацию перед продолжением, а также правила классификации доказательств, которые не позволяют AI выдавать догадки за факты. Каждый вывод должен быть помечен как `OBSERVED` (непосредственно проверено), `INFERRED` (логически выведено из статического анализа) или `POSSIBLE` (требует дальнейшей проверки).

---

## Ресурсы MCP (11 URI)

Ресурсы — это конечные точки только для чтения, к которым AI-клиенты могут обращаться через шаблоны URI. Они дополняют инструменты, предоставляя структурированные данные без необходимости явных вызовов инструментов.

### Статические ресурсы

| URI | Описание |
|---|---|
| `reversecore://guide` | Руководство по использованию инструментов с правилами путей к файлам и лучшими практиками |
| `reversecore://guide/structures` | Техническое руководство по восстановлению структур и анализу перекрёстных ссылок |
| `reversecore://tools` | Полная документация по всем 120 зарегистрированным инструментам |
| `reversecore://logs` | Журналы приложения (последние 100 строк) |

### Динамические ресурсы (виртуальная файловая система для каждого бинарного файла)

Эти URI разрешаются для каждого бинарного файла и по запросу вызывают соответствующие инструменты анализа:

| Шаблон URI | Описание |
|---|---|
| `reversecore://{filename}/strings` | Извлечь все строки из бинарного файла |
| `reversecore://{filename}/iocs` | Извлечь IOC (IP-адреса, URL, email, хэши) |
| `reversecore://{filename}/func/{address}/code` | Декомпилированный псевдо-C код функции |
| `reversecore://{filename}/func/{address}/asm` | Дизассемблированный код функции |
| `reversecore://{filename}/func/{address}/cfg` | Граф потока управления в формате Mermaid |
| `reversecore://{filename}/functions` | Список всех функций в бинарном файле |
| `reversecore://{filename}/dormant_detector` | Результаты анализа dormant detector |

---

## Быстрый старт

### Вариант 1 — PyPI (самый простой)```bash
pip install reversecore-mcp
reversecore-mcp

### Вариант 3 — Сборка из исходного кода (Docker Compose)```bash
git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
./scripts/run-docker.sh        # auto-detects Intel / Apple Silicon

### Вариант 4 — Python (локальная разработка)```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

> Замените `reversecore-mcp-arm64` на `reversecore-mcp`, если вы на Intel/AMD.

---

### 🌐 Вариант 2: режим SSE HTTP

Для сетевой потоковой передачи (Server-Sent Events):```json
{
  "mcpServers": {
    "Reversecore_MCP": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

### Тестирование```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

### Хуки Pre-commit

Следующие хуки запускаются автоматически при каждом коммите:

1. **Ruff** — линтинг с авто-исправлением + проверка форматирования
2. **trailing-whitespace** — удаляет завершающие пробелы
3. **end-of-file-fixer** — гарантирует, что файлы заканчиваются новой строкой
4. **check-yaml / check-json** — проверяет синтаксис YAML/JSON
5. **check-added-large-files** — блокирует файлы размером > 1 МБ
6. **check-merge-conflict** — обнаруживает неразрешённые маркеры слияния
7. **detect-private-key** — предотвращает случайную фиксацию ключей
8. **Bandit** — сканирование безопасности Python

---

## Конвейер CI/CD

Каждый пуш в `main` запускает 11 задач конвейера. Все они должны быть успешно пройдены перед развёртыванием.```
 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

Этот образ пересобирается только при изменении версий инструментов. Время сборки: ~12 минут.

### Слой 2: Образ приложения (`Dockerfile`)

Наследуется от базового образа и копирует код приложения:```
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"]

**Другие каталоги:**```
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.",
    )

Затем зарегистрируйте его в `__init__.py` соответствующего плагина и добавьте тесты в `tests/unit/`.

---

## Участие в разработке

1. Сделайте форк репозитория
2. Создайте ветку для функциональности: `git checkout -b feat/my-feature`
3. Пишите тесты вместе с кодом — покрытие не должно опускаться ниже 80%
4. Убедитесь, что все проверки проходят: `pytest`, `ruff check`, `mypy`, `bandit`
5. Откройте pull request с понятным описанием

Пожалуйста, ознакомьтесь с [Руководством по участию в разработке](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md) для получения информации о стандартах кода, соглашениях по docstring (в стиле Google) и чек-листе pull request.

---

## Документация

| Документ | Описание |
|---|---|
| [Руководство по установке](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/getting-started/installation.md) | Подробная настройка для всех окружений |
| [Руководство по архитектуре](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/architecture.md) | Архитектура системы и детали компонентов |
| [Руководство по участию в разработке](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md) | Стандарты кода, docstring, процесс pull request |
| [Руководство по тестированию](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/testing.md) | Паттерны тестирования, фикстуры и покрытие |
| [Справочник по API](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/api/) | Справочник по инструментам и модулям |
| [Руководство пользователя](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/user-guide/) | Рабочие процессы анализа |

---

## Примеры использования

### Пример 1: базовый анализ вредоносного ПО```
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..."

### Пример 3: Цифровое криминалистическое расследование```
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

---

## Поддержка нескольких архитектур

Модуль `arch_registry.py` сопоставляет имена архитектур с параметрами конфигурации Radare2, что позволяет инструментам работать с разными архитектурами процессоров без ручной настройки:

| Архитектура | Ключ | Архитектура r2 | Разрядность | Регистр PC | Регистр 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` |

**Разрешение псевдонимов** обрабатывается автоматически:
- `amd64` → `x86_64`
- `aarch64` → `arm64`
- `arm` с `bits=64` → `arm64`
- `arm` с `bits=16` или `bits=32` → `arm32`

Такие инструменты, как `Radare2_esil_emulate`, `assemble_instructions` и `r2_simulate_patch`, используют этот реестр для корректной настройки среды анализа для любого целевого двоичного файла.

---

## Система кэширования результатов

Два уровня кэширования минимизируют избыточные вычисления:

### Кэш результатов инструмента (`result_cache.py`)

Декоратор `@cache_tool_result` кэширует вывод любого инструмента на основе SHA256-хеша двоичного файла и именованных аргументов инструмента:```
Cache key = SHA256( "<tool_name>::{sorted_json_kwargs}" )

**Storage:** Async SQLite database at the path configured by `MEMORY_DB_PATH` (default: `~/.reversecore_mcp/memory.db`).

**Portability:** Use `export_memory_store` and `import_memory_store` to transfer the entire memory database between environments.

---

## Web Dashboard

When running in HTTP mode (`MCP_TRANSPORT=http`), a web dashboard is available at `http://localhost:8000/dashboard`. It provides:

- Binary upload with drag-and-drop
- Real-time analysis status
- Interactive function list and disassembly view
- IOC extraction results
- Server health monitoring

**Tech stack:** FastAPI + Jinja2 templates + HTMX (loaded locally from `dashboard/static/`, no CDN dependency for CSP compliance).

**Security features:**
- CSRF tokens on all state-changing forms
- Jinja2 auto-escaping enabled
- All user input sanitized via `html.escape()` before display
- Path traversal protection via `validate_file_path()`

---

## Deployment

### Production Checklist

Before deploying to production:

| Item | How |
|---|---|
| Set API key | `MCP_API_KEY=<strong-random-key>` |
| Use non-root user | Built-in: container runs as `appuser` (UID 1000) |
| Set resource limits | Default: 2 CPU / 4 GB RAM in `docker-compose.yml` |
| Enable structured logging | `LOG_FORMAT=json` for log aggregation |
| Configure Redis | `REDIS_URL=redis://<host>:6379/0` for task queue and caching |
| Set workspace path | `REVERSECORE_WORKSPACE=/path/to/isolated/directory` |
| Review rate limits | `REVERSECORE_RATE_LIMIT=60` (requests/min, adjust as needed) |
| Enable sandbox | `REVERSECORE_SANDBOX_ENABLED=true` for dynamic analysis isolation |

### Health Checks

The server provides HTTP health check endpoints for orchestration:```bash
# Liveness (always 200 if process is running)
curl http://localhost:8000/health/live

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

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