RedGap

Find the red gaps in your detection coverage.

RedGap is an automated, MITRE ATT&CK-mapped offense↔detection coverage harness. It runs 38 benign ATT&CK techniques (across 11 tactics) against its own disposable local lab, collects real telemetry with an independent collector, and then deterministically — from logs and Sigma rules, with no AI in the loop — decides whether each technique was detected or is a gap. The output is a coverage report (technique → detected? → gap type) plus an ATT&CK Navigator layer.

The name is the output: in the coverage grid, detected techniques are green and gaps are red. RedGap finds the red.

v0.1 — what this is and is not. RedGap v0.1 is a deterministic harness over a fixed set of techniques. It is not an autonomous agent that continuously attacks and adapts. Adaptive, gap-driven technique chaining (the agent choosing its next attack from the last result) is the honest next step, tracked on the roadmap. Precise scope on purpose.

Status. RedGap's own parser + evaluator ingests all 122 real SigmaHQ linux/process_creation rules with zero parser errors and zero evaluator crashes — that ruleset is vendored under tests/corpus/ and checked by test_sigmahq_corpus.py, so the claim is reproducible, not asserted. 290 tests run fully offline in CI. Coverage is computed from 38 committed real-telemetry captures — one per technique, each with a raw log + parsed events + sha256 provenance — not authored logs; the default run detects 26/38 across 11 ATT&CK tactics. See docs/architecture.md · committed output in docs/samples/.

The one idea: the verdict is not the AI's to make

Every detected verdict is a pure function of (logs, rules), computed and written to disk before any language model is ever called. An optional LLM planner may (a) choose the order of techniques and decide when to stop, and (b) narrate the report. It cannot decide whether something was detected — both the deterministic and the LLM planner return the engine's coverage, never model text. A test asserts the coverage report is byte-identical with and without the LLM.

This is deliberate. LLMs hallucinate confident verdicts; a coverage tool whose ground truth an LLM can fabricate is worthless. RedGap draws the trust boundary in code.

The verdict is a pure function of logs and rules, written to disk before any model runs. The LLM (dashed red) can only order techniques and narrate — it sits outside the verdict path.

Quickstart (offline, no API key, no cloud)

The default path is REPLAY: it re-evaluates real telemetry captured from a prior live run (committed as fixtures with provenance) through the exact same engine used in LIVE mode. No Docker, no key, no network.

pip install redgap
redgap run            # REPLAY: prints the coverage table + writes out/coverage.{json,md} + navigator-layer.json

From source instead (or before the first PyPI release):

git clone https://github.com/befnoz/redgap && cd redgap
pip install -e .
redgap run

Live dashboard: the same coverage, as an interactive web page — https://befnoz.github.io/redgap/. Drop your own out/coverage.json on it to render your gap grid entirely in the browser (nothing is uploaded). See docs/DEPLOY.md to switch it on.

To run the real thing against the local Docker lab:

redgap run --live     # brings up the disposable lab, executes techniques, captures fresh telemetry

To try the optional LLM planner (needs the llm extra and ANTHROPIC_API_KEY):

pip install -e ".[llm]"    # adds the optional anthropic SDK
redgap run --llm           # equivalently: COVERAGE_LLM=1 redgap run

The committed coverage.json is identical whichever planner ran — a test asserts it.

What a run shows

A run executes 38 benign techniques across 11 ATT&CK tactics and produces a real coverage grid: 26 detected · 12 gaps (7 rule, 5 base-rate). Every verdict is computed by the engine from captured telemetry against real SigmaHQ rules — see the live grid at the dashboard or docs/samples/. The original kill-chain below is the illustrative core, showing both kinds of gap and the remediation round-trip:

The remediation round-trip is the point: technique 5 fires but no rule catches it (a rule gap). Write one Sigma rule, re-run the same command, and watch the verdict flip red→green (redgap run --fix → 27/38). Both the before and after coverage reports are committed — RedGap is a tool that finds a real blind spot and closes it, not a status printer.

Ethics & scope

⚠️ RedGap attacks only its own disposable local lab. There is deliberately no free-form target flag; the live lab runs with no network, and every container launch is gated at runtime by an allowlist (assert_lab_only) that the test suite proves cannot be widened. Every technique is a benign, published Atomic-Red-Team-derived detection test with no exploit payload, no off-box action, and no runtime downloads. See ETHICS.md, SCOPE.md, and SECURITY.md.

Not shipped: weaponizable breadth, real exploits, credential material, or anything that runs against a system you do not own.

Roadmap (honest next steps)

• Adaptive, gap-driven technique chaining (agent picks the next attack from the last verdict).
• Effect / syscall-level detection (e.g. utimensat for timestomp) via a higher-fidelity collector.
• Correlation rules (turn the base-rate gap into a real detection).
• Portability: the rules are standard Sigma, so they already run unchanged in Zircolite or any SIEM.

License

MIT — see LICENSE. Third-party attributions in NOTICE. ATT&CK® is a registered trademark of The MITRE Corporation.