AI 어시스턴트는 이를 도구 호출로 나눕니다:```
r2_decompile("sample.exe", "main")
  → extract_iocs("sample.exe")
    → add_mitre_technique(technique_id="T1071.001", ...)
      → create_analysis_report(template_type="quick_triage")

### 핵심 인프라(37개 모듈)

`reversecore_mcp/core/` 디렉터리는 모든 도구가 기반으로 하는 공유 인프라를 포함합니다:

| 모듈 | 용도 |
|---|---|
| `config.py` | Pydantic BaseSettings 및 34개 이상의 환경 변수 |
| `security.py` | 입력 검증(sanitization), 명령 인수 검증 |
| `validators.py` | TOCTOU 완화 및 심볼릭 링크 해석을 포함한 파일·바이너리 경로 검증 |
| `r2_pool.py` | 크기 구성이 가능한 스레드 안전 Radare2 연결 풀 |
| `r2_helpers.py` | 구조화된 Radare2 출력 파싱 |
| `metrics.py` | 도구별 실행 시간, 호출 횟수, 오류율, 캐시 통계 |
| `memory.py` | 세션 간 분석 결과를 유지하기 위한 비동기 SQLite 기반 AI 메모리 저장소 |
| `mitre_mapper.py` | MITRE ATT&CK 기법 ID 매핑 엔진 |
| `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 → r2 arch/bits/registers) |
| `result_cache.py` | SHA256 기반 도구 결과 캐싱 데코레이터(`@cache_tool_result`) |
| `analysis_cache.py` | 다중 레벨 디컴파일 캐시(L1: Redis, L2: SQLite) |
| `result.py` | `ToolSuccess` / `ToolError` Pydantic 모델 |
| `exceptions.py` | `RCMCP-E*` 오류 코드를 가진 17개 예외 클래스 |
| `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` | orjson 기반 JSON 직렬화(stdlib json보다 3~5배 빠름) |
| `logging_config.py` | Loguru 기반 구조화 로깅 |
| `report_generator.py` | 보고서 렌더링 엔진(Markdown, xhtml2pdf를 통한 PDF) |
| `resource_manager.py` | MCP 리소스 수명주기 관리 |
| `sast/python_ast_scanner.py` | Python AST 기반 취약점 스캐너 |
| `sast/regex_scanner.py` | C/C++ 정규식 기반 취약점 스캐너 |
| `sast/rule_manager.py` | SAST 규칙 로딩 및 관리 |

---

## 도구 카탈로그(120개 도구)

모든 도구는 구조화된 `ToolResult`를 반환합니다. 즉, 타입이 지정된 `data`를 가진 `ToolSuccess` 또는 `RCMCP-E*` 오류 코드를 가진 `ToolError`입니다. 도구는 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) | 기능 탐지 — "데이터 암호화", "지속성 생성" 등 |
| 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 | 두 파일 버전 간 의미론적 바이너리 diff |
| 15 | `analyze_variant_changes` | Radare2 | 바이너리 변종 간 변경 사항 분석 |
| 16 | `match_libraries` | Radare2 | 함수 지문으로 정적으로 링크된 라이브러리 식별 |
| 17 | `patch_diff_1day` | Radare2 + heuristics | 1-day 취약점 연구를 위한 자동 패치 diff 분석 |
| 18 | `analyze_patch_diff_auto` | Radare2 + inference | 자동 패치 취약점 추론 |
| 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) 분석 |

---

### 🔐 소스 코드 감사 플러그인(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 등) |

**AI 메모리 관리(11개 도구)**

이 도구들은 비동기 SQLite 데이터베이스를 사용하여 AI가 분석 세션 전반에 걸쳐 결과를 유지하고 회상할 수 있게 합니다:

| # | 도구 | 설명 |
|---|---|---|
| 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 도구는 r2pipe 세션을 자동으로 관리하는 스레드 안전 연결 풀(`r2_pool.py`)을 사용합니다.

| # | 도구 | 설명 |
|---|---|---|
| 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로 디컴파일(r2에 내장된 Ghidra 엔진, 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 + 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 | 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 | 브라우저 기록, 레지스트리 하이브, 이벤트 로그, 프리페치 수집 |
| 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` | 서버 타임스탬프 가져오기(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` | 분류된 메모 추가(결과, 경고, 행동) |
| 116 | `add_mitre_technique` | MITRE ATT&CK 기법 ID 문서화 |
| 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개 모드)

