Proactive Threat Hunting

Structured, hypothesis-driven threat hunting with campaign management, cross-SIEM query library, IOC sweeps, collaborative workflows, and automatic detection rule generation.

Complete 7 Models 30+ Endpoints Multi-SIEM

Overview

The Threat Hunting module enables SOC analysts to conduct structured, hypothesis-driven threat hunts across customer environments. Unlike reactive alert triage, threat hunting is proactive -- analysts formulate hypotheses about adversary behavior, build SIEM queries across multiple platforms (KQL, SPL, EQL, AQL, UDM), execute them against tenant data, record findings, and convert confirmed findings into permanent detection rules.

The module supports the full hunt lifecycle: campaign creation, hypothesis management, query execution, finding recording, retrospective IOC hunts, cross-tenant IOC sweeps, collaborative notes/tasks, reporting, and threat landscape intelligence with MITRE coverage gap analysis.

What Was Proposed

Structured hunt campaigns tied to MITRE ATT&CK techniques
Hypothesis-driven workflow with status tracking (proposed/testing/confirmed/refuted)
Multi-SIEM query library organized by technique and tactic
Query execution against tenant SIEMs (KQL, SPL, EQL, AQL, UDM)
Finding-to-Sigma-rule conversion
Retrospective IOC hunting with configurable lookback
Cross-tenant IOC sweep with batch and scheduled modes
Collaborative hunting with notes, tasks, and analyst assignment
Hunt playbooks with step-by-step instructions
Reporting: executive summaries, full reports, hunt metrics, Sigma export
Threat landscape: technique heatmap, coverage gap analysis
7 PostgreSQL database models for persistence

What's Built

Service Components

ThreatHuntingService

Campaign CRUD with status lifecycle (draft/active/completed/cancelled)
Query management with multi-SIEM support
Finding recording with severity and evidence
Finding-to-Sigma-rule conversion
Retrospective IOC hunting
Hunt statistics
Pre-built query library organized by MITRE technique/tactic

HuntWorkflow

Hypothesis creation linked to campaigns
Status tracking: draft → testing → confirmed/refuted
Pre-built hypothesis templates
MITRE technique & data source mapping

IOCSweeper

Single IOC sweep across tenants
Batch IOC sweep (multiple IOCs at once)
Sweep result retrieval
Scheduled recurring sweeps
9 IOC types: ip, domain, hash_md5, hash_sha256, url, email, filename, registry_key, mutex

Collaboration & Reporting

Hunt notes (observation, finding, question, action_item)
Analyst task assignment with due dates
Full hunt reports with executive summaries
Hunt metrics: completion rate, findings/hunt, avg duration
Bulk Sigma rule export from campaign findings
Threat landscape intelligence & coverage gap analysis

Architecture

Hunt Campaign Flow

Analyst → Create Campaign + Hypothesis → Select/Write Queries → Execute Against SIEM → Record Findings → Convert to Detection Rules

Service singletons: threat_hunting_service, hunt_workflow, ioc_sweeper, hunt_playbooks, hunt_collaboration, hunt_reporter, threat_landscape

API Routing

Router prefix: /api/v1/hunting — Tag: threat-hunting

Campaign Endpoints

POST /api/v1/hunting/campaigns

Create a new hunt campaign. Body: name, hypothesis, mitre_techniques[], created_by, description, tags[]

GET /api/v1/hunting/campaigns

List all campaigns. Filter: ?status=draft|active|completed|cancelled

GET /api/v1/hunting/campaigns/{campaign_id}

Get full campaign details including queries and findings.

PATCH /api/v1/hunting/campaigns/{campaign_id}/status

Update campaign status (draft/active/completed/cancelled).

Query Endpoints

POST /api/v1/hunting/campaigns/{campaign_id}/queries

Add a hunt query. Body: query (text), siem_type (kql/spl/eql/aql/udm), description.

POST /api/v1/hunting/campaigns/{campaign_id}/execute/{query_id}

Execute a hunt query against tenant SIEM. Optional: ?tenant_id=...

Finding Endpoints

POST /api/v1/hunting/campaigns/{campaign_id}/findings

Record a finding. Body: title, description, severity, evidence[], mitre_technique, iocs_found[], recommendation.

POST /api/v1/hunting/findings/{finding_id}/to-rule

Convert a finding into a Sigma detection rule.

Retrospective & IOC Sweep

POST /api/v1/hunting/retrospective

Search historical SIEM data for IOCs. Body: iocs[], lookback_days (1-365), tenant_id.

POST /api/v1/hunting/sweep

Sweep a single IOC across tenants. Body: ioc_type, ioc_value, tenant_ids[].

POST /api/v1/hunting/sweep/batch

Batch sweep multiple IOCs. Body: iocs[{type, value}], tenant_ids[].

GET /api/v1/hunting/sweep/{sweep_id}/results

Get results of a completed IOC sweep.

POST /api/v1/hunting/sweep/schedule

Schedule a recurring IOC sweep. Body: iocs[], frequency_hours (1-720), tenant_ids[].

Hypothesis Workflow

POST /api/v1/hunting/hypotheses

Create a hypothesis. Body: campaign_id, title, description, mitre_techniques[], data_sources[], expected_evidence.

GET /api/v1/hunting/hypotheses/{campaign_id}

List all hypotheses for a campaign.

PUT /api/v1/hunting/hypotheses/{hypothesis_id}

Update hypothesis status (draft/testing/confirmed/refuted) and attach findings.

GET /api/v1/hunting/hypothesis-templates

List pre-built hypothesis templates.

Collaboration

POST /api/v1/hunting/{campaign_id}/notes

Add a note: analyst_id, content, note_type (observation/finding/question/action_item).

GET /api/v1/hunting/{campaign_id}/notes

Get all notes for a campaign. Filter: ?note_type=...

POST /api/v1/hunting/{campaign_id}/tasks

Assign a task: analyst_id, description, due_hours (1-720).

PUT /api/v1/hunting/tasks/{task_id}

Update task status (pending/in_progress/completed).

Reporting & Landscape

GET /api/v1/hunting/{campaign_id}/report

Generate full hunt report with executive summary, methodology, findings, MITRE mapping.

GET /api/v1/hunting/{campaign_id}/executive-summary

Concise executive summary for a campaign.

GET /api/v1/hunting/metrics

Aggregated hunt metrics: completion rate, findings per hunt, avg duration.

POST /api/v1/hunting/{campaign_id}/export-sigma

Export all findings from a campaign as Sigma detection rules.

GET /api/v1/hunting/stats

Aggregate hunting statistics (active campaigns, total findings, rules generated, library size).

GET /api/v1/hunting/landscape

Current threat landscape: trends, active campaigns, top techniques.

GET /api/v1/hunting/technique-heatmap

MITRE ATT&CK technique heatmap with hunt coverage overlay.

GET /api/v1/hunting/coverage-gaps

Identify techniques not yet covered by hunts.

Query Library

GET /api/v1/hunting/library

Browse pre-built queries. Filters: ?tactic=..., ?keyword=...

GET /api/v1/hunting/library/{technique_id}

Get queries for a specific MITRE technique.

Hunt Playbooks

GET /api/v1/hunting/playbooks

List all available hunt playbooks.

GET /api/v1/hunting/playbooks/{playbook_id}

Get detailed playbook with step-by-step instructions.

Frontend Route

/threat-hunting — Full-featured page with stats dashboard, campaign cards, query library browser with KQL/SPL/EQL tabs, campaign detail view, new campaign modal, and retrospective hunt form.

Prerequisites

PostgreSQL database with 7 tables (see Data Model below)
Access to tenant SIEM connectors for query execution
SQLAlchemy ORM with app.core.database.Base
Frontend uses api client from @/lib/api-client

Data Model

7 SQLAlchemy models in platform/api/app/models/threat_hunting.py, persisted to PostgreSQL:

Model	Table	Key Fields
HuntCampaign	`hunt_campaigns`	id (PK), tenant_id (idx), name, description, hypothesis, status (enum: draft/active/completed/cancelled), created_by, mitre_techniques (JSON), tags (JSON), created_at, updated_at
HuntQuery	`hunt_queries`	id (PK), campaign_id (FK, idx), query_text, siem_type, description, status (enum: pending/running/completed/failed), executed_at, result_count
HuntFinding	`hunt_findings`	id (PK), campaign_id (FK, idx), title, description, severity (enum: 5 levels), mitre_technique, evidence (JSON), iocs (JSON), converted_to_rule, created_at
HuntHypothesis	`hunt_hypotheses`	id (PK), campaign_id (FK, idx), hypothesis_text, status (enum: proposed/testing/confirmed/rejected), rationale, created_by, created_at
IOCSweep	`ioc_sweeps`	id (PK), tenant_id (idx), ioc_type, ioc_value, status (enum: pending/running/completed), started_at, completed_at, match_count, results (JSON)
HuntNote	`hunt_notes`	id (PK), campaign_id (FK, idx), author, content, note_type (enum: observation/finding/question/action_item), created_at
HuntTask	`hunt_tasks`	id (PK), campaign_id (FK, idx), title, description, assigned_to, status (enum: pending/in_progress/completed), due_date, created_at

Relationships

HuntCampaign has one-to-many relationships (with cascade="all, delete-orphan") to: HuntQuery, HuntFinding, HuntHypothesis, HuntNote, HuntTask.

UI Description

The frontend at /threat-hunting includes:

Stats Dashboard -- 4 stat cards: Active Campaigns, Total Findings, Rules Generated, Queries in Library
Active Campaigns Grid -- 2-column cards with campaign name, status badge (draft/active/completed), hypothesis, MITRE technique tags, query count, findings count, start date. Click to view detail.
Campaign Detail View -- Back button, campaign header with status, hypothesis, MITRE tags. Hunt queries table with execution status (pending/running/completed/failed). Findings table with severity, technique, IOC count, and "Convert to Rule" action. "Generate Report" button.
Query Library Browser -- Search input + tactic filter dropdown. 2-column query cards with name, technique ID, description, tactic. Expandable KQL/SPL/EQL tabs showing syntax-highlighted query code.
Retrospective Hunt -- Collapsible section with IOC textarea (one per line), lookback period dropdown (30/60/90 days), "Submit Hunt" button.
New Campaign Modal -- Form: Campaign Name, Hypothesis (textarea), MITRE Techniques (comma-separated).

Source Files

Component	Path
API Router	`platform/api/app/routers/threat_hunting.py`
Service Engine	`platform/api/app/services/threat_hunting.py`
DB Models	`platform/api/app/models/threat_hunting.py`
Frontend Page	`platform/frontend/src/app/threat-hunting/page.tsx`