redgap 0.1.0__tar.gz

redgap-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Secrets / local config — never commit an API key
+.env
+*.key
+secrets.*
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Runtime output (reports are regenerated; only committed samples live under docs/ or fixtures/)
+out/
+out-*/
+*.tmp

redgap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 befnoz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

redgap-0.1.0/NOTICE

@@ -0,0 +1,46 @@
+RedGap — third-party components and attributions
+=================================================
+
+RedGap itself is licensed under the MIT License (see LICENSE).
+
+This project depends on, references, or derives benign test procedures from the
+following third-party works. Each remains under its own license; RedGap claims
+no ownership of them and thanks their authors.
+
+Runtime dependencies
+--------------------
+- pySigma (SigmaHQ)            — LGPL-2.1        — Sigma rule parsing.
+                                 https://github.com/SigmaHQ/pySigma
+- Typer                        — MIT             — command-line interface.
+- Rich                         — MIT             — terminal rendering.
+- PyYAML                       — MIT             — YAML loading.
+
+Optional dependency
+--------------------
+- anthropic (Anthropic SDK)    — MIT             — optional LLM orchestration only.
+
+Detection content
+-----------------
+- Sigma community rules (SigmaHQ) are distributed under the Detection Rule
+  License (DRL-1.1). Any SigmaHQ rule vendored under rules/ retains its original
+  header, author, and license reference. See:
+  https://github.com/SigmaHQ/sigma/blob/master/LICENSE.Detection.Rules.md
+- The full SigmaHQ linux/process_creation ruleset (122 rules) is vendored verbatim
+  under tests/corpus/sigmahq_linux_process_creation/ as TEST INPUT only (engine
+  validation), under DRL-1.1. Source commit and refresh steps are in that directory's
+  README. These rules are not loaded at runtime.
+
+Technique provenance
+-------------------
+- The benign techniques executed by RedGap are derived from Atomic Red Team
+  (Red Canary), MIT License. RedGap runs only well-known, published, benign
+  detection tests against its own disposable local lab — never novel offense.
+  https://github.com/redcanaryco/atomic-red-team
+
+Telemetry / tooling referenced (not redistributed)
+--------------------------------------------------
+- snoopy (a2o/snoopy)          — GPL-2.0         — execve command logger used as
+                                 an independent telemetry collector in the lab image.
+- Sysmon for Linux (Microsoft) — MIT             — optional high-fidelity collector.
+- MITRE ATT&CK / ATT&CK Navigator layer format — MITRE terms of use. ATT&CK(R) is
+  a registered trademark of The MITRE Corporation.

