PEAK Threat Hunting Notebooks

A structured collection of threat hunting notebooks using the PEAK methodology (Prepare, Execute, Act, Knowledge) for Azure ML Studio.

Overview

This repository provides a standardized framework for threat hunting using Jupyter notebooks with the PEAK methodology:

• Prepare: Hypothesis development and environment setup
• Execute: Query execution and data analysis
• Act: Response actions and alerting
• Knowledge: Documentation and lessons learned

Repository Structure

peak-threat-hunting-notebooks/
├── README.md                    # This file
├── CONTRIBUTING.md             # Guidelines for contributors
├── requirements.txt            # Python dependencies
├── .gitignore                 # Git ignore rules
│
├── template/
│   └── peak_hunt_template.ipynb   # Master template for new hunts
│
├── hunts/
│   ├── H001_execve_suspicious_linux.ipynb      # Hypothesis-driven hunt
│   ├── B001_baseline_network_volume.ipynb      # Baseline-driven hunt
│   └── M001_model_assisted_anomaly_detection.ipynb  # Model-assisted hunt
│
└── shared/
    └── splunk_helpers.py           # Common utilities and functions

Getting Started

Prerequisites

• Azure ML Studio workspace
• Access to Splunk environment
• Python 3.8+ with Jupyter support

Installation

1. Clone the repository:

   git clone https://github.com/THORCollective/peak-threat-hunting-notebooks.git
   cd peak-threat-hunting-notebooks

2. Install dependencies:

   pip install -r requirements.txt

3. Set up environment variables:

   # Add to your environment or .env file
   export SPLUNK_HOST="your-splunk-host"
   export SPLUNK_PORT="8089"
   export SPLUNK_USERNAME="your-username"
   # Use Azure Key Vault for passwords

Creating a New Hunt

1. Copy the template:

   cp template/peak_hunt_template.ipynb hunts/H002_your_new_hunt.ipynb

2. Open in Azure ML Studio:

   • Launch JupyterLab, Classic Jupyter, or VSCode
   • Navigate to your new hunt notebook
   • Follow the PEAK methodology sections

3. Fill in the metadata:

   • Hunt ID and title
   • Hypothesis statement
   • ABLE scoping (Attack, Behavior, Location, Evidence)
   • Expected outcomes

Hunt Naming Convention

Use the following naming pattern for hunt notebooks:

• H###_description.ipynb - Hypothesis-driven hunts
• B###_description.ipynb - Baseline-driven hunts
• M###_description.ipynb - Model-assisted hunts

Examples:

• H001_execve_suspicious_linux.ipynb
• B001_baseline_network_volume.ipynb
• M001_model_assisted_anomaly_detection.ipynb

PEAK Methodology

1. Prepare Phase

• Hypothesis Development: Clear, testable hypothesis
• ABLE Scoping: Define Attack, Behavior, Location, Evidence
• Environment Setup: Splunk connections, data sources
• Query Planning: Draft initial queries and filters

2. Execute Phase

• Data Collection: Run Splunk queries and gather data
• Analysis: Statistical analysis, visualization, pattern detection
• Refinement: Iterate on queries based on initial results
• Validation: Verify findings against known good/bad examples

3. Act Phase

• Response Actions: Immediate response to positive findings
• Alerting: Create detection rules and alerts
• Escalation: Procedures for confirmed threats
• Documentation: Record actions taken

4. Knowledge Phase

• Lessons Learned: Document insights and improvements
• Methodology Updates: Enhance hunting techniques
• Sharing: Contribute findings to team knowledge base
• Follow-up: Suggest related hunts or investigations

Shared Utilities

The shared/ directory contains common functions:

from shared.splunk_helpers import (
    connect_to_splunk,
    run_search,
    plot_timeline,
    export_results
)

Available functions:

• connect_to_splunk() - Establish Splunk connection
• run_search(query, earliest, latest) - Execute SPL queries
• plot_timeline(df, time_col, value_col) - Create time-series plots
• export_results(df, filename) - Save results to various formats

Best Practices

Security

• Never commit credentials - Use Azure Key Vault
• Sanitize outputs - Remove sensitive data before sharing
• Access control - Follow principle of least privilege

Analysis

• Document assumptions - Clearly state what you're looking for
• Show your work - Include reasoning for each step
• Validate findings - Cross-reference with multiple data sources
• Consider false positives - Account for legitimate use cases

Collaboration

• Clear naming - Use descriptive titles and IDs
• Reproducible - Include all necessary steps and dependencies
• Peer review - Have colleagues review complex hunts
• Version control - Commit frequently with clear messages

Example Hunts

H001: Suspicious Linux Execve Calls

Hypothesis-driven hunt looking for unusual process execution patterns on Linux systems.

B001: Baseline Network Volume

Baseline-driven hunt establishing normal network traffic patterns for anomaly detection.

M001: Model-Assisted Anomaly Detection

Model-assisted hunt using machine learning to identify anomalous user behavior.

Contributing

Please read CONTRIBUTING.md for guidelines on:

• Adding new hunts
• Improving existing templates
• Code style and formatting
• Pull request process

Support

For questions or issues:

• Check existing hunt notebooks for examples
• Review Azure ML Studio documentation
• Contact the threat hunting team
• Create GitHub issues for bugs or feature requests

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Happy hunting! 🔍