Multi-source threat actor intelligence for everyone.

THEORY is an open-source alternative to enterprise threat intelligence platforms. It generates analyst-grade dossiers on threat actors by aggregating data from MITRE ATT&CK, Malpedia, AlienVault OTX, SigmaHQ, ThreatFox, CISA, and vendor research blogs — then synthesizes everything using an LLM into a clean executive overview and actor-specific intelligence summaries.

Built for threat intelligence analysts, detection engineers, security researchers, and students who believe good intelligence shouldn't require a six-figure subscription.

---

What THEORY produces

For any supported threat actor, THEORY generates:

• LLM-written synopsis — 4-6 sentence executive overview synthesized from all available data, at the top of every dossier
• TTP table — every known technique with tactic, confidence score, and detection guidance
• Detection opportunities — Sigma rules mapped directly to actor TTPs
• Malware inventory — all associated families with full descriptions
• IOC table — deduplicated, defanged indicators from OTX and ThreatFox with confidence scores and malware family attribution
• Recent intelligence — LLM-synthesized summaries of recent vendor research articles, with source attribution and links
• Campaigns — full campaign descriptions with dates and ATT&CK links
• Targeted sectors and CISA advisories
• IR playbooks — analyst-ready checklists with IOC blocks, detection checklists, hunt hypotheses, and containment guidance
• ATT&CK Navigator layers — confidence-colored heatmaps importable directly into MITRE Navigator
• HTML dossiers — self-contained, shareable intelligence reports that open in any browser
• Detection coverage gap reports — compare actor TTPs against your local detection rules

Output formats: terminal dossier, markdown, JSON, STIX 2.1 (for MISP/OpenCTI/Sentinel), IOC CSV, HTML, ATT&CK Navigator, and IR playbook (markdown or Jira).

---

Quick Start

# 1. Clone the repository
git clone https://github.com/threatcraft-co/theory
cd theory

# 2. Create a virtual environment
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

# 3. Install THEORY and dependencies
pip install -e .

# 4. Download the ATT&CK bundle (required for MITRE source)
theory --update-bundles

# 5. Configure your API keys
cp .env.example .env
# Edit .env and add your OTX_API_KEY (free at otx.alienvault.com)

# 6. Run your first dossier
theory --actor APT28

That's it. Your first dossier renders in the terminal and saves to output/dossiers/apt28.md.

---

Sources

Key	Source	Auth Required	Cache
mitre	MITRE ATT&CK (local bundle)	None	7 days
cisa	CISA Advisories + KEV	None	Per request
malpedia	Malpedia malware database	None	Per request
otx	AlienVault OTX	OTX_API_KEY	Per request
sigma	SigmaHQ detection rules (local clone)	GITHUB_TOKEN (optional)	7 days
threatfox	ThreatFox IOCs	None	24 hours
vendor	Vendor intel synthesis (LLM)	LLM API key	7 days

Coming in v1.2 — IOC Enrichment Sources:

Key	Source	Auth Required	Free Tier
shodan	Shodan host data + C2 detection	SHODAN_API_KEY	100 queries/month
censys	Censys certificate + host data	CENSYS_API_KEY	Community tier
criminalip	Criminal IP threat scoring	CRIMINALIP_API_KEY	Free tier
virustotal	VirusTotal hash + domain reputation	VIRUSTOTAL_API_KEY	500 requests/day

# Live status of all sources
theory --list-sources

---

Usage

Basic dossier

theory --actor APT28
theory --actor "Fancy Bear"         # alias resolution — same output
theory --actor "Forest Blizzard"    # same actor, different name

Choosing sources

# Default (mitre + cisa + malpedia, no auth needed)
theory --actor APT28

# Add community IOCs
theory --actor APT28 --sources mitre,cisa,malpedia,otx

# Full enrichment including detection rules
theory --actor APT28 --sources mitre,cisa,malpedia,otx,sigma,threatfox

# With vendor intelligence synthesis (requires LLM key in .env)
theory --actor APT28 --sources mitre,cisa,malpedia,otx,sigma,threatfox,vendor

Output formats

# Terminal + markdown file (default)
theory --actor APT28

# Raw JSON profile
theory --actor APT28 --output json

# STIX 2.1 bundle (import into MISP, OpenCTI, Sentinel)
theory --actor APT28 --output stix

# IOC-only CSV (for SIEM lookup tables)
theory --actor APT28 --sources mitre,otx,threatfox --output csv

# Self-contained HTML dossier (shareable, opens in any browser)
theory --actor APT28 --sources mitre,malpedia,otx --output html

# ATT&CK Navigator layer (import at mitre-attack.github.io/attack-navigator)
theory --actor APT28 --sources mitre,malpedia,otx --output navigator

# IR playbook with detection checklist and IOC blocks
theory --actor APT28 --sources mitre,sigma --output playbook

# IR playbook in Jira wiki markup
theory --actor APT28 --sources mitre,sigma --output playbook --playbook-format jira

