ThreatHunter-Playbook

A community-driven, open-source project to share detection logic, adversary tradecraft and resources to make detection development more efficient.

4,508

850

4,508

View on GitHub

Top Related Projects

cti

2,044

Cyber Threat Intelligence Repository expressed in STIX 2.0

atomic-red-team

11,629

Small and highly portable detection tests based on MITRE's ATT&CK.

OSSEM

1,289

Open Source Security Events Metadata (OSSEM)

Quick Overview

The OTRF/ThreatHunter-Playbook is a comprehensive resource for cybersecurity professionals, focusing on threat hunting techniques and methodologies. It provides a collection of hunting queries, data analysis procedures, and detection strategies to help security teams proactively identify and mitigate potential threats in their environments.

Pros

Extensive collection of threat hunting techniques and queries
Well-organized and categorized content for easy navigation
Regular updates and contributions from the cybersecurity community
Includes both general and platform-specific hunting strategies

Cons

May require advanced knowledge of security concepts and tools
Some queries might need adaptation for specific environments
Limited coverage of certain niche or emerging threat vectors
Requires ongoing maintenance to keep up with evolving threats

Getting Started

To get started with the ThreatHunter-Playbook:

Visit the GitHub repository: https://github.com/OTRF/ThreatHunter-Playbook
Browse the docs folder for detailed documentation and guides
Explore the notebooks directory for Jupyter notebooks with practical examples
Review the resources section for additional tools and references
Join the community discussions in the Issues and Pull Requests sections to contribute or ask questions

Note: This project is not a code library, but rather a collection of resources and documentation for threat hunting. Therefore, code examples and a quick start guide are not applicable in this context.

Competitor Comparisons

cti

2,044

Cyber Threat Intelligence Repository expressed in STIX 2.0

Pros of cti

Comprehensive MITRE ATT&CK framework data in STIX format
Regular updates with the latest threat intelligence
Widely adopted and integrated into many security tools

Cons of cti

Focuses primarily on data, lacking specific detection and response guidance
May require additional processing to extract actionable insights
Less emphasis on practical implementation for threat hunting

Code Comparison

ThreatHunter-Playbook (YAML):

name: Suspicious PowerShell Download Cradle
description: Detects suspicious PowerShell download cradles
detection:
  selection:
    EventID: 4104
    ScriptBlockText|contains:
      - 'Net.WebClient'
      - 'DownloadString'

cti (STIX JSON):

{
  "type": "attack-pattern",
  "id": "attack-pattern--970a3432-3237-47ad-bcca-7d8cbb217736",
  "name": "PowerShell",
  "description": "Adversaries may use PowerShell to execute various commands...",
  "kill_chain_phases": [
    {
      "kill_chain_name": "mitre-attack",
      "phase_name": "execution"
    }
  ]
}

While ThreatHunter-Playbook provides specific detection rules, cti offers structured threat intelligence data that can be used to develop comprehensive detection strategies.

atomic-red-team

11,629

Small and highly portable detection tests based on MITRE's ATT&CK.

Pros of Atomic Red Team

Extensive library of pre-built tests for various attack techniques
Easy-to-use format with tests organized by MITRE ATT&CK tactics
Active community and frequent updates

Cons of Atomic Red Team

Focuses primarily on attack simulation, less on detection and response
May require additional tools or setup for some tests

Code Comparison

ThreatHunter-Playbook (Jupyter Notebook example):

from openhunt.mordorutils import *
spark = get_spark()

df = spark.read.parquet(path)
df.printSchema()
df.show(10,False)

Atomic Red Team (YAML test definition):

attack_technique: T1003.001
display_name: 'OS Credential Dumping: LSASS Memory'
atomic_tests:
  - name: Dump LSASS.exe Memory using ProcDump
    auto_generated_guid: 0be2230c-9ab3-4ac2-8826-3199b9a0ebf8

ThreatHunter-Playbook provides more comprehensive analytics and detection strategies, while Atomic Red Team excels in providing a wide range of attack simulations. ThreatHunter-Playbook uses Jupyter Notebooks for analysis, whereas Atomic Red Team uses YAML for test definitions. Both repositories complement each other, with ThreatHunter-Playbook focusing on threat hunting and Atomic Red Team on attack simulation.

OSSEM

1,289

Open Source Security Events Metadata (OSSEM)

Pros of OSSEM

Provides a comprehensive data model for security events
Focuses on standardizing data structures and relationships
Offers broader applicability across various security tools and platforms

Cons of OSSEM

More complex and requires deeper understanding of data modeling
Less immediate practical application for threat hunting
May require more effort to implement in existing security workflows

Code Comparison

OSSEM (Data Dictionary):

- Standard_Name: UserName
  Standard_Type: String
  Description: The name of the user account
  Sample_Value: john.doe

ThreatHunter-Playbook (Analytic):

title: Suspicious PowerShell Download
description: Detects PowerShell downloading files from the internet
author: John Doe
detection:
  selection:
    EventID: 4104
    ScriptBlockText: '*Invoke-WebRequest*'

