detect-forge 0.1.0__py3-none-any.whl

detect_forge/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("detect-forge")

detect_forge/_stubs.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import click
+
+from .console import err_console
+from .exit_codes import RESERVED
+
+
+def stub_command(name: str, message: str, *, help_text: str | None = None) -> click.Command:
+    """Return a click command that prints `message` to stderr and exits RESERVED.
+
+    Used by every subcommand that is registered for discoverability but has
+    not yet been implemented.
+
+    Args:
+        name: The command name as it appears on the CLI.
+        message: Multi-line stderr message printed before exit.
+        help_text: Optional one-line summary shown in the parent group's
+            `--help` listing. Defaults to the first line of ``message``.
+    """
+    summary = help_text if help_text is not None else message.split("\n", 1)[0]
+
+    @click.command(name=name, help=summary)
+    @click.argument("args", nargs=-1, type=click.UNPROCESSED)
+    @click.pass_context
+    def _stub(ctx: click.Context, args: tuple[str, ...]) -> None:
+        _ = args  # accept and ignore any positional args so users hit the stub
+        err_console.print(message)
+        ctx.exit(RESERVED)
+
+    return _stub

detect_forge/_tactics.py

@@ -0,0 +1,57 @@
+"""Canonical ATT&CK enterprise tactic shortname → (TA-ID, display name) mapping.
+
+Source: MITRE ATT&CK Enterprise matrix. Stable across ATT&CK versions — last refreshed
+2026-05-29 against ATT&CK v15.
+
+The shortname is what each ``AttackTechnique.tactic_ids`` actually contains (parsed
+from STIX ``kill_chain_phases.phase_name``). The TA-ID and display name are used for
+reports and the Navigator layer.
+"""
+
+from __future__ import annotations
+
+# Ordered by ATT&CK Navigator matrix display order (left to right).
+TACTIC_DISPLAY_ORDER: tuple[str, ...] = (
+    "reconnaissance",
+    "resource-development",
+    "initial-access",
+    "execution",
+    "persistence",
+    "privilege-escalation",
+    "defense-evasion",
+    "credential-access",
+    "discovery",
+    "lateral-movement",
+    "collection",
+    "command-and-control",
+    "exfiltration",
+    "impact",
+)
+
+_TACTIC_LOOKUP: dict[str, tuple[str, str]] = {
+    "reconnaissance":        ("TA0043", "Reconnaissance"),
+    "resource-development":  ("TA0042", "Resource Development"),
+    "initial-access":        ("TA0001", "Initial Access"),
+    "execution":             ("TA0002", "Execution"),
+    "persistence":           ("TA0003", "Persistence"),
+    "privilege-escalation":  ("TA0004", "Privilege Escalation"),
+    "defense-evasion":       ("TA0005", "Defense Evasion"),
+    "credential-access":     ("TA0006", "Credential Access"),
+    "discovery":             ("TA0007", "Discovery"),
+    "lateral-movement":      ("TA0008", "Lateral Movement"),
+    "collection":            ("TA0009", "Collection"),
+    "command-and-control":   ("TA0011", "Command and Control"),
+    "exfiltration":          ("TA0010", "Exfiltration"),
+    "impact":                ("TA0040", "Impact"),
+}
+
+
+def lookup_tactic(shortname: str) -> tuple[str, str]:
+    """Return ``(TA-ID, display_name)`` for an ATT&CK tactic shortname.
+
+    Unknown shortnames return ``(shortname, shortname.title().replace("-", " "))`` so
+    the report stays informative if MITRE adds a new tactic before we refresh.
+    """
+    if shortname in _TACTIC_LOOKUP:
+        return _TACTIC_LOOKUP[shortname]
+    return (shortname, shortname.replace("-", " ").title())

detect_forge/audit/__init__.py