# Non-technical executive summary (BLUF format, requires LLM key)
theory --actor APT28 --output exec

# Executive summary with sector context
theory --actor "Lazarus Group" --output exec --sector finance

# All formats at once (dossier + JSON + STIX + CSV + Navigator + HTML)
theory --actor APT28 --output all

# Print only — don't write files
theory --actor APT28 --no-save

Detection coverage gap analysis

# Compare actor TTPs against your local detection rules
theory --actor APT28 --sources mitre,sigma --detection-path ~/my-sigma-rules

# Output: coverage %, covered techniques, and gaps sorted by confidence

Browse what's available

theory --list-actors    # 35 supported actors with aliases
theory --list-sources   # all sources with auth and cache info

Maintenance

# Refresh ATT&CK bundle, Sigma rules, and APT campaign collection
theory --update-bundles

Verbose / debug mode

theory --actor APT28 --sources mitre,cisa --verbose

---

Alias resolution

THEORY knows 35 actors by all their names (275 aliases total). Any alias resolves to the same canonical dossier:

theory --actor "Cozy Bear"          # → APT29
theory --actor "Midnight Blizzard"  # → APT29
theory --actor "Nobelium"           # → APT29
theory --actor "NOBELIUM"           # → APT29 (case-insensitive)

The output file is always named by the canonical actor — --actor "Fancy Bear" produces apt28.md, not fancy_bear.md.

theory --list-actors    # see all 35 actors and their aliases

---

LLM Actor Synopsis

Every dossier opens with an Intelligence Overview — a 4-6 sentence executive synopsis written by Claude (or your configured LLM) using the full aggregated profile as context.

The synopsis:

• Uses the name you queried, not aliases
• Covers origin, motivations, target sectors, signature TTPs, notable malware, and recent activity
• Works with or without --sources vendor — synthesizes from structured MITRE data alone if needed
• Appears at the top of both the terminal output and the markdown file

LLM provider resolution order: Claude → OpenAI → Ollama. Set THEORY_LLM_PROVIDER in .env to override, or leave blank to auto-detect. Ollama runs fully offline.

---

Vendor Intelligence Synthesis

When you add vendor to your sources, THEORY fetches recent articles from 40+ threat research blogs (Mandiant, Google TAG, Unit 42, Secureworks, Recorded Future, CrowdStrike, Kaspersky GReAT, Check Point Research, Sophos, Proofpoint, and more) and uses an LLM to synthesize what each article reveals about your actor specifically.

# Set your preferred provider and API key in .env
THEORY_LLM_PROVIDER=claude
ANTHROPIC_API_KEY=your_key_here

# Run with synthesis
theory --actor "Lazarus Group" --sources mitre,malpedia,otx,vendor

The dossier includes a Recent Intelligence section with actor-specific summaries, source attribution, and direct links to original articles.

---

Sigma Detection Rules

THEORY uses a local clone of the SigmaHQ repository — no rate limits, no API, instant results.

# First run clones the repo (~150MB, ~1-2 minutes, one time only)
theory --actor APT28 --sources mitre,sigma --no-save

# Every subsequent run is instant
theory --actor APT28 --sources mitre,sigma --no-save

Detection rules are linked directly to actor TTPs in the dossier. See docs/SIGMA_RATE_LIMITS.md for full details.

---

HTML Dossier

THEORY generates self-contained HTML dossiers with a dark intelligence-grade aesthetic. No server required — opens in any browser, works offline. All CSS and JS are embedded inline.

theory --actor APT28 --sources mitre,malpedia,otx --output html
# writes: output/dossiers/apt28.html

Features: collapsible sections, sortable TTP table, tactic filter buttons, IOC freshness indicators (fresh/aging/stale), malware cards, vendor intel cards, and a confidence summary header. Shareable as a single file.

---

ATT&CK Navigator Export

THEORY exports ATT&CK Navigator v4.5 layers, color-coded by confidence level (HIGH=red, MEDIUM=amber, LOW=yellow). Techniques with Sigma coverage get a score boost.

theory --actor APT28 --sources mitre,malpedia,otx --output navigator
# writes: output/dossiers/apt28.navigator.json

Import into Navigator:

1. Go to https://mitre-attack.github.io/attack-navigator/
2. Open Layer → Upload from Local
3. Select the .navigator.json file

---

IR Playbook

THEORY generates incident response playbooks from actor profiles — structured, analyst-ready checklists that turn intelligence into action.

# Markdown format (renders in GitHub, Confluence, Notion, ServiceNow)
theory --actor APT28 --sources mitre,sigma --output playbook

# Jira wiki markup (paste directly into issue descriptions)
theory --actor APT28 --sources mitre,sigma --output playbook --playbook-format jira

Playbook sections:

• Immediate IOC Blocks — FRESH and AGING indicators formatted for firewall/SIEM
• Detection Checklist — TTPs as checkboxes with Sigma rule links, grouped by tactic
• Hunt Hypotheses — LLM-generated plain-language hunt queries per high-confidence TTP
• Malware Reference — known families, types, and hashes
• Containment Guidance — LLM-generated, sector-aware response steps (use --sector to tailor)
• References — all source URLs cited in the profile

