Nebulock-Inc/agentic-threat-hunting-framework

Agentic Threat Hunting Framework (ATHF)

What it is – A Python‑based, markdown‑driven framework that adds memory, structure, and AI‑ready context to a security team’s threat‑hunting workflow. It does not perform detection itself; instead it records each hunt using a lightweight LOCK pattern (Learn → Observe → Check → Keep), stores the records in a searchable repository, and exposes a set of CLI commands and an optional MCP server so AI assistants (Claude, Copilot, Cursor, etc.) can read and act on that knowledge.

Key pieces

• LOCK pattern – a four‑step template that every hunt is written into as a markdown file. This makes the hunt easy for both humans and LLMs to parse.
• GATES method – a validation skill that scores a finished hunt and decides whether the resulting detection should be promoted, held, made time‑boxed, etc. The skill is invoked via a chat‑style command (/gates --hunt H‑0001).
• CLI (athf) – commands to initialise a workspace, create research notes, start new hunts, list/search hunts, run validation, and pull MITRE ATT&CK metadata. Optional extras install extra dependencies for ATT&CK data ([attack]) or the MCP server ([mcp]).
• MCP server – a local micro‑service that lets an LLM‑powered coding assistant call ATHF functions (search, hypothesis generation, etc.) without leaving the editor.
• Maturity model – five levels (0 = ad‑hoc, 4 = fully autonomous agents) that describe how far a team has progressed in using ATHF.

Who it’s for – Security operations or threat‑hunting teams that already have a hunting methodology (e.g., PEAK, TaHiTI) and want a lightweight way to capture, search, and reuse that work, especially when they plan to involve LLM‑based assistants.

How you would use it

1. pip install agentic-threat-hunting-framework and run athf init to create a workspace.
2. Run athf research new … to generate a markdown research note (optionally powered by an LLM).
3. Create a hunt with athf hunt new …, filling in the LOCK sections.
4. When the hunt is finished, invoke the GATES skill (/gates --hunt H‑XXXX) to get a promotion verdict.
5. Optionally feed the GATES output into the companion detection‑engineering framework (ADEF) to build production rules.

Why it matters – By persisting every hunt in a consistent, machine‑readable format, ATHF prevents knowledge loss, enables semantic search, and lets LLM assistants suggest queries or hypotheses based on the team’s own history rather than starting from scratch each time.

Limitations – ATHF does not include its own detection engine, data collection, or SIEM integration; it relies on the organization’s existing tools and on external LLM assistants for any generative capabilities.

---

Quick start snippet

pip install agentic-threat-hunting-framework
athf init               # set up workspace
athf research new --topic "LSASS dumping" --technique T1003.001
athf hunt new --technique T1003.001 --title "LSASS Credential Dumping" --research R-0001
/gates --hunt H-0001    # ask the AI skill to score the hunt

---

Further reading – The repository includes detailed docs on the LOCK pattern, the GATES method, the MCP integration, and a maturity‑model guide, plus a showcase of example hunts.