The OSSEM example shows a data dictionary entry, focusing on standardizing data fields. The ThreatHunter-Playbook example demonstrates a practical detection rule, ready for implementation in threat hunting scenarios.

sigma

10,226

Main Sigma Rule Repository

Pros of Sigma

Generic, vendor-agnostic rule format for easier sharing and portability
Extensive collection of pre-written detection rules
Supports conversion to various SIEM and data analysis tools

Cons of Sigma

Primarily focused on detection rules, less comprehensive for full threat hunting workflows
May require additional tools or scripts for implementation in some environments

Code Comparison

Sigma rule example:

title: Suspicious PowerShell Download
detection:
  selection:
    EventID: 4104
    ScriptBlockText|contains:
      - 'Net.WebClient'
      - '.DownloadFile'
  condition: selection

ThreatHunter-Playbook notebook example:

# Query for PowerShell download events
results = spark.sql("""
SELECT ScriptBlockText
FROM powershell_events
WHERE ScriptBlockText LIKE '%Net.WebClient%'
  AND ScriptBlockText LIKE '%.DownloadFile%'
""")

Both repositories provide valuable resources for threat detection and hunting. Sigma offers a standardized approach to writing and sharing detection rules, while ThreatHunter-Playbook provides more comprehensive playbooks and workflows for threat hunting scenarios. The choice between them depends on specific use cases and integration requirements.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

The Threat Hunter Playbook

The Threat Hunter Playbook is a community-driven, open source project focused on documenting how threat hunters think, plan, and reason before, during, and after a hunt. The project captures adversary tradecraft, detection logic, and supporting resources in a structured way to make threat hunting more effective and repeatable. All hunt documents follow the structure of MITRE ATT&CK, organizing post-compromise behavior into tactical groups and expressing it through interactive Jupyter notebooks. These notebooks combine markdown, analytics, datasets, and validation queries, allowing hunts to be treated as executable documents that preserve intent and reasoningânot just resultsâand can be run locally or remotely using pre-recorded security datasets and BinderHub.

With recent advances in Generative AI, the project has entered a transformation phase focused on augmenting threat hunting workflows across planning, execution, and reporting. Rather than replacing existing practices, the goal is to integrate AI in a way that reinforces structure and intent throughout the lifecycle. As a first step, the project incorporates solutions such as Agent Skills to capture hunting knowledge as explicit workflows, providing clear guidance, templates, and references. Agent Skills guide reasoning and decision making, refining broad inputs into structured, testable hunt artifacts and laying the groundwork for deeper AI augmentation over time.

Docs: https://threathunterplaybook.com/

Goals

Document and share how threat hunters plan, reason, and structure hunts across the full lifecycle.
Expedite the development of hunt techniques and hypotheses grounded in system behavior and adversary tradecraft.
Provide reusable workflows, templates, and references that support consistent hunt planning and analysis.
Enable validation and experimentation using pre-recorded security datasets, locally or through cloud-based environments.
Enable AI-augmented threat hunting workflows with human oversight.
Accelerate learning and knowledge sharing through open source, community-driven resources.

Threat Hunting as a Framework

The Threat Hunter Playbook is organized around a simple, repeatable lifecycle grounded in shared understanding of system behavior, adversary tradecraft, and environmental context. The framework captures how hunts are planned, executed, and documented, emphasizing structure and reasoning over ad hoc investigation.

At a high level, the framework consists of three stages:

Plan â Build context and analytic intent by defining the behavior being hunted, assumptions, expected activity, and how that behavior should manifest in telemetry.
Execute â Apply the plan by running queries, analyzing results, and iterating as assumptions are tested and new context emerges.
Report â Capture outcomes regardless of results, including findings, false positives, visibility gaps, and follow-on actions.

While the framework spans the full hunting lifecycle, the work in this repository currently concentrates on formalizing the planning stage, where intent, assumptions, and analytic structure are established before execution begins.

Agent Skills for Threat Hunting

To support this evolution, the project introduces Agent Skills as a way to express threat hunting workflows in a form that both humans and AI agents can follow consistently. Agent Skills package knowledge as explicit workflows with ordered steps, templates, and references, allowing agents to apply structure where it is most valuable.

In this project, Agent Skills are used to generate a structured hunt blueprint through workflows such as:

Researching system internals and adversary tradecraft
Defining a focused hunt hypothesis
Identifying relevant data sources
Developing analytics that model adversary behavior
Assembling a complete hunt blueprint for execution

For a detailed walkthrough and example of these workflows in action, see the accompanying blog post.

https://blog.openthreatresearch.com/evolving-the-threat-hunter-playbook-planning-hunts-with-agent-skills/

Authors

Roberto Rodriguez @Cyb3rWard0g
Jose Luis Rodriguez @Cyb3rPandaH

Acknowledgements

We document and share our content via a Jupyter Book which was created by Sam Lau and Chris Holdgraf with support of the UC Berkeley Data Science Education Program and the Berkeley Institute for Data Science

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot