nebulock-inc/agentic-threat-hunting-frameworkATHF ist ein Framework für agentisches Threat Hunting - Systeme, die sich erinnern, lernen und mit zunehmender Autonomie handeln können.
# 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](#-quick-start)** • **[Installation](#installation)** • **[Documentation](#documentation)** • **[Examples](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
*Geben Sie Ihrem Threat-Hunting-Programm Gedächtnis und Handlungsfähigkeit.*
Das **Agentic Threat Hunting Framework (ATHF)** ist die Gedächtnis- und Automatisierungsschicht für Ihr Threat-Hunting-Programm. Es verleiht Ihren Hunts Struktur, Persistenz und Kontext – und macht jede vergangene Untersuchung sowohl für Menschen als auch für KI zugänglich.
ATHF funktioniert mit jeder Hunting-Methodik (PEAK, TaHiTI oder Ihrem eigenen Prozess). Es ist kein Ersatz; es ist die Schicht, die Ihren bestehenden Prozess KI-fähig macht.
## Was ist ATHF?
ATHF bietet Struktur und Persistenz für Threat-Hunting-Programme. Es ist ein Markdown-basiertes Framework, das:
- Hunts mithilfe des LOCK-Musters dokumentiert (Learn → Observe → Check → Keep)
- Ein durchsuchbares Repository vergangener Untersuchungen pflegt
- KI-Assistenten in die Lage versetzt, auf Ihre Umgebung und frühere Arbeiten zu verweisen
- Mit jeder SIEM/EDR-Plattform funktioniert
- **NEU:** KI-gestützte Research- und Hypothesengenerierungs-Agenten enthält (v0.3.0+)
## Das Problem
Die meisten Threat-Hunting-Programme verlieren wertvollen Kontext, sobald ein Hunt endet. Notizen liegen in Slack oder Tickets, Queries werden einmal geschrieben und vergessen, und Lessons Learned existieren nur in den Köpfen der Analysten.
Selbst KI-Tools starten jedes Mal bei null, ohne Zugriff auf Ihre Umgebung, Ihre Daten oder Ihre vergangenen Hunts.
ATHF ändert das, indem es Ihren Hunts Struktur, Persistenz und Kontext verleiht.
**Mehr lesen:** [docs/why-athf.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md)
## Das LOCK-Muster
Jeder Threat Hunt folgt derselben grundlegenden Schleife: **Learn → Observe → Check → Keep**.
- **Learn:** Kontext aus Threat Intel, Alerts oder Anomalien sammeln
- **Observe:** Eine Hypothese über das Verhalten des Angreifers bilden
- **Check:** Hypothesen mit gezielten Queries testen
- **Keep:** Erkenntnisse und Lessons Learned festhalten
**Warum LOCK?** Es ist klein genug, um verwendet zu werden, und streng genug, damit Agenten es interpretieren können. Indem jeder Hunt in diesem Format erfasst wird, ermöglicht ATHF KI-Assistenten, frühere Arbeiten abzurufen und verfeinerte Queries auf Basis vergangener Ergebnisse vorzuschlagen.
**Mehr lesen:** [docs/lock-pattern.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md)
## GATES-Methode: Validierung der Hunt-zu-Detection-Beförderung
Nach Abschluss der **KEEP**-Phase eines Hunts validiert die **GATES-Methode**, ob Ihre Erkenntnisse zu Produktions-Detections, wiederkehrenden Hunts oder Advisories befördert werden sollten.
**G**eneralizable, **A**dditive, **T**unable, **E**xposure-tested, **S**ustainable
> **Hinweis:** GATES ist darauf ausgelegt, mit dem ATHF-Framework zu arbeiten, und wurde in diesem Kontext umfassend getestet. Während die Methodik (5 BASE-Kriterien, Verdict-Typen) konzeptionell übertragbar ist, empfehlen wir, sie als Teil des vollständigen ATHF-Workflows zu verwenden, um beste Ergebnisse zu erzielen. Siehe `.claude/skills/gates/` für die vollständige Integration.
> **Installation:** GATES ist derzeit nur über `git clone` verfügbar. Benutzer, die über `pip install` installiert haben, sollten das Repository klonen, um auf GATES zuzugreifen. Wir arbeiten daran, GATES in die pip-Distribution aufzunehmen (verfolgt als Issue #21).
GATES bewertet aus Hunts abgeleitete Detections mithilfe eines zweistufigen Frameworks: 5 BASE-Kriterien (bewertet anhand von Hunt-Daten) identifizieren Deployment-Kandidaten, während 5 ADVANCED-Kriterien (in der Produktion validiert) **resiliente Detections mit niedrigen False-Positive- und False-Negative-Raten** sicherstellen:
| Gate | Frage | Erkennt |
|------|----------|---------|
| **G** - Generalizable | Ist dies wiederholbar? | IOC-basierte Regeln, die schnell ablaufen |
| **A** - Additive | Füllt es eine Coverage-Lücke? | Doppelte oder redundante Detections |
| **T** - Tunable | Können wir Angriff von Normal unterscheiden? | Baseline-Rauschen-Mismatch (häufigste FP-Ursache) |
| **E** - Exposure-tested | Haben wir Evasions abgedeckt? | Eindimensionale Detections |
| **S** - Sustainable | Können wir dies aufrechterhalten? | Regeln mit hohem Volumen und niedrigem TP |
Verdicts basieren auf BASE-Scores (/5). Siehe `.claude/skills/gates/` für ADVANCED-Validierungsmethoden.
**Quick Start** — geben Sie dies in Ihren Assistenten ein; `/gates` ist ein Skill, kein Shell-Befehl:
```text
/gates --hunt H-0001
```
**Verdict-Typen:**
- ✅ **PROMOTE** (4.0-5.0) - Als dauerhafte Erkennung einsetzen
- ⚠️ **CONDITIONAL** (3.0-3.9) - Nach Erfüllung der Voraussetzungen einsetzen
- ❌ **HOLD** (0.0-2.9) - Logik bewahren, nicht einsetzen
- ⏱️ **TIME_BOX** - Kampagnenspezifisch, 90-Tage-Aktualisierung
- 🔄 **RECURRING_HUNT** - Vierteljährliche Ausführung, nicht 24/7
- 🚫 **DROP** - Nicht erkennenswert; aufgezeichnet, damit es nicht erneut vorgeschlagen wird
Ein **Gate-FAIL überschreibt das Score-Band**, und wenn zwei Gates fehlschlagen, gewinnt der erste Treffer in
dieser Reihenfolge: A→DROP, G→TIME_BOX, E→HOLD, S→RECURRING_HUNT, T→CONDITIONAL. Die
obigen Bänder gelten nur, wenn kein Gate fehlgeschlagen ist. Vollständige Regel:
`.claude/skills/gates/SKILL.md` Schritt 4.
**Hinweis:** Das GATES-Urteil „PROMOTE" bedeutet das Einsetzen einer Erkennungsregel. Dies ist verschieden von `athf hunt promote`, das Hunt-Dateien zwischen Verzeichnissen verschiebt.
**Integration mit ADEF (Detection Engineering Framework):**
Nach der GATES-Validierung fahren Sie mit ADEF für das Produktions-Detection-Engineering fort:
```
ATHF Workspace ADEF Workspace
────────────── ──────────────
Hunt (LOCK)
↓
GATES Validate
↓
H-XXXX_GATES.yaml ────────────→ FORGE (F-O-R-G-E)
↓
Production Rule
```
**Vollständiger Workflow:**
1. Im ATHF-Workspace den Hunt validieren — Assistenten-Eingabe, kein Shell-Befehl:
```text
/gates --hunt H-0903
```
→ schreibt `hunt-promotion-analysis/H-0903_GATES.yaml` (eine Datei pro Hunt, N
Kandidaten darin). Ein Hunt, dessen Verdict archivierend ist (`HOLD`, `DROP`, `TIME_BOX`,
`RECURRING_HUNT`), gibt stattdessen eine `.md`-Erzählung aus — es gibt keine Regel zu erstellen, also
gilt Schritt 2 nur für `.yaml`-Ausgabe.
2. Importiere dieses Dokument in ADEF:
```bash
adef hunt-promote --gates ~/athf-workspace/hunt-promotion-analysis/H-0903_GATES.yaml
# --dry-run first to preview what it would mint
```
Deploybare Kandidaten landen jeweils in der Find-Phase mit einem `D-XXXX`, einem Katalogeintrag
und einem Journal; archivierte werden als übersprungen gemeldet. Kein `cd` nötig — ADEF ermittelt
seinen Workspace aus `ADEF_WORKSPACE` (Standard `~/work/adef-workspace/`). Bestätige, dass dein
ADEF diesen Modus hat, mit `adef hunt-promote --help`.
**ADEF-Repository:** https://github.com/Nebulock-Inc/agentic-detection-engineering-framework
GATES stellt sicher, dass du die richtigen Detektionen auf die richtige Weise deployest, um Alert-Fatigue und operativen Reibungsverlust zu vermeiden.
**Mehr erfahren:** [.claude/skills/gates/README.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md)
## Die fünf Stufen des agentischen Huntings
ATHF definiert ein einfaches Reifegradmodell. Jede Stufe baut auf der vorherigen auf.
**Die meisten Teams werden auf den Stufen 1–2 bleiben. Alles darüber hinaus ist optionale Reife.**
| Stufe | Fähigkeit | Was du bekommst |
|-------|-----------|--------------|
| **0** | Ad-hoc | Hunts existieren in Slack, Tickets oder Analystennotizen |
| **1** | Dokumentiert | Persistente Hunt-Einträge mit LOCK |
| **2** | Durchsuchbar | KI liest und erinnert sich an deine Hunts |
| **3** | Generativ | KI führt Abfragen über MCP-Tools aus, betreibt Recherche |
| **4** | Agentisch | Autonome Agenten überwachen und handeln, generieren Hypothesen |
**Stufe 1:** Betriebsbereit innerhalb eines Tages
**Stufe 2:** Betriebsbereit innerhalb einer Woche
**Stufe 3:** 2-4 Wochen (optional)
**Stufe 4:** 1-3 Monate (optional)
**Mehr erfahren:** [docs/maturity-model.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md)
## 🚀 Schnellstart
### Option 1: Installation von PyPI (Empfohlen)
```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
```
### Option 2: Installation aus dem Quellcode (Entwicklung)
```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
```
### Option 3: Reines Markdown (keine Installation)
```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
```
**Wählen Sie Ihren KI-Assistenten:** Claude Code, GitHub Copilot oder Cursor – jedes Tool, das Ihre Repository-Dateien lesen kann.
**Vollständige Anleitung:** [docs/getting-started.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md)
## 🔧 CLI-Befehle
ATHF enthält eine voll ausgestattete CLI zur Verwaltung Ihrer Hunts. Hier eine Kurzübersicht:
### Workspace initialisieren
```bash
athf init # Interactive setup
athf init --non-interactive # Use defaults
```
### Recherche & Hypothesengenerierung (NEU in 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 erstellen
```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
```
### Auflisten & Suchen
```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
```
### Validieren & Statistiken
```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
```
Die Erkennungsqualität wird durch die **Skill** GATES bewertet, die dein Assistent aufruft —
sie ist nicht Teil der `athf` CLI und gehört daher nicht in den obigen Shell-Block:
```text
/gates --hunt H-0001
```
### ATT&CK-Datenverwaltung (NEU in 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
```
Ohne `mitreattack-python` verwendet ATHF einen hartcodierten v14-Fallback (14 Taktiken, ungefähre Anzahlen). Damit erhältst du vollständige Technik-Metadaten: Plattformen, Datenquellen, Untertechniken und genaue Anzahlen.
### MCP-Server (NEU in 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
```
Konfigurieren Sie in `~/.claude/mcp-servers.json`:
```json
{
"athf": {
"command": "athf-mcp",
"env": { "ATHF_WORKSPACE": "/path/to/your/hunts" }
}
}
```
Der eigenständige `athf-mcp`-Einstiegspunkt erkennt deinen Workspace automatisch aus dem cwd oder der `ATHF_WORKSPACE`-Umgebungsvariable. Verwende `athf mcp serve --workspace /path` für explizite Pfade.
> **Sicherheitshinweis:** Die Transporte `sse` und `streamable-http` binden an `127.0.0.1` und sind **unauthentifiziert**. Jedes Tool liest deinen gesamten Workspace, und einige rufen LLM-Agenten auf deine Kosten auf. Übergib `--host` nur, um an ein routbares Interface zu binden, und stelle in diesem Fall einen authentifizierenden Proxy davor. Der Standard-`stdio`-Transport öffnet überhaupt keinen Socket.
Stellt 17 Tools bereit: Hunt-Management, semantische Suche, ATT&CK-Abdeckung, Recherche, Investigations und KI-gestützte Hypothesengenerierung — alle direkt aus deinem KI-Coding-Assistenten zugänglich.
**Vollständige Dokumentation:** [CLI-Referenz](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/CLI_REFERENCE.md)
## 📺 In Aktion erleben
Erlebe ATHF in Aktion: Initialisiere einen Workspace, erstelle Hunts und erkunde deinen Threat-Hunting-Katalog in unter 60 Sekunden.
**[Beispiel-Hunts ansehen →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)**
## Installation
Siehe den Abschnitt [Schnellstart](#-quick-start) oben für Installationsoptionen (PyPI, Quellcode oder reines Markdown).
**Voraussetzungen:**
- Python 3.11 oder höher (für die CLI-Option)
- Dein bevorzugter KI-Coding-Assistent
## Dokumentation
### Kernkonzepte
- [Warum ATHF existiert](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/why-athf.md) - Das Problem und die Lösung
- [Das LOCK-Muster](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/lock-pattern.md) - Struktur für alle Hunts
- [Reifegradmodell](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md) - Die fünf Stufen erklärt
- [Erste Schritte](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/getting-started.md) - Schritt-für-Schritt-Onboarding
### Stufenspezifische Leitfäden
- [Stufe 1: Dokumentierte Hunts](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-1-documented-hunts)
- [Stufe 2: Durchsuchbarer Speicher](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/maturity-model.md#level-2-searchable-memory)
- [Stufe 3: Generative Fähigkeiten](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
- [Stufe 4: Agentische Workflows](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/level4-agentic-workflows.md)
### Integration & Anpassung
- [Installation & Entwicklung](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md) - Einrichtung, Fork-Anpassung, Tests
- [GATES-Methode](https://github.com/nebulock-inc/agentic-threat-hunting-framework/blob/main/.claude/skills/gates/README.md) - Skill zur Erkennungsvalidierung (verbindet LOCK → ADEF)
- [MCP-Katalog](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/integrations/MCP_CATALOG.md) - Verfügbare Tool-Integrationen
- [Schnellstart-Leitfäden](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/tree/main/integrations/quickstart/) - Einrichtung für bestimmte Tools
- [ATHF verwenden](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) - Einführung und Anpassung
## 🎖️ Ausgewählte Hunts
### H-0001: macOS Information Stealer Detection
Erkannte Atomic Stealer beim Sammeln von Safari-Cookies via AppleScript.
**Ergebnis:** 1 True Positive, Host isoliert vor der Exfiltration.
**Zentrale Erkenntnis:** Verhaltensbasierte Erkennung übertraf signaturbasierte Ansätze. Die Prozess-Signaturvalidierung identifizierte unsignierte Malware, die Datensammlung versuchte.
[Vollständigen Hunt ansehen →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/hunts/H-0001.md) | [Weitere Beispiele ansehen →](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/SHOWCASE.md)
## Warum das wichtig ist
Du fragst dich vielleicht, wie dies mit Frameworks wie [PEAK](https://www.splunk.com/en_us/blog/security/peak-threat-hunting-framework.html) interagiert. PEAK gibt dir eine solide Methode, wie man huntet. ATHF baut auf dieser Grundlage auf, indem es dir Struktur, Gedächtnis und Kontinuität bietet. PEAK leitet die Arbeit an. ATHF stellt sicher, dass du die Arbeit festhältst, organisierst und über zukünftige Hunts hinweg wiederverwendest.
Agentisches Threat Hunting bedeutet nicht, Analysten zu ersetzen. Es geht darum, Systeme zu bauen, die:
- sich merken, was zuvor getan wurde
- aus vergangenen Erfolgen und Fehlern lernen
- menschliches Urteilsvermögen durch kontextuellen Abruf unterstützen
Wenn dein Framework ein Gedächtnis hat, verlierst du kein Wissen mehr durch Personalwechsel oder vergessene Notizen. Wenn dein KI-Assistent auf dieses Gedächtnis zugreifen kann, wird er zum Kraftmultiplikator.
## 💬 Community & Einführung
- **GitHub Discussions:** [Fragen stellen, Hunts teilen](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/discussions)
- **Issues:** [Bugs melden oder Features anfragen](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/issues)
- **LinkedIn:** [Nebulock Inc.](https://www.linkedin.com/company/nebulock-inc) - Folge für Updates
**ATHF in deiner Organisation verwenden:** ATHF ist ein Framework zum Verinnerlichen, keine Plattform zum Erweitern. Forke es, passe es an, mach es zu deinem. Siehe [USING_ATHF.md](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/USING_ATHF.md) für Einführungsempfehlungen. Deine Hunts bleiben deine — das Zurückgeben ist optional, aber willkommen.
**Repository:** [https://github.com/Nebulock-Inc/agentic-threat-hunting-framework](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)
Das Ziel ist, jedem Threat-Hunting-Team zu helfen, von ad-hoc Gedächtnis zu strukturierter, agentischer Fähigkeit zu gelangen.
---
## 🛠️ Entwicklung & Anpassung
ATHF ist darauf ausgelegt, geforkt und für deine Organisation angepasst zu werden.
**Siehe [docs/INSTALL.md#development--customization](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework/blob/main/docs/INSTALL.md#development--customization) für:**
- Einrichten deines Forks für die Entwicklung
- Pre-Commit-Hooks für Codequalität
- Tests und Typprüfung
- Anpassungsbeispiele
- CI/CD-Integration
Schnellstart:
```bash
pip install -e ".[dev]" # Install dev dependencies
pre-commit install # Set up quality checks
pytest tests/ -v # Run tests
```
---
## 👤 Autor
Erstellt von **Sydney Marrone** © 2025
---
**Fang klein an. Dokumentiere eine Jagd. Füge Struktur hinzu. Baue Erinnerung auf.**
Erinnerung ist der Multiplikator. Handlungsfähigkeit ist die Kraft.
Sobald dein Programm sich erinnern kann, wird alles andere möglich.
Viel Erfolg bei der Jagd!