mrphrazer/agentic-malware-analysis

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을 참조하십시오.