MirrorLab

ATT&CK technique simulation & detection coverage — know which attacks your Sigma rules actually catch.

┌────────────────────────────────────────────────────────────────────────┐
│                              MirrorLab                                  │
│                                                                        │
│  ┌──────────┐   ┌──────────┐   ┌────────────┐   ┌──────────────────┐   │
│  │Simulators│──▶│Detection │──▶│Adversarial │──▶│    Reporting     │   │
│  │ 7 ATT&CK │   │  Engine  │   │ Resilience │   │ HTML·Nav·MD·JSON │   │
│  │techniques│   │  Sigma   │   │  mutate ×  │   │ coverage · gaps  │   │
│  │ dry-run  │   │  native  │   │ 11 evasions│   │ resilience grade │   │
│  └──────────┘   └──────────┘   └────────────┘   └──────────────────┘   │
│                    would it       how much                             │
│                     fire?      attacker effort?                        │
└────────────────────────────────────────────────────────────────────────┘

What makes MirrorLab different: most coverage tools stop at "would this rule fire?" — a binary that scores a detection pinned to one hardcoded string the same as one built on invariant behaviour. MirrorLab's Adversarial Resilience Engine goes further and asks "how much attacker effort does this detection actually cost?" — mutating the telemetry the way a real operator would and re-running your rules against every variant to find the cheapest bypass, then handing you the fix.

Demo

🎬 Demo GIF coming — run mirrorlab simulate --all --no-report to see it live.

Features

Feature	Status
7 built-in ATT&CK technique simulators	✅
Dry-run mode (no Docker required)	✅
Real Docker sandbox execution (optional)	✅
Native Sigma rule matching engine	✅
12 bundled detection rules	✅
Adversarial Resilience Engine — mutation-based evasion testing	✅
Cost-weighted resilience score + grade (brittle → hardened)	✅
Universal-evasion detection (defence-in-depth analysis)	✅
Explainable near-miss diagnostics (which predicate blocked?)	✅
Hardening advisor — concrete before/after Sigma edits	✅
--fail-under CI gate for resilience regressions	✅
ATT&CK Navigator layer export (v4.9)	✅
Self-contained HTML coverage + resilience dashboards	✅
GFM Markdown report with Shields.io badge	✅
mirrorlab.yml full config support	✅
GitHub Actions CI (tests, lint, type check, docs, sandbox image)	✅
MkDocs documentation site	✅

Quick install

pip install mirrorlab

Or from source:

git clone https://github.com/amibhai/mirrorlab
cd mirrorlab
pip install -e .

Usage examples

1. Full pipeline for specific techniques

mirrorlab simulate T1059.001 T1082 --rules ./sigma/rules --output ./reports

Output:

╭──────────────────────────────────────────────╮
│  Simulating T1059.001, T1082  (2 techniques) │
╰──────────────────────────────────────────────╯
⠸ T1059.001  ok  8 events
⠸ T1082      ok  6 events

┌─ Simulation Results + Coverage ──────────────┐
│ T1059.001  PowerShell         8  3  100%      │
│ T1082      System Discovery   6  1   83%      │
└──────────────────────────────────────────────┘
╭── Summary ──╮
│ Coverage: 100%  Gaps: None │
╰─────────────╯
  ✓ ./reports/coverage_report.html
  ✓ ./reports/navigator_layer.json

2. Run all 7 simulators

mirrorlab simulate --all --output ./reports

3. Filter by tactic

mirrorlab simulate --tactic credential_access --rules ./sigma/rules

Adversarial Resilience Engine ⚔️

A rule that fires on the exact attack it was written for can still be worthless: if renaming a flag or inserting a quote turns it off, an attacker pays almost nothing to evade it. mirrorlab harden measures that.

mirrorlab harden --all --rules ./sigma/rules --html ./reports/resilience.html

For each rule that fires, MirrorLab mutates the telemetry the way a real operator would and re-runs the actual detection matcher against every variant:

┌─ T1027 Obfuscated Files or Information  score=0.66 ────────────────────┐
│ ⚠ 1 UNIVERSAL EVASION — one move blinds the entire detection stack     │
│    [low] slash-dash-swap: Many native tools accept both / and - flags  │
│                                                                        │
│ PowerShell Encoded Command Execution  ██████████████░░░░░░  BRITTLE     │
│  cost     evasion          field        mutated value                  │
│  trivial  flag-abbreviate  CommandLine  powershell.exe -e SQBFAF…      │
│  low      backtick-insert  CommandLine  powershell.exe -E`ncodedComm…  │
│  low      slash-dash-swap  CommandLine  powershell.exe /EncodedComm…   │
│   suggested hardening                                                   │
│     - CommandLine|contains: '-encodedcommand'                          │
│     + CommandLine|re: '(?i)\-e(ncodedcommand)?\b'                       │
│     Match the flag stem plus optional remainder so -enc / -e still hit. │
└────────────────────────────────────────────────────────────────────────┘

What you get:

• Resilience score + grade — cost-weighted survival, capped by the cheapest bypass (attackers pick the cheapest option, so the grade reflects that)
• Universal evasions — one mutation that defeats every rule covering a technique, exposing fake defence-in-depth
• Concrete hardening edits — a before/after Sigma diff for each finding
• Reproducible — the mutation corpus is seeded; same seed, same findings
• CI gate — --fail-under 0.8 exits non-zero when resilience regresses

mirrorlab list-mutators               # see the evasion corpus (cheapest first)
mirrorlab harden T1059.001 --seed 7   # deterministic single-technique run
mirrorlab run --all --harden          # full pipeline + resilience report

Docker sandbox (optional)

By default, simulators run in dry-run mode: they emit realistic, synthetic Sysmon-style events without touching a real system — no Docker required, safe to run anywhere including CI.

For real containerized execution, build the sandbox image and install the optional docker extra:

docker build -t mirrorlab/sandbox:latest -f sandbox/Dockerfile .
pip install "mirrorlab[docker]"

mirrorlab will then run each simulator's (harmless, read-only) payload inside a throwaway, network-isolated container instead of falling back to dry-run. Resource limits, network mode, and privilege level are all controlled by the docker: block in mirrorlab.yml:

docker:
  image: "mirrorlab/sandbox:latest"
  timeout_seconds: 60
  network_mode: "none"
  memory_limit: "256m"
  remove_after: true
  privileged: false

Coverage heatmap

📊 Coverage heatmap screenshot coming — open ./reports/navigator_layer.json in ATT&CK Navigator to view.

Roadmap

Phase	Description	Status
1	ATT&CK client, config schema, CLI scaffold	✅ Complete
2	Technique simulation engine (7 simulators)	✅ Complete
3	Sigma detection engine (native matcher)	✅ Complete
4	Reporting: HTML, Navigator, Markdown, JSON	✅ Complete
5	CLI polish, docs, GitHub release	✅ Complete
6	Real Docker sandbox, PyPI packaging, hardening	✅ Complete
7	Adversarial Resilience Engine (mutation testing, near-miss, hardening)	✅ Complete

Project structure

mirrorlab/
├── simulators/     7 ATT&CK technique simulators
├── detection/      Native Sigma matcher + DetectionEngine
├── adversarial/    Resilience engine: mutators, explain, harden, reports
├── reporting/      HTML, Navigator, Markdown, JSON reporters
├── attack/         ATT&CK STIX client with disk cache
└── config/         Pydantic config schema

sandbox/Dockerfile  Optional Docker sandbox image for real execution
sigma/rules/        12 bundled Sigma detection rules
docs/               MkDocs documentation site
tests/              339 tests across all phases

Contributing

1. Fork & clone
2. pip install -e ".[dev]"
3. Add your simulator in mirrorlab/simulators/
4. Add a Sigma rule in sigma/rules/
5. pytest tests/ -v — all tests must pass
6. Open a PR

See CONTRIBUTING for the full 5-step guide.

License

MIT — see LICENSE.