프롬프트는 구조화된 페르소나, 단계별 도구 사용 시퀀스, 증거 분류 규칙으로 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` | 코드 유사성 및 공통 계보를 위한 바이너리 비교 |

### 보안 연구(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` | 1-day 취약점 연구를 위한 자동 패치 diff |
| `cve_discovery_pipeline_mode` | 전체 CVE 발견 파이프라인: 패치 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, 이메일, 해시) |
| `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(가장 간단함)```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

> Intel/AMD를 사용하는 경우 `reversecore-mcp-arm64`를 `reversecore-mcp`로 교체하세요.

---

### 🌐 옵션 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 Hooks)

다음 훅은 모든 커밋에서 자동으로 실행됩니다:

1. **Ruff** — 자동 수정 및 형식 검사를 포함한 린트
2. **trailing-whitespace** — 끝부분 공백 제거
3. **end-of-file-fixer** — 파일이 개행 문자로 끝나도록 보장
4. **check-yaml / check-json** — YAML/JSON 구문 검증
5. **check-added-large-files** — 1MB 초과 파일 차단
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.",
    )

Then register it in the appropriate plugin's `__init__.py` and add tests in `tests/unit/`.

---

## 기여

1. 저장소를 포크하세요
2. 기능 브랜치를 생성하세요: `git checkout -b feat/my-feature`
3. 코드와 함께 테스트를 작성하세요 — 커버리지는 80% 미만으로 떨어지면 안 됩니다
4. 모든 게이트가 통과하는지 확인하세요: `pytest`, `ruff check`, `mypy`, `bandit`
5. 명확한 설명과 함께 풀 리퀘스트를 여세요

코드 표준, docstring 규칙(Google 스타일), 풀 리퀘스트 체크리스트는 [기여 가이드](https://github.com/sjkim1127/reversecore_mcp/blob/HEAD/docs/development/contributing.md)를 읽어주세요.

---

## 문서

| 문서 | 설명 |
|---|---|
| [설치 가이드](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, PR 워크플로 |
| [테스트 가이드](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 구성 매개변수에 매핑하여 수동 구성 없이도 다양한 CPU 아키텍처에서 도구가 작동하도록 합니다:

| 아키텍처 | 키 | 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`
- `bits=64`인 `arm` → `arm64`
- `bits=16` 또는 `bits=32`인 `arm` → `arm32`

`Radare2_esil_emulate`, `assemble_instructions`, `r2_simulate_patch` 같은 도구는 이 레지스트리를 사용하여 모든 대상 바이너리에 맞게 분석 환경을 올바르게 구성합니다.

---

## 결과 캐시 시스템

두 개의 캐싱 계층이 중복 계산을 최소화합니다:

### 도구 결과 캐시 (`result_cache.py`)

`@cache_tool_result` 데코레이터는 바이너리 파일의 SHA256 해시와 도구의 키워드 인자를 기반으로 모든 도구의 출력을 캐시합니다:```
Cache key = SHA256( "<tool_name>::{sorted_json_kwargs}" )

**저장소:** `MEMORY_DB_PATH`에 설정된 경로의 비동기 SQLite 데이터베이스 (기본값: `~/.reversecore_mcp/memory.db`).

**이식성:** `export_memory_store`와 `import_memory_store`를 사용하여 전체 메모리 데이터베이스를 환경 간에 전송할 수 있습니다.

---

## 웹 대시보드

HTTP 모드(`MCP_TRANSPORT=http`)로 실행 중이면 `http://localhost:8000/dashboard`에서 웹 대시보드를 사용할 수 있습니다. 제공 기능:

- 드래그 앤 드롭 바이너리 업로드
- 실시간 분석 상태
- 대화형 함수 목록 및 디스어셈블리 뷰
- IOC 추출 결과
- 서버 상태 모니터링

**기술 스택:** FastAPI + Jinja2 템플릿 + HTMX (`dashboard/static/`에서 로컬로 로드, CSP 준수를 위해 CDN 의존성 없음).

**보안 기능:**
- 모든 상태 변경 폼에 대한 CSRF 토큰
- Jinja2 자동 이스케이프 활성화
- 모든 사용자 입력은 표시 전에 `html.escape()`로 정화됩니다.
- `validate_file_path()`를 통한 경로 순회 보호

---

## 배포

### 프로덕션 체크리스트

프로덕션에 배포하기 전에:

| 항목 | 방법 |
|---|---|
| API 키 설정 | `MCP_API_KEY=<strong-random-key>` |
| 비루트 사용자 사용 | 기본 제공: 컨테이너는 `appuser`(UID 1000)로 실행됩니다. |
| 리소스 제한 설정 | 기본값: `docker-compose.yml`에서 CPU 2개 / RAM 4GB |
| 구조화된 로깅 활성화 | 로그 집계를 위한 `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 상태 확인 엔드포인트를 제공합니다:```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