redgap 0.1.0__py3-none-any.whl

redgap/__init__.py

@@ -0,0 +1,9 @@
+"""RedGap — automated MITRE ATT&CK-mapped offense<->detection coverage harness.
+
+The deterministic core (models, allowlist, telemetry schema, detection engine,
+coverage) has no third-party dependencies beyond pySigma at the parsing edge and
+never depends on a language model. The optional LLM planner lives behind the
+``redgap[llm]`` extra and is disabled by default.
+"""
+
+__version__ = "0.1.0"

redgap/_resources.py

@@ -0,0 +1,44 @@
+"""Locate RedGap's committed data (Sigma rules, replay fixtures, lab build context)
+in BOTH an editable checkout and an installed wheel.
+
+In a source checkout the data lives at the repository root (``rules/``, ``fixtures/``,
+``lab/``). The wheel force-includes those same trees *inside* the package
+(``redgap/rules`` …), so an installed ``redgap`` resolves them through
+``importlib.resources`` instead of guessing a path relative to the repo root. This is
+what lets ``pip install .`` / ``pipx install redgap`` run ``redgap run`` from any
+directory — not only an editable install run from the source tree.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+
+def _data_root(name: str) -> Path:
+    # Installed wheel: the data tree is force-included inside the package. This assumes a
+    # filesystem-based install (pip/pipx unpack to site-packages — the supported targets),
+    # not zipimport/zipapp; str() on the Traversable is a real path there.
+    try:
+        packaged = files("redgap") / name
+        if packaged.is_dir():
+            return Path(str(packaged))
+    except (ModuleNotFoundError, FileNotFoundError, NotADirectoryError):
+        pass
+    # Editable install / source checkout: the data lives at the repository root.
+    return Path(__file__).resolve().parents[2] / name
+
+
+def rules_dir() -> Path:
+    """Directory holding the shipped Sigma rules."""
+    return _data_root("rules")
+
+
+def fixtures_dir() -> Path:
+    """Directory holding the committed replay telemetry fixtures."""
+    return _data_root("fixtures") / "replay"
+
+
+def lab_dir() -> Path:
+    """Docker build context for the disposable lab (LIVE mode only)."""
+    return _data_root("lab")

redgap/allowlist.py

@@ -0,0 +1,147 @@
+"""Target allowlist — the gate that keeps RedGap pointed at its own lab.
+
+RedGap must never be usable against a system the operator does not own. That is
+enforced structurally here, not by convention, on two surfaces:
+
+* **Container launches (the LIVE path).** Every ``docker run`` goes through
+  :func:`assert_lab_only`, which refuses to start a container unless networking is
+  disabled (``--network none``) or pinned to the private lab subnet. ``lab.py`` routes
+  each launch through it, so an edit that quietly networks the lab fails at runtime.
+* **Target strings.** :func:`resolve_and_check` accepts only loopback, the lab subnet,
+  or the fixed lab hostnames. There is deliberately **no** function to add a host and
+  nothing here reads the environment or CLI to widen the set; hostnames are matched
+  literally (no DNS), so a name that resolves to loopback cannot slip through. This is
+  the guard for any network-reachable target surface (LIVE-remote is on the roadmap).
+
+``tests/test_allowlist.py`` asserts both gates and that neither can be widened.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from collections.abc import Sequence
+
+#: Loopback ranges (the only IP targets that make sense for a local lab).
+_LOOPBACK_NETS = (
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("::1/128"),
+)
+
+#: The fixed private bridge the disposable Docker lab is pinned to. Not routable.
+_LAB_SUBNET = ipaddress.ip_network("172.28.0.0/24")
+
+#: The only literal hostnames accepted (the lab's compose service names + loopback).
+_LAB_HOSTNAMES = frozenset({"localhost", "lab", "redgap-lab"})
+
+
+class TargetNotAllowed(ValueError):
+    """Raised when a target is not the local lab. Never caught to 'try anyway'."""
+
+
+def is_allowed(target: str) -> bool:
+    """Return True iff ``target`` is loopback, the lab subnet, or a lab hostname."""
+    t = (target or "").strip()
+    if not t:
+        return False
+    try:
+        ip = ipaddress.ip_address(t)
+    except ValueError:
+        # Not an IP literal: accept only the fixed lab hostnames, verbatim.
+        return t.lower() in _LAB_HOSTNAMES
+    if any(ip in net for net in _LOOPBACK_NETS):
+        return True
+    return ip in _LAB_SUBNET
+
+
+def resolve_and_check(target: str) -> str:
+    """Return the normalized target if allowed; otherwise raise TargetNotAllowed.
+
+    This is the only sanctioned way to obtain a target for the runner/lab.
+    """
+    t = (target or "").strip()
+    if not is_allowed(t):
+        raise TargetNotAllowed(
+            f"refusing target {target!r}: RedGap only acts against its own local lab "
+            f"(loopback, {_LAB_SUBNET}, or one of {sorted(_LAB_HOSTNAMES)}). "
+            f"There is no override — this is by design (see ETHICS.md)."
+        )
+    return t.lower() if not _is_ip(t) else t
+
+
+def _is_ip(value: str) -> bool:
+    try:
+        ipaddress.ip_address(value)
+        return True
+    except ValueError:
+        return False
+
+
+# Global flags that could point docker at a remote/other engine — never allowed.
+_DAEMON_REDIRECT_FLAGS = frozenset({"-H", "--host", "--context", "-c"})
+# Subcommands that create/launch a container (as `docker run` or `docker container run`).
+_CONTAINER_CREATE_VERBS = frozenset({"run", "create"})
+# Global flags that consume a following value, so that value is not the subcommand.
+_VALUE_GLOBAL_FLAGS = frozenset(
+    {
+        "-H", "--host", "--context", "-c", "--config",
+        "--log-level", "-l", "--tlscacert", "--tlscert", "--tlskey",
+    }
+)  # fmt: skip
+
+
+def _network_values(docker_args: Sequence[str]) -> list[str]:
+    """Every ``--network``/``--net`` value in a docker argv. docker *appends* repeated
+    ``--network`` flags and attaches the container to all of them, so we collect all."""
+    vals: list[str] = []
+    args = list(docker_args)
+    for i, arg in enumerate(args):
+        if arg in ("--network", "--net"):
+            if i + 1 < len(args):
+                vals.append(args[i + 1])
+        elif arg.startswith("--network=") or arg.startswith("--net="):
+            vals.append(arg.split("=", 1)[1])
+    return vals
+
+
+def _effective_verb_and_index(args: list[str]) -> tuple[str | None, int]:
+    """The docker subcommand verb and its index, skipping leading global flags (and any
+    values they consume) and an optional ``container`` management-group word."""
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a.startswith("-"):
+            i += 2 if (a in _VALUE_GLOBAL_FLAGS and "=" not in a) else 1
+            continue
+        if a == "container":  # `docker container run/create` == `docker run/create`
+            i += 1
+            continue
+        return a, i
+    return None, len(args)
+
+
+def assert_lab_only(docker_args: Sequence[str]) -> None:
+    """Gate a docker invocation so RedGap can only ever act on its own offline lab.
+
+    Refuses (1) any daemon-redirecting global flag (``-H``/``--host``/``--context``),
+    which could target a remote engine, and (2) any container-creating command
+    (``run``/``create``, including the ``docker container …`` form) whose networking is
+    not disabled — every ``--network``/``--net`` value must be ``none``. Non-creating
+    commands (build, exec, cp, rm, inspect) are allowed. :mod:`redgap.lab` routes every
+    docker call through here, so an edit that networks the lab fails at runtime."""
+    args = list(docker_args)
+    verb, verb_idx = _effective_verb_and_index(args)
+    # Global flags sit before the verb; none may redirect the daemon off the local box.
+    for a in args[:verb_idx]:
+        if a.split("=", 1)[0] in _DAEMON_REDIRECT_FLAGS:
+            raise TargetNotAllowed(
+                f"refusing docker invocation with {a!r}: RedGap uses the local docker "
+                f"daemon only, never a remote/redirected engine (see ETHICS.md)."
+            )
+    if verb not in _CONTAINER_CREATE_VERBS:
+        return
+    nets = _network_values(args[verb_idx:])
+    if not nets or any(n != "none" for n in nets):
+        raise TargetNotAllowed(
+            f"refusing to launch a container with networking {nets or ['(default bridge)']}: "
+            f"RedGap's lab must run with '--network none'. There is no override — by design."
+        )

