threat-research-mcp - Open-source MCP server for defensive security: in

项目说明

<di="center">

🔍 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<br>
Works with Claude Desktop · Cline · Cursor · Copilot · any MCP-compatible client

<br>

![CI]()
![CodeQL]()
![Security]()
![Python 3.10+]()
![MCP]()

<br>

At a glance · Quick Start · Li · Co Matrix · How It Works · Tool Catalog · Limitations · Contributing

</div>

---

🎯 At a glance

<table>
<tr>
<th width="50%">What it does</th>
<th width="50%">What it doesn't do</th>
</tr>
<tr>
<td ="top">

</td>
<td ="top">

</td>
</tr>
</table>

---

📊 Component status

| Component | Status | Notes |
|---|:---:|---|
| Project hygiene | 🟢 Strong | 129 tests, 65% co gate, ruff/bandit/pip-audit clean, pinned deps |
| MCP wiring | 🟢 Strong | 49 tools registered , 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 co | 🟡 Decent | 37 techniques × multi-SIEM in the hunt playbook |
| Curated Sigma rules | 🟠 Thin | Only 3 hand-written rules. E 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 en profile, no deploy_to_siem, no deployment registry |
| E | 🔴 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

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

<details>
<summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>

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

</details>

<details>
<summary><b>VS Code / Cline / Roo Code</b> — <code>./settings.json</code></summary>

</details>

<details>
<summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code></summary>

</details>

---

🎬 Li

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

Input — paste into Claude:

Pipeline output:

What you get back:

> ℹ️ The confidence model is intentionally conser — e sources often land in LOW / MEDIUM. Thresholds and weights are tunable in playbook/confidence_weights.yaml. See Limitations for details.

---

🧭 Co Matrix

Legend:
&nbsp;✅ hand-written / curated&nbsp;&nbsp;·&nbsp;&nbsp;🟡 playbook query (hand-written, embedded in hunt playbook)&nbsp;&nbsp;·&nbsp;&nbsp;🔗 community link only (no_curated_rule)&nbsp;&nbsp;·&nbsp;&nbsp;❌ 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:

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:

Each stage is also callable indi.

Confidence scoring

Every detected technique gets a score built from four dimensions:

