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は脅威ハンティングプログラムに構造と永続性を提供します。Markdownベースのフレームワークで、以下を実現します：
- 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基準（本番環境で検証）が**偽陽性率と偽陰性率の低い、回復力のある検知**を保証します：
| ゲート | 問い | 検出するもの |
|------|----------|---------|
| **G** - Generalizable | これは再現可能か？ | すぐに失効するIOCベースのルール |
| **A** - Additive | カバレッジのギャップを埋めるか？ | 重複または冗長な検知 |
| **T** - Tunable | 攻撃と正常を区別できるか？ | ベースラインノイズの不一致（偽陽性の最大要因） |
| **E** - Exposure-tested | 回避策をカバーしたか？ | 単一次元の検知 |
| **S** - Sustainable | これを維持できるか？ | 大量・低真陽性のルール |
判定は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時間365日ではない
- 🚫 **DROP** - 検知する価値なし。再提案されないよう記録
**ゲートの FAIL はスコア帯を上書き**し、2つのゲートが失敗した場合は
この順序で最初に一致したものが優先される: A→DROP、G→TIME_BOX、E→HOLD、S→RECURRING_HUNT、T→CONDITIONAL。
上記のスコア帯はゲートが FAIL しなかった場合にのみ適用される。完全なルール:
`.claude/skills/gates/SKILL.md` ステップ4。
**注記:** GATES の「PROMOTE」判定は検知ルールをデプロイすることを意味する。これは `athf hunt promote` とは異なり、こちらはハントファイルをディレクトリ間で移動するものである。
**ADEF (Detection Engineering Framework) との統合:**
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` を書き込む（ハントごとに1ファイル、内部にN個の候補）。判定がアーカイブ（`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
```
Deployable candidates each land at the Find stage with a `D-XXXX`, a catalog record
and a journal; archival ones are reported as skipped. No `cd` needed — ADEF resolves
its workspace from `ADEF_WORKSPACE` (default `~/work/adef-workspace/`). Confirm your
ADEF has this mode with `adef hunt-promote --help`.
**ADEF Repository:** https://github.com/Nebulock-Inc/agentic-detection-engineering-framework
GATES ensures you deploy the right detections the right way, avoiding alert fatigue and operational friction.
**Read more:** [.claude/skills/gates/README.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md)
## The Five Levels of Agentic Hunting
ATHF defines a simple maturity model. Each level builds on the previous one.
**Most teams will live at Levels 1–2. Everything beyond that is optional maturity.**
| 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:** Operational within a day
**Level 2:** Operational within a week
**Level 3:** 2-4 weeks (optional)
**Level 4:** 1-3 months (optional)
**Read more:** [docs/maturity-model.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md)
## 🚀 Quick Start
### Option 1: Install from PyPI (Recommended)
```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、ソース、または純粋な Markdown）については、上記の[クイックスタート](#-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) - 5 つのレベルを解説
- [はじめに](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 の Cookie を収集する 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
---
**小さく始めよう。1つのハントを記録しよう。構造を加えよう。記憶を築こう。**
記憶は乗数。主体性は力。
あなたのプログラムが記憶できるようになれば、あとはすべてが可能になる。
ハッピーハンティング！