redgap/catalog.py

@@ -0,0 +1,63 @@
+"""The v0.1 technique catalog (metadata only).
+
+Five benign, MITRE ATT&CK-mapped techniques forming a small kill-chain. Execution
+and cleanup live in the ``techniques/`` modules; this file is the pure-data catalog
+the engine, coverage join, and reports use. Names and IDs verified against
+attack.mitre.org on 2026-08-11.
+
+The mix is deliberate — three detections and two *different kinds* of gap — so the
+coverage report demonstrates real gap intelligence rather than an all-green list.
+"""
+
+from __future__ import annotations
+
+from redgap.models import GapType, Technique
+
+CATALOG: tuple[Technique, ...] = (
+    Technique(
+        id="T1087.001",
+        name="Account Discovery: Local Account",
+        tactics=("Discovery",),
+        description="Enumerate local accounts by reading /etc/passwd.",
+        atomic_ref="T1087.001",
+        expected_gap_type=GapType.NONE,  # detected
+    ),
+    Technique(
+        id="T1057",
+        name="Process Discovery",
+        tactics=("Discovery",),
+        description="List running processes with ps/top.",
+        atomic_ref="T1057",
+        # base-rate gap: ps/top are ubiquitous; a single-event rule would flood.
+        # Real signal needs correlation (roadmap). We deliberately ship no rule.
+        expected_gap_type=GapType.BASE_RATE,
+    ),
+    Technique(
+        id="T1136.001",
+        name="Create Account: Local Account",
+        tactics=("Persistence",),
+        description="Create a local account with useradd (nologin, no password).",
+        atomic_ref="T1136.001",
+        expected_gap_type=GapType.NONE,  # detected
+    ),
+    Technique(
+        id="T1548.001",
+        name="Abuse Elevation Control Mechanism: Setuid and Setgid",
+        tactics=("Privilege Escalation", "Defense Evasion"),
+        description="Set the setuid bit on an inert /bin/true copy after chown root.",
+        atomic_ref="T1548.001",
+        expected_gap_type=GapType.NONE,  # detected by a shipped SigmaHQ rule
+    ),
+    Technique(
+        id="T1070.006",
+        name="Indicator Removal: Timestomp",
+        tactics=("Defense Evasion",),
+        description="Alter file timestamps with touch -r/-t.",
+        atomic_ref="T1070.006",
+        # rule gap by default: telemetry is present but no rule ships. Closed in
+        # the remediation round-trip (rules/roundtrip/timestomp_touch.yml).
+        expected_gap_type=GapType.RULE,
+    ),
+)
+
+BY_ID: dict[str, Technique] = {t.id: t for t in CATALOG}

