AI 에이전트(AI agents)에 의해 구동되는 자동화된 심층 악성코드 역공학 (Reverse Engineering). Kali 기반의 Docker 환경은 50개 이상의 RE 도구들을 MCP(Model Context Protocol)로 연결된 디스어셈블러 (Disassembler) 백엔드 (Binary Ninja 또는 Ghidra) 및 구조화된 다단계 오케스트레이터 (Orchestrator) 스킬과 결합하여, 인간의 개입 없이도 원시 바이너리 (Raw binary)를 순위가 매겨진 증거, 검증된 가설, 컴포넌트 맵 (Component maps), 그리고 우선순위가 지정된 심층 분석 계획이 담긴 케이스 디렉토리로 변환합니다. Claude Code 및 Codex CLI에서 즉시 사용 가능합니다.
배경 지식, 사례 연구 및 평가를 확인하려면 동반 블로그 포스트인 'Building a Pipeline for Agentic Malware Analysis'를 참조하십시오.
초기 악성코드 분석에는 해시 (Hashes) 및 컴파일러 아티팩트 (Compiler artifacts) 수집, 문자열 (Strings) 추출, 임포트 (Imports) 검사, YARA 및 capa 실행, 결과 상관관계 분석, 정밀 조사를 위한 코드 영역 식별 등 다수의 일상적인 단계가 포함됩니다. 이러한 단계들은 더 깊은 분석을 위한 기초를 제공하지만, 종종 반복적이고 시간이 많이 소요됩니다.
이 저장소는 해당 워크플로우의 상당 부분을 자동화합니다. 오케스트레이터 (Orchestrator) 스킬은 분석 아티팩트를 수집 및 정리하고, 관련 신호를 강조하며, 증거에 기반한 가설을 생성하고, 기본적인 컴포넌트 모델을 구축하며, 우선순위가 지정된 심층 분석 계획을 준비합니다. 모든 중간 결과는 디스크 상의 샘플별 케이스 디렉토리에 저장되어 워크플로우를 더 쉽게 재개하고 검토할 수 있습니다.
MCP를 통해 에이전트는 Binary Ninja 또는 Ghidra를 사용하여 함수를 검사하고, 교차 참조 (Cross-references)를 추적하며, 발견된 내용을 구체적인 코드 위치와 연결할 수 있습니다. 그 결과, 단순한 임시 분류 (Ad hoc triage)를 넘어 후속 분석을 위한 구조화된 시작점을 제공합니다.
- 50개 이상의 RE 및 악성코드 분석 도구가 포함된 Kali Linux 컨테이너
- 자동 MCP 백엔드 선택 (Binary Ninja 또는 Ghidra)
malware-analysis-orchestrator
Claude Code 및 Codex CLI를 위한 스킬 - strings, imports, YARA, capa, signal ranking, 가설 생성 (hypothesis generation)을 위한 헬퍼 스크립트
-
번들링된 YARA 규칙 (crypto, anti-debug/anti-VM, capabilities, packer -- Yara-Rules/rules 출처, GPL-2.0)
-
공격적인 기본값 (aggressive defaults)이 적용된 Claude Code 및 Codex용 래퍼 (Wrapper) 스크립트
-
컨테이너 재빌드 시에도 유지되는 영구 상태 (Binary Ninja 라이선스, Claude 인증, Codex 인증)
-
PE, ELF 및 Mach-O 지원
-
콘텐츠 해시 (Content-hash) 기반의 이미지 캐싱
-
buildx를 포함한 Docker
-
Anthropic API 키 또는 Claude 계정 (Claude Code용) 또는 OpenAI API 키 (Codex용)
-
권장 사항: 헤드리스 (headless) 사용이 가능한 라이선스가 포함된 Binary Ninja Linux zip 파일 (아래 Setup 섹션 참조)
중요: run_docker.sh는 현재 작업 디렉토리를 컨테이너 내의 /agent 경로에 마운트 (mount)합니다.
에이전트 래퍼 (agent wrappers)는 설계상 모든 권한(--dangerously-skip-permissions / --dangerously-bypass-approvals-and-sandbox)을 가지고 실행되므로, 에이전트가 해당 디렉토리 내의 모든 것을 읽고, 쓰고, 실행할 수 있습니다. 저장소를 전용 디렉토리에 클론 (clone)하고, 에이전트가 접근하기를 원하는 파일만 그곳에 두십시오.
git clone https://github.com/mrphrazer/agentic-malware-analysis.git
cd agentic-malware-analysis
cp /path/to/binaryninja_linux.zip ./binaryninja.zip # 권장 사항; 이 파일이 없으면 대신 Ghidra가 사용됩니다
...
수행되는 작업:
- Docker Buildx 빌더 준비
binaryninja.zip이 있는 경우 Binary Ninja와 해당 MCP 서버를 설치하며, 그렇지 않은 경우 대체 수단으로 Ghidra와 해당 MCP 서버를 설치합니다.- 선택된 MCP 서버 저장소를
mcp/로 클론합니다.
- 이미지를 빌드합니다 (또는 콘텐츠 해시에 기반하여 캐시된 이미지를 재사용합니다).
- 호스트 디렉토리로부터 BN 라이선스, Claude 자격 증명 및 Codex 자격 증명을 주입 (seed)합니다.
- 현재 디렉토리가
/agent에 마운트된 상태로 컨테이너를 실행합니다.
컨테이너 내부:
claude # 또는: codex
포함된 예시 샘플을 추출하고 오케스트레이터 (orchestrator) 스킬로 분석을 시작하십시오:
cd examples && unzip -P infected samples.zip && cd ..
그 다음 에이전트에게 프롬프트 (prompt)를 입력하십시오:
examples/samples/mfc42ul.dll에 있는 악성코드(malware)를 분석하십시오 -- 해당 샘플의 기능 및 특징에 대한 상세한 개요와 그에 상응하는 코드 위치를 제공하십시오. /agent/agent_helpers/claude/skills/malware-analysis-orchestrator/ 스킬을 사용하십시오.
...
샘플의 상세 정보 및 배경은 examples/README.md를 참조하십시오.
Binary Ninja는 헤드리스 (headless) MCP 서버를 통해 Ghidra보다 실질적으로 더 나은 분석 결과를 제공하며, 권장되는 디스어셈블러 (disassembler) 백엔드입니다. Binary Ninja zip 파일이 없는 경우, 환경은 자동으로 Ghidra로 폴백 (fallback) 됩니다.
Binary Ninja를 사용하려면 run_docker.sh를 실행하기 전에 리포지토리 루트에 Linux 헤드리스 zip 파일을 배치하십시오:
cp /path/to/binaryninja_linux.zip ./binaryninja.zip
파일 이름은 반드시 binaryninja.zip이어야 합니다. 또는, 다음과 같이 명시적으로 지정할 수 있습니다:
BINARY_NINJA_ZIP=/path/to/binaryninja.zip ./run_docker.sh
Binary Ninja는 유효한 license.dat가 필요합니다. 처음 실행할 때, run_docker.sh는 ~/.binaryninja/license.dat에 있는 기존 라이선스를 컨테이너의 /home/agent/.binaryninja에 마운트(mount)되는 Docker 전용 디렉토리(~/.binaryninja-docker/)로 복사합니다. 라이선스는 이미지에 절대 포함(baked)되지 않습니다. 다른 호스트 디렉토리를 사용하려면 다음과 같이 입력하십시오:
BINARY_NINJA_USER_DIR=/path/to/binaryninja-user-dir ./run_docker.sh
run_docker.sh는 호스트의 ~/.claude-docker/에 지속적인 Claude 상태 디렉토리를 유지하며, 이는 컨테이너의 /home/agent/.claude에 마운트됩니다. 처음 실행할 때, 사용 가능한 경우 ~/.claude/.credentials.json에서 자격 증명 (credentials)을 시딩 (seed) 합니다. 컨테이너 내부에서 claude auth로 로그인할 수도 있으며, 자격 증명은 마운트된 디렉토리를 통해 컨테이너 재빌드 시에도 유지됩니다. 다른 호스트 디렉토리를 사용하려면 다음과 같이 입력하십시오:
CLAUDE_USER_DIR=/path/to/claude-dir ./run_docker.sh
run_docker.sh는 호스트의 ~/.codex-docker/에 지속적인 Codex 상태 디렉토리를 유지하며, 이는 컨테이너의 /home/agent/.codex에 마운트됩니다. 처음 실행할 때, ~/.codex/auth.json에서 자격 증명을 시딩 (seed) 합니다.
사용 가능한 경우입니다. 또한 컨테이너 내부에서 codex login 명령어로 로그인할 수 있습니다.
; 자격 증명은 마운트된 디렉토리에 저장되어 컨테이너를 다시 빌드해도 유지됩니다. 다른 호스트 디렉토리를 사용하려면 다음과 같이 실행하세요:
CODEX_USER_DIR=/path/to/codex-dir ./run_docker.sh
핑거프린팅 (Fingerprinting): file, sha256sum, md5sum, ssdeep, die/diec, yara, capa
문자열 추출 (String extraction): strings, floss (FLARE-FLOSS), rabin2
역어셈블 및 분석 (Disassembly and analysis): radare2, binwalk, gdb/gdb-multiarch, capstone (Python)
바이너리 유틸리티 (Binary utilities): objdump, readelf, nm, patchelf, elfutils
헥스 에디터 (Hex editors): hexedit, bvi, xxd, ht, hexwalk
동적 분석 (Dynamic analysis): strace, ltrace, qemu-user
빌드 도구 (Build tools): gcc, g++, clang, lldb, lld, llvm, cmake, nasm
Python: Python 3, pip, venv, ipython, ipdb, uv
데이터 처리 (Data processing): jq, yq
추출 (Extraction): upx, unblob, ropper
Node.js: Node.js 22
에이전트 CLI (Agent CLIs): Claude Code, Codex CLI
조건부 (Conditional): Binary Ninja headless + Python API (zip 파일 제공 시) 또는 Ghidra + pyghidra
-
작업 디렉토리 (Working directory):
/agent
-
사용자 (User):
agent (비루트(non-root), 비밀번호 없는 sudo) - 권한 (Capabilities):
SYS_PTRACE, seccomp=unconfined
-
볼륨 마운트 (Volume mounts):
-
호스트 . → /agent
-
BN 사용자 디렉토리 → /home/agent/.binaryninja
-
Claude 상태 디렉토리 → /home/agent/.claude
-
Codex 상태 디렉토리 → /home/agent/.codex
-
호스트
환경은 자동으로 하나의 MCP 백엔드를 선택하고 구성합니다. Binary Ninja를 권장하며, Binary Ninja zip 파일이 제공되지 않을 경우 Ghidra를 대체제로 사용합니다.
Binary Ninja 설치됨 → binary-ninja-headless-mcp (binary_ninja_headless_mcp로 등록)
Binary Ninja 없음 → ghidra-headless-mcp (ghidra_headless_mcp로 등록)
선택된 저장소는 런타임 시 run_docker.sh에 의해 mcp/ 디렉토리로 클론됩니다. 컨테이너 시작 시, configure-agent-mcp.sh가 프로젝트 범위의 .mcp.json 파일을 작성합니다.
올바른 MCP 서버 엔트리를 포함한 (Claude Code) 및 Codex 설정.
업스트림 리포지토리(upstream repos)를 재정의합니다:
BINJA_MCP_REPO_URL=https://github.com/mrphrazer/binary-ninja-headless-mcp.git ./run_docker.sh
GHIDRA_MCP_REPO_URL=https://github.com/mrphrazer/ghidra-headless-mcp.git ./run_docker.sh
malware-analysis-orchestrator 스킬은 구조화된 다단계 악성코드 분석 워크플로우 (workflow)를 구동합니다. 이 스킬은 Claude Code와 Codex CLI 모두에서 사용할 수 있습니다.
입력 및 핑거프린팅 (Intake and fingerprinting)-- 해시 (hashes), 파일 유형, 패커/컴파일러 탐지, YARA 스캔, capa 스캔
원시 문자열 수집 (Raw strings collection)-- 소스 태그를 포함한 strings, rabin2, floss 사용
원시 API/임포트 수집 (Raw API/import collection)-- rabin2, 포맷별 특화 도구 (PE/ELF/Mach-O)
시그널 필터링 및 순위 지정 (Signal filtering and ranking)-- 기능(capability)에 따라 흥미로운 문자열 및 임포트의 점수를 매기고 순위를 지정
가설 생성 (Hypothesis generation)-- 증거 간 교차 연결, 신뢰도 및 증거를 바탕으로 한 동작 가설 생성
구성 요소 인벤토리 및 상호작용 모델링 (Component inventory and interaction modeling)-- 구성 요소 추론, 데이터/제어 흐름 (data/control flow) 매핑
심층 분석 계획 및 우선순위 지정 (Deep analysis planning and prioritization)-- 대상 함수, 예상 결과, 중단 기준이 포함된 순차적 작업
보고 (Reporting)-- 요약 보고서 (executive summary), 기술적 발견 사항, IOC, 미결 질문
각 분석은 status/<NNN>-<filename>/ 경로에 샘플별 영구 디렉토리를 생성하며, 여기에는 13개의 필수 아티팩트 (artifact) 파일이 포함됩니다:
| # | 파일 (File) | 내용 (Content) |
|---|
| 1 | 00_sample_profile.md | 해시 (Hashes), 파일 유형 (file type), 패커 (packer), YARA, capa 결과 |
| 2 | 01_strings_raw.txt | 소스 태그가 포함된 모든 추출된 문자열 (strings) |
| 3 | 02_strings_interesting.md | 카테고리별로 순위가 매겨진 흥미로운 문자열 (interesting strings) |
| 4 | 03_imports_raw.txt | 소스 태그가 포함된 전체 임포트 테이블 (import tables) |
| 5 | 04_imports_interesting.md | 기능 (capability)별 의심스러운 API 클러스터 (clusters) |
| 6 | 05_behavior_hypotheses.md | 신뢰도 및 증거를 포함한 가설 (hypotheses) |
| 7 | 06_component_inventory.md | 역할 및 증거가 포함된 추론된 구성 요소 (components) |
| 8 | 07_interaction_model.md | 구성 요소 간의 데이터 및 제어 흐름 (data and control flow) |
| 9 | 08_deep_analysis_plan.md | 순서가 지정된 심층 분석 (deep-analysis) 작업 |
| 10 | 09_priority_queue.md | 근거 및 차단 요소 (blockers)가 포함된 우선순위 큐 (priority queue) |
| 11 | 10_reporting_draft.md | 요약 보고서 (executive summary) 및 기술적 조사 결과 (technical findings) |
| 12 | INDEX.md | 아티팩트 (artifact) 목록, 타임스탬프 (timestamps), 누락된 항목 |
| 13 | CURRENT_STATE.json | 기계 판독이 가능한 단계 및 진행 상태 |
이러한 외부화된 상태 (externalized state)는 워크플로우를 컨텍스트 윈도우 압축 (context-window compaction)에 대해 탄력적으로 만들어 줍니다. 즉, 에이전트가 대화 기록 (conversation history)에 의존하는 대신 디스크에서 케이스 파일 (case files)을 다시 읽어옵니다.
| 스크립트 (Script) | 목적 (Purpose) |
|---|
init_status_tree.sh | 샘플에 대한 케이스 디렉토리 (case directory) 생성 또는 재사용 |
collect_strings.sh | strings, rabin2 -zz, floss를 실행하고 원시 출력 (raw output) 기록 |
collect_imports.sh | rabin2 -i 및 형식 지정 임포트 도구 실행 |
scan_yara.sh | 번들된 YARA 규칙으로 샘플 스캔 |
scan_capa.sh | ATT&CK/MBC 기능 식별을 위해 capa 실행 |
rank_signals.py | 흥미로운 문자열 및 임포트의 점수 산정 및 순위 지정 |
build_hypothesis.py | 기본 동작 가설 (baseline behavior hypotheses) 생성 (선택 사항) |
update_state.py | 단계 전환에 따른 CURRENT_STATE.json 업데이트 |
resolve_case.sh | 샘플에 대한 최신 케이스 디렉토리 확인 |
Yara-Rules/rules (GPL-2.0)에서 가져온 4개의 규칙 세트:
crypto_signatures.yar
-- 암호화 알고리즘 및 상수 탐지
antidebug_antivm.yar
-- 안티 디버깅 (anti-debug) 및 안티 VM (anti-VM) 기술 탐지
capabilities.yar
-- 악성 기능 (malicious capability) 탐지
packer_compiler_signatures.yar
-- 패커 (packer) 및 컴파일러 시그니처 탐지
Orchestrator (오케스트레이터)
-- 단계 구동, 아티팩트 (artifact) 완전성 강제, 병렬 수집 스케줄링
Planner (플래너)
-- 중간 증거 소비, 가설 생성, 심층 분석 우선순위 정의
Reporter (리포터)
-- 추적 가능한 증거를 포함한 경영진 및 기술 요약 보고서 생성
-
기본 모델:
opus
-
기본 노력 수준:
high
-
기본 권한:
--dangerously-skip-permissions
-
관리 명령 (auth, doctor, mcp, update 등)은 기본값 없이 그대로 전달됩니다 - 자격 증명 설정은 Claude Code Authentication을 참조하십시오.
-
기본 모델:
gpt-5.4
-
기본 추론 수준:
xhigh
-
기본 권한:
--dangerously-bypass-approvals-and-sandbox
-
기능:
multi_agent, child_agents_md
-
관리 명령 (login, logout, mcp, features 등)은 기본값 없이 그대로 전달됩니다 - 자격 증명 설정은 Codex CLI Authentication을 참조하십시오.