---

Detection Coverage Gap Analysis

Compare an actor's TTPs against your local detection rules to find where you lack coverage.

theory --actor APT28 --sources mitre,sigma --detection-path ~/my-sigma-rules

THEORY greps your detection directory for each technique ID and reports:

• Coverage percentage with a visual bar
• Gaps — techniques with no local rule, sorted by confidence (HIGH first)
• Covered — techniques you can already detect

Saves a markdown report to output/dossiers/<actor>_coverage_gap.md.

---

IOC Safety

All URLs, domains, and IPs in THEORY dossiers are automatically defanged using industry-standard notation — hxxp://, [.] — so they cannot be accidentally clicked or resolved in any markdown renderer, browser, or IDE preview.

The IOC CSV export (--output csv) retains raw values for SIEM ingestion, where your platform handles the defanging.

---

Adding custom feeds

Add your own RSS feeds to config/feeds.yaml:

custom:
  - name: My Internal TI Feed
    url: https://internal.company.com/threat-intel
    rss: https://internal.company.com/threat-intel/rss
    type: rss
    tier: 2
    apt_focus: true
    tags: [internal, custom]
    enabled: true

---

STIX 2.1 Export

THEORY produces valid STIX 2.1 bundles importable into:

• MISP — import via Events → Import → STIX 2.x
• OpenCTI — import via the STIX connector
• Splunk Enterprise Security — via the TAXII connector
• Microsoft Sentinel — via the Threat Intelligence data connector

theory --actor APT28 --sources mitre,malpedia,otx --output stix
# writes: output/dossiers/apt28.stix.json

---

Architecture

theory/                              ← Python package (CLI entry point)
  __init__.py                        ← public API: main(), run()
  __main__.py                        ← enables python -m theory
  _cli.py                            ← pipeline orchestrator
  _version.py                        ← version string

theory.py                            ← compatibility shim (points to package)

collectors/
  base.py                            ← base collector class
  mitre_attack.py                    ← MITRE ATT&CK (local STIX bundle)
  cisa_advisories.py                 ← CISA advisories + KEV + alias table
  malpedia.py                        ← Malpedia malware database
  alienvault_otx.py                  ← AlienVault OTX pulses and IOCs
  sigma_rules.py                     ← SigmaHQ local clone (no rate limits)
  threatfox.py                       ← ThreatFox IOC database (enrichment)
  vendor_intel.py                    ← RSS feed fetcher + relevance scorer
  intelligence_synthesizer.py        ← LLM provider abstraction + synthesis

processors/
  normalizer.py                      ← Schema validation and normalization
  deduplicator.py                    ← Cross-source dedup + confidence scoring

mappers/
  mitre.py                           ← MITRE ATT&CK mapper
  cisa.py                            ← CISA mapper

reporters/
  dossier.py                         ← Rich terminal + markdown output
  json_reporter.py                   ← JSON profile export
  stix_reporter.py                   ← STIX 2.1 bundle export
  csv_reporter.py                    ← IOC-only CSV export
  html_reporter.py                   ← Self-contained HTML dossier
  navigator_reporter.py              ← ATT&CK Navigator layer export
  playbook_reporter.py               ← IR playbook (markdown + Jira)

config/
  feeds.yaml                         ← 40+ verified vendor intelligence feeds
  detection_repos.yaml               ← curated detection repo registry
  actors.yaml                        ← actor configuration

docs/
  SIGMA_RATE_LIMITS.md               ← Sigma architecture docs
  SCHEDULED_UPDATES.md               ← Cron/launchd automation setup
  SECURITY_AUDIT_2026-06.md          ← Security audit documentation

tests/                               ← ~310 offline tests

---

Running the tests

pytest tests/ -v                              # all tests
pytest tests/test_stix_reporter.py -v        # STIX only
pytest tests/test_phase9_vendor_intel.py -v  # vendor intel only
pytest tests/test_security_hardening.py -v   # security hardening

All tests run fully offline — no API keys required.

---

Requirements

• Python 3.11+
• Dependencies installed via pip install -e .
• ATT&CK bundle downloaded via theory --update-bundles
• API keys: see .env.example for the full list with registration links

---

Contributing

See CONTRIBUTING.md for the full guide. Quick reference:

Adding a new actor — edit collectors/cisa_advisories.py and add to ALIAS_TABLE:

"Actor Name": frozenset({
    "actor name", "alias one", "alias two", "g0000",
}),

Adding a new source — implement collector, mapper, and tests. See CONTRIBUTING.md.

Adding a vendor feed — edit config/feeds.yaml and add to the sources list.

Reporting issues — github.com/threatcraft-co/theory/issues

---

Legal

THEORY aggregates publicly available third-party data. See DISCLAIMER.md and LEGAL.md for full terms.

---

License

MIT License — see LICENSE for details.

---

Built by Threatcraft — open-source threat intelligence for the security community.