Threat Research Mcp

🔍 Threat Research MCP

Paste a threat report. Get a triage package in seconds.

IOC extraction · ATT&CK mapping · Hunt queries · Sigma rules · MITRE STIX enrichment Works with Claude Desktop · Cline · Cursor · Copilot · any MCP-compatible client

[](https://github.com/harshthakur6293/threat-research-mcp/actions/workflows/ci.yml) [](https://github.com/harshthakur6293/threat-research-mcp/actions/workflows/codeql.yml) [](https://github.com/harshthakur6293/threat-research-mcp/actions/workflows/security.yml) [](https://www.python.org/downloads/) [](LICENSE) [](https://modelcontextprotocol.io) [-ef4444)](#-at-a-glance)

[At a glance](#-at-a-glance) · [Quick Start](#-quick-start) · [Live Example](#-live-example) · [Coverage Matrix](#-coverage-matrix) · [How It Works](#-how-it-works) · [Tool Catalog](#-tool-catalog) · [Limitations](#-limitations) · [Contributing](#-contributing)

---

🎯 At a glance

What it does What it doesn't do

• A workflow orchestrator that takes free-form threat report text and emits a structured triage package: IOCs, ATT&CK technique guesses, hunt queries, and a navigator layer.
• A deterministic, offline-first MCP server — no LLM calls inside the toolbox, no hallucinated technique IDs, runs air-gapped.
• A 284-keyword ATT&CK index loaded from one YAML file ([keywords.yaml](src/threatresearchmcp/playbook/keywords.yaml)) that contributors can edit without touching Python.
• A hunt playbook with 37 techniques of hand-written SPL / KQL / Elastic / SQL queries embedded per log source.
• A self-contained HTML report with a D3 force graph, IOC table, and hunt cards — the strongest deliverable in the box.
• An honest scaffold for SOC teams to fork, extend with their own curated rules, and pipe into Claude Desktop / Cursor / Cline.

• Not a replacement for SigmaHQ or Elastic detection-rules. Only 3 full hand-written Sigma rules ship in the box. Everything else returns no_curated_rule + community search links.
• Not "production-ready" out of the box. Outputs are analyst drafts. Review, tune, and test against your environment before deploying.
• Not authoritative ATT&CK. Mapping is keyword-based; semantic gaps exist. Pair with mitre-attack-mcp or use the optional STIX enrichment for authoritative technique data.
• Not a TIP. Campaign tracking is JSON files on disk — fine for one analyst, not for a shared SOC platform.
• Not a SIEM connector. It produces queries; you copy/paste or deploy them via your own pipeline. No deploy_to_siem tool exists yet.
• Not a threat-intel feed. It analyzes intel that you paste or ingest — it doesn't subscribe to feeds for you.

---

📊 Component status

| Component | Status | Notes | |---|:---:|---| | Project hygiene | 🟢 Strong | 129 tests, 65% coverage gate, ruff/bandit/pip-audit clean, pinned deps | | MCP wiring | 🟢 Strong | 49 tools registered via FastMCP, stdio transport idiomatic | | HTML report | 🟢 Strong | Self-contained, D3 force graph + heatmap + IOC table — the marquee output | | IOC extraction | 🟡 Decent | Context-aware confidence + FP filtering; known edge cases on multi-dot TLDs | | ATT&CK keyword mapping | 🟡 Decent | 284 keywords, 119 techniques covered; semantic gaps remain | | Hunt query coverage | 🟡 Decent | 37 techniques × multi-SIEM in the hunt playbook | | Curated Sigma rules | 🟠 Thin | Only 3 hand-written rules. Everything else returns no_curated_rule + community links | | Confidence calibration | 🟠 Thin | Heuristic; tends to label LOW on noisy reports. Tunable in confidence_weights.yaml | | SOC operational integration | 🔴 Absent | No environment profile, no deploy_to_siem, no deployment registry | | Eval harness | 🔴 Absent | evals/run_test.py exists but no curated public-report eval set | | PyPI distribution | 🟠 In progress | Publish workflow merged; first pip install threat-research-mcp pending PyPI account setup |

---

⚡ Quick Start

# 1. Clone and install
git clone https://github.com/harshthakur6293/threat-research-mcp
cd threat-research-mcp
pip install -e ".[dev]"

# 2. Verify — 129 tests should pass (5 skipped: optional deps)
python -m pytest -q

# 3. Start the MCP server (your client connects via stdio)
python -m threat_research_mcp

> PyPI / uvx distribution coming. Publish workflow is merged; first release pending PyPI Trusted Publisher setup. Local install is the supported path today.

Claude Desktop — claudedesktopconfig.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "threat-research-mcp": {
      "command": "python",
      "args": ["-m", "threat_research_mcp"],
      "cwd": "/path/to/threat-research-mcp"
    }
  }
}