| Dimension | Weight | What it measures |
|---|:---:|---|
| keyword_specificity | 35% | How diagnostic the keyword is (mimikatz=0.95 vs. script=0.30) |
| e | 25% | How many independent signals fired (1 keyword=0.30 → 5+ keywords=0.95) |
| ioc_corroboration | 20% | Whether extracted IOCs align with the technique (network IOC + C2 technique = +0.30 bonus) |
| source_quality | 20% | Authority of the intelligence source (cisa_ad=1.0 · =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, in your en |
| 🟠 LOW | 0.35 – 0.55 | Weak signal — analyst review before acting |
| ⚫ SUPPRESSED | < 0.35 | Returned in suppressed[] — noise filtered from main list |

> ⚠️ Calibration is conser. On many real-world reports, most techniques will land in LOW / MEDIUM. Tune thresholds and dimension weights in playbook/confidence_weights.yaml for your en.

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 authoritati directly from the official MITRE CTI STIX bundle:

One-time setup:

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

---

📖 What Each Stage Produces

<details>
<summary><b>IOC Extraction</b> — <code>extract_iocs</code></summary>

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

Context patterns live in playbook/ioc_context_patterns.yaml — editable without code changes.

Known edge case: multi-dot TLDs (*.trycloudflare.com, *.net.br) and sketchy newer TLDs (.site, .sh) may be o. Tracked in Limitations.
</details>

<details>
<summary><b>ATT&CK Mapping</b> — <code>map_ttp</code></summary>

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

To add a keyword: edit playbook/keywords.yaml and restart the server — no Python changes needed.
</details>

<details>
<summary><b>Hunt Hypotheses</b> — <code>hunt_for_techniques</code></summary>

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

37 techniques ha queries in the hunt playbook. Techniques outside the playbook return a techniques_not_in_playbook notice.
</details>

<details>
<summary><b>Sigma Rules</b> — <code>sigma_bundle_for_techniques</code></summary>

Returns hand-written Sigma rules for 3 techniques only: T1059.001, T1003.001, T1071.001.

For e else, returns a structured no_curated_rule response with direct search links to SigmaHQ, Elastic detection-rules, and Splunk Security Content — no plausible-looking fake rules are generated.

This is intentional. Generating a plausible-looking generic rule for every technique is worse than honestly returning "I don't have this — here's where to look."
</details>

---

🗂️ Tool Catalog

49 registered MCP tools across 12 categories. Full in in server.py.

🚀 Primary Workflow

| Tool | What it does |
|---|---|
| run_pipeline_tool | Full pipeline: text → IOCs → ATT&CK → hunts → Sigma (one call) |
| extract_iocs | Context-aware IOC extraction with confidence scores |
| map_ttp | ATT&CK technique mapping with e + confidence |
| hunt_from_intel | Hunt hypotheses directly from raw text |
| hunt_for_techniques | Hunt hypotheses for specific technique IDs |
| list_log_sources_tool | List a log source keys for filtering |
| generate_threat_report | Self-contained HTML report from pipeline JSON |
| na | ATT&CK Na layer JSON |

🌐 STIX Enrichment *(optional — requires setup)*

| Tool | What it does |
|---|---|
| enrich_techniques_stix | Platforms · data sources · detection notes · threat groups from MITRE STIX |
| stix_status | Check if mitreattack-python + STIX bundle are ready |

📋 Sigma and Detection Drafts

| Tool | What it does |
|---|---|
| generate_sigma_rule | Build Sigma from title + behavior description |
| sigma_for_technique | Curated Sigma (3 techniques) or no_curated_rule with community links |
| sigma_bundle_for_techniques | Batch Sigma for multiple techniques |
| | Offline structure (no CLI needed) |
| score_sigma | Score specificity, co, FP risk — *see known issue* |
| score_technique_sigma | Score a built-in curated rule — *see known issue* |
| kql_for_technique | Microsoft Sentinel KQL — 37 techniques from hunt playbook |
| spl_for_technique | Splunk SPL — 37 techniques from hunt playbook |
| eql_for_technique | Elastic EQL — 37 techniques from hunt playbook |
| sql_detection | Generic SQL (Snowflake / BigQuery / Athena / Databricks) — 37 techniques |
| yara_for_technique | YARA file-scanning rules — 10 techniques |
| generate_yara | Custom YARA from string patterns |
| ioc_sigma_bundle | IOC blocklist Sigma bundle with TTL guidance |
| detection_co | Gap analysis: tracked techniques detections |
| atomic_tests_for_technique | Atomic Red Team test IDs for |

🔬 IOC Enrichment *(optional — requires API keys)*

| Tool | What it does |
|---|---|
| enrich_ioc_tool | Single IOC: · OTX · AbuseIPDB · URLhaus |
| enrich_iocs_tool | Bulk enrich comma-separated IOCs (capped at 20) |

📥 Intake and Parsing

| Tool | What it does |
|---|---|
| ingest_feed | TAXII 2.1 · RSS/Atom · HTML · local file ingestion |
| analyze_intel | Pipeline on text + ingested feed documents |
| parse_stix | Parse STIX 2.x bundle JSON |
| stix_to_text | Flatten STIX to pipeline-ready text |
| timeline | Sort log lines / event notes chronologically |

🔗 MISP Integration *(optional — requires MISP_URL + MISP_KEY)*

| Tool | What it does |
|---|---|
| misp_pull | Pull events → IOCs + pipeline-ready text |
| misp_push_sigma | Push Sigma rule as attribute to a MISP event |
| misp_create_event | Create MISP event from pipeline output |

📁 Campaign Tracking *(JSON file-based — not a TIP)*

| Tool | What it does |
|---|---|
| campaign_update | Store / update campaign state |
| campaign_get | Retrie state |
| campaign_list | List all tracked campaigns |
| campaign_correlate_ioc | Find campaigns sharing an IOC |

🗄️ Storage and Search

| Tool | What it does |
|---|---|
| search_intel_history | Search stored analysis products (SQLite) |
| get_intel_by_id | Retrie product by row ID |
| search_ingested_docs | Search ingested document store |

🧬 Local ATT&CK Database *(optional — requires python scripts/build_attack_db.py)*

| Tool | What it does |
|---|---|
| attack_get_technique | Full technique card: platforms, data sources, detection |
| attack_get_threat_groups | Groups known to use a technique |
| attack_get_techniques_by_group | Techniques attributed to a threat group |
| attack_attribute_to_group | Rank groups by technique o (Jaccard similarity) |
| attack_get_data_sources | Map ATT&CK data sources to SIEM log sources |
| attack_get_mitigations | ATT&CK recommended mitigations |

---

🔧 Playbook Files

E tunable lives in playbook/ — no Python changes needed:

| File | Controls |
|---|---|
| keywords.yaml | 284-entry keyword → ATT&CK technique index (single source of truth) |
| confidence_weights.yaml | Scoring dimensions, thresholds, specificity tiers |
| ioc_context_patterns.yaml | IOC context scoring (MALICIOUS / / RESEARCHER) |
| atomic_tests.yaml | Atomic Red Team test ID mapping per technique |
| siems/ | SIEM field profiles for KQL / SPL / EQL generation |

Add a new keyword — edit keywords.yaml and restart:

---

⚠️ Limitations

Generated outputs are analyst drafts — review and tune before deploying anything to production.

Co

| Limitation | Detail |
|---|---|
| Curated Sigma rules | Only 3 hand-written full Sigma rules (T1059.001, T1003.001, T1071.001). All others return no_curated_rule + SigmaHQ / Elastic / Splunk search links. By design — no fake rules generated. |
| Hunt playbook co | 37 techniques with hand-written SPL / KQL / Elastic / SQL queries. Techniques outside the playbook get a techniques_not_in_playbook notice from the standalone detection tools. |
| Sigma platform awareness | Curated Sigma rules are Windows-focused. macOS / Linux / cloud campaigns may recei logsources. Tracked as a roadmap item. |
| YARA co | Hand-written rules for 10 techniques only — predominantly Windows. |

Confidence model

| Limitation | Detail |
|---|---|
| Conser calibration | On real-world reports, most techniques tend to land in LOW / MEDIUM, even for high-quality sources. Tune thresholds/weights in confidence_weights.yaml. |
| Keyword-based heuristic | Not ground truth. A LOW confidence label means "weak signal" — review e before acting. |
| Semantic gaps | Substring matching can miss paraphrased ad behavior. Expand keywords.yaml to impro for your common report sources. |

Known issues

| Issue | Detail | Se |
|---|---|:---:|
| score_sigma co metric | The metric scans rule text for splunk: / kql: / elastic: substrings that don't exist in Sigma YAML. Co dimension is effectively always 0. | 🟡 Medium |
| score_technique_sigma en | Passes a JSON en from generate_sigma_for_technique to a YAML scorer. Rationale will reference wrong fields. | 🟡 Medium |
| Unstable Sigma rule UUIDs | Rule IDs are generated via uuid.uuid4() on every in rather than uuid5(namespace, technique_id). Breaks detection-as-code change management — same rule gets a new UUID every run. | 🟡 Medium |
| Multi-dot domain extraction | *.trycloudflare.com, *.net.br, and similar are o by the domain extractor's TLD heuristic. Real C2 may be missed. | 🟠 Lower (filtered output is in filtered_fps) |

These are tracked as roadmap items — see Contributing if you want to take one on.

Operational gaps

| Limitation | Detail |
|---|---|
| No en profile | No configs/my-soc.yaml to filter output to your SIEM stack. Every analyst gets all 49 tools and all SIEM flavours regardless of which they use. |
| No deploy_to_siem | Generated queries are text. You copy/paste or build your own deployment pipeline. |
| No deployment registry | The MCP doesn't remember which rules you' promoted. Co delta analysis is per-call, not cumulative. |
| No SIEM-nati | Output is loose KQL / SPL / EQL. Not sa.conf, ARM templates, or Kibana detection-rules TOML. |
| No SIEM query syntactic | Generated queries are templated strings — not linted against pySigma backends or SIEM schemas. |
| No e | evals/run_test.py exists but no curated public-report eval set. Every change is anecdotally . |
| Campaign tracking is files on disk | One analyst, shared-git workflow only. Not a relational TIP. |
| Enrichment rate limiting | Bulk enrich caps at 20 IOCs but has no per-source quota tracking or circuit breakers. |

Setup requirements

| Component | Requires |
|---|---|
| ATT&CK SQLite DB (6 attack_* tools) | python scripts/build_attack_db.py run once |
| STIX enrichment | pip install 'threat-research-mcp[attack]' + python scripts/download_attack_stix.py |
| IOC enrichment | Optional API keys (, OTX_API_KEY, ABUSEIPDB_API_KEY) |
| MISP integration | MISP_URL + MISP_KEY env vars |
| PyPI / uvx | Publish workflow merged; first release pending PyPI Trusted Publisher setup |

---

🛣️ Roadmap

Honest priorities, in order:

1. Recalibrate the confidence model so high-quality ad land MEDIUM, not LOW
2. Hand-author 10–15 more curated Sigma rules targeting top-10 enterprise techniques + macOS / cloud gaps
3. Fix score_sigma co metric and score_technique_sigma en bug
4. Stable rule UUIDs via uuid5(namespace, technique_id) for change management
5. Platform-aware Sigma dispatch so macOS reports don't recei rules
6. Domain extractor: loosen TLD heuristic for multi-dot domains (*.trycloudflare.com etc.)
7. E with 10+ public reports + expected outputs as pytest fixtures
8. En profile config (configs/my-soc.yaml) for SOC filtering
9. Native SIEM artifact output (sa.conf, ARM, detection-rules TOML)
10. PyPI publish + u support

If one of these matters to you, open an issue or PR — see Contributing.

---

🛠️ De

---

📁 Repository Layout

---

🤝 Contributing

Contributions are welcome — all PRs require CI to pass and owner review before merging.

Highest-impact areas (matched to the Roadmap):

1. Curated Sigma rules — add to src/threat_research_mcp/tools/generate_sigma.py.
Priority gaps: T1190 T1059.003 T1105 T1098.004 T1136.001 T1219 T1496 T1543.001 (macOS) T1548.006 (macOS)

2. New ATT&CK keyword mappings — edit playbook/keywords.yaml, no Python needed:

3. E — add threat reports with expected IOC counts and technique IDs to evals/. Format matches evals/run_test.py.

4. SIEM profiles — extend playbook/siems/ with field mappings for additional log sources.

5. Known issue fixes — the Limitations section enumerates each with se. Start there for a clear-scoped first PR.

Workflow:

Please open an issue before starting large changes.

---

📄 License

MIT © Harsh Thakur

项目信息

开发语言：Python

Star 数：5

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕 Open-source MCP server for defensive security: intel ingestion → research → hunting → detection drafts展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。