Reversecore MCP

ИИ‑усиленный обратный инжиниринг и анализ безопасности с использованием Model Context Protocol

MCP‑сервер, который предоставляет ИИ‑ассистентам, таким как Claude и Cursor, возможность выполнять обратный инжиниринг, анализ вредоносного ПО, исследование уязвимостей, цифровую криминалистику и аудит исходного кода на естественном языке.

Содержание

Что такое Reversecore MCP?
Архитектура
Каталог инструментов (120 инструментов)
Направленные запросы анализа (22 режима)
Ресурсы MCP (11 URI)
Быстрый старт
Подключение к вашему ИИ-клиенту
Конфигурация
Модель безопасности
Разработка
Конвейер CI/CD
Архитектура сборки Docker
Требования к системе
Структура проекта
Обработка ошибок
Добавление новых инструментов
Вклад
Документация
Лицензия

Что такое Reversecore MCP?

Reversecore MCP — это сервер Протокола контекста модели, который объединяет 120 инструментов анализа в один интерфейс, который могут вызывать AI-ассистенты через естественный язык.

Вместо изучения синтаксиса командной строки для дюжины разных инструментов, вы описываете, что хотите:

"Decompile the main function of this malware sample, extract all network IOCs,
 map the behavior to MITRE ATT&CK, and generate a triage report."

AI-ассистент разбивает это на вызовы инструментов:

r2_decompile("sample.exe", "main")
  → extract_iocs("sample.exe")
    → add_mitre_technique(technique_id="T1071.001", ...)
      → create_analysis_report(template_type="quick_triage")

Каждый инструмент возвращает структурированный ToolResult (либо ToolSuccess, либо ToolError) с типизированными данными, которые ИИ может использовать для рассуждений, цепочки последующих запросов или отображения пользователю.

Что охватывает

Домен	Что вы можете сделать
Статический анализ	Дизассемблирование, декомпиляция (r2ghidra), разбор бинарников (LIEF), обнаружение упаковщиков (DIE), обнаружение возможностей (CAPA), извлечение строк, сканирование прошивки (binwalk)
Динамический и символьный	Эмуляция ESIL, символьное выполнение angg, анализ замусоривания, создание harness для фаззинга
Анализ вредоносного ПО	Извлечение IOC, сканирование YARA, обнаружение спящих бекдоров, генерация адаптивных вакцин, автономный поиск уязвимостей
Исследование уязвимостей	Обнаружение опасных API, поиск гаджетов ROP, анализ эксплуатации кучи, triage сбоев, генерация PoC
Цифровая криминалистика	Криминалистика памяти (Volatility3), анализ PCAP (Scapy), криминалистика диска (Sleuth Kit), корреляция артефактов
Аудит исходного кода	Сканирование AST Python, сканирование шаблонов regex C/C++
Отчетность	Отчеты, основанные на сеансах, с сопоставлением MITRE ATT&CK, генерация правил SIGMA, отчеты VEX, доставка по email

Архитектура

AI Client (Claude / Cursor / any MCP-compatible client)
        │  MCP Protocol (stdio or HTTP/SSE)
        ▼
┌──────────────────────────────────────────────────────┐
│                   FastMCP 3.4.4 Server               │
│          120 registered tools · Fully async          │
│                  Python 3.10–3.12                    │
├────────────────────┬─────────────────────────────────┤
│   Guided Prompts   │  Dynamic Resources              │
│  (22 analysis      │  (11 URI-based: per-binary      │
│   modes)           │   strings, IOCs, ASM, CFG, …)   │
├────────────────────┴─────────────────────────────────┤
│                  Core Infrastructure                 │
│  Config · Security · Validators · Exceptions (17)    │
│  R2 Pool · Metrics · Memory (SQLite) · Task Queue    │
│  MITRE Mapper · Evidence Engine · Resilience Layer   │
│  Arch Registry (x86/ARM/MIPS/RISC-V/PPC)            │
│  Result Cache (SHA256) · Analysis Cache (Redis+SQL)  │
│  SAST (Python AST + C/C++ Regex) · Plugin System     │
├──────────────────────────────────────────────────────┤
│                 Analysis Engines                     │
│  Radare2 6.0.4     │  YARA 4.3.1 · LIEF · Capstone  │
│  r2ghidra           │  CAPA · angr · Qiling          │
│  Volatility3 · Scapy│ DIE · Binwalk · Sleuth Kit    │
│  pwntools · ROPgadget│ Keystone (assembler)          │
└──────────────────────────────────────────────────────┘

