theory

KO | EN

gitlite — search

#python #hacktoberfest #react #typescript #llm #android #linux #macos #java #kubernetes #vue #pytorch #mcp #ios

(★ 9)

Theory automates adversary profiling using public threat intelligence sources. Input a threat actor name. Output a structured dossier covering TTPs, infrastructure, malware, and detection opportunities.

theory 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Theory Logo](https://raw.githubusercontent.com/threatcraft-co/theory/main/media/Theory%20Logo.png)

[![CI](https://github.com/threatcraft-co/theory/actions/workflows/ci.yml/badge.svg)](https://github.com/threatcraft-co/theory/actions/workflows/ci.yml)

**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

```bash
# 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 |

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

---

## Usage

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

### Choosing sources
```bash
# 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
```bash
# 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
```bash
# 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
```bash
theory --list-actors    # 35 supported actors with aliases
theory --list-sources   # all sources with auth and cache info
```

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

### Verbose / debug mode
```bash
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:

```bash
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`.

```bash
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.

```bash
# 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.

```bash
# 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.

```bash
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.

```bash
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.

```bash
# 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.

```bash
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`:

```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

```bash
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/                               ← 337 offline tests
```

---

## Running the tests

```bash
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 `config/actors.yaml` and add a new entry with the canonical name, aliases, and metadata. See the existing entries in that file for the schema.

**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](https://github.com/threatcraft-co) — open-source threat intelligence for the security community.*

theory

theory 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

theory

theory 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README