nebulock-inc/agentic-threat-hunting-frameworkATHF — это фреймворк для агентного поиска угроз, предназначенный для создания систем, способных запоминать, обучаться и действовать с возрастающей автономией.
# Фреймворк агентного охоты за угрозами (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)**
*Дайте вашей программе охоты за угрозами память и агентность.*
**Фреймворк агентного охоты за угрозами (ATHF)** — это слой памяти и автоматизации для вашей программы охоты за угрозами. Он придаёт вашим охотам структуру, персистентность и контекст, делая каждое прошлое расследование доступным как для людей, так и для ИИ.
ATHF работает с любой методологией охоты (PEAK, TaHiTI или вашим собственным процессом). Это не замена; это слой, который делает ваш существующий процесс готовым к ИИ.
## Что такое ATHF?
ATHF обеспечивает структуру и персистентность для программ охоты за угрозами. Это фреймворк на основе markdown, который:
- Документирует охоты с использованием паттерна LOCK (Learn → Observe → Check → Keep)
- Поддерживает доступный для поиска репозиторий прошлых расследований
- Позволяет ИИ-ассистентам ссылаться на вашу среду и предыдущую работу
- Работает с любой платформой SIEM/EDR
- **НОВОЕ:** Включает агентов генерации исследований и гипотез на основе ИИ (v0.3.0+)
## Проблема
Большинство программ охоты за угрозами теряют ценный контекст после завершения охоты. Заметки остаются в Slack или тикетах, запросы пишутся один раз и забываются, а извлечённые уроки существуют только в головах аналитиков.
Даже ИИ-инструменты каждый раз начинают с нуля без доступа к вашей среде, вашим данным или вашим прошлым охотам.
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:** Соберите контекст из threat intel, оповещений или аномалий
- **Observe:** Сформулируйте гипотезу о поведении противника
- **Check:** Проверьте гипотезы с помощью целевых запросов
- **Keep:** Зафиксируйте находки и извлечённые уроки
**Почему LOCK?** Он достаточно мал для использования и достаточно строг для интерпретации агентами. Фиксируя каждую охоту в этом формате, ATHF делает возможным для ИИ-ассистентов вспоминать предыдущую работу и предлагать уточнённые запросы на основе прошлых результатов.
**Подробнее:** [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 оценивает детекты, полученные из охоты, используя двухуровневый фреймворк: 5 критериев BASE (оцениваются по данным охоты) определяют кандидатов на развёртывание, в то время как 5 критериев ADVANCED (валидируются в производстве) обеспечивают **устойчивые детекты с низкими показателями ложноположительных и ложноотрицательных срабатываний**:
| Гейт | Вопрос | Что выявляет |
|------|----------|---------|
| **G** - Generalizable | Это повторяемо? | Правила на основе IOC, которые быстро устаревают |
| **A** - Additive | Заполняет ли это пробел в покрытии? | Дублирующие или избыточные детекты |
| **T** - Tunable | Можем ли мы отличить атаку от нормы? | Несоответствие базового шума (главная причина FP) |
| **E** - Exposure-tested | Покрыли ли мы обходы? | Одномерные детекты |
| **S** - Sustainable | Можем ли мы это поддерживать? | Правила с высоким объёмом и низким TP |
Вердикты основаны на оценках BASE (/5). См. `.claude/skills/gates/` для методов валидации ADVANCED.
**Быстрый старт** — введите это вашему ассистенту; `/gates` — это навык, а не shell-команда:
```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** — ежеквартальное выполнение, не круглосуточное
- 🚫 **DROP** — не стоит обнаружения; зафиксировано, чтобы не предлагалось повторно
**Провал gate переопределяет диапазон оценки**, и когда два gate терпят неудачу, побеждает первое совпадение в
этом порядке: A→DROP, G→TIME_BOX, E→HOLD, S→RECURRING_HUNT, T→CONDITIONAL. Диапазоны
выше применяются только тогда, когда ни один gate не завершился неудачей. Полное правило:
`.claude/skills/gates/SKILL.md` Шаг 4.
**Примечание:** Вердикт GATES "PROMOTE" означает развертывание правила обнаружения. Это отличается от `athf hunt promote`, который перемещает файлы hunt между каталогами.
**Интеграция с 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 проверьте hunt — ввод для ассистента, а не команда оболочки:
```text
/gates --hunt H-0903
```
→ записывает `hunt-promotion-analysis/H-0903_GATES.yaml` (один файл на hunt, N
кандидатов внутри). Hunt, вердикт которого — архивный (`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
```
Развёртываемые кандидаты попадают на этап Find с `D-XXXX`, записью в каталоге
и журналом; архивные отмечаются как пропущенные. `cd` не нужен — ADEF определяет
своё рабочее пространство из `ADEF_WORKSPACE` (по умолчанию `~/work/adef-workspace/`). Убедитесь,
что ваш ADEF поддерживает этот режим, с помощью `adef hunt-promote --help`.
**Репозиторий ADEF:** https://github.com/Nebulock-Inc/agentic-detection-engineering-framework
GATES гарантирует, что вы развёртываете нужные детекции правильным способом, избегая усталости от алертов и операционных трений.
**Подробнее:** [.claude/skills/gates/README.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md)
## Пять уровней агентного охоты
ATHF определяет простую модель зрелости. Каждый уровень строится на предыдущем.
**Большинство команд будут находиться на уровнях 1–2. Всё, что выше, — опциональная зрелость.**
| Уровень | Возможность | Что вы получаете |
|-------|-----------|--------------|
| **0** | Ad-hoc | Охота существует в Slack, тикетах или заметках аналитиков |
| **1** | Документированная | Постоянные записи об охоте с использованием LOCK |
| **2** | Доступная для поиска | ИИ читает и вспоминает ваши охоты |
| **3** | Генеративная | ИИ выполняет запросы через инструменты MCP, проводит исследования |
| **4** | Агентная | Автономные агенты мониторят и действуют, генерируют гипотезы |
**Уровень 1:** Работает в течение дня
**Уровень 2:** Работает в течение недели
**Уровень 3:** 2-4 недели (опционально)
**Уровень 4:** 1-3 месяца (опционально)
**Подробнее:** [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
```
**Выберите вашего ИИ-ассистента:** 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
```
### Создание Hunts
```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, который вызывает ваш ассистент —
он не является частью CLI `athf`, поэтому не должен находиться в блоке shell выше:
```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, исследования, расследования и генерация гипотез на основе ИИ — всё доступно напрямую из вашего ИИ-ассистента для программирования.
**Полная документация:** [Справочник 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)**
## Установка
См. раздел [Быстрый старт](#-quick-start) выше для вариантов установки (PyPI, из исходников или чистый markdown).
**Предварительные требования:**
- Python 3.11 или выше (для варианта с CLI)
- Ваш любимый ИИ-ассистент для программирования
## Документация
### Основные концепции
- [Зачем существует 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 Information Stealer
Обнаружен Atomic Stealer, собирающий cookies Safari через AppleScript.
**Результат:** 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 гарантирует, что вы фиксируете работу, организуете её и переиспользуете в будущих охотах.
Агентная охота за угрозами — это не замена аналитиков. Это построение систем, которые могут:
- Помнить, что было сделано ранее
- Учиться на прошлых успехах и ошибках
- Поддерживать человеческое суждение с помощью контекстного припоминания
Когда у вашего фреймворка есть память, вы перестаёте терять знания из-за текучести кадров или забытых заметок. Когда ваш ИИ-ассистент может обращаться к этой памяти, он становится усилителем возможностей.
## 💬 Сообщество и внедрение
- **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
---
**Начните с малого. Задокументируйте одну охоту. Добавьте структуру. Постройте память.**
Память — это множитель. Агентность — это сила.
Как только ваша программа обретёт память, всё остальное станет возможным.
Удачной охоты!