@@ -0,0 +1,27 @@
+"""The audit meta-subcommand.
+
+Composes stale + coverage + backtest into a unified report.
+Public entry point: ``scan_audit(rule_dir, **kwargs)``.
+
+See ``docs/superpowers/specs/2026-06-08-audit-design.md`` for design.
+"""
+
+from __future__ import annotations
+
+from .models import (
+    AuditReport,
+    AuditSubResult,
+    AuditSummary,
+    SubcommandName,
+    SubResultStatus,
+)
+from .orchestrator import run_audit as scan_audit
+
+__all__ = [
+    "AuditReport",
+    "AuditSubResult",
+    "AuditSummary",
+    "SubResultStatus",
+    "SubcommandName",
+    "scan_audit",
+]

detect_forge/audit/cli.py

@@ -0,0 +1,229 @@
+"""The audit subcommand — composes stale + coverage + backtest."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import click
+from click.core import ParameterSource
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from ..config import (
+    find_config_file,
+    load_audit_config_or_defaults,
+    load_backtest_config_or_defaults,
+    load_coverage_config_or_defaults,
+    load_stale_config_or_defaults,
+)
+from ..console import err_console
+from ..exit_codes import GATED, RESERVED
+from ..settings import Settings
+
+log = logging.getLogger(__name__)
+
+
+def _abs_against(base: Path | None, value: str) -> Path:
+    """Resolve a possibly-relative config path against the config-file dir."""
+    p = Path(value)
+    if p.is_absolute() or base is None:
+        return p
+    return base / p
+
+
+@click.command(name="audit")
+@click.argument(
+    "rule_dir",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+)
+@click.option(
+    "--format", "output_format",
+    type=click.Choice(["terminal", "json", "html"]),
+    default="terminal", show_default=True,
+    help="Output format. Navigator is NOT supported in v0.1 — run "
+         "coverage/backtest directly for those layers.",
+)
+@click.option(
+    "--output", "-o",
+    type=click.Path(path_type=Path), default=None,
+    help="Write output to file instead of stdout",
+)
+@click.option(
+    "--no-cache", is_flag=True, default=False,
+    help="Bypass STIX + Mordor caches across all subcommands",
+)
+@click.option(
+    "--domain",
+    type=click.Choice(["enterprise-attack", "ics-attack", "mobile-attack"]),
+    default=Settings().attack_domain, show_default=True,
+    help="ATT&CK domain",
+)
+@click.option(
+    "--no-gate", is_flag=True, default=False,
+    help="Don't exit 2 even if the audit gate would have fired",
+)
+@click.option(
+    "--skip",
+    multiple=True,
+    type=click.Choice(["stale", "coverage", "backtest"]),
+    help="Skip a subcommand entirely. Repeatable.",
+)
+@click.option(
+    "--priority-list",
+    type=click.Path(exists=True, path_type=Path), default=None,
+    help="Path to custom priority list JSON (shared by coverage + backtest)",
+)
+@click.option(
+    "--with-llm-proposals", is_flag=True, default=False,
+    help="Enable LLM diff proposals in stale (off by default — cost gate)",
+)
+@click.option(
+    "--platform",
+    type=click.Choice(["windows", "linux", "macos", "all"]),
+    default="all", show_default=True,
+    help="Backtest-only: limit Mordor datasets by platform",
+)
+@click.option(
+    "--mordor-source",
+    type=click.Path(exists=True, path_type=Path), default=None,
+    help="Backtest-only: local Security-Datasets checkout (overrides config)",
+)
+@click.option(
+    "--techniques", default=None,
+    help="Backtest-only: comma-separated technique IDs to restrict scan",
+)
+@click.option(
+    "--semantic-threshold",
+    type=float, default=0.65, show_default=True,
+    help="Stale: cosine similarity threshold for semantic drift",
+)
+@click.pass_context
+def audit_cmd(
+    ctx: click.Context,
+    rule_dir: Path,
+    output_format: str,
+    output: Path | None,
+    no_cache: bool,
+    domain: str,
+    no_gate: bool,
+    skip: tuple[str, ...],
+    priority_list: Path | None,
+    with_llm_proposals: bool,
+    platform: str,
+    mordor_source: Path | None,
+    techniques: str | None,
+    semantic_threshold: float,
+) -> None:
+    """Run every check in one step — stale + coverage + backtest."""
+    from . import reporter, scan_audit
+
+    settings = Settings()
+    audit_cfg = load_audit_config_or_defaults()
+    stale_cfg = load_stale_config_or_defaults()
+    coverage_cfg = load_coverage_config_or_defaults()
+    backtest_cfg = load_backtest_config_or_defaults()
+    config_file = find_config_file()
+    config_dir = config_file.parent if config_file is not None else None
+    effective_no_cache = no_cache or settings.no_cache
+
+    # Compute enabled subcommands: config.subcommands MINUS CLI --skip.
+    from typing import cast as _cast  # noqa: PLC0415
+
+    from ..audit.models import SubcommandName  # noqa: PLC0415
+    config_enabled: set[SubcommandName] = set(audit_cfg.subcommands)
+    cli_skip: set[SubcommandName] = _cast(
+        "set[SubcommandName]", set(skip)
+    )
+    enabled: set[SubcommandName] = config_enabled - cli_skip
+    if not enabled:
+        err_console.print(
+            "[critical]No subcommands enabled "
+            "(everything was either disabled in config or --skipped).[/critical]"
+        )
+        ctx.exit(RESERVED)
+        return
+
+    # Gate strategy: config drives ('all' default, 'never' kills); --no-gate forces never.
+    effective_gate_strategy = audit_cfg.gate_strategy
+    if no_gate:
+        effective_gate_strategy = "never"
+
+    # LLM: opt-in via CLI flag or config; model + quota come from [stale].
+    effective_llm_model: str | None = None
+    if with_llm_proposals or audit_cfg.include_llm_proposals:
+        effective_llm_model = stale_cfg.llm_model
+
+    # Semantic threshold precedence: env > CLI-explicit > [stale] config > default.
+    effective_threshold = stale_cfg.semantic_threshold
+    if ctx.get_parameter_source("semantic_threshold") == ParameterSource.COMMANDLINE:
+        effective_threshold = semantic_threshold
+    if settings.semantic_threshold is not None:
+        effective_threshold = settings.semantic_threshold
+
+    # Priority list: CLI --priority-list wins; else [coverage] priority_list
+    # resolved against the config-file dir (shared by coverage + backtest).
+    effective_priority: Path | None = priority_list
+    if effective_priority is None and coverage_cfg.priority_list:
+        effective_priority = _abs_against(config_dir, coverage_cfg.priority_list)
+
+    # Platform / mordor-source: CLI overrides [backtest] config.
+    effective_platform = platform
+    if ctx.get_parameter_source("platform") != ParameterSource.COMMANDLINE:
+        effective_platform = backtest_cfg.platform
+    effective_mordor: Path | None = mordor_source
+    if effective_mordor is None and backtest_cfg.mordor_source:
+        effective_mordor = _abs_against(config_dir, backtest_cfg.mordor_source)
+
+    # Technique filter parse.
+    technique_filter: set[str] | None = None
+    if techniques:
+        technique_filter = {t.strip() for t in techniques.split(",") if t.strip()}
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("{task.description}"),
+        console=err_console,
+        transient=True,
+    ) as progress:
+        prog_task = progress.add_task("Running audit...", total=None)
+        report = scan_audit(
+            rule_dir,
+            enabled=enabled,
+            gate_strategy=effective_gate_strategy,
+            domain=domain,
+            cache_dir=settings.cache_dir,
+            cache_ttl_hours=settings.cache_ttl_hours,
+            no_cache=effective_no_cache,
+            priority_list=effective_priority,
+            platform=effective_platform,
+            technique_filter=technique_filter,
+            mordor_source=effective_mordor,
+            semantic_threshold=effective_threshold,
+            llm_model=effective_llm_model,
+            max_proposals=stale_cfg.max_proposals,
+            coverage_gate_on_priority_gaps=coverage_cfg.gate_on_priority_gaps,
+            backtest_gate_on_priority_silence=backtest_cfg.gate_on_priority_silence,
+            backtest_gate_on_broken_rules=backtest_cfg.gate_on_broken_rules,
+        )
+        progress.remove_task(prog_task)
+
+    rendered = reporter.render(report, output_format=output_format)
+
+    if output:
+        output.write_text(rendered, encoding="utf-8")
+        err_console.print(f"[info]Report written to {output}[/info]")
+    else:
+        click.echo(rendered, nl=False, color=output_format == "terminal")
+
+    # Exit code per spec §4:
+    # 2 — audit gate fired (gate-fire wins over errored)
+    # 1 — at least one subcommand errored AND gate didn't fire
+    # 0 — clean
+    if report.summary.audit_would_gate and not no_gate:
+        ctx.exit(GATED)
+    if report.summary.subcommands_errored > 0:
+        ctx.exit(RESERVED)
+
+
+def register(group: click.Group) -> None:
+    group.add_command(audit_cmd)

detect_forge/audit/models.py

@@ -0,0 +1,74 @@
+"""Pydantic models for the audit subcommand.
+
+AuditReport is the public surface — passed to reporters and rendered.
+Per spec §7, AuditSubResult is a tagged union over the 3 subcommand
+report types; exactly one of {stale_report, coverage_report,
+backtest_report} is populated when status == "ran".
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from ..backtest.models import BacktestReport
+from ..coverage.models import CoverageReport
+from ..stale.models import StalenessReport
+
+SubcommandName = Literal["stale", "coverage", "backtest"]
+SubResultStatus = Literal["ran", "skipped", "errored"]
+
+
+class AuditSubResult(BaseModel):
+    """Wraps a single subcommand's outcome.
+
+    When ``status == "ran"``: the matching ``*_report`` field is populated;
+    ``error`` is None; ``would_gate`` and ``score`` are meaningful.
+    When ``status == "skipped"`` or ``"errored"``: all ``*_report`` fields
+    are None; ``score`` is None; ``would_gate`` is False.
+    """
+
+    subcommand: SubcommandName
+    status: SubResultStatus
+    error: str | None = None
+    would_gate: bool = False
+    score: int | None = None
+
+    stale_report: StalenessReport | None = None
+    coverage_report: CoverageReport | None = None
+    backtest_report: BacktestReport | None = None
+
+
+class AuditSummary(BaseModel):
+    """Top-of-report stats. ``audit_would_gate`` drives the CI exit code."""
+
+    rules_scanned: int
+    """How many rules were discovered in the rule_dir (after parse)."""
+
+    stale_health: int | None
+    """Per spec §6: 100 * (total_rules - critical) / total_rules. None if skipped/errored."""
+    coverage_completeness: int | None
+    """100 * full / total_techniques."""
+    backtest_verification_rate: int | None
+    """100 * rules_fires / (rules_parsed - rules_unsupported)."""
+
+    subcommands_ran: int
+    subcommands_skipped: int
+    subcommands_errored: int
+
+    audit_would_gate: bool
+    """True when every enabled subcommand's ``would_gate`` predicate is True."""
+
+    attack_domain: str
+    generated_at: datetime
+    elapsed_seconds: float
+
+
+class AuditReport(BaseModel):
+    """Final audit report passed to renderers."""
+
+    summary: AuditSummary
+    sub_results: list[AuditSubResult] = Field(default_factory=list)
+    """Always 3 entries when produced by run_audit(), ordered stale → coverage → backtest."""

