scrufflehog 0.1.0__py3-none-any.whl

scrufflehog/__init__.py

@@ -0,0 +1,14 @@
+"""scrufflehog — deterministically verify that your redactors actually redact.
+
+Everyone scans for secrets that leaked. scrufflehog tests whether the redaction
+you rely on actually works: it runs adversarial probes through your own redactor
+and asserts the secret is gone and not trivially reversible, and checks your
+field denylist/allow-list covers the sensitive names you think it does.
+"""
+from .oracles import Defect, assert_output, reversible
+from .probes import Probe, get_probe_set
+from .engine import RunResult, run
+
+__version__ = "0.1.0"
+__all__ = ["Defect", "assert_output", "reversible", "Probe", "get_probe_set",
+           "RunResult", "run"]

scrufflehog/advisor.py

@@ -0,0 +1,39 @@
+"""Optional advisor interface — the ONLY place non-determinism may enter.
+
+An advisor proposes INPUTS and HYPOTHESES; it never renders a verdict. The
+deterministic oracle still decides every defect. The default NoopAdvisor makes
+the engine byte-identical to a pure deterministic run — the agentic layer is
+strictly additive and opt-in. See docs/AGENTIC.md.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from .probes import Probe
+
+
+class CoverageVerdict:
+    CONFIRMED = "confirmed"      # a real field with this name reaches the redactor
+    REFUTED = "refuted"          # no such field is logged here — drop the finding
+    UNCONFIRMED = "unconfirmed"  # can't tell — finding stands as a hypothesis
+
+
+@runtime_checkable
+class Advisor(Protocol):
+    def propose_probes(self, redactor_src: str, entry: dict) -> list[Probe]: ...
+    def discover_redactors(self, target: Path) -> list[dict]: ...
+    def confirm_coverage_gap(self, target: Path, field: str, redactor: str) -> str: ...
+
+
+class NoopAdvisor:
+    """Default. Adds nothing; the run stays purely deterministic."""
+
+    def propose_probes(self, redactor_src: str, entry: dict) -> list[Probe]:
+        return []
+
+    def discover_redactors(self, target: Path) -> list[dict]:
+        return []
+
+    def confirm_coverage_gap(self, target: Path, field: str, redactor: str) -> str:
+        return CoverageVerdict.UNCONFIRMED

scrufflehog/advisors/__init__.py

@@ -0,0 +1,2 @@
+"""Optional advisors. Import the concrete one you want; the core never imports
+these, so the base package stays dependency-free and deterministic."""

scrufflehog/advisors/llm.py

@@ -0,0 +1,167 @@
+"""LLMAdvisor — the optional agentic layer.
+
+Provider-agnostic: you pass a `complete(prompt: str) -> str` callable, so this
+works with any backend (Anthropic, OpenAI, Bedrock, a local model) with no hard
+SDK dependency. The core package never imports this module.
+
+Invariant (see docs/AGENTIC.md): the advisor only proposes INPUTS and
+HYPOTHESES. It NEVER renders a verdict — the deterministic oracle still decides
+every defect. So:
+  - propose_probes: returns extra probes (planted secrets we control) for the
+    engine to run through the redactor + oracle. The model picks realistic
+    SHAPES; ground truth (the secret) is still ours.
+  - discover_redactors: returns candidate config entries for a human to confirm.
+  - confirm_coverage_gap: returns CONFIRMED/REFUTED/UNCONFIRMED by asking the
+    model to check real field usage — but a coverage finding only ever
+    DOWNGRADES to refuted or stays a hypothesis; the model can't invent one.
+
+Every method degrades to the deterministic default (empty / UNCONFIRMED) on any
+error, malformed output, or timeout. A broken advisor can never fail a run or
+manufacture a finding.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Callable
+
+from ..advisor import CoverageVerdict
+from ..probes import Probe, weak_secret_space
+
+CompleteFn = Callable[[str], str]
+
+_MAX_SRC = 6000        # cap redactor source sent to the model
+_MAX_PROBES = 6        # cap generated probes per redactor
+
+
+def _extract_json(text: str):
+    """Pull the first JSON array/object out of a model reply (tolerant of prose
+    or ```json fences). Returns the parsed value or None."""
+    if not text:
+        return None
+    fenced = re.search(r"```(?:json)?\s*(.*?)```", text, re.DOTALL)
+    candidate = fenced.group(1) if fenced else text
+    # try array then object
+    for opener, closer in (("[", "]"), ("{", "}")):
+        i, j = candidate.find(opener), candidate.rfind(closer)
+        if i != -1 and j != -1 and j > i:
+            try:
+                return json.loads(candidate[i:j + 1])
+            except json.JSONDecodeError:
+                continue
+    return None
+
+
+class LLMAdvisor:
+    def __init__(self, complete: CompleteFn):
+        self._complete = complete
+
+    # --- 1. domain-matched probe generation -------------------------------
+    def propose_probes(self, redactor_src: str, entry: dict) -> list[Probe]:
+        if not redactor_src:
+            return []
+        prompt = (
+            "You are helping test a redaction function. Given its source, return "
+            "a JSON array of test INPUTS shaped like the data this redactor is "
+            "meant to process (e.g. if it redacts URLs, produce URL strings; if "
+            "log field values, produce those). For each, give a JSON object "
+            '{"name": str, "input": str, "secret": str} where `secret` is a '
+            "substring of `input` that MUST be redacted. Use the literal token "
+            "SECRET_MARKER as the sensitive value inside each input so it is "
+            "unambiguous. Return ONLY the JSON array.\n\n"
+            f"Redactor source:\n```\n{redactor_src[:_MAX_SRC]}\n```")
+        try:
+            parsed = _extract_json(self._complete(prompt))
+        except Exception:  # noqa: BLE001
+            return []
+        if not isinstance(parsed, list):
+            return []
+        probes: list[Probe] = []
+        for i, item in enumerate(parsed[:_MAX_PROBES]):
+            if not isinstance(item, dict):
+                continue
+            inp = item.get("input")
+            secret = item.get("secret")
+            if not isinstance(inp, str) or not isinstance(secret, str) or not secret:
+                continue
+            # Substitute OUR controlled secret for the model's marker so ground
+            # truth is ours, not the model's — it only chose the SHAPE.
+            controlled = "test1234"
+            inp2 = inp.replace("SECRET_MARKER", controlled)
+            sec2 = secret.replace("SECRET_MARKER", controlled)
+            if sec2 not in inp2:
+                continue  # discard shapes where the secret isn't actually present
+            probes.append(Probe(
+                name=str(item.get("name", f"llm-probe-{i}"))[:60],
+                input=inp2, secret=sec2, secret_space=weak_secret_space()))
+        return probes
+
+    # --- 2. redactor discovery (proposals for human/config confirmation) ---
+    def discover_redactors(self, target: Path) -> list[dict]:
+        # Intentionally conservative: discovery is advisory and needs a repo
+        # walk the caller opts into. Left as a proposal hook; returns [] unless
+        # a subclass wires a file walk. Kept simple to avoid scanning huge trees
+        # by default.
+        return []
+
+    # --- 3. coverage-gap confirmation -------------------------------------
+    def confirm_coverage_gap(self, target: Path, field: str, redactor: str) -> str:
+        """Ask whether a field named `field` plausibly reaches this redactor in
+        the codebase. Can only REFUTE (drop) or leave UNCONFIRMED — never
+        promote to a defect the oracle didn't produce."""
+        # Cheap deterministic pre-check: does the token even appear in the tree?
+        # (A model call is only worth it if there's something to reason about.)
+        try:
+            hits = self._grep_field(target, field)
+        except Exception:  # noqa: BLE001
+            return CoverageVerdict.UNCONFIRMED
+        if not hits:
+            # The field name appears nowhere — the gap is likely moot here.
+            # Still only UNCONFIRMED (absence in source ≠ never logged), unless
+            # the model is available to make the call.
+            pass
+        prompt = (
+            "A log/PII redactor does NOT redact a field named "
+            f"'{field}'. Here are code lines mentioning it (may be empty):\n"
+            + "\n".join(hits[:20]) +
+            "\n\nBased ONLY on this, is a field literally named "
+            f"'{field}' plausibly present in data this redactor processes? "
+            'Answer with JSON {"verdict": "confirmed"|"refuted"|"unconfirmed"}. '
+            "Use 'refuted' only if the name clearly does not occur as a data "
+            "field here.")
+        try:
+            parsed = _extract_json(self._complete(prompt))
+        except Exception:  # noqa: BLE001
+            return CoverageVerdict.UNCONFIRMED
+        if isinstance(parsed, dict):
+            v = str(parsed.get("verdict", "")).lower()
+            if v in (CoverageVerdict.CONFIRMED, CoverageVerdict.REFUTED,
+                     CoverageVerdict.UNCONFIRMED):
+                return v
+        return CoverageVerdict.UNCONFIRMED
+
+    @staticmethod
+    def _grep_field(target: Path, field: str) -> list[str]:
+        """Deterministic, cheap: source lines mentioning the field name. Bounded
+        to keep it fast; skips obvious vendored/build dirs."""
+        out: list[str] = []
+        skip = {"node_modules", ".git", "dist", "build", "target", ".venv", "vendor"}
+        exts = {".go", ".py", ".ts", ".js", ".rs", ".java", ".rb", ".proto"}
+        pat = re.compile(re.escape(field), re.IGNORECASE)
+        for p in target.rglob("*"):
+            if len(out) >= 50:
+                break
+            if not p.is_file() or p.suffix not in exts:
+                continue
+            if any(part in skip for part in p.parts):
+                continue
+            try:
+                for ln in p.read_text(encoding="utf-8", errors="replace").splitlines():
+                    if pat.search(ln):
+                        out.append(f"{p.name}: {ln.strip()[:160]}")
+                        if len(out) >= 50:
+                            break
+            except OSError:
+                continue
+        return out