redgap/cli.py

@@ -0,0 +1,134 @@
+"""The ``redgap`` command — the only module that imports typer/rich.
+
+Default run is REPLAY: re-evaluate the committed real-telemetry fixtures fully offline,
+with no Docker and no API key. ``--live`` captures fresh telemetry from the Docker lab;
+``--fix`` loads the closing rule that flips the timestomp gap red -> green.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.table import Table
+
+from redgap import __version__
+from redgap.pipeline import exit_code_for, run_coverage
+from redgap.target import ReplayTarget
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="RedGap — automated MITRE ATT&CK offense<->detection coverage harness.",
+)
+console = Console()
+
+_LIVE_BANNER = "LIVE — capturing real telemetry from the disposable lab"
+_REPLAY_BANNER = "REPLAY — re-evaluating real captured telemetry; no live attack run"
+
+
+def _now() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat()
+
+
+def _render(verdicts, report: dict, mode: str) -> None:
+    summary = report["summary"]
+    table = Table(box=box.SIMPLE_HEAVY, title=f"RedGap coverage — {mode}", title_style="bold")
+    table.add_column("ATT&CK", style="bold")
+    table.add_column("Technique")
+    table.add_column("Tactic", style="dim")
+    table.add_column("Result", justify="left")
+    table.add_column("Rule / gap")
+    by_id = {t["id"]: t for t in report["techniques"]}
+    for v in verdicts:
+        t = by_id[v.technique_id]
+        if v.detected:
+            result = "[green]● detected[/green]"
+            rule = ", ".join(v.firing_rules)
+        else:
+            result = f"[red]● gap[/red] [dim]({v.gap_type.value})[/dim]"
+            rule = "[dim]—[/dim]"
+        if v.unexpected:
+            result += " [yellow](regression)[/yellow]"
+        table.add_row(v.technique_id, t["name"], " / ".join(t["tactics"]), result, rule)
+    console.print(table)
+    gaps_str = ", ".join(f"{k}:{n}" for k, n in summary["gaps_by_type"].items()) or "none"
+    gap_word = "gap" if summary["gaps"] == 1 else "gaps"
+    console.print(
+        f"[bold green]{summary['detected']}[/bold green]/{summary['techniques']} detected · "
+        f"[bold red]{summary['gaps']}[/bold red] {gap_word}  [dim]({gaps_str})[/dim]"
+    )
+
+
+@app.command()
+def run(
+    live: Annotated[
+        bool, typer.Option("--live", help="Capture fresh telemetry from the Docker lab.")
+    ] = False,
+    fix: Annotated[
+        bool, typer.Option("--fix", help="Load the closing rule (flips the timestomp gap green).")
+    ] = False,
+    out: Annotated[
+        Path, typer.Option(help="Write coverage.json/.md/navigator-layer.json here.")
+    ] = Path("out"),
+    json_out: Annotated[
+        bool, typer.Option("--json", help="Print coverage JSON (for CI); no table.")
+    ] = False,
+    llm: Annotated[
+        bool, typer.Option("--llm", help="Use the optional LLM planner (needs ANTHROPIC_API_KEY).")
+    ] = False,
+) -> None:
+    """Run the coverage loop (REPLAY by default)."""
+    if live:
+        from redgap.target import LiveDockerTarget
+
+        target = LiveDockerTarget()
+    else:
+        target = ReplayTarget()
+
+    if not json_out:
+        console.print(f"[dim]{_LIVE_BANNER if live else _REPLAY_BANNER}[/dim]")
+
+    verdicts, report = run_coverage(
+        target, generated_at=_now(), out_dir=out, fix=fix, use_llm=(True if llm else None)
+    )
+
+    if json_out:
+        typer.echo(_json.dumps(report, indent=2, ensure_ascii=False))
+    else:
+        _render(verdicts, report, target.mode)
+        console.print(f"[dim]wrote coverage.json/.md + navigator-layer.json → {out}/[/dim]")
+
+    raise typer.Exit(exit_code_for(verdicts))
+
+
+@app.command()
+def capture(
+    at: Annotated[str, typer.Option(help="captured_at timestamp to stamp into provenance.")] = "",
+    git_commit: Annotated[
+        str, typer.Option(help="git commit to stamp into provenance.")
+    ] = "unknown",
+) -> None:
+    """Regenerate the committed real-telemetry fixtures from a live lab run (needs Docker)."""
+    from redgap import lab
+
+    console.print("[dim]building the lab image and capturing real telemetry (needs Docker)…[/dim]")
+    counts = lab.capture_all(at or _now(), git_commit=git_commit)
+    for tid, n in counts.items():
+        console.print(f"  {tid}: [bold]{n}[/bold] events")
+    console.print("[green]fixtures regenerated.[/green]")
+
+
+@app.command()
+def version() -> None:
+    """Print the RedGap version."""
+    typer.echo(f"redgap {__version__}")
+
+
+if __name__ == "__main__":
+    app()

redgap/detection/__init__.py

@@ -0,0 +1,5 @@
+"""Deterministic detection: parse Sigma, evaluate it, compute coverage.
+
+Nothing in this package depends on a language model. Every verdict is a pure
+function of (events, rules).
+"""

redgap/detection/coverage.py

@@ -0,0 +1,133 @@
+"""Coverage: join rules to techniques and compute the deterministic verdict.
+
+For each technique we gather the events its execution produced, find the rules
+tagged to that technique, and ask the engine whether any rule fires on any event.
+``detected`` is a pure boolean from that. The whole ``Verdict`` is computed here and
+persisted before any LLM is invoked.
+
+Rules that were EXCLUDED at load (unsupported feature / unreadable) are threaded in so a
+dropped closing rule cannot masquerade as a "no rule shipped" base-rate gap — the report
+distinguishes "you wrote a rule we could not evaluate" from "there is no rule".
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from redgap.detection.engine import Event, rule_matches
+from redgap.detection.sigma_ast import LoadedRule
+from redgap.models import Evidence, GapType, Technique, Verdict
+
+#: Excluded rule as returned by load_rules_detailed: (path, reason, technique_ids).
+ExcludedRule = tuple[str, str, tuple[str, ...]]
+
+
+def _parent(technique_id: str) -> str:
+    return technique_id.split(".")[0]
+
+
+def rule_covers(rule: LoadedRule, technique: Technique) -> bool:
+    """True if ``rule`` is tagged to ``technique`` (exact, or a sub-technique rule
+    covering its parent). A parent-only tag is NOT credited to a child sub-technique."""
+    for rid in rule.technique_ids:
+        if rid == technique.id:
+            return True
+        if _parent(rid) == technique.id:  # a sub-technique rule covers its parent
+            return True
+    return False
+
+
+def _exact_tagged(technique_ids: Sequence[str], technique: Technique) -> bool:
+    """A rule/exclusion is tagged EXACTLY to this technique (not merely via sub->parent)."""
+    return technique.id in technique_ids
+
+
+def _gap_type(
+    technique: Technique,
+    detected: bool,
+    telemetry_present: bool,
+    exact_rule_present: bool,
+) -> GapType:
+    if detected:
+        return GapType.NONE
+    if not telemetry_present:
+        # Executed but the collector saw nothing: a visibility/data-source gap.
+        return GapType.VISIBILITY
+    if exact_rule_present:
+        # A rule specifically for THIS technique exists (loaded-but-not-firing, or
+        # excluded at load) — a rule gap, regardless of what the catalog expected. This
+        # is the remediation round-trip's signal and it must not be masked as base-rate.
+        return GapType.RULE
+    # No rule is tagged to this technique at all; the catalog says why (rule vs base-rate).
+    if technique.expected_gap_type in (GapType.RULE, GapType.BASE_RATE):
+        return technique.expected_gap_type
+    return GapType.RULE
+
+
+def evaluate_technique(
+    technique: Technique,
+    events: list[Event],
+    rules: list[LoadedRule],
+    excluded: Sequence[ExcludedRule] = (),
+) -> Verdict:
+    """Compute the deterministic verdict for one technique execution."""
+    telemetry_present = len(events) > 0
+    candidates = [r for r in rules if rule_covers(r, technique)]
+    excluded_for_technique = [x for x in excluded if _exact_tagged(x[2], technique)]
+
+    firing_rules: list[str] = []
+    matched_event_ids: list[str] = []
+    evidence: list[Evidence] = []
+
+    for rule in candidates:
+        for event in events:
+            match = rule_matches(rule, event)
+            if match is None:
+                continue
+            if rule.id not in firing_rules:
+                firing_rules.append(rule.id)
+            if match.event_id not in matched_event_ids:
+                matched_event_ids.append(match.event_id)
+            evidence.append(
+                Evidence(
+                    rule_id=match.rule_id,
+                    rule_title=match.rule_title,
+                    event_id=match.event_id,
+                    matched_fields=match.matched_fields,
+                )
+            )
+
+    detected = len(firing_rules) > 0
+    # Gap typing keys on EXACT-tagged rules (loaded or excluded), so a sub->parent credit
+    # cannot downgrade a base-rate technique and an excluded closing rule still reads RULE.
+    exact_present = any(_exact_tagged(r.technique_ids, technique) for r in candidates) or bool(
+        excluded_for_technique
+    )
+    gap_type = _gap_type(technique, detected, telemetry_present, exact_present)
+    return Verdict(
+        technique_id=technique.id,
+        executed=True,
+        telemetry_present=telemetry_present,
+        detected=detected,
+        gap_type=gap_type,
+        firing_rules=tuple(firing_rules),
+        matched_event_ids=tuple(matched_event_ids),
+        evidence=tuple(evidence),
+        expected_gap_type=technique.expected_gap_type,
+        candidates_evaluated=len(candidates),
+        candidates_excluded=len(excluded_for_technique),
+        unexpected=(not detected and technique.expected_gap_type is GapType.NONE),
+    )
+
+
+def evaluate_all(
+    techniques: list[Technique],
+    events_by_technique: dict[str, list[Event]],
+    rules: list[LoadedRule],
+    excluded: Sequence[ExcludedRule] = (),
+) -> list[Verdict]:
+    """Verdicts for every technique, in catalog order (deterministic)."""
+    return [
+        evaluate_technique(t, events_by_technique.get(t.id, []), rules, excluded)
+        for t in techniques
+    ]