redgap-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: redgap
+Version: 0.1.0
+Summary: Automated, MITRE ATT&CK-mapped offense<->detection coverage harness. Finds the red gaps in your detection coverage.
+Author: befnoz
+License: MIT License
+        
+        Copyright (c) 2026 befnoz
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: coverage,detection-engineering,mitre-attack,purple-team,security,sigma
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: pysigma==1.5.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pre-commit>=3.8; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# RedGap
+
+**Find the red gaps in your detection coverage.**
+
+RedGap is an automated, MITRE ATT&CK-mapped **offense↔detection coverage harness**. It runs a small set of *benign* ATT&CK techniques 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.
+
+[![CI](https://github.com/befnoz/redgap/actions/workflows/ci.yml/badge.svg)](https://github.com/befnoz/redgap/actions/workflows/ci.yml)
+<!-- Uncomment once Pages is enabled / the package is on PyPI: -->
+<!-- [![Live demo](https://img.shields.io/badge/demo-live-2e7d32)](https://befnoz.github.io/redgap/) -->
+<!-- [![PyPI](https://img.shields.io/pypi/v/redgap)](https://pypi.org/project/redgap/) -->
+
+> **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/`](tests/corpus/sigmahq_linux_process_creation/) and checked by [`test_sigmahq_corpus.py`](tests/test_sigmahq_corpus.py), so the claim is reproducible, not asserted. **290 tests** run fully offline in CI. Coverage is computed from **5 committed real-telemetry captures** — one per technique, each with a raw log + parsed events + sha256 provenance — not authored logs. See [docs/architecture.md](docs/architecture.md) · committed output in [docs/samples/](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.
+
+![RedGap architecture — the deterministic pipeline, with the optional LLM planner drawn outside the verdict path](docs/architecture.svg)
+
+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.
+
+```bash
+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):
+
+```bash
+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/` (see [docs/DEPLOY.md](docs/DEPLOY.md) to switch it on).
+
+To run the real thing against the local Docker lab:
+
+```bash
+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`):
+
+```bash
+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 v0.1 run is a five-technique mini kill-chain that deliberately produces **both** detections and gaps — and two *different kinds* of gap, because a coverage tool that is all-green is just a checklist:
+
+| # | ATT&CK | Tactic | Result |
+|---|--------|--------|--------|
+| 1 | T1087.001 Account Discovery: Local | Discovery | detected |
+| 2 | T1057 Process Discovery | Discovery | **gap (base-rate)** — too noisy for a single-event rule; needs correlation (roadmap) |
+| 3 | T1136.001 Create Account: Local | Persistence | detected |
+| 4 | T1548.001 Setuid/Setgid | Priv. Esc / Defense Evasion | detected (matches a shipped SigmaHQ rule) |
+| 5 | T1070.006 Timestomp | Defense Evasion | **gap (rule)** → closed live in 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. 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](ETHICS.md), [SCOPE.md](SCOPE.md), and [SECURITY.md](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](LICENSE). Third-party attributions in [NOTICE](NOTICE). ATT&CK® is a registered trademark of The MITRE Corporation.

redgap-0.1.0/README.md

@@ -0,0 +1,103 @@
+# RedGap
+
+**Find the red gaps in your detection coverage.**
+
+RedGap is an automated, MITRE ATT&CK-mapped **offense↔detection coverage harness**. It runs a small set of *benign* ATT&CK techniques 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.
+
+[![CI](https://github.com/befnoz/redgap/actions/workflows/ci.yml/badge.svg)](https://github.com/befnoz/redgap/actions/workflows/ci.yml)
+<!-- Uncomment once Pages is enabled / the package is on PyPI: -->
+<!-- [![Live demo](https://img.shields.io/badge/demo-live-2e7d32)](https://befnoz.github.io/redgap/) -->
+<!-- [![PyPI](https://img.shields.io/pypi/v/redgap)](https://pypi.org/project/redgap/) -->
+
+> **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/`](tests/corpus/sigmahq_linux_process_creation/) and checked by [`test_sigmahq_corpus.py`](tests/test_sigmahq_corpus.py), so the claim is reproducible, not asserted. **290 tests** run fully offline in CI. Coverage is computed from **5 committed real-telemetry captures** — one per technique, each with a raw log + parsed events + sha256 provenance — not authored logs. See [docs/architecture.md](docs/architecture.md) · committed output in [docs/samples/](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.
+
+![RedGap architecture — the deterministic pipeline, with the optional LLM planner drawn outside the verdict path](docs/architecture.svg)
+
+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.
+
+```bash
+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):
+
+```bash
+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/` (see [docs/DEPLOY.md](docs/DEPLOY.md) to switch it on).
+
+To run the real thing against the local Docker lab:
+
+```bash
+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`):
+
+```bash
+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 v0.1 run is a five-technique mini kill-chain that deliberately produces **both** detections and gaps — and two *different kinds* of gap, because a coverage tool that is all-green is just a checklist:
+
+| # | ATT&CK | Tactic | Result |
+|---|--------|--------|--------|
+| 1 | T1087.001 Account Discovery: Local | Discovery | detected |
+| 2 | T1057 Process Discovery | Discovery | **gap (base-rate)** — too noisy for a single-event rule; needs correlation (roadmap) |
+| 3 | T1136.001 Create Account: Local | Persistence | detected |
+| 4 | T1548.001 Setuid/Setgid | Priv. Esc / Defense Evasion | detected (matches a shipped SigmaHQ rule) |
+| 5 | T1070.006 Timestomp | Defense Evasion | **gap (rule)** → closed live in 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. 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](ETHICS.md), [SCOPE.md](SCOPE.md), and [SECURITY.md](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](LICENSE). Third-party attributions in [NOTICE](NOTICE). ATT&CK® is a registered trademark of The MITRE Corporation.

redgap-0.1.0/docs/DEPLOY.md

@@ -0,0 +1,56 @@
+# Deploying RedGap
+
+Two independent things: the **web dashboard** (GitHub Pages) and the **`pip install redgap`**
+package (PyPI). Both are wired with GitHub Actions; you only do a little one-time setup.
+
+## 1. Web dashboard → GitHub Pages
+
+`docs/index.html` is a self-contained dashboard (no external assets). It renders the real
+coverage output — the ATT&CK heatmap, the coverage table, and the `--fix` round-trip toggle.
+
+**One-time:** repo **Settings → Pages → Source = "GitHub Actions"**.
+
+After that, every push to `main` that touches `docs/**` runs `.github/workflows/pages.yml`
+and publishes to:
+
+```
+https://<your-username>.github.io/redgap/
+```
+
+That URL is the clickable proof to put in the CES application. (Prefer the branch method
+instead? Settings → Pages → "Deploy from a branch" → `main` → `/docs` also works — then you
+can delete `pages.yml`.)
+
+## 2. `pip install redgap` → PyPI
+
+The package is already wheel/sdist-clean (`python -m build` + `twine check` pass, and CI's
+`install-smoke` job proves a non-editable install runs from any directory).
+
+**First, check the name is free:** open <https://pypi.org/project/redgap/>. If it is taken,
+rename the project in `pyproject.toml` (`name = "..."`, e.g. `redgap-coverage`) and update the
+`url:` lines in `.github/workflows/publish.yml`.
+
+**Set up Trusted Publishing (recommended — no tokens/secrets):**
+1. On PyPI: your account → **Publishing** → **Add a pending publisher**.
+2. Fill in: PyPI project name `redgap`, owner = your GitHub user, repository `redgap`,
+   workflow `publish.yml`, environment `pypi`.
+3. Save. (A "pending" publisher lets the very first release create the project.)
+
+**Release:**
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+The tag fires `.github/workflows/publish.yml`, which builds and publishes. Then anyone can:
+```bash
+pip install redgap
+```
+
+**Token fallback** (if you skip Trusted Publishing): create a PyPI API token, add it as the
+repo secret `PYPI_API_TOKEN`, and pass `with: { password: ${{ secrets.PYPI_API_TOKEN }} }` to
+the `pypa/gh-action-pypi-publish` step.
+
+## Update the version
+
+Bump `version` in `pyproject.toml`, then tag `v<that version>`. Keep the tag and the
+`pyproject.toml` version in sync.

redgap-0.1.0/docs/architecture.md

@@ -0,0 +1,41 @@
+# Architecture
+
+![RedGap architecture](architecture.svg)
+
+RedGap runs a small set of benign, MITRE ATT&CK-mapped techniques against a disposable
+lab, collects real process-execution telemetry with an **independent** collector, and
+decides — deterministically, from logs and Sigma rules — whether each technique was
+*detected* or is a *gap*.
+
+## The trust boundary
+
+The single load-bearing property is that the `detected` verdict is a **pure function of
+`(events, rules)`**, computed and written to disk **before** any language model is
+called. The optional LLM planner may choose the order of techniques and narrate the
+report; it drives the same validated tool executor the deterministic planner uses and
+**cannot** produce or change a verdict. `tests/test_planner.py` asserts the coverage is
+byte-identical with and without the LLM — even when the model finishes early, runs a
+subset, or requests a technique that does not exist.
+
+## The pieces
+
+| Component | File | Role |
+|-----------|------|------|
+| Technique catalog | `src/redgap/catalog.py`, `techniques/registry.py` | 5 benign techniques + their commands and cleanup |
+| Lab | `lab/`, `src/redgap/lab.py` | Disposable Docker container + a ~40-line `LD_PRELOAD` execve collector |
+| Target | `src/redgap/target.py` | `ReplayTarget` (committed real fixtures, offline) / `LiveDockerTarget` |
+| Telemetry | `src/redgap/telemetry/` | snoopy-format parser → SigmaHQ `process_creation` events |
+| Detection | `src/redgap/detection/` | pySigma parser + RedGap's own AST evaluator; coverage join |
+| Planner | `src/redgap/planner.py` | Heuristic (default) / LLM (optional), one `ToolExecutor` |
+| Report | `src/redgap/report/` | `coverage.json`, `coverage.md`, ATT&CK Navigator layer |
+
+## Two modes, one engine
+
+- **REPLAY** (default): re-evaluate committed real-telemetry fixtures. Offline, no key,
+  no Docker — what CI runs and what a reviewer reproduces in one command.
+- **LIVE** (`--live`): bring up the Docker lab, execute the techniques, capture fresh
+  telemetry, and run the **same** engine.
+
+Fixtures are verbatim captures with `provenance.json` (sha256, kernel, image id, exact
+commands, timestamp) and are regenerable via `redgap capture`; the nightly LIVE CI job
+re-captures on a clean runner so the fixtures are auditable, not hand-authored.

redgap-0.1.0/docs/architecture.svg

@@ -0,0 +1,78 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 360" font-family="-apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif">
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0 L10,5 L0,10 z" fill="#57606a"/>
+    </marker>
+    <marker id="arrowR" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0 L10,5 L0,10 z" fill="#cf222e"/>
+    </marker>
+  </defs>
+
+  <rect x="0" y="0" width="900" height="360" fill="#ffffff"/>
+  <text x="24" y="34" font-size="18" font-weight="700" fill="#1f2328">RedGap — offense &#8596; detection coverage</text>
+  <text x="24" y="54" font-size="12" fill="#57606a">The verdict is deterministic; the LLM is an optional layer that sits outside it.</text>
+
+  <!-- optional LLM box -->
+  <rect x="330" y="88" width="380" height="52" rx="8" fill="#fdeff0" stroke="#cf222e" stroke-width="1.5" stroke-dasharray="6 4"/>
+  <text x="520" y="110" font-size="13" font-weight="700" fill="#cf222e" text-anchor="middle">LLM planner &#183; optional</text>
+  <text x="520" y="128" font-size="11" fill="#a4404a" text-anchor="middle">orders techniques &#183; narrates &#8212; cannot set a verdict</text>
+
+  <!-- pipeline boxes -->
+  <g font-size="13" font-weight="700" fill="#1f2328">
+    <g>
+      <rect x="20" y="200" width="120" height="80" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+      <text x="80" y="234" text-anchor="middle">Technique</text>
+      <text x="80" y="250" text-anchor="middle">catalog</text>
+      <text x="80" y="268" text-anchor="middle" font-size="10.5" font-weight="400" fill="#57606a">5 benign &#183; MITRE</text>
+    </g>
+    <g>
+      <rect x="168" y="200" width="120" height="80" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+      <text x="228" y="242" text-anchor="middle">Lab</text>
+      <text x="228" y="262" text-anchor="middle" font-size="10.5" font-weight="400" fill="#57606a">Docker &#183; Replay</text>
+    </g>
+    <g>
+      <rect x="316" y="200" width="120" height="80" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+      <text x="376" y="234" text-anchor="middle">Collector</text>
+      <text x="376" y="250" text-anchor="middle" font-size="10.5" font-weight="400" fill="#57606a">independent</text>
+      <text x="376" y="266" text-anchor="middle" font-size="10.5" font-weight="400" fill="#57606a">execve &#8594; events</text>
+    </g>
+    <g>
+      <rect x="464" y="200" width="120" height="80" rx="8" fill="#e9f6ef" stroke="#1a7f4b" stroke-width="1.5"/>
+      <text x="524" y="234" text-anchor="middle" fill="#12633a">Sigma engine</text>
+      <text x="524" y="252" text-anchor="middle" font-size="10.5" font-weight="700" fill="#1a7f4b">deterministic</text>
+      <text x="524" y="268" text-anchor="middle" font-size="10.5" font-weight="400" fill="#57606a">verdict = f(logs, rules)</text>
+    </g>
+    <g>
+      <rect x="612" y="200" width="120" height="80" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+      <text x="672" y="242" text-anchor="middle">Coverage</text>
+      <text x="672" y="262" text-anchor="middle" font-size="10.5" font-weight="400" fill="#57606a">detected / gap</text>
+    </g>
+    <g>
+      <rect x="760" y="200" width="120" height="80" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+      <text x="820" y="234" text-anchor="middle">Reports</text>
+      <text x="820" y="252" text-anchor="middle" font-size="10.5" font-weight="400" fill="#57606a">JSON &#183; Markdown</text>
+      <text x="820" y="268" text-anchor="middle" font-size="10.5" font-weight="400" fill="#57606a">ATT&amp;CK Navigator</text>
+    </g>
+  </g>
+
+  <!-- pipeline arrows -->
+  <g stroke="#57606a" stroke-width="1.6" marker-end="url(#arrow)">
+    <line x1="140" y1="240" x2="166" y2="240"/>
+    <line x1="288" y1="240" x2="314" y2="240"/>
+    <line x1="436" y1="240" x2="462" y2="240"/>
+    <line x1="584" y1="240" x2="610" y2="240"/>
+    <line x1="732" y1="240" x2="758" y2="240"/>
+  </g>
+
+  <!-- LLM connectors (dashed, red) -->
+  <g stroke="#cf222e" stroke-width="1.4" stroke-dasharray="5 4" fill="none">
+    <path d="M400,140 C400,175 300,165 260,199" marker-end="url(#arrowR)"/>
+    <path d="M672,200 C672,168 640,150 632,141" marker-end="url(#arrowR)"/>
+  </g>
+  <text x="300" y="182" font-size="10" fill="#cf222e">chooses next</text>
+  <text x="686" y="176" font-size="10" fill="#cf222e" text-anchor="start">read-only</text>
+
+  <!-- caption -->
+  <text x="24" y="320" font-size="12" fill="#1f2328">The <tspan font-weight="700">detected / gap</tspan> verdict is a pure function of logs and Sigma rules, written to disk <tspan font-weight="700">before</tspan> any model is called.</text>
+  <text x="24" y="340" font-size="12" fill="#57606a">REPLAY re-evaluates real captured telemetry offline; a test asserts the coverage is byte-identical with and without the LLM.</text>
+</svg>