detect_forge/audit/orchestrator.py

@@ -0,0 +1,208 @@
+"""Audit orchestrator: composes stale + coverage + backtest into AuditReport.
+
+Each subcommand runs sequentially in-process. Failure isolation: a
+crashing subcommand becomes an AuditSubResult with status='errored';
+the other two still run.
+
+Gate composition per spec §5: strict-AND — audit_would_gate is True
+only when ALL enabled subcommands' would_gate predicates are True.
+gate_strategy='never' overrides to always-False.
+
+The scoring/gate-predicate functions are imported from .scoring; this
+module is purely composition + error handling + summary building.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Literal
+
+from ..backtest import scan_backtest
+from ..coverage import scan_coverage
+from ..stale import scan as scan_stale
+from .models import AuditReport, AuditSubResult, AuditSummary, SubcommandName
+from .scoring import (
+    backtest_verification_rate,
+    backtest_would_gate,
+    coverage_completeness,
+    coverage_would_gate,
+    stale_health,
+    stale_would_gate,
+)
+
+log = logging.getLogger(__name__)
+
+
+def run_audit(
+    rule_dir: Path,
+    *,
+    enabled: set[SubcommandName] | None = None,
+    gate_strategy: Literal["all", "never"] = "all",
+    domain: str = "enterprise-attack",
+    cache_dir: Path | None = None,
+    cache_ttl_hours: int = 24,
+    no_cache: bool = False,
+    priority_list: Path | None = None,
+    platform: str = "all",
+    technique_filter: set[str] | None = None,
+    mordor_source: Path | None = None,
+    semantic_threshold: float = 0.65,
+    llm_model: str | None = None,
+    max_proposals: int = 5,
+    coverage_gate_on_priority_gaps: bool = True,
+    backtest_gate_on_priority_silence: bool = True,
+    backtest_gate_on_broken_rules: bool = True,
+) -> AuditReport:
+    """Compose all 3 subcommands into a single AuditReport.
+
+    Each subcommand call is wrapped in try/except. A crashing subcommand
+    becomes a sub_result with status='errored' and the rest continue.
+
+    Args:
+        rule_dir: Detection rule directory.
+        enabled: Set of subcommands to run. Default: all 3.
+        gate_strategy: 'all' for strict-AND composition; 'never' to disable.
+        domain, cache_dir, cache_ttl_hours, no_cache, priority_list:
+            forwarded to each subcommand.
+        platform, technique_filter, mordor_source: backtest-only kwargs.
+        semantic_threshold, llm_model, max_proposals: stale-only kwargs.
+    """
+    if enabled is None:
+        enabled = {"stale", "coverage", "backtest"}
+
+    started = time.monotonic()
+    sub_results: list[AuditSubResult] = []
+    rules_scanned: int = 0
+
+    # ---- Stale ----
+    if "stale" in enabled:
+        try:
+            stale_report = scan_stale(
+                rule_dir,
+                domain=domain,
+                cache_dir=cache_dir,
+                cache_ttl_hours=cache_ttl_hours,
+                no_cache=no_cache,
+                semantic_threshold=semantic_threshold,
+                llm_model=llm_model,
+                max_proposals=max_proposals,
+            )
+            rules_scanned = max(rules_scanned, stale_report.summary.total_rules)
+            sub_results.append(AuditSubResult(
+                subcommand="stale",
+                status="ran",
+                would_gate=stale_would_gate(stale_report),
+                score=stale_health(stale_report),
+                stale_report=stale_report,
+            ))
+        except Exception as exc:  # noqa: BLE001 — failure isolation per spec §11
+            log.error("stale subcommand failed: %s", exc, exc_info=True)
+            sub_results.append(AuditSubResult(
+                subcommand="stale",
+                status="errored",
+                error=f"{type(exc).__name__}: {exc}",
+            ))
+    else:
+        sub_results.append(AuditSubResult(subcommand="stale", status="skipped"))
+
+    # ---- Coverage ----
+    if "coverage" in enabled:
+        try:
+            cov_report = scan_coverage(
+                rule_dir,
+                domain=domain,
+                cache_dir=cache_dir,
+                cache_ttl_hours=cache_ttl_hours,
+                no_cache=no_cache,
+                priority_list=priority_list,
+            )
+            rules_scanned = max(rules_scanned, cov_report.summary.rules_parsed)
+            sub_results.append(AuditSubResult(
+                subcommand="coverage",
+                status="ran",
+                would_gate=coverage_would_gate(
+                    cov_report, gate_on_priority_gaps=coverage_gate_on_priority_gaps
+                ),
+                score=coverage_completeness(cov_report),
+                coverage_report=cov_report,
+            ))
+        except Exception as exc:  # noqa: BLE001
+            log.error("coverage subcommand failed: %s", exc, exc_info=True)
+            sub_results.append(AuditSubResult(
+                subcommand="coverage",
+                status="errored",
+                error=f"{type(exc).__name__}: {exc}",
+            ))
+    else:
+        sub_results.append(AuditSubResult(subcommand="coverage", status="skipped"))
+
+    # ---- Backtest ----
+    if "backtest" in enabled:
+        try:
+            bt_report = scan_backtest(
+                rule_dir,
+                domain=domain,
+                cache_dir=cache_dir,
+                cache_ttl_hours=cache_ttl_hours,
+                no_cache=no_cache,
+                priority_list=priority_list,
+                platform=platform,
+                technique_filter=technique_filter,
+                mordor_source=mordor_source,
+            )
+            rules_scanned = max(rules_scanned, bt_report.summary.rules_parsed)
+            sub_results.append(AuditSubResult(
+                subcommand="backtest",
+                status="ran",
+                would_gate=backtest_would_gate(
+                    bt_report,
+                    gate_on_priority_silence=backtest_gate_on_priority_silence,
+                    gate_on_broken_rules=backtest_gate_on_broken_rules,
+                ),
+                score=backtest_verification_rate(bt_report),
+                backtest_report=bt_report,
+            ))
+        except Exception as exc:  # noqa: BLE001
+            log.error("backtest subcommand failed: %s", exc, exc_info=True)
+            sub_results.append(AuditSubResult(
+                subcommand="backtest",
+                status="errored",
+                error=f"{type(exc).__name__}: {exc}",
+            ))
+    else:
+        sub_results.append(AuditSubResult(subcommand="backtest", status="skipped"))
+
+    # ---- Compose summary ----
+    ran = [sr for sr in sub_results if sr.status == "ran"]
+    skipped = [sr for sr in sub_results if sr.status == "skipped"]
+    errored = [sr for sr in sub_results if sr.status == "errored"]
+
+    audit_would_gate = (
+        gate_strategy == "all"
+        and len(ran) > 0
+        and all(sr.would_gate for sr in ran)
+        and len(ran) == len(enabled)  # All enabled subcommands actually ran
+    )
+
+    stale_sr = next((sr for sr in ran if sr.subcommand == "stale"), None)
+    cov_sr = next((sr for sr in ran if sr.subcommand == "coverage"), None)
+    bt_sr = next((sr for sr in ran if sr.subcommand == "backtest"), None)
+
+    summary = AuditSummary(
+        rules_scanned=rules_scanned,
+        stale_health=stale_sr.score if stale_sr else None,
+        coverage_completeness=cov_sr.score if cov_sr else None,
+        backtest_verification_rate=bt_sr.score if bt_sr else None,
+        subcommands_ran=len(ran),
+        subcommands_skipped=len(skipped),
+        subcommands_errored=len(errored),
+        audit_would_gate=audit_would_gate,
+        attack_domain=domain,
+        generated_at=datetime.now(UTC),
+        elapsed_seconds=time.monotonic() - started,
+    )
+
+    return AuditReport(summary=summary, sub_results=sub_results)