scrufflehog/cli.py

@@ -0,0 +1,82 @@
+"""scrufflehog CLI — verify a target's redactors against a config."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .config import load_config
+from .engine import run
+from .output import FORMATTERS
+
+
+def _load_advisor(name: str):
+    if name == "none":
+        from .advisor import NoopAdvisor
+        return NoopAdvisor()
+    if name == "llm":
+        from .advisors.llm import LLMAdvisor
+        complete = _resolve_completion_backend()
+        if complete is None:
+            print("--advisor llm needs a completion backend. Set SCRUFFLEHOG_LLM "
+                  "to a 'module:function' path resolving to a complete(prompt)->str "
+                  "callable (e.g. your Anthropic/OpenAI/Bedrock wrapper).",
+                  file=sys.stderr)
+            raise SystemExit(2)
+        return LLMAdvisor(complete)
+    raise SystemExit(f"unknown advisor: {name!r}")
+
+
+def _resolve_completion_backend():
+    """Resolve a `complete(prompt)->str` callable from SCRUFFLEHOG_LLM=
+    'package.module:function'. Provider-agnostic — the user points it at their
+    own model wrapper, so scrufflehog needs no SDK dependency."""
+    import importlib
+    import os
+    spec = os.environ.get("SCRUFFLEHOG_LLM")
+    if not spec or ":" not in spec:
+        return None
+    mod_name, fn_name = spec.split(":", 1)
+    try:
+        mod = importlib.import_module(mod_name)
+        return getattr(mod, fn_name)
+    except (ImportError, AttributeError) as e:
+        print(f"could not load SCRUFFLEHOG_LLM={spec!r}: {e}", file=sys.stderr)
+        return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="scrufflehog",
+        description="Deterministically verify that your redactors actually redact.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    v = sub.add_parser("verify", help="verify redactors declared in a config")
+    v.add_argument("--config", required=True, type=Path)
+    v.add_argument("--target", required=True, type=Path,
+                   help="repo checkout the config's module paths are relative to")
+    v.add_argument("--format", choices=sorted(FORMATTERS), default="text")
+    v.add_argument("--advisor", choices=["none", "llm"], default="none",
+                   help="optional agentic assist (proposes probes / confirms "
+                        "coverage gaps); verdicts stay deterministic")
+    v.add_argument("--fail-on-defect", action="store_true",
+                   help="exit non-zero if any defect is found (for CI gating)")
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "verify":
+        if not args.target.is_dir():
+            print(f"target not a directory: {args.target}", file=sys.stderr)
+            return 2
+        config = load_config(args.config)
+        advisor = _load_advisor(args.advisor)
+        result = run(args.target, config, advisor)
+        print(FORMATTERS[args.format](result, str(args.target)))
+        if args.fail_on_defect and result.defects:
+            return 1
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scrufflehog/config.py

@@ -0,0 +1,55 @@
+"""Load a scrufflehog config — the externalised redactor registry.
+
+TOML shape (see examples/):
+
+    [[transform]]
+    lang = "python"          # python | go | rust | node
+    module = "app/redact.py"
+    fn = "redact"
+    kind = "value"           # value | row | tree
+    probe_set = "value"      # value | url_apikey
+    # go extras:  import = "...", wrap = "error"
+    # rust extras: call = "mycrate::redact(&line)"
+    # node extras: export = "default"
+
+    [[coverage]]
+    module = "app/redact.py"
+    symbol = "SECRET_KEYS"
+    extract = "py_collection"   # go_map_keys | py_collection | ts_redact_paths | rust_str_set
+    match = "exact_ci"          # exact_ci | substring_ci | field_substring_ci
+    doc_claims_substring = false
+    # corpus = ["ssn", "cvv", ...]   # optional; defaults to the built-in list
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+try:
+    import tomllib  # py3.11+
+except ModuleNotFoundError:  # pragma: no cover
+    import tomli as tomllib  # type: ignore
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise FileNotFoundError(f"config not found: {path}")
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+    config = {"transform": data.get("transform", []),
+              "coverage": data.get("coverage", [])}
+    _validate(config)
+    return config
+
+
+def _validate(config: dict[str, Any]) -> None:
+    for e in config["transform"]:
+        for req in ("lang", "module"):
+            if req not in e:
+                raise ValueError(f"transform entry missing {req!r}: {e}")
+        if e["lang"] != "rust" and "fn" not in e and e.get("export") != "default":
+            raise ValueError(f"transform entry needs 'fn' (or export='default'): {e}")
+    for s in config["coverage"]:
+        for req in ("module", "symbol", "extract"):
+            if req not in s:
+                raise ValueError(f"coverage entry missing {req!r}: {s}")

