peak-to-sigma

Convert PEAK-framework threat hunt reports into production detection rules.

Supports: Sigma · KQL (Sentinel/Defender) · SPL (Splunk) · Databricks SQL · MITRE ATT&CK Navigator

---

Why

Every structured threat hunt should produce durable detection artifacts. When a hunt confirms attacker behavior, the findings should immediately feed back into your detection stack — not sit in a Word document.

peak-to-sigma closes the hunt-to-detection gap. Feed it a structured hunt report and it outputs ready-to-deploy detection rules in every format your stack consumes, plus a MITRE ATT&CK Navigator layer showing exactly what you hunted and what you confirmed.

flowchart TD
    subgraph INPUT["INPUT"]
        A["🔍 Threat Hunt\n─────────────\nPEAK Phase\nHypothesis\nVerdict"]
        B["📡 Data Sources\n─────────────\nEndpoint · Network\nIdentity · Cloud"]
        C["🎯 Findings & IOCs\n─────────────\nATT&CK Technique\nConfirmed / Unconfirmed\n15 IOC Types"]
    end

    subgraph REPORT["HUNT REPORT  (.yaml / .json)"]
        D["HuntReport\n─────────────\nPydantic v2 validation\nCross-field checks"]
    end

    subgraph ENGINE["GENERATION ENGINE"]
        E["Logsource\nResolver\n─────────\n25+ sources\nmapped to\nSigma categories"]
        F["IOC → Field\nMapper\n─────────\nCross-platform\nfield translation"]
    end

    subgraph OUTPUT["OUTPUT ARTIFACTS"]
        G["📄 Sigma YAML\n─────────────\nstable / experimental\nhigh / medium level"]
        H["☁️  KQL\n─────────────\nMicrosoft Sentinel\nDefender XDR"]
        I["🔎 SPL\n─────────────\nSplunk Enterprise\nSecurity CIM"]
        J["🗄️  SQL\n─────────────\nDatabricks\nDelta Lake"]
        K["🗺️  Navigator\n─────────────\nATT&CK Layer v4.5\nconfirmed = red\nunconfirmed = amber"]
        L["🤖 Enrichment\n─────────────\nLLM gap analysis\nOpenAI · Anthropic"]
    end

    A & B & C --> D
    D --> E & F
    E & F --> G & H & I & J & K
    D -.->|"--enrich"| L

    style INPUT    fill:#0d0d24,stroke:#2a2a7a,color:#e0e0ff
    style REPORT   fill:#0d0d24,stroke:#b44fff,color:#e0e0ff
    style ENGINE   fill:#0d0d24,stroke:#2a2a7a,color:#e0e0ff
    style OUTPUT   fill:#0d0d24,stroke:#2a2a7a,color:#e0e0ff
    style A        fill:#12122e,stroke:#2a2a7a,color:#e0e0ff
    style B        fill:#12122e,stroke:#2a2a7a,color:#e0e0ff
    style C        fill:#12122e,stroke:#2a2a7a,color:#e0e0ff
    style D        fill:#1a0a2e,stroke:#b44fff,color:#e0e0ff
    style E        fill:#12122e,stroke:#2a2a7a,color:#e0e0ff
    style F        fill:#12122e,stroke:#2a2a7a,color:#e0e0ff
    style G        fill:#12122e,stroke:#05d9e8,color:#e0e0ff
    style H        fill:#12122e,stroke:#05d9e8,color:#e0e0ff
    style I        fill:#12122e,stroke:#05d9e8,color:#e0e0ff
    style J        fill:#12122e,stroke:#05d9e8,color:#e0e0ff
    style K        fill:#12122e,stroke:#05d9e8,color:#e0e0ff
    style L        fill:#12122e,stroke:#ffe900,color:#e0e0ff

Loading

---

Install

pip install peak-to-sigma

With LLM enrichment support:

pip install 'peak-to-sigma[enrich]'

Or install from source for development:

git clone https://github.com/acseguin21/peak-to-sigma
cd peak-to-sigma
pip install -e ".[dev]"

---

Quick Start

# Generate all formats from the bundled example
peak-to-sigma main --hunt examples/aitm_hunt.yaml

# Output goes to ./detections/<hunt-slug>/
ls detections/aitm-proxy-detection-infostealer-delivery/
# sigma/   kql/   spl/   sql/   aitm-proxy-detection-infostealer-delivery_layer.json

Or use the guided web UI:

pip install 'peak-to-sigma[web]'
peak-to-sigma serve
# Open http://localhost:8000

---

Web UI

peak-to-sigma ships a local web interface — a guided, educational wizard that walks analysts through structuring their hunt findings and generating detection artifacts with full in-browser previews.

pip install 'peak-to-sigma[web]'
peak-to-sigma serve

Open http://localhost:8000 in your browser.

Features:

• 4-step wizard: Hunt Metadata → Data Sources → Findings & IOCs → Generate
• Educational tooltips on every field explaining PEAK phases, ATT&CK technique formats, IOC types, and detection confidence levels
• In-browser syntax-highlighted output (Sigma YAML, KQL, SPL, SQL) with copy-to-clipboard
• MITRE ATT&CK Navigator layer preview and download
• One-click ZIP download of all generated artifacts
• Load the bundled AiTM example to see a complete flow
• Runs entirely locally — no data leaves your machine

# Options
peak-to-sigma serve --host 0.0.0.0 --port 9000   # bind to all interfaces
peak-to-sigma serve --reload                       # dev mode with auto-reload

---

CLI Usage

peak-to-sigma main --hunt REPORT [OPTIONS]

