nebulock-inc/agentic-threat-hunting-frameworkATHF는 에이전틱 위협 헌팅을 위한 프레임워크입니다 - 기억하고, 학습하며, 점진적 자율성을 가지고 행동하는 시스템을 구축합니다.
# Agentic Threat Hunting Framework (ATHF)
[](https://pypi.org/project/agentic-threat-hunting-framework/)
[](https://pypi.org/project/agentic-threat-hunting-framework/)
[](https://www.python.org/downloads/)
[](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/LICENSE)
[](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/stargazers)
**[빠른 시작](#-quick-start)** • **[설치](#installation)** • **[문서](#documentation)** • **[예제](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
*위협 헌팅 프로그램에 기억과 자율성을 부여하세요.*
**Agentic Threat Hunting Framework (ATHF)** 는 위협 헌팅 프로그램을 위한 기억 및 자동화 계층입니다. 헌팅에 구조, 지속성, 그리고 컨텍스트를 부여하여 과거의 모든 조사를 사람과 AI 모두가 접근할 수 있게 만듭니다.
ATHF는 모든 헌팅 방법론(PEAK, TaHiTI 또는 자체 프로세스)과 함께 작동합니다. 이는 대체물이 아니라, 기존 프로세스를 AI에 적합하게 만드는 계층입니다.
## ATHF란 무엇인가?
ATHF는 위협 헌팅 프로그램에 구조와 지속성을 제공합니다. 다음과 같은 마크다운 기반 프레임워크입니다:
- LOCK 패턴(Learn → Observe → Check → Keep)을 사용하여 헌팅을 문서화
- 과거 조사에 대한 검색 가능한 저장소 유지
- AI 어시스턴트가 사용자 환경과 이전 작업을 참조할 수 있도록 지원
- 모든 SIEM/EDR 플랫폼과 호환
- **신규:** AI 기반 리서치 및 가설 생성 에이전트 포함 (v0.3.0+)
## 문제점
대부분의 위협 헌팅 프로그램은 헌팅이 끝나면 귀중한 컨텍스트를 잃습니다. 노트는 Slack이나 티켓에 흩어져 있고, 쿼리는 한 번 작성되고 잊히며, 교훈은 분석가의 머릿속에만 존재합니다.
AI 도구조차도 사용자 환경, 데이터, 과거 헌팅에 대한 접근 없이는 매번 처음부터 시작합니다.
ATHF는 헌팅에 구조, 지속성, 컨텍스트를 부여함으로써 이를 바꿉니다.
**더 읽어보기:** [docs/why-athf.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md)
## LOCK 패턴
모든 위협 헌팅은 동일한 기본 루프를 따릅니다: **Learn → Observe → Check → Keep**.
- **Learn:** 위협 인텔, 경보 또는 이상 징후로부터 컨텍스트 수집
- **Observe:** 공격자 행동에 대한 가설 수립
- **Check:** 표적화된 쿼리로 가설 검증
- **Keep:** 발견 사항과 교훈 기록
**왜 LOCK인가?** 사용하기에 충분히 작으면서도 에이전트가 해석하기에 충분히 엄격합니다. 모든 헌팅을 이 형식으로 기록함으로써 ATHF는 AI 어시스턴트가 이전 작업을 회상하고 과거 결과를 바탕으로 개선된 쿼리를 제안할 수 있게 합니다.
**더 읽어보기:** [docs/lock-pattern.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md)
## GATES 방법: 헌팅-탐지 승격 검증
헌팅의 **KEEP** 단계를 완료한 후, **GATES 방법**은 발견 사항을 프로덕션 탐지, 반복 헌팅 또는 권고 사항으로 승격해야 하는지 검증합니다.
**G**eneralizable(일반화 가능), **A**dditive(추가적), **T**unable(조정 가능), **E**xposure-tested(노출 테스트됨), **S**ustainable(지속 가능)
> **참고:** GATES는 ATHF 프레임워크와 함께 작동하도록 설계되었으며 해당 컨텍스트에서 광범위하게 테스트되었습니다. 방법론(5가지 BASE 기준, 판정 유형)은 개념적으로 이식 가능하지만, 최상의 결과를 위해 전체 ATHF 워크플로의 일부로 사용할 것을 권장합니다. 전체 통합은 `.claude/skills/gates/`를 참조하세요.
> **설치:** GATES는 현재 `git clone`을 통해서만 사용할 수 있습니다. `pip install`로 설치한 사용자는 GATES에 접근하려면 저장소를 클론해야 합니다. 현재 GATES를 pip 배포에 포함시키기 위해 작업 중입니다 (Issue #21로 추적 중).
GATES는 헌팅에서 도출된 탐지를 2계층 프레임워크로 평가합니다: 5가지 BASE 기준(헌팅 데이터에서 평가)이 배포 후보를 식별하고, 5가지 ADVANCED 기준(프로덕션에서 검증)이 **낮은 오탐 및 미탐률을 가진 복원력 있는 탐지**를 보장합니다:
| Gate | 질문 | 포착 대상 |
|------|----------|---------|
| **G** - Generalizable | 반복 가능한가? | 빠르게 만료되는 IOC 기반 규칙 |
| **A** - Additive | 커버리지 격차를 채우는가? | 중복되거나 불필요한 탐지 |
| **T** - Tunable | 공격과 정상을 구분할 수 있는가? | 베이스라인 노이즈 불일치 (최대 오탐 원인) |
| **E** - Exposure-tested | 회피를 커버했는가? | 단일 차원 탐지 |
| **S** - Sustainable | 유지 관리할 수 있는가? | 고볼륨, 저TP 규칙 |
판정은 BASE 점수(/5)를 기반으로 합니다. ADVANCED 검증 방법은 `.claude/skills/gates/`를 참조하세요.
**빠른 시작** — 어시스턴트에게 다음과 같이 입력하세요; `/gates`는 스킬이며 셸 명령이 아닙니다:
```text
/gates --hunt H-0001
```
**판정 유형:**
- ✅ **PROMOTE** (4.0-5.0) - 상시 탐지로 배포
- ⚠️ **CONDITIONAL** (3.0-3.9) - 전제 조건 충족 후 배포
- ❌ **HOLD** (0.0-2.9) - 로직은 보존하되 배포하지 않음
- ⏱️ **TIME_BOX** - 캠페인 한정, 90일마다 갱신
- 🔄 **RECURRING_HUNT** - 분기별 실행, 24/7 아님
- 🚫 **DROP** - 탐지할 가치 없음, 재제안되지 않도록 기록
**게이트 FAIL은 점수 구간을 무시하며**, 두 개의 게이트가 실패하면 다음 순서에서
첫 번째 일치가 우선한다: A→DROP, G→TIME_BOX, E→HOLD, S→RECURRING_HUNT, T→CONDITIONAL.
위의 구간은 게이트가 FAIL하지 않았을 때만 적용된다. 전체 규칙:
`.claude/skills/gates/SKILL.md` Step 4.
**참고:** GATES의 "PROMOTE" 판정은 탐지 규칙을 배포하는 것을 의미한다. 이는 헌트 파일을 디렉터리 간에 이동시키는 `athf hunt promote`와는 다르다.
**ADEF(탐지 엔지니어링 프레임워크)와의 통합:**
GATES 검증 후, 프로덕션 탐지 엔지니어링을 위해 ADEF로 진행한다:
```
ATHF Workspace ADEF Workspace
────────────── ──────────────
Hunt (LOCK)
↓
GATES Validate
↓
H-XXXX_GATES.yaml ────────────→ FORGE (F-O-R-G-E)
↓
Production Rule
```
**전체 워크플로:**
1. ATHF 워크스페이스에서 헌트를 검증합니다 — 셸 명령이 아닌 어시스턴트 입력입니다:
```text
/gates --hunt H-0903
```
→ `hunt-promotion-analysis/H-0903_GATES.yaml`을 작성합니다 (헌트당 파일 하나, 내부에 N개의
후보). 판정이 archival(`HOLD`, `DROP`, `TIME_BOX`,
`RECURRING_HUNT`)인 헌트는 대신 `.md` 서술을 출력합니다 — 구축할 규칙이 없으므로
2단계는 `.yaml` 출력에만 적용됩니다.
2. 해당 문서를 ADEF로 가져옵니다:
```bash
adef hunt-promote --gates ~/athf-workspace/hunt-promotion-analysis/H-0903_GATES.yaml
# --dry-run first to preview what it would mint
```
배포 가능한 후보들은 각각 `D-XXXX`, 카탈로그 레코드, 저널과 함께 Find 단계에 도달하며, 아카이브 대상은 건너뛴 것으로 보고됩니다. `cd`가 필요 없습니다 — ADEF는 `ADEF_WORKSPACE`(기본값 `~/work/adef-workspace/`)에서 워크스페이스를 확인합니다. `adef hunt-promote --help`로 ADEF에 이 모드가 있는지 확인하세요.
**ADEF Repository:** https://github.com/Nebulock-Inc/agentic-detection-engineering-framework
GATES는 알림 피로와 운영상의 마찰을 피하면서 올바른 탐지를 올바른 방식으로 배포할 수 있게 해줍니다.
**Read more:** [.claude/skills/gates/README.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md)
## 에이전틱 헌팅의 다섯 단계
ATHF는 단순한 성숙도 모델을 정의합니다. 각 단계는 이전 단계를 기반으로 합니다.
**대부분의 팀은 레벨 1–2에 머무릅니다. 그 이상은 모두 선택적인 성숙도입니다.**
| Level | Capability | What You Get |
|-------|-----------|--------------|
| **0** | Ad-hoc | Hunts exist in Slack, tickets, or analyst notes |
| **1** | Documented | Persistent hunt records using LOCK |
| **2** | Searchable | AI reads and recalls your hunts |
| **3** | Generative | AI executes queries via MCP tools, conducts research |
| **4** | Agentic | Autonomous agents monitor and act, generate hypotheses |
**Level 1:** 하루 안에 운영 가능
**Level 2:** 일주일 안에 운영 가능
**Level 3:** 2-4주 (선택 사항)
**Level 4:** 1-3개월 (선택 사항)
**Read more:** [docs/maturity-model.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md)
## 🚀 빠른 시작
### 옵션 1: PyPI에서 설치 (권장)
```bash
# Install ATHF
pip install agentic-threat-hunting-framework
# Initialize your hunt program
athf init
# NEW: Conduct research before hunting (5-skill methodology)
athf research new --topic "LSASS dumping" --technique T1003.001
# Create your first hunt (link to research)
athf hunt new --technique T1003.001 --title "LSASS Credential Dumping" --research R-0001
```
### 옵션 2: 소스에서 설치 (개발)
```bash
# Clone and install from source
git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
cd agentic-threat-hunting-framework
pip install -e .
# Initialize and start hunting
athf init
athf hunt new --technique T1003.001
```
### 옵션 3: 순수 Markdown (설치 불필요)
```bash
# Clone the repository
git clone https://github.com/Nebulock-Inc/agentic-threat-hunting-framework
cd agentic-threat-hunting-framework
# Copy a template and start documenting
mkdir -p hunts
cp athf/data/templates/HUNT_LOCK.md hunts/H-0001.md
# Customize AGENTS.md with your environment
# Add your SIEM, EDR, and data sources
```
**AI 어시스턴트 선택:** Claude Code, GitHub Copilot 또는 Cursor - 저장소 파일을 읽을 수 있는 모든 도구.
**전체 가이드:** [docs/getting-started.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md)
## 🔧 CLI 명령어
ATHF는 헌트를 관리하기 위한 완전한 기능의 CLI를 포함합니다. 다음은 빠른 참조입니다:
### 워크스페이스 초기화
```bash
athf init # Interactive setup
athf init --non-interactive # Use defaults
```
### 연구 및 가설 생성 (v0.3.0의 새로운 기능)
```bash
# Conduct thorough pre-hunt research (15-20 min)
athf research new --topic "LSASS dumping" --technique T1003.001
# Quick research for urgent hunts (5 min)
athf research new --topic "Pass-the-Hash" --depth basic
# Generate AI-powered hypothesis from threat intel
athf agent run hypothesis-generator --threat-intel "APT29 targeting SaaS"
# List research and agents
athf research list
athf agent list
```
### 헌트 생성
```bash
athf hunt new # Interactive mode
athf hunt new \
--technique T1003.001 \
--title "LSASS Dumping Detection" \
--platform windows \
--hunt-type baseline \
--research R-0001 # Link to research document
# --hunt-type: hypothesis (default) | baseline | model-assisted
```
### 목록 및 검색
```bash
athf hunt list # Show all hunts
athf hunt list --status completed # Filter by status
athf hunt list --directory test # Filter by environment (test/production)
athf hunt list --hunt-type baseline # Filter by hunt category
athf hunt list --output json # JSON output
athf hunt search "kerberoasting" # Full-text search
athf hunt search "credential" --directory production # Search with directory filter
athf research search "credential" # Search research docs
```
### 검증 및 통계
```bash
athf hunt validate # Validate all hunts
athf hunt validate H-0001 # Validate specific hunt
athf hunt stats # Show statistics (incl. hunts by type)
athf hunt stats --by hunt_type --status completed --output json # Category breakdown
athf hunt coverage # MITRE ATT&CK coverage
athf research stats # Research metrics
```
탐지 품질은 어시스턴트가 호출하는 GATES **skill**로 채점됩니다 —
이는 `athf` CLI의 일부가 아니므로 위의 셸 블록에 속하지 않습니다:
```text
/gates --hunt H-0001
```
### ATT&CK 데이터 관리 (v0.11.0의 새로운 기능)
```bash
# Install STIX support (optional)
pip install 'agentic-threat-hunting-framework[attack]'
# Download live ATT&CK data (835+ techniques with full metadata)
athf attack update
# Check provider status
athf attack status
# Look up technique metadata
athf attack lookup T1003.001
# List techniques for a tactic
athf attack techniques credential-access
```
`mitreattack-python` 없이 ATHF는 하드코딩된 v14 폴백(14개 전술, 대략적인 개수)을 사용합니다. 이를 사용하면 플랫폼, 데이터 소스, 하위 기법, 정확한 개수를 포함한 전체 기법 메타데이터를 얻을 수 있습니다.
### MCP 서버 (v0.11.0의 새로운 기능)
```bash
# Install MCP dependencies
pip install 'agentic-threat-hunting-framework[mcp]'
# Start MCP server (for Claude Code, Copilot, Cursor, etc.)
athf mcp serve --workspace /path/to/hunts
```
`~/.claude/mcp-servers.json`에서 구성:
```json
{
"athf": {
"command": "athf-mcp",
"env": { "ATHF_WORKSPACE": "/path/to/your/hunts" }
}
}
```
독립 실행형 `athf-mcp` 진입점은 cwd 또는 `ATHF_WORKSPACE` 환경 변수에서 워크스페이스를 자동 감지합니다. 명시적 경로를 지정하려면 `athf mcp serve --workspace /path`를 사용하세요.
> **보안 참고:** `sse` 및 `streamable-http` 전송 방식은 `127.0.0.1`에 바인딩되며 **인증되지 않습니다**. 모든 도구는 전체 워크스페이스를 읽고 일부는 사용자의 비용으로 LLM 에이전트를 호출합니다. 라우팅 가능한 인터페이스에 바인딩하려면 `--host`를 전달할 때만 사용하고, 그럴 때는 인증 프록시를 앞에 두세요. 기본 `stdio` 전송 방식은 소켓을 전혀 열지 않습니다.
17개의 도구를 제공합니다: 헌트 관리, 시맨틱 검색, ATT&CK 커버리지, 리서치, 조사, 그리고 AI 기반 가설 생성 — 모두 AI 코딩 어시스턴트에서 직접 접근할 수 있습니다.
**전체 문서:** [CLI 레퍼런스](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/CLI_REFERENCE.md)
## 📺 실제 동작 보기
ATHF의 실제 동작을 확인하세요: 워크스페이스 초기화, 헌트 생성, 그리고 60초 이내에 위협 헌팅 카탈로그 탐색까지.
**[예제 헌트 보기 →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
## 설치
설치 옵션(PyPI, 소스, 또는 순수 마크다운)은 위의 [빠른 시작](#-quick-start) 섹션을 참조하세요.
**사전 요구 사항:**
- Python 3.11 이상 (CLI 옵션용)
- 즐겨 사용하는 AI 코드 어시스턴트
## 문서
### 핵심 개념
- [ATHF가 존재하는 이유](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md) - 문제와 해결책
- [LOCK 패턴](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md) - 모든 헌트의 구조
- [성숙도 모델](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md) - 다섯 단계 설명
- [시작하기](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md) - 단계별 온보딩
### 레벨별 가이드
- [레벨 1: 문서화된 헌트](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-1-documented-hunts)
- [레벨 2: 검색 가능한 메모리](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-2-searchable-memory)
- [레벨 3: 생성 기능](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
- [레벨 4: 에이전틱 워크플로](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
### 통합 및 커스터마이징
- [설치 및 개발](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md) - 설정, 포크 커스터마이징, 테스트
- [GATES 방법](https://github.com/nebulock-inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md) - 탐지 검증 스킬 (LOCK → ADEF 연결)
- [MCP 카탈로그](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/integrations/MCP_CATALOG.md) - 사용 가능한 도구 통합
- [빠른 시작 가이드](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/tree/main/integrations/quickstart/) - 특정 도구 설정
- [ATHF 사용하기](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) - 도입 및 커스터마이징
## 🎖️ 주요 헌트
### H-0001: macOS 정보 탈취기 탐지
AppleScript를 통해 Safari 쿠키를 수집하는 Atomic Stealer를 탐지했습니다.
**결과:** 1건의 실제 양성, 유출 전 호스트 격리.
**핵심 인사이트:** 행위 기반 탐지가 시그니처 기반 접근보다 우수한 성능을 보였습니다. 프로세스 시그니처 검증으로 데이터 수집을 시도하는 서명되지 않은 악성코드를 식별했습니다.
[전체 헌트 보기 →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/hunts/H-0001.md) | [더 많은 예제 보기 →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)
## 이것이 중요한 이유
이것이 [PEAK](https://www.splunk.com/en_us/blog/security/peak-threat-hunting-framework.html)와 같은 프레임워크와 어떻게 상호작용하는지 궁금할 수 있습니다. PEAK는 헌트를 수행하는 방법에 대한 견고한 방법론을 제공합니다. ATHF는 구조, 메모리, 연속성을 제공함으로써 그 기반 위에 구축됩니다. PEAK는 작업을 안내합니다. ATHF는 그 작업을 포착하고, 정리하고, 향후 헌트에서 재사용할 수 있도록 보장합니다.
에이전틱 위협 헌팅은 분석가를 대체하는 것이 아닙니다. 다음과 같은 시스템을 구축하는 것입니다:
- 이전에 무엇이 수행되었는지 기억하기
- 과거의 성공과 실수로부터 배우기
- 맥락적 회상을 통해 인간의 판단 지원하기
프레임워크에 메모리가 있으면 인력 이탈이나 잊힌 메모로 인해 지식이 유실되는 일이 없습니다. AI 어시스턴트가 그 메모리를 참조할 수 있으면 강력한 힘의 배가 효과를 발휘합니다.
## 💬 커뮤니티 및 도입
- **GitHub Discussions:** [질문하기, 헌트 공유하기](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)
- **Issues:** [버그 신고 또는 기능 요청](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues)
- **LinkedIn:** [Nebulock Inc.](https://www.linkedin.com/company/nebulock-inc) - 업데이트 팔로우
**조직에서 ATHF 사용하기:** ATHF는 확장할 플랫폼이 아니라 내재화할 프레임워크입니다. 포크하고, 커스터마이징하고, 자신만의 것으로 만드세요. 도입 지침은 [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md)를 참조하세요. 여러분의 헌트는 여러분의 것으로 남습니다—공유는 선택 사항이지만 감사히 여깁니다.
**저장소:** [https://github.com/Nebulock-Inc/agentic-threat-hunting-framework](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)
목표는 모든 위협 헌팅 팀이 임시방편적 기억에서 구조화된 에이전틱 역량으로 나아가도록 돕는 것입니다.
---
## 🛠️ 개발 및 커스터마이징
ATHF는 조직에 맞게 포크하고 커스터마이징하도록 설계되었습니다.
**다음을 위해 [docs/INSTALL.md#development--customization](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md#development--customization)을 참조하세요:**
- 개발을 위한 포크 설정
- 코드 품질을 위한 pre-commit 훅
- 테스트 및 타입 검사
- 커스터마이징 예제
- CI/CD 통합
빠른 시작:
```bash
pip install -e ".[dev]" # Install dev dependencies
pre-commit install # Set up quality checks
pytest tests/ -v # Run tests
```
---
## 👤 작성자
**Sydney Marrone** 제작 © 2025
---
**작게 시작하세요. 하나의 헌트를 문서화하세요. 구조를 추가하세요. 기억을 쌓으세요.**
기억은 배수입니다. 주체성은 힘입니다.
여러분의 프로그램이 기억할 수 있게 되면, 그 밖의 모든 것이 가능해집니다.
즐거운 헌팅 되세요!