Основная инфраструктура (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`	Хранилище памяти ИИ на основе асинхронного SQLite для сохранения результатов анализа между сеансами
`mitre_mapper.py`	Механизм сопоставления идентификаторов техник MITRE ATT&CK
`evidence.py`	Система классификации доказательств: `OBSERVED`, `INFERRED`, `POSSIBLE`
`resilience.py`	Шаблоны декораторов повторов, прерывателя цепи и таймаута
`task_queue.py`	Фоновая очередь задач через Redis + arq
`extension_registry.py`	Регистрация плагинов и управление их жизненным циклом
`arch_registry.py`	Сопоставление множественных архитектур (x86, x86_64, ARM32, ARM64, MIPS, RISC-V, PPC → arch/bits/registers r2)
`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`	Сканер уязвимостей на основе regex C/C++
`sast/rule_manager.py`	Загрузка и управление правилами SAST

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

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

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

#	Инструмент	Бэкенд	Описание
1	`run_strings`	`strings` CLI	Извлечение 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)	Обнаружение возможностей — «шифрует данные», «создаёт persistence» и т.д.
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 (Run-Time Type Information)
14	`diff_binaries`	Radare2	Семантическое различие бинарников между двумя версиями файла
15	`analyze_variant_changes`	Radare2	Анализ изменений между вариантами бинарника
16	`match_libraries`	Radare2	Идентификация статически связанных библиотек по отпечатку функций
17	`patch_diff_1day`	Radare2 + heuristics	Автоматизированный анализ диффа патча для исследования уязвимостей типа 1‑день
18	`analyze_patch_diff_auto`	Radare2 + inference	Автоматизированный вывод уязвимостей из диффа патча
19	`emulate_binary`	Radare2 ESIL	Эмуляция кода с трассировкой регистров/памяти через 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	Анализ потока данных с отслеживанием загрязнения от источников к стокам

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

#	Инструмент	Бэкенд	Описание
25	`audit_source_code`	AST + Regex	Сканер Python AST + регулярок 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 и т.д.)

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

Эти инструменты позволяют ИИ сохранять и извлекать результаты анализа между сессиями с использованием асинхронной базы данных 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`	Обнаружение криптографических констант (S‑бокс AES и т.д.)
74	`Radare2_find_gadgets`	Найти гаджеты ROP/JOP
75	`Radare2_calculate_entropy`	Вычислить энтропию по секциям

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

#	Инструмент	Бэкенд	Описание
76	`dormant_detector`	Radare2 + heuristics	Найти скрытые бэкдоры, сиротские функции, временные бомбы, логические бомбы
77	`adaptive_vaccine`	YARA + Radare2	Генерировать правила YARA для обнаружения + бинарные патчи для нейтрализации угроз
78	`vulnerability_hunter`	Radare2 + analysis	Обнаружить опасные шаблоны 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 + heuristics	Анализ эксплуатации кучи (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	Анализ таблицы MFT NTFS
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`	Custom parsers	Собрать историю браузера, кусты реестра, журналы событий, prefetch
103	`artifact_correlate_ioc`	Custom parsers	Коррелировать артефакты с известными IOC
104	`artifact_generate_yara`	YARA	Генерировать правила YARA на основе шаблонов артефактов
105	`artifact_timeline`	Custom parsers	Построить хронологию из нескольких источников артефактов
106	`artifact_report`	Custom parsers	Сгенерировать отчёт по анализу артефактов

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

#	Инструмент	Описание
107	`get_system_time`	Получить метку времени сервера (предотвращает галлюцинации дат у ИИ)
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`	Добавлять помеченные заметки (обнаружение, предупреждение, поведение)
116	`add_mitre_technique`	Документировать идентификаторы техник MITRE ATT&CK
117	`set_severity`	Установить уровень серьёзности сеанса (низкий/средний/высокий/критический)
118	`create_analysis_report`	Сформировать отчёт в 4 режимах: `full_analysis`, `quick_triage`, `ioc_summary`, `executive_brief`
119	`generate_vex_report`	Сгенерировать отчёт VEX (обмен информацией о эксплуатируемости уязвимостей)
120	`generate_sigma_rule`	Сгенерировать правила SIGMA для обнаружения

Направленные подсказки анализа (22 режима)

Подсказки представляют собой готовые рабочие процессы анализа, которые настраивают ИИ с использованием структурированной личности, последовательности использования инструментов по шагам и правил классификации доказательств. Вы активируете их, ссылаясь на имя подсказки в своём ИИ‑клиенте.

Анализ вредоносного ПО (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`	Анализ ransomware: анализ шифрования, оценка восстановления ключа
`code_similarity_mode`	Сравнение бинарников на сходство кода и общее происхождение

Исследование безопасности (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 и разработка эксплойтов (5 подсказок)

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

Прочее (2 подсказки)

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

Как работают промпты: Каждый промпт «подготавливает» ИИ с помощью структурированного анализа персоны. Он включает контрольные точки цепочки мыслей (Chain-of-Thought) (где ИИ должен остановиться и оценить перед продолжением) и правила классификации доказательств, которые не позволяют ИИ выдавать спекуляции за факт. Каждое обнаружение должно быть помечено как OBSERVED (прямо проверено), INFERRED (логически выведено из статического анализа) или POSSIBLE (требует дальнейшей проверки).

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

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

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

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

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

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

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

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

Вариант 1 — PyPI (Самый простой)

pip install reversecore-mcp
reversecore-mcp

Требования: Radare2 должен быть установлен в вашей системе (r2 --version). YARA устанавливается автоматически через yara-python.

Вариант 2 — Docker (Рекомендуется для полной функциональности)

Все движки анализа (Radare2, r2ghidra, YARA, Binwalk, Sleuth Kit, GDB и др.) предустановлены:

docker run -i --rm \
  -v /path/to/your/samples:/app/workspace \
  -e REVERSECORE_WORKSPACE=/app/workspace \
  -e MCP_TRANSPORT=stdio \
  ghcr.io/sjkim1127/reversecore_mcp:latest

Вариант 3 — Сборка из исходников (Docker Compose)

git clone https://github.com/sjkim1127/Reversecore_MCP.git
cd Reversecore_MCP
./scripts/run-docker.sh        # auto-detects Intel / Apple Silicon

Или вручную:

docker compose --profile x86 up -d    # Intel/AMD
docker compose --profile arm64 up -d  # Apple Silicon (M1/M2/M3)

Вариант 4 — Python (Локальная разработка)

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

Требования для локального режима: Radare2 должен быть установлен в вашей системе (r2 --version). Индивидентные бэкенды инструментов (YARA, LIEF, Capstone и др.) устанавливаются через pip. Для полной поддержки форензики также потребуются Volatility3, Scapy и Sleuth Kit.

Подключение к вашему ИИ-клиенту

Добавьте конфигурацию сервера в настройки клиента вашей IDE (например, ~/.cursor/mcp.json или claude_desktop_config.json).

⚡ Вариант 1: Режим exec Docker (Рекомендуется)

Если вы запустили контейнер через Docker Compose, этот режим перенаправляет stdio прямо в работающий контейнер. Нулевая задержка запуска, постоянная память и полная доступность инструментов.

{
  "mcpServers": {
    "Reversecore_MCP": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "-e",
        "MCP_TRANSPORT=stdio",
        "reversecore-mcp-arm64",
        "python",
        "-m",
        "reversecore_mcp.server"
      ]
    }
  }
}

Замените reversecore-mcp-arm64 на reversecore-mcp, если вы используете Intel/AMD.

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

Для потоковой передачи по сети (Server-Sent Events):

{
  "mcpServers": {
    "Reversecore_MCP": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

📦 Вариант 3: Режим Stdio (Docker по требованию)

Запускает свежий изолированный контейнер для каждой сессии:

🍎 macOS

{
"mcpServers": {
  "reversecore": {
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-v", "/Users/YOUR_USERNAME/samples:/app/workspace",
      "-e", "REVERSECORE_WORKSPACE=/app/workspace",
      "-e", "MCP_TRANSPORT=stdio",
      "ghcr.io/sjkim1127/reversecore_mcp:latest"
    ]
  }
}
}

🐧 Linux

{
"mcpServers": {
  "reversecore": {
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-v", "/home/YOUR_USERNAME/samples:/app/workspace",
      "-e", "REVERSECORE_WORKSPACE=/app/workspace",
      "-e", "MCP_TRANSPORT=stdio",
      "ghcr.io/sjkim1127/reversecore_mcp:latest"
    ]
  }
}
}

🪟 Windows

{
"mcpServers": {
  "reversecore": {
    "command": "docker",
    "args": [
      "run", "-i", "--rm",
      "-v", "C:/samples:/app/workspace",
      "-e", "REVERSECORE_WORKSPACE=/app/workspace",
      "-e", "MCP_TRANSPORT=stdio",
      "ghcr.io/sjkim1127/reversecore_mcp:latest"
    ]
  }
}
}

⚠️ Важно — Пути файлов внутри Docker

Ваша локальная папка смонтирована в /app/workspace внутри контейнера. Всегда ссылайтесь на файлы только по имени файла, а не по вашему полному локальному пути.

❌ Неправильно ✅ Правильно

r2_decompile("/Users/john/samples/mal.exe") r2_decompile("mal.exe")

❌ Неправильно	✅ Правильно
`r2_decompile("/Users/john/samples/mal.exe")`	`r2_decompile("mal.exe")`

Конфигурация

Все настройки можно задать через переменные окружения или файл .env (см. .env.example). Настройки управляются через Pydantic BaseSettings с префиксом REVERSECORE_.

Основные настройки

Переменная	Значение по умолчанию	Описание
`MCP_TRANSPORT`	`stdio`	Режим транспорта: `stdio` или `http`
`REVERSECORE_WORKSPACE`	`./` (текущая директория)	Каталог рабочей области анализа
`REVERSECORE_READ_DIRS`	`""`	Список дополнительных каталогов только для чтения, разделённых запятыми
`REVERSECORE_STRICT_PATHS`	`false`	Генерировать ошибки при отсутствующих путях вместо предупреждений
`REVERSECORE_STRUCTURED_ERRORS`	`false`	Включить структурированные ответы об ошибках с кодами ошибок
`REVERSECORE_DEFAULT_TOOL_TIMEOUT`	`120`	Таймаут выполнения инструмента по умолчанию в секундах
`REVERSECORE_MAX_OUTPUT_SIZE`	`10000000`	Максимальный размер вывода инструментов (в байтах)

Настройки режима HTTP

Переменная	Значение по умолчанию	Описание
`MCP_HOST`	`0.0.0.0`	Интерфейс хоста для привязки (автоматически переопределяется на `127.0.0.1`, если нет API ключа)
`MCP_PORT`	`8000`	Порт для HTTP сервера
`MCP_API_KEY`	(unset)	Ключ API для аутентификации HTTP (`X-API-Key` или `Authorization: Bearer`)
`REVERSECORE_RATE_LIMIT`	`60`	Максимальное число запросов в минуту (только режим HTTP, через slowapi)
`MAX_UPLOAD_SIZE`	`100000000`	Максимальный размер загружаемого файла (по умолчанию 100 МБ)
`FILE_RETENTION_MINUTES`	`1440`	Срок хранения загруженных файлов (по умолчанию 24 ч)

Настройки Radare2

Переменная	Значение по умолчанию	Описание
`REVERSECORE_R2_POOL_SIZE`	`3`	Число соединений Radare2 в пуле
`REVERSECORE_R2_POOL_TIMEOUT`	`30`	Таймаут получения соединения из пула
`REVERSECORE_R2_EXTENSIONS`	`""`	Список через запятую классов расширений r2 (`module:ClassName`)
`REVERSECORE_GHIDRA_MAX_PROJECTS`	`3`	Максимальное количество кешированных проектов декомпилятора r2ghidra
`REVERSECORE_GHIDRA_EXTENSIONS`	`""`	Список через запятую классов расширений Ghidra
`MAX_EMULATION_INSTRUCTIONS`	`1000`	Максимальное число инструкций эмуляции ESIL

Настройки песочницы

Переменная	Значение по умолчанию	Описание
`REVERSECORE_SANDBOX_ENABLED`	`false`	Включить выполнение в песочнице для динамических аналитических инструментов
`REVERSECORE_SANDBOX_MODE`	`auto`	Режим песочницы: `auto`, `host`, `container`, `disabled`
`REVERSECORE_SANDBOX_DOCKER_IMAGE`	`reversecore-sandbox:latest`	Docker-образ для выполнения в песочнице
`REVERSECORE_SANDBOX_CPU_LIMIT`	`1.0`	Лимит ядер CPU для контейнеров песочницы
`REVERSECORE_SANDBOX_MEMORY_LIMIT`	`512m`	Лимит памяти для контейнеров песочницы
`REVERSECORE_SANDBOX_PIDS_LIMIT`	`100`	Лимит PID для контейнеров песочницы
`REVERSECORE_SANDBOX_USER`	`nobody`	Пользователь без прав root для выполнения в песочнице

Хранилище и очередь

Переменная	Значение по умолчанию	Описание
`REDIS_URL`	`redis://localhost:6379/0`	URL Redis для очереди задач и кэширования результатов
`MEMORY_DB_PATH`	`~/.reversecore_mcp/memory.db`	Путь к базе данных SQLite памяти AI
`REVERSECORE_LIEF_MAX_FILE_SIZE`	`1000000000`	Максимальный размер файла для разбора LIEF (1 ГБ)

Журналирование

Переменная	Значение по умолчанию	Описание
`LOG_LEVEL`	`INFO`	Уровень детализации логов: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`LOG_FILE`	`<tempdir>/reversecore/app.log`	Путь к файлу лога
`LOG_FORMAT`	`human`	Формат лога: `human` (читаемый) или `json` (структурированный)

Плагины и SAST

Переменная	Значение по умолчанию	Описание
`REVERSECORE_PLUGIN_DIRS`	`""`	Список через запятую директорий для сканирования в поиске плагинов расширений
`REVERSECORE_SAST_RULES_PATH`	`""`	Путь к файлу пользовательских правил SAST в формате YAML

Модель безопасности

Безопасность реализована в виде защиты в глубине, с защитой на нескольких уровнях:

Безопасность ввода и путей

Контроль	Реализация
Отсутствие инъекции оболочки	Все вызовы subprocess используют список аргументов, никогда не строки оболочки (`execution.py`)
Предотвращение обхода пути	Функции `validate_file_path()` и `validate_binary_path()` разрешают символические ссылки и ограничивают доступ рабочей областью (`validators.py`)
Смягчение TOCTOU	Флаг `bypass_cache=True` повторно проверяет пути для предотвращения условий гонки
Очистка ввода	Все параметры очищаются перед выполнением (`security.py`)
Защита от CSRF	Формы дашборда требуют валидации CSRF на основе токенов (`dashboard/__init__.py`)

Сеть и аутентификация

Контроль	Реализация
Аутентификация, безопасная против timing-атак	`secrets.compare_digest()` для сравнения ключа API (`web/auth.py`)
Ограниченные векторы аутентификации	Принимаются только заголовки `X-API-Key` и `Authorization: Bearer`; параметры запроса и cookies не используются
Fallback только на loopback	При отсутствии `MCP_API_KEY` доступ к HTTP ограничен `127.0.0.1` (`web/middleware.py`)
Ограничение скорости	Настраиваемые лимиты в минуту через slowapi
Заголовки безопасности	HSTS, X-Content-Type-Options, X-Frame-Options, CSP во всех HTTP-ответах (`web/middleware.py`)
Сведённый к минимуму endpoint `/health`	Публичный эндпоинт возвращает только `{"status": "alive"}`; детали доступны только после аутентификации (`web/endpoints.py`)

Контейнер и время выполнения

Контроль	Реализация
Выполнение без прав root	Запуск от пользователя `appuser` (UID 1000) с минимальными возможностями
Ограничения ресурсов	Docker Compose enforces limits CPU (2.0) и памяти (4 ГБ)
Изоляция песочницы	Опциональная изоляция на основе контейнеров для динамических аналитических инструментов

CI/CD Security Gates

Control	Implementation
Сканирование секретов	Gitleaks запускается при каждом коммите (pre-commit хук + CI)
SAST	Bandit сканирует весь Python‑код при каждом коммите
CodeQL	GitHub CodeQL статический анализ при каждом пуше в `main`
Аудит зависимостей	pip-audit при каждом пуше — нет непроверенных CVE
Сканирование контейнеров	Trivy сканирует Docker‑образы на уязвимости (от LOW до CRITICAL)
Шлюз безопасности эксплойтов	POC‑шаблоны сканируются Bandit; фаззинг DAST через Hypothesis; проверяется изоляция контейнера

Структурированная обработка ошибок

Все 17 классов исключений несут коды ошибок RCMCP-E* для программной обработки. Подробную иерархию см. в разделе Error Handling.

Разработка

Настройка

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
pip install -r requirements-dev.txt
pre-commit install   # installs Ruff, Bandit, Gitleaks hooks

Тестирование

# 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

Статус тестов: - ✅ 1 957 unit tests проходят на Python 3.10 / 3.11 / 3.12 - 📊 87% покрытия кода (минимум 80% обеспечивается в CI) - 🔒 Нулевые выводы Bandit - ⚡ Полностью асинхронный набор тестов через pytest-asyncio

Маркеры тестов:

Маркер	Назначение
`@pytest.mark.unit`	Быстрые unit‑тесты
`@pytest.mark.integration`	Тесты, требующие Docker или внешних инструментов
`@pytest.mark.slow`	Долгоrunning тесты
`@pytest.mark.benchmark`	Производительные бенчмарки
`@pytest.mark.security`	Тесты проверки границ безопасности

Качество кода

ruff check reversecore_mcp/      # Lint (E, W, F, I, B, C4, UP rules)
ruff format reversecore_mcp/     # Format
mypy reversecore_mcp/            # Type check (0 errors across 108 files)
bandit -r reversecore_mcp/       # Security scan (all severities)
pip-audit                        # Dependency CVE scan

Pre-commit хуки

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

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

CI/CD Pipeline

Каждый пуш в 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

Политика нулевого обхода: сбои в CI/CD никогда не решаются изменением конфигурации пайплайна. Основные причины всегда исправляются непосредственно в исходном коде или зависимостях.

Архитектura сборки Docker

Сборка Docker использует двухслойный подход, чтобы время сборки оставалось управляемым.

Слой 1: Базовый образ (`Dockerfile.base`)

Многоэтапная сборка, компилирующая все медленно собирающиеся, редко меняющиеся зависимости из исходников:

compiler-toolchain (python:3.12-slim-bookworm + build tools)
    ├── compiler-yara      (YARA 4.3.1 from source)     [parallel]
    ├── compiler-r2        (Radare2 6.0.4 from source)   [parallel]
    │     └── compiler-r2ghidra  (r2ghidra plugin)       [sequential]
    └── compiler-pip       (pip install into /opt/venv)  [parallel]

base (final runtime: python:3.12-slim-bookworm)
    ├── Runtime packages: file, binutils, gdb, binwalk, graphviz, nasm, sleuthkit
    ├── /opt/yara (compiled YARA)
    ├── /opt/radare2 (compiled r2 + r2ghidra)
    ├── /opt/venv (Python packages)
    └── Non-root user: appuser (UID 1000)

Этот образ пересобирается только при изменении версий инструментов. Время сборки: ~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"]

Время сборки: ~60 секунд.

Docker Compose

Три сервиса с профилями, специфичными для архитектуры:

Service	Profile	Description
`reversecore-mcp`	`default`, `x86`	Intel/AMD x86_64
`reversecore-mcp-arm64`	`arm64`, `macos`	Apple Silicon ARM64
`redis`	all profiles	Redis 7 Alpine для очереди задач и кеширования

Ограничения ресурсов: 2,0 ядра CPU, 4 ГБ памяти на контейнер.

Требования к системе

Component	Minimum	Recommended
CPU	4 ядра	8+ ядер
RAM	8 ГБ	16 ГБ
Хранилище	20 ГБ	50 ГБ SSD
ОС	Linux / macOS	Среда Docker (любая ОС)
Docker	20.10+	24.0+
Python (локальный режим)	3.10	3.11 или 3.12

Структура проекта

reversecore_mcp/
├── core/                          # Infrastructure layer (37 modules)
│   ├── config.py                  # Pydantic BaseSettings (34+ env vars)
│   ├── exceptions.py              # Exception hierarchy (17 classes, RCMCP-E* codes)
│   ├── security.py                # Input sanitization & command arg validation
│   ├── validators.py              # Path validators (TOCTOU-hardened, symlink-safe)
│   ├── r2_pool.py                 # Thread-safe Radare2 connection pool
│   ├── r2_helpers.py              # Structured Radare2 output parsing
│   ├── metrics.py                 # Per-tool timing, counts, error rates, cache stats
│   ├── decorators.py              # @log_execution, @track_metrics
│   ├── error_handling.py          # @handle_tool_errors decorator
│   ├── error_formatting.py        # Structured error formatting
│   ├── execution.py               # Safe subprocess with timeout/output limits
│   ├── command_spec.py            # Command specifications
│   ├── memory.py                  # Async SQLite AI memory store
│   ├── mitre_mapper.py            # MITRE ATT&CK mapping engine
│   ├── evidence.py                # Evidence classification (OBSERVED/INFERRED/POSSIBLE)
│   ├── resilience.py              # Retry, circuit-breaker, timeout patterns
│   ├── task_queue.py              # Background task queue (Redis + arq)
│   ├── extension_registry.py      # Plugin registration system
│   ├── arch_registry.py           # Multi-arch mapping (x86/ARM/MIPS/RISC-V/PPC)
│   ├── result_cache.py            # SHA256-based tool result caching
│   ├── analysis_cache.py          # Multi-level decompilation cache (Redis + SQLite)
│   ├── result.py                  # ToolSuccess / ToolError Pydantic models
│   ├── loader.py                  # Dynamic tool module loader
│   ├── plugin.py                  # Plugin base class
│   ├── extension.py               # Extension base class
│   ├── container.py               # Container/sandbox execution
│   ├── audit.py                   # Audit logging
│   ├── binary_cache.py            # Binary file caching
│   ├── json_utils.py              # orjson-backed JSON (3-5x faster)
│   ├── logging_config.py          # Loguru logging configuration
│   ├── report_generator.py        # Report rendering (Markdown, PDF)
│   ├── resource_manager.py        # MCP resource lifecycle
│   └── sast/                      # Source code scanners
│       ├── python_ast_scanner.py  # Python AST vulnerability scanner
│       ├── regex_scanner.py       # C/C++ regex vulnerability scanner
│       ├── rule_manager.py        # SAST rule loader
│       └── default_rules.yaml     # Default scanning rules
│
├── tools/                         # MCP tool implementations (120 tools)
│   ├── analysis/                  # Static analysis (24 tools)
│   │   ├── static_analysis.py     # file, strings, binwalk
│   │   ├── lief_tools.py          # LIEF binary parser
│   │   ├── capa_tools.py          # CAPA capability detection
│   │   ├── die_tools.py           # Detect It Easy packer detection
│   │   ├── diff_tools.py          # Binary diffing
│   │   ├── emulation_tools.py     # ESIL emulation
│   │   ├── fuzz_tools.py          # Fuzzing harness generator
│   │   ├── fuzzing_campaign.py    # Full fuzzing campaign runner
│   │   ├── symbolic_analysis.py   # angr symbolic execution
│   │   ├── signature_tools.py     # Library signature matching
│   │   ├── source_auditor.py      # SAST (Python + C/C++)
│   │   ├── crash_triage.py        # GDB crash triage
│   │   ├── taint_analysis.py      # Source→sink taint tracing
│   │   ├── advanced_yara.py       # Advanced YARA generation
│   │   ├── patch_vuln_inference.py # Patch vulnerability inference
│   │   └── cache_tools.py         # Analysis cache management
│   │
│   ├── radare2/                   # Disassembly & decompilation (30 tools)
│   │   ├── radare2_mcp_tools.py   # Core Radare2 tool set
│   │   ├── r2ghidra_tools.py      # r2ghidra decompiler (cached)
│   │   ├── r2_analysis.py         # Deep function analysis
│   │   ├── r2_db.py               # SQLite annotation + cache DB
│   │   ├── r2_esil_simulator.py   # Multi-arch ESIL simulator
│   │   └── r2_session.py          # Stateful analysis sessions
│   │
│   ├── malware/                   # Threat detection (9 tools)
│   │   ├── dormant_detector.py    # Backdoor/logic bomb detection
│   │   ├── ioc_tools.py           # IOC extraction
│   │   ├── yara_tools.py          # YARA scanning
│   │   ├── adaptive_vaccine.py    # YARA rule + patch generation
│   │   ├── vulnerability_hunter.py # Dangerous API detection
│   │   ├── autonomous_hunter.py   # Autonomous vuln hunting pipeline
│   │   ├── heap_exploit.py        # Heap exploitation analysis
│   │   ├── poc_generator.py       # PoC exploit generation
│   │   └── rop_builder.py         # ROP chain construction
│   │
│   ├── forensics/                 # Digital forensics (22 tools)
│   │   ├── memory.py              # Volatility3 memory forensics
│   │   ├── network.py             # Scapy PCAP analysis
│   │   ├── disk.py                # Sleuth Kit disk forensics
│   │   └── artifact.py            # Browser/registry/event log analysis
│   │
│   ├── report/                    # Report generation (14 tools)
│   │   ├── report_mcp_tools.py    # MCP-registered report tools
│   │   ├── report_tools.py        # Report rendering logic
│   │   ├── session.py             # Session state management
│   │   ├── converter.py           # Format conversion (Markdown → PDF/HTML)
│   │   ├── email.py               # SMTP report delivery
│   │   ├── sigma_generator.py     # SIGMA rule generation
│   │   └── vex_generator.py       # VEX report generation
│   │
│   └── common/                    # Shared utilities (20 tools)
│       ├── file_operations.py     # File ops, workspace management
│       ├── server_tools.py        # Server health, tool metrics
│       ├── memory_tools.py        # AI memory management (11 tools)
│       ├── patch_explainer.py     # Binary patch explanation
│       └── assembler.py           # Keystone assembler
│
├── prompts/                       # AI reasoning prompts (22 modes)
│   ├── malware.py                 # 9 malware analysis prompts
│   ├── security.py                # 6 security research prompts
│   ├── cve_research.py            # 5 CVE/exploit research prompts
│   ├── game.py                    # Game client analysis prompt
│   ├── report.py                  # Report generation prompt
│   ├── server_health.py           # Server inspection prompts
│   └── common.py                  # Shared constants (DOCKER_PATH_RULE, LANGUAGE_RULE)
│
├── dashboard/                     # Web dashboard (FastAPI + HTMX)
│   ├── templates/                 # Jinja2 templates with HTMX fragments
│   └── static/                    # htmx.min.js (local, CSP-compliant)
│
├── web/                           # HTTP transport layer
│   ├── auth.py                    # API key authentication middleware
│   ├── middleware.py              # Security headers, loopback restriction
│   └── endpoints.py               # /health, file upload, dashboard routes
│
├── resources.py                   # 11 MCP resources (static + dynamic per-binary)
└── server.py                      # FastMCP server entry point

Другие каталоги:

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

Обработка ошибок

Все пользовательские исключения наследуются от ReversecoreError и несут структурированные коды ошибок:

Exception	Code	Type	When
`ReversecoreError`	`RCMCP-E000`	`UNKNOWN_ERROR`	Базовый класс для всех ошибок
`ValidationError`	`RCMCP-E001`	`VALIDATION_ERROR`	Неверный ввод, плохие параметры
`ExecutionTimeoutError`	`RCMCP-E002`	`TIMEOUT_ERROR`	Инструмент превысил таймаут
`ToolNotFoundError`	`RCMCP-E003`	`TOOL_ERROR`	Требуемый CLI‑инструмент не установлен
`OutputLimitExceededError`	`RCMCP-E004`	`OUTPUT_ERROR`	Выход превысил максимальный размер
`ToolExecutionError`	`RCMCP-E005`	`EXECUTION_ERROR`	Подпроцесс вернул ненулевой код
`BinaryAnalysisError`	`RCMCP-E100`	`BINARY_ANALYSIS_ERROR`	Общая ошибка бинарного анализа
`DecompilationError`	`RCMCP-E101`	`DECOMPILATION_ERROR`	Декомпиляция r2ghidra не удалась
`DisassemblyError`	`RCMCP-E102`	`DISASSEMBLY_ERROR`	Дизассемблирование Radare2 не удалось
`StructureRecoveryError`	`RCMCP-E103`	`STRUCTURE_RECOVERY_ERROR`	Восстановление структуры C не удалось
`SignatureGenerationError`	`RCMCP-E104`	`SIGNATURE_GENERATION_ERROR`	Генерация YARA/сигнатур не удалась
`EmulationError`	`RCMCP-E105`	`EMULATION_ERROR`	Эмуляция ESIL не удалась
`ToolTimeoutError`	`RCMCP-E200`	`TOOL_TIMEOUT_ERROR`	Внешний инструмент исчерпал таймаут
`GhidraConnectionError`	`RCMCP-E201`	`GHIDRA_CONNECTION_ERROR`	Проблема соединения r2ghidra
`Radare2Error`	`RCMCP-E202`	`RADARE2_ERROR`	Команда Radare2 завершилась с ошибкой
`WorkspaceError`	`RCMCP-E300`	`WORKSPACE_ERROR`	Ошибка доступа к файлу рабочего пространства
`SecurityViolationError`	`RCMCP-E301`	`SECURITY_VIOLATION`	Нарушение политики безопасности
`PathTraversalError`	`RCMCP-E302`	`PATH_TRAVERSAL`	Обнаружена попытка path traversal

Клиенты ИИ могут использовать поле error_code для программной обработки сбоев и решения, повторять ли попытку, использовать альтернативный инструмент или сообщать об ошибке пользователю.

Добавление новых инструментов

Следуйте этому шаблону, чтобы добавить новый инструмент MCP:

# reversecore_mcp/tools/analysis/my_tool.py

from reversecore_mcp.core.decorators import log_execution
from reversecore_mcp.core.result import ToolResult, success, failure
from reversecore_mcp.core.security import validate_file_path


@log_execution()
async def my_analysis_tool(
    file_path: str,
    option: str | None = None,
) -> ToolResult:
    """Analyze a binary for X.

    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/.

Вклад

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

Пожалуйста, ознакомьтесь с руководством по contributingu по стандартам кода, соглашениям о docstring (Google-style) и чеклисту pull request.

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

Документ	Описание
Руководство по установке	Подробная настройка для всех окружений
Руководство по архитектуре	Проект системы и детали компонентов
Руководство по contributingu	Стандарты кода, docstring, workflow PR
Руководство по тестированию	Паттерны тестов, фикстуры и покрытие
Справочник API	Справочник инструментов и модулей
Руководство пользователя	Рабочие процессы анализа

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

Пример 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..."

Пример 2: Исследование уязвимостей с анализом загрязнения

User: "Find exploitable bugs in this network daemon"

AI activates: taint_analysis_mode

AI calls:
  1. taint_trace("daemon", verify_with_angr=True)
     → Found 3 source→sink paths:
       recv() → strcpy()   [CWE-120, CONFIRMED by angr]
       read() → sprintf()  [CWE-134, LIKELY]
       getenv() → system() [CWE-78, POSSIBLE]

  2. vulnerability_hunter("daemon")
     → 12 dangerous API calls, 4 exploitable patterns

  3. generate_poc_exploit(target="daemon", vuln_type="bof", offset=128)
     → Python exploit script generated

AI response: "I found a confirmed stack buffer overflow where recv() data
flows directly into strcpy() at 0x40123C. angr proved the path is reachable.
Here's a working PoC..."

Пример 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

Пример 4: Сравнение патчей для исследований уязвимостей нулевого дня

User: "Compare the patched and unpatched versions to find what was fixed"

AI activates: patch_diff_auto_mode

AI calls:
  1. diff_binaries("libfoo-1.0.so", "libfoo-1.1.so")
     → 3 functions changed, 1 new function

  2. patch_diff_1day("libfoo-1.0.so", "libfoo-1.1.so")
     → Automated analysis: bounds check added at parse_header()

  3. r2_decompile("libfoo-1.0.so", "parse_header")
     → Decompiled vulnerable version (no bounds check)

  4. r2_decompile("libfoo-1.1.so", "parse_header")
     → Decompiled patched version (memcpy size limited)

AI response: "The patch adds a bounds check in parse_header() at 0x12340.
The old version copies user-controlled length bytes via memcpy without
validation, creating a heap buffer overflow (CWE-122)."

Поддержка множества архитектур

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

Архитектура	Ключ	r2 Архитектура	Разрядности	Регистр PC	Регистр SP
Intel 32-бит	`x86`	`x86`	32	`eip`	`esp`
Intel/AMD 64-бит	`x86_64`	`x86`	64	`rip`	`rsp`
ARM 32-бит / Thumb	`arm32`	`arm`	16, 32	`r15`	`r13`
ARM 64-бит (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}" )

Бэкенд хранения: база данных SQLite через r2_db.py, доступная через инструменты get_cached_result() и set_cached_result().

Метрики: попадания и пропуски кэша отслеживаются через metrics_collector.record_cache_hit() и record_cache_miss(), видимые через инструмент get_tool_metrics.

Кэш анализа (`analysis_cache.py`)

Многоуровневый кэш специально для результатов декомпиляции (которые дороги в вычислениях):

Уровень	Бэкенд	Формат ключа	TTL	Назначение
L1	Redis	`ghidra:decompile:{file_hash}:{function_address}:{decompiler}`	1 час (3600с)	Быстрый, совместно используемый между сеансами
L2	SQLite	Таблица `decompilation_cache`	Постоянный	Переживает перезапуски Redis

Импорт/Экспорт: инструменты export_analysis_cache и import_analysis_cache позволяют сохранять состояние кэша в/из файлов rcpack для обмена между средами.

Система памяти ИИ

Система памяти ИИ (memory_tools.py + core/memory.py) обеспечивает постоянное, запрашиваемое хранилище для результатов анализа между сеансами. Это позволяет ИИ:

Запоминать то, что ранее было обнаружено о бинарнике
Перекрёстно ссылаться на результаты между разными образцами
Тегировать и искать сессии по теме, семейству вредоносного ПО или технике

Как это работает

create_memory_session("analysis of ransomware sample")
    │
    ├── store_analysis_finding("Found AES-256 encryption at 0x401000", tags=["crypto", "ransomware"])
    ├── store_analysis_finding("C2 beacon interval: 30 seconds", tags=["c2", "network"])
    └── tag_analysis_session(tags=["ransomware", "financial-sector"])

# Later, in a different session:
query_analysis_memories("ransomware encryption")
    → Returns previous findings about ransomware encryption patterns

get_binary_analysis_context("sample.exe")
    → Returns all findings ever recorded for this binary

Хранилище: Асинхронная база данных SQLite по пути, заданному в MEMORY_DB_PATH (по умолчанию: ~/.reversecore_mcp/memory.db).

Переносимость: Используйте export_memory_store и import_memory_store для переноса всей базы данных памяти между окружениями.

Веб-панель

При запуске в HTTP-режиме (MCP_TRANSPORT=http) веб-панель доступна по адресу http://localhost:8000/dashboard. Она предоставляет:

Загрузка бинарника с перетаскиванием
Статус анализа в реальном времени
Интерактивный список функций и дизассемблерный вид
Результаты извлечения IOC
Мониторинг состояния сервера

Стек технологий: FastAPI + шаблоны Jinja2 + HTMX (загружается локально из dashboard/static/, отсутствие зависимости от CDN для соответствия CSP).

Особенности безопасности: - CSRF токены во всех формах, изменяющих состояние - Автоэкранирование Jinja2 включено - Ввод пользователя очищается через html.escape() перед отображением - Защита от пути обхода через validate_file_path()

Развёртывание

Контрольный список для продакшена

Перед развёртыванием в продакшене:

Элемент	Как
Установить ключ API	`MCP_API_KEY=<strong-random-key>`
Использовать непривилегированного пользователя	Встроено: контейнер запускается от `appuser` (UID 1000)
Установить лимиты ресурсов	По умолчанию: 2 CPU / 4 GB RAM в `docker-compose.yml`
Включить структурированное логирование	`LOG_FORMAT=json` для агрегации логов
Настроить Redis	`REDIS_URL=redis://<host>:6379/0` для очереди задач и кэширования
Установить путь рабочей области	`REVERSECORE_WORKSPACE=/path/to/isolated/directory`
Проверить лимиты скорости	`REVERSECORE_RATE_LIMIT=60` (запросов/мин, при необходимости отрегулировать)
Включить песочницу	`REVERSECORE_SANDBOX_ENABLED=true` для изоляции динамического анализа

Проверки состояния

Сервер предоставляет HTTP endpoints проверки состояния для оркестрации:

# 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

Эти конечные точки освобождены от аутентификации по API key, поэтому балансировщики нагрузки и оркестраторы контейнеров могут их опрашивать.

Проверка состояния контейнера

Образ Docker содержит встроенную инструкцию HEALTHCHECK, которая проверяет TCP-подключение к порту 8000 каждые 30 секунд. Docker и Kubernetes автоматически перезапускают нездоровые контейнеры.

Устранение неполадок

Распространённые проблемы

Инструмент возвращает RCMCP-E003: Инструмент не найден

Необходимый CLI-инструмент не установлен в окружении.

Решение: Если используется Docker, проверьте, что инструмент присутствует в базовом образе:

docker exec reversecore-mcp-arm64 which r2 yara binwalk tsk_recover gdb

Если используется локальная установка Python, установите недостающий инструмент:

# macOS
brew install radare2 yara binwalk sleuthkit

# Ubuntu/Debian
apt install radare2 yara binwalk sleuthkit

Ошибка таймаута (RCMCP-E002 / RCMCP-E200)

Анализ превысил настроенный таймаут.

Решение: Увеличьте таймаут:

export REVERSECORE_DEFAULT_TOOL_TIMEOUT=300  # 5 minutes

Для больших бинарников (>100 МБ) рассмотрите использование быстрых вариантов сканирования: - run_capa_quick вместо run_capa - detect_packer вместо detect_packer_deep

Ошибка обхода пути (RCMCP-E302)

Вы сослались на файл вне рабочей директории.

Решение: Сначала скопируйте файл в рабочую директорию:

copy_to_workspace("/path/to/file.exe")

Или смонтируйте дополнительные каталоги как только для чтения:

export REVERSECORE_READ_DIRS=/opt/samples,/mnt/evidence

Контейнер Docker не запускается на Apple Silicon

Убедитесь, что вы используете профиль ARM64:

docker compose --profile arm64 up -d

Или используйте скрипт автоматического определения:

./scripts/run-docker.sh

Отказ в подключении к Redis

Очередь задач требует запущенного экземпляра Redis.

Решение: Запустите Redis вместе с основным сервисом:

docker compose --profile arm64 up -d   # Starts both reversecore and redis

Или отключите функции, зависящие от Redis, не задавая переменную REDIS_URL.

Декомпиляция r2ghidra даёт пустой вывод

Это обычно означает, что функция не была проанализирована сначала.

Решение: Выполните анализ перед декомпиляцией:

Radare2_analyze_binary("sample.exe")
Radare2_decompile_function("sample.exe", "main")

Часто задаваемые вопросы

Заменяет ли это Ghidra или IDA Pro?

Нет. Этот проект является дополнением, а не заменой. Он использует r2ghidra (встроенный в Radare2 движок декомпиляции Ghidra) для декомпиляции. Он не предоставляет GUI и не имеет интерактивного рабочего процесса анализа полноценного дизассемблера. Его цель — позволить ИИ-ассистентам выполнять задачи анализа программно.

Требуется ли отдельная установка Ghidra или JDK?

Нет. Плагин r2ghidra непосредственно внедряет движок декомпиляции Ghidra внутрь Radare2. Не нужен JDK, не нужна установка Ghidra, не нужны файлы проекта Ghidra. Достаточно иметь r2 со скомпилированным плагином r2ghidra.

Какие клиенты MCP поддерживаются?

Любой клиент, реализующий спецификацию Model Context Protocol. Протестировано с: Claude Desktop, Cursor, Windsurf и Google Antigravity. Сервер поддерживает как транспорт stdio, так и HTTP/SSE.

Можно ли анализировать файлы Windows PE в Linux/macOS?

Да. Статический анализ (дизассемблирование, декомпиляция, извлечение строк, извлечение IOC, сканирование YARA) работает с любым форматом файла независимо от ОС хоста. Динамический анализ (эмуляция, фаззинг) может иметь ограничения в зависимости от целевой архитектуры.

Насколько безопасно анализировать вредоносное ПО с помощью этого инструмента?

Контейнер Docker обеспечивает изоляцию: пользователь без прав root, по умолчанию без сети в CI, ограничения ресурсов. Для анализа живого вредоносного ПО мы рекомендуем запускать в выделенной виртуальной машине или использовать функцию песочницы (REVERSECORE_SANDBOX_ENABLED=true). Статические инструменты анализа (r2, YARA, strings) никогда не исполняют целевой бинарный файл.

Какой максимальный размер файла?

Лимиты по умолчанию: - Загрузка: 100 МБ (MAX_UPLOAD_SIZE) - Парсинг LIEF: 1 ГБ (REVERSECORE_LIEF_MAX_FILE_SIZE) - Вывод инструмента: 10 МБ (REVERSECORE_MAX_OUTPUT_SIZE)

Все лимиты можно настроить через переменные окружения.

Благодарности

Этот проект построен на работе многих open-source проектов:

Проект	Роль в Reversecore MCP
Radare2	Дизассемблирование, эмуляция, анализ бинарных файлов
r2ghidra	Движок декомпиляции Ghidra для Radare2
FastMCP	Фреймворк сервера MCP
YARA	Сопоставление шаблонов для обнаружения вредоносного ПО
LIEF	Анализ форматов бинарных файлов (PE, ELF, Mach-O)
CAPA	Обнаружение возможностей Mandiant FLARE
angr	Движок символического выполнения
Capstone	Фреймворк дизассемблирования
Keystone	Фреймворк ассемблирования
pwntools	Набор инструментов для разработки эксплоитов
ROPgadget	Поисковик гаджетов ROP
Volatility3	Фреймворк анализа памяти в цифровой криминалистике
Scapy	Анализ сетевых пакетов
Sleuth Kit	Набор инструментов для анализа дисков в цифровой криминалистике
Binwalk	Анализ прошивки
Detect It Easy	Обнаружение упаковщиков/компиляторов

Лицензия

MIT — см. LICENSE для подробностей.

GitHub · PyPI · FastMCP Docs · MCP Spec · Radare2 · YARA

Reversecore_MCP