Options:
  --hunt, -h PATH          Path to PEAK hunt report (.yaml / .yml / .json)  [required]
  --output, -o TEXT        Comma-separated formats: sigma,kql,spl,sql  [default: all]
  --mitre-layer            Generate ATT&CK Navigator layer JSON  [default: on]
  --no-mitre-layer         Skip Navigator layer
  --enrich                 Run LLM enrichment (requires API key env var)
  --out PATH               Base output directory  [default: ./detections]
  --include-unconfirmed    Also generate draft rules for unconfirmed findings
  --llm-provider TEXT      LLM provider: openai or anthropic  [default: openai]
  --version, -v            Show version and exit
  --help                   Show this message and exit

Examples

# Sigma rules only
peak-to-sigma main --hunt hunt_report.yaml --output sigma

# KQL and Sigma, no Navigator layer
peak-to-sigma main --hunt hunt_report.yaml --output sigma,kql --no-mitre-layer

# Include draft rules for unconfirmed findings (labelled medium confidence)
peak-to-sigma main --hunt hunt_report.yaml --include-unconfirmed

# Custom output directory
peak-to-sigma main --hunt hunt_report.yaml --out ./detections/q2-2026

# LLM enrichment via OpenAI (set OPENAI_API_KEY first)
peak-to-sigma main --hunt hunt_report.yaml --enrich

# LLM enrichment via Anthropic
ANTHROPIC_API_KEY=sk-... peak-to-sigma main --hunt hunt_report.yaml --enrich --llm-provider anthropic

---

Hunt Report Schema

Hunt reports are YAML (or JSON) files following this structure:

hunt:
  name: "AiTM Proxy Detection — Infostealer Delivery"
  hypothesis: "Threat actors are using adversary-in-the-middle frameworks..."
  analyst: "Andre Seguin"
  date: "2026-04-08"
  peak_phase: "Scoped"   # Unscoped | Scoped | Validated

data_sources:
  - name: "Microsoft Defender EDR"
    type: endpoint        # endpoint | network | cloud | identity | email | web
    coverage: high        # high | medium | low

findings:
  - tactic: "Credential Access"
    technique: "T1557.001"              # MITRE ATT&CK ID
    technique_name: "Adversary-in-the-Middle: LLMNR/NBT-NS Poisoning"
    confirmed: true
    description: "Observed proxy process injecting into browser SSL sessions..."
    data_source_ref: "Microsoft Defender EDR"   # must match a data_sources entry
    iocs:
      - type: process_name
        value: "suspicious_proxy.exe"
      - type: cert_issuer
        value: "Untrusted Root CA"

verdict: "Confirmed attacker activity. Hunt promoted to ongoing monitoring."

IOC Types

Type	Maps to
process_name	Sigma Image, KQL FileName, SPL process_name
command_line	Sigma CommandLine, KQL ProcessCommandLine
parent_process	Sigma ParentImage, KQL InitiatingProcessFileName
hash_sha256	Sigma sha256, KQL SHA256
ip	Sigma DestinationIp, KQL RemoteIP
domain	Sigma DestinationHostname, KQL RemoteUrl
cert_issuer	Sigma CertificateIssuer
registry_key	Sigma TargetObject, KQL RegistryKey
file_path	Sigma TargetFilename, KQL FolderPath
url	Sigma cs-uri-stem
user_agent	Sigma cs-user-agent
email_sender	Sigma SenderAddress, KQL SenderFromAddress
network_port	Sigma DestinationPort, KQL RemotePort
hash_md5, hash_sha1	Sigma Hashes

---

Output Formats

Sigma (.yml)

One rule per confirmed finding. Generated directly as Sigma-compatible YAML — no pySigma programmatic API required. Rules are round-trip compatible with sigma-cli for conversion to any additional backends.

sigma convert -t splunk detections/my-hunt/sigma/t1557-001-*.yml

KQL (.kql)

Microsoft Sentinel / Defender XDR queries. Attempts pySigma Kusto backend conversion first; falls back to direct KQL construction from IOCs. Usable in Sentinel analytic rules or Defender custom detections.

SPL (.spl)

Splunk searches using CIM-compliant field names. Compatible with Splunk Enterprise Security.

Databricks SQL (.sql)

Delta Lake / Unity Catalog queries targeting security.* tables. Assumes a standard security data lake schema — adjust table names for your environment.

MITRE ATT&CK Navigator Layer (.json)

Layer schema v4.5. Confirmed findings are red, unconfirmed findings (when --include-unconfirmed is passed) are amber. Import directly into the ATT&CK Navigator.

---

LLM Enrichment (--enrich)

When --enrich is passed, the tool calls an LLM with the hunt findings and produces enrichment_suggestions.md containing:

• Detection gaps
• Related ATT&CK techniques not investigated
• Recommended data sources
• False positive risks
• Suggested hunting pivots

Requires:

pip install 'peak-to-sigma[enrich]'

# Then set one of:
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

Enrichment output is clearly labelled as AI-generated. Treat as analytical starting points, not confirmed detections.

---

Development

# Install all dependencies (core + web + dev)
pip install -e ".[web,dev]"

# Run tests
pytest

# Lint
ruff check peak_to_sigma tests

# Type check
mypy peak_to_sigma

# Launch web UI in dev mode (auto-reload on file changes)
peak-to-sigma serve --reload

---

PEAK Framework

This tool is built around the PEAK Threat Hunting Framework by Shan Bhukya and the threat hunting community. PEAK (Prepare, Execute, Act with Knowledge) provides a structured methodology for hypothesis-driven threat hunting.

---

MITRE ATT&CK

This project references the MITRE ATT&CK® framework. ATT&CK is a registered trademark of The MITRE Corporation. Use of ATT&CK technique IDs and tactic names follows the MITRE ATT&CK Terms of Use.

---

License

MIT