scrufflehog/coverage/__init__.py

@@ -0,0 +1,4 @@
+from .extract import extract_key_set, DEFAULT_SENSITIVE_FIELDS
+from .semantics import covered
+
+__all__ = ["extract_key_set", "covered", "DEFAULT_SENSITIVE_FIELDS"]

scrufflehog/coverage/extract.py

@@ -0,0 +1,104 @@
+"""Static extraction of a redactor's field-name denylist / allow-list.
+
+A field-name list is DATA, not behaviour — so we can extract it from source and
+check coverage WITHOUT executing the target's language. This is what makes
+coverage mode language-agnostic.
+
+Extractors:
+  go_map_keys     — keys of `var X = map[string]struct{}{ "k": {}, ... }`
+  py_collection   — string entries of a Python list/tuple/set literal
+  ts_redact_paths — leaf field names from a path allow-list
+                    (e.g. redact.req('body.email') -> email;
+                     body.message[*].phone_number -> phone_number)
+  rust_str_set    — string literals in a Rust slice/array/HashSet-from literal
+
+Fails LOUD on an empty extraction: an empty set from source that plainly has
+entries means the extractor missed the literal, and silently returning it would
+false-positive "everything is missed" on a good list. A genuinely empty list is
+reportable, but must be proven, not inferred from a parse miss.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+# A generic, public-knowledge corpus of field names a PII/secret redactor is
+# reasonably expected to cover. Users can override per-target in config.
+DEFAULT_SENSITIVE_FIELDS = [
+    "ssn", "social_security_number", "cvv", "cvc", "card_number", "pan",
+    "iban", "swift", "routing_number", "account_number", "phone_number",
+    "phone", "mobile", "passport", "passport_number", "drivers_license",
+    "dob", "date_of_birth", "email", "email_address", "password", "secret",
+    "token", "api_key", "apikey", "authorization", "pin", "security_code",
+    "credit_card", "bank_account", "tax_id",
+]
+
+_GO_MAP_KEY_RE = re.compile(r'"([^"\\]+)"\s*:\s*\{\}')
+_STR_RE = re.compile(r'"([^"\\]+)"|\'([^\'\\]+)\'')
+
+
+def _scoped_block(src: str, symbol: str, extract: str) -> str:
+    """Return the literal block belonging to `symbol`, brace/bracket-balanced.
+    Anchors on a declaration (`symbol =` / `symbol:` / map decl), not a comment
+    mention. Handles Go's `map[string]struct{}{` (first `{` is struct{}'s body)."""
+    m = re.search(rf'\b{re.escape(symbol)}\b\s*(?:=|:?=|:|\bmap\b|\[\])', src)
+    idx = m.start() if m else src.find(symbol)
+    if idx == -1:
+        raise ValueError(f"symbol {symbol!r} not found")
+
+    if extract == "go_map_keys":
+        open_re = re.search(r'\}\s*\{', src[idx:])
+        if not open_re:
+            raise ValueError(f"could not locate map literal opening for {symbol!r}")
+        brace = idx + open_re.end() - 1
+    else:
+        candidates = [p for p in (src.find("{", idx), src.find("[", idx),
+                                   src.find("(", idx)) if p != -1]
+        if not candidates:
+            raise ValueError(f"no literal block after {symbol!r}")
+        brace = min(candidates)
+
+    opener = src[brace]
+    closer = {"{": "}", "[": "]", "(": ")"}[opener]
+    depth, end = 0, brace
+    for i in range(brace, len(src)):
+        if src[i] == opener:
+            depth += 1
+        elif src[i] == closer:
+            depth -= 1
+            if depth == 0:
+                end = i
+                break
+    return src[brace:end + 1]
+
+
+def extract_key_set(target: Path, spec: dict[str, Any]) -> set[str]:
+    path = target / spec["module"]
+    if not path.exists():
+        raise FileNotFoundError(f"coverage module not found: {spec['module']}")
+    src = path.read_text(encoding="utf-8", errors="replace")
+    extract = spec["extract"]
+    block = _scoped_block(src, spec["symbol"], extract)
+
+    if extract == "go_map_keys":
+        keys = {m.lower() for m in _GO_MAP_KEY_RE.findall(block)}
+    elif extract in ("py_collection", "rust_str_set"):
+        keys = {(a or b).lower() for a, b in _STR_RE.findall(block)}
+    elif extract == "ts_redact_paths":
+        keys = set()
+        for a, b in _STR_RE.findall(block):
+            raw = a or b
+            leaf = re.sub(r'\[[^\]]*\]', '', raw).rstrip('.').split('.')[-1]
+            leaf = leaf.strip().strip('"\'')
+            if leaf:
+                keys.add(leaf.lower())
+    else:
+        raise ValueError(f"unknown extract kind: {extract!r}")
+
+    if not keys:
+        raise ValueError(
+            f"extracted 0 keys from {spec['symbol']!r} in {spec['module']} — "
+            f"the extractor likely failed to locate the literal (fail-loud: "
+            f"refusing to report a false 'everything missed').")
+    return keys

scrufflehog/coverage/semantics.py

@@ -0,0 +1,19 @@
+"""Match semantics — how a redactor decides whether a field name is covered.
+
+Mirrors the target redactor's own matching so the coverage verdict reflects what
+the redactor actually does, not what we assume.
+"""
+from __future__ import annotations
+
+
+def covered(field_name: str, keys: set[str], match: str) -> bool:
+    f = field_name.lower()
+    if match == "exact_ci":
+        return f in keys
+    if match == "substring_ci":
+        # redactor redacts a field if ANY key is a substring of the field name
+        return any(k in f for k in keys)
+    if match == "field_substring_ci":
+        # inverse: redactor redacts if the field name is a substring of any key
+        return any(f in k for k in keys)
+    raise ValueError(f"unknown match semantics: {match!r}")

scrufflehog/engine.py

@@ -0,0 +1,134 @@
+"""Engine — ties runners + coverage + oracles into a verification run.
+
+Two families:
+  transform-strength — execute each registered redactor on its probe set,
+                       apply the oracles to the output.
+  coverage           — statically extract each denylist/allow-list and check a
+                       sensitive-field corpus against it.
+
+The advisor (default no-op) may add probes, discover redactors, or confirm
+coverage gaps — but the deterministic oracle renders every verdict.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .advisor import Advisor, CoverageVerdict, NoopAdvisor
+from .coverage import covered, extract_key_set, DEFAULT_SENSITIVE_FIELDS
+from .oracles import (COVERAGE_GAP, REDACTOR_ERRORED, Defect, assert_output)
+from .probes import Probe, get_probe_set
+from .runners import make_producer
+
+
+@dataclass
+class RunResult:
+    defects: list[Defect] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+
+def _transform_probes(target: Path, entry: dict, advisor: Advisor) -> list[Probe]:
+    probes = get_probe_set(entry.get("probe_set", "value"))
+    # Advisor may ADD domain-matched probes; deterministic set always included.
+    src = ""
+    mod = entry.get("module")
+    if mod and (target / mod).exists():
+        try:
+            src = (target / mod).read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            src = ""
+    try:
+        probes = probes + advisor.propose_probes(src, entry)
+    except Exception:  # noqa: BLE001 — advisor failure degrades to deterministic
+        pass
+    return probes
+
+
+def verify_transform(target: Path, entry: dict, advisor: Advisor) -> tuple[list[Defect], str]:
+    lang = entry.get("lang", "python")
+    label = f"{entry.get('module', '?')}:{entry.get('fn', '?')}"
+    kind = entry.get("kind", "value")
+    try:
+        produce = make_producer(target, entry)
+    except (FileNotFoundError, AttributeError, RuntimeError, ValueError, ImportError) as e:
+        return ([Defect(label, REDACTOR_ERRORED, "-",
+                        f"[{lang}] could not prepare redactor: {e}")],
+                f"[transform:{lang}] {label}: unprepared")
+    probes = _transform_probes(target, entry, advisor)
+    defects: list[Defect] = []
+    try:
+        for p in probes:
+            try:
+                out = produce(p)
+            except Exception as exc:  # noqa: BLE001 — a crashing redactor IS a defect
+                defects.append(Defect(label, REDACTOR_ERRORED, p.name,
+                                      f"redactor raised {type(exc).__name__}: {exc}"))
+                continue
+            d = assert_output(out, p, label, kind)
+            if d is not None:
+                defects.append(d)
+    finally:
+        cleanup = getattr(produce, "_cleanup", None)
+        if callable(cleanup):
+            cleanup()
+    return defects, f"[transform:{lang}] {label}: {len(defects)} defect(s)"
+
+
+def verify_coverage(target: Path, spec: dict, advisor: Advisor) -> tuple[list[Defect], str]:
+    label = f"{spec['module']}:{spec['symbol']}"
+    try:
+        keys = extract_key_set(target, spec)
+    except (FileNotFoundError, ValueError) as e:
+        return ([Defect(label, REDACTOR_ERRORED, "-",
+                        f"coverage target did not resolve: {e}")],
+                f"[coverage] {label}: unresolved")
+    match = spec.get("match", "exact_ci")
+    corpus = spec.get("corpus", DEFAULT_SENSITIVE_FIELDS)
+    defects: list[Defect] = []
+    for f in corpus:
+        if covered(f, keys, match):
+            continue
+        # Advisor may confirm/refute the hypothesis; default leaves it standing.
+        try:
+            verdict = advisor.confirm_coverage_gap(target, f, label)
+        except Exception:  # noqa: BLE001
+            verdict = CoverageVerdict.UNCONFIRMED
+        if verdict == CoverageVerdict.REFUTED:
+            continue
+        suffix = "" if verdict == CoverageVerdict.UNCONFIRMED else f" [{verdict}]"
+        defects.append(Defect(
+            label, COVERAGE_GAP, f,
+            f"sensitive field {f!r} not caught by the {len(keys)}-key list "
+            f"under {match} matching — it is not redacted{suffix}"))
+    if spec.get("doc_claims_substring") and match == "exact_ci" and defects:
+        defects.append(Defect(
+            label, COVERAGE_GAP, "<doc-mismatch>",
+            "redactor docs claim partial/substring matching but the behaviour is "
+            "exact — fields expected to be covered by substring are NOT"))
+    return defects, f"[coverage] {label}: {len(defects)} gap(s)"
+
+
+def run(target: Path, config: dict[str, Any], advisor: Advisor | None = None) -> RunResult:
+    """Run all transform + coverage checks in `config` against `target`.
+
+    config = {"transform": [entry, ...], "coverage": [spec, ...]}
+    """
+    advisor = advisor or NoopAdvisor()
+    result = RunResult()
+
+    transform = config.get("transform", [])
+    coverage = config.get("coverage", [])
+    if not transform and not coverage:
+        result.notes.append("no redactors configured — nothing to verify")
+        return result
+
+    for entry in transform:
+        defects, note = verify_transform(target, entry, advisor)
+        result.defects.extend(defects)
+        result.notes.append(note)
+    for spec in coverage:
+        defects, note = verify_coverage(target, spec, advisor)
+        result.defects.extend(defects)
+        result.notes.append(note)
+    return result