VS Code / Cline / Roo Code — .vscode/settings.json

{
  "cline.mcpServers": {
    "threat-research-mcp": {
      "command": "python",
      "args": ["-m", "threat_research_mcp"],
      "cwd": "${workspaceFolder}/../threat-research-mcp"
    }
  }
}

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "threat-research-mcp": {
      "command": "python",
      "args": ["-m", "threat_research_mcp"],
      "cwd": "/path/to/threat-research-mcp"
    }
  }
}

---

🎬 Live Example

Real run against the Google Mandiant UNC6692 Snow Flurries report (Teams phishing → browser extension backdoor → credential theft):

Input — paste into Claude:

Source: https://cloud.google.com/blog/topics/threat-intelligence/unc6692
UNC6692 Microsoft Teams phishing impersonating IT helpdesk. AutoHotkey
scripts from S3. SNOWBELT browser extension C2 over WebSocket AES-GCM.
SNOWGLAZE Python tunneler wss://sad4w7h913-b4a57f9c36eb.herokuapp.com:443/ws
SHA256 7f1d71e1e079f3244a69205588d504ed830d4c473747bb1b5c520634cc5a2477
lsass credential dump pass-the-hash lateral movement. Black Basta ransomware.

Pipeline output:

Source quality auto-detected: vendor_blog (0.75)
IOCs extracted: 4  (1 domain · 3 SHA256 hashes)

ATT&CK Techniques: 14 above threshold
  T1566.004  [MEDIUM 0.59]  Spearphishing via Service
               evidence: teams phishing, teams lure, impersonating it
  T1071      [MEDIUM 0.56]  Application Layer Protocol
               evidence: c2, command and control
  T1003.001  [LOW    0.54]  LSASS Memory
               evidence: lsass, credential dump
  T1550.002  [LOW    0.43]  Pass the Hash
  T1486      [LOW    0.47]  Data Encrypted for Impact
  ... 9 more

Sigma rules generated: 14  (1 curated · 13 with SigmaHQ/Elastic links)
Hunt hypotheses: 8

What you get back:

• IOC table with confidence scores and MALICIOUS / UNKNOWN / VICTIM labels
• ATT&CK technique cards with keyword evidence and links to attack.mitre.org
• Hunt queries (SPL · KQL · EQL · SQL) per technique × log source
• Curated Sigma YAML for the 3 supported techniques; community search links for the rest
• ATT&CK Navigator JSON — drag into attack.mitre.org/navigator
• Self-contained HTML report with D3 force graph, heatmap, and hunt cards

> ℹ️ The confidence model is intentionally conservative — even high-quality vendor_blog sources often land in LOW / MEDIUM. Thresholds and weights are tunable in [playbook/confidence_weights.yaml](src/threatresearchmcp/playbook/confidence_weights.yaml). See [Limitations](#-limitations) for details.

---

🧭 Coverage Matrix

Legend:  ✅ hand-written / curated  ·  🟡 playbook query (hand-written, embedded in hunt playbook)  ·  🔗 community link only (no_curated_rule)  ·  ❌ not covered

| Technique | Keyword index | Hunt hypothesis | Full Sigma | KQL | SPL | EQL | SQL | YARA | |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | T1059.001 PowerShell | ✅ | ✅ | ✅ | 🟡 | 🟡 | 🟡 | 🟡 | ✅ | | T1003.001 LSASS Memory | ✅ | ✅ | ✅ | 🟡 | 🟡 | 🟡 | 🟡 | ✅ | | T1071.001 C2 over Web Protocols | ✅ | ✅ | ✅ | 🟡 | 🟡 | 🟡 | 🟡 | ✅ | | T1053.005 Scheduled Task | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ✅ | | T1547.001 Registry Run Key | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ✅ | | T1505.003 Web Shell | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ✅ | | T1566.001 Spearphishing Attachment | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ✅ | | T1021.001 / .002 RDP / SMB | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1078 Valid Accounts | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1110.003 Password Spraying | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1486 Ransomware Encryption | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ✅ | | T1558.003 Kerberoasting | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1190 Exploit Public-Facing App | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1055 Process Injection | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ✅ | | T1027 Obfuscated Files | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ✅ | | T1543.003 Windows Service | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1041 / T1567.002 Exfiltration | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1046 Network Port Scanning | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1539 Steal Web Cookies | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1204.002 Malicious File | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1560.001 Archive (rar/7z) | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1059.002 AppleScript | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1543.001 Launch Agent (macOS) | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1548.006 TCC Manipulation (macOS) | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1555.003 Browser Credentials | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1195.001 / .002 Supply Chain | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1530 Cloud Storage Access | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1552.005 IMDS Credentials | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1078.004 Cloud Valid Accounts | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | T1609 / T1610 / T1613 Containers | ✅ | ✅ | 🔗 | 🟡 | 🟡 | 🟡 | 🟡 | ❌ | | Other 80+ techniques in keyword index | ✅ | ❌ | 🔗 | 🔗 | 🔗 | 🔗 | 🔗 | ❌ |

Bottom line:

• 3 full hand-written Sigma rules (T1059.001, T1003.001, T1071.001)
• 37 techniques with embedded SPL/KQL/Elastic/SQL queries in the hunt playbook
• 119 unique techniques in the keyword index (mapping only, no hand-written queries)
• All other techniques fall through to no_curated_rule with community search links

This matrix is manually maintained. If it drifts from reality, please open an issue.

---

🔬 How It Works

The pipeline

run_pipeline_tool chains all stages automatically from a single text input:

flowchart TD
    A["📄 Raw Intel Textreport · blog · IR note · paste"] --> B
    B["🔎 extract_iocsIPv4 · domains · hashes · emailsconfidence-scored · context-labelledRFC1918 / benign CDN auto-filtered"]
    B --> C["🗺️ map_ttp284-keyword ATT&CK indexevidence-based confidence scoresource quality auto-detectedIOC corroboration bonus"]
    C --> D["🎯 hunt_for_techniquesSPL · KQL · EQL · SQL queriesper technique × log source"]
    C --> E["📋 sigma_bundle3 curated rulescommunity links for the restno fake rules generated"]
    C --> F["🗃️ navigator_layerATT&CK Navigator JSONdrag into attack.mitre.org"]
    C --> G["📊 generate_threat_reportself-contained HTMLD3 force graph · heatmaphunt cards · Sigma cards"]

Each stage is also callable individually.

Confidence scoring

Every detected technique gets a score built from four dimensions:

| Dimension | Weight | What it measures | |---|:---:|---| | keywordspecificity | 35% | How diagnostic the keyword is (mimikatz=0.95 vs. script=0.30) | | evidencediversity | 25% | How many independent signals fired (1 keyword=0.30 → 5+ keywords=0.95) | | ioccorroboration | 20% | Whether extracted IOCs align with the technique (network IOC + C2 technique = +0.30 bonus) | | sourcequality | 20% | Authority of the intelligence source (cisa_advisory=1.0 · vendor_blog=0.75) |

| Label | Score | What to do | |:---:|:---:|---| | 🟢 HIGH | ≥ 0.75 | Multiple specific signals — treat as confirmed, deploy detection | | 🟡 MEDIUM | 0.55 – 0.75 | Credible — worth hunting, validate in your environment | | 🟠 LOW | 0.35 – 0.55 | Weak signal — analyst review before acting | | ⚫ SUPPRESSED | ⚠️ Calibration is conservative. On many real-world vendor reports, most techniques will land in LOW / MEDIUM. Tune thresholds and dimension weights in [playbook/confidence_weights.yaml](src/threatresearchmcp/playbook/confidence_weights.yaml) for your environment.

Source quality is auto-detected from URLs in the pasted text — CISA, Microsoft, Google/Mandiant, NCSC, and ISAC domains are all recognized automatically.

---

✨ STIX Enrichment (optional)

After run_pipeline_tool maps technique IDs, pass them to enrich_techniques_stix to pull authoritative detail directly from the official MITRE CTI STIX bundle:

T1059.001 — PowerShell
platforms:      Windows
data_sources:   Process: Process Creation
                Script: Script Execution
                Command: Command Execution
detection:      MITRE official guidance string
threat_groups:  APT32, Lazarus Group, Kimsuky, OilRig (+more)

One-time setup:

pip install "threat-research-mcp[attack]"      # installs mitreattack-python
python scripts/download_attack_stix.py          # downloads enterprise-attack.json (~50 MB)

Run stix_status to check if enrichment is active. The core pipeline works without this — STIX enrichment degrades gracefully.

---

📖 What Each Stage Produces

IOC Extraction — extract_iocs

Context-aware extraction with a confidence score and label per indicator. Automatically filters RFC1918 / loopback IPs, version strings, macOS bundle IDs (com.apple.*), and known-benign CDN domains.

{
  "ips":     [{"value": "185.220.101.47",     "confidence": 0.92, "label": "MALICIOUS"}],
  "domains": [{"value": "cdn.apple-cdn.org",  "confidence": 0.85, "label": "MALICIOUS"}],
  "hashes":  [{"value": "a3f8c2d1...",        "confidence": 0.78, "label": "HASH"}],
  "emails":  [{"value": "hr@careers-talent.io","confidence": 0.71, "label": "MALICIOUS"}],
  "filtered_fps": [{"value": "192.168.1.1",   "reason": "RFC1918"}]
}

Context patterns live in [playbook/ioc_context_patterns.yaml](src/threatresearchmcp/playbook/ioccontextpatterns.yaml) — editable without code changes.

Known edge case: multi-dot TLDs (*.trycloudflare.com, *.net.br) and sketchy newer TLDs (.site, .sh) may be over-rejected. Tracked in [Limitations](#-limitations).

ATT&CK Mapping — map_ttp

Maps text to techniques using a 284-keyword index loaded from [playbook/keywords.yaml](src/threatresearchmcp/playbook/keywords.yaml) — the single source of truth for all keyword→technique mappings. No hardcoded data in Python.

{
  "techniques": [
    {
      "id": "T1059.002",
      "name": "AppleScript",
      "tactic": "execution",
      "evidence": ["osascript", "applescript"],
      "confidence": 0.82,
      "confidence_label": "HIGH",
      "url": "https://attack.mitre.org/techniques/T1059/002/"
    }
  ],
  "suppressed": [...],
  "source_quality": "vendor_blog"
}

To add a keyword: edit [playbook/keywords.yaml](src/threatresearchmcp/playbook/keywords.yaml) and restart the server — no Python changes needed.

Hunt Hypotheses — huntfortechniques

Returns one hypothesis per technique × log source with a ready-to-run query in four SIEM flavours:

{
  "hypothesis": "Attacker invoked osascript to execute in-memory payload",
  "technique_id": "T1059.002",
  "log_source_key": "edr_macos",
  "queries": {
    "spl":     "index=edr source=macos process_name=osascript ...",
    "kql":     "DeviceProcessEvents | where FileName =~ 'osascript' ...",
    "elastic": "pr

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [harshthakur6293](https://github.com/harshthakur6293)
- **Source:** [harshthakur6293/threat-research-mcp](https://github.com/harshthakur6293/threat-research-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.