leftblock 0.3.3__tar.gz → 0.3.4__tar.gz

{leftblock-0.3.3 → leftblock-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: leftblock
-Version: 0.3.3
+Version: 0.3.4
 Summary: LeftBlock: a pluggable inspection gate for Git commits
 License: MIT License
         
@@ -55,7 +55,7 @@ flowchart LR
     style Check fill:#e5f3ff,stroke:#175cd3
 ```
 
-Local check-only mode installs a Git **`pre-commit` hook**. Receipt mode installs a **`commit-msg` hook**, which runs later but still before Git creates the commit object. The local hook never offers an override or adds a receipt. The default Gitleaks command scans the staged diff, not every working-tree file or all existing history. Staging may already write blobs to the local object database, so blocking a commit does not erase every local copy.
+Local check-only mode installs a Git **`pre-commit` hook**. Receipt mode installs a **`commit-msg` hook**, which runs later but still before Git creates the commit object. The local hook offers no interactive override and adds no receipt; a false alarm can be handled only by a recorded, reasoned override that is committed and reviewable (see [Overriding a false alarm](#overriding-a-false-alarm)). The default Gitleaks command scans the staged diff, not every working-tree file or all existing history. Staging may already write blobs to the local object database, so blocking a commit does not erase every local copy.
 
 This is a layered defense, not a guarantee that a repository contains no sensitive information. Scanners can miss formats or context, allowlists and configuration affect coverage, and hooks can be bypassed with `--no-verify` or disabled. In receipt mode, interactive approval can intentionally override findings. Missing scanners, invalid configuration, or other checker errors block the commit without an override. Use review, narrowly scoped exceptions, and independent checks before pushing or deploying as additional layers.
 
@@ -124,7 +124,7 @@ configures the integration; it does not install scanner binaries.
 In the intended Python environment:
 
 ```bash
-python -m pip install leftblock==0.3.3
+python -m pip install leftblock==0.3.4
 python -m leftblock.cli --help
 ```
 
@@ -162,11 +162,59 @@ leftblock check --config /absolute/path/to/policy.yml
 
 Use the actual policy path for the repository. The command returns a
 nonzero status for findings, unavailable scanners, or an invalid setup;
-it never offers an override. Before adopting a hook in another project,
+it offers no interactive override, only the recorded override described
+below. Before adopting a hook in another project,
 verify that a synthetic sensitive fixture is blocked and a clean fixture
 passes in a throwaway repository. Keep private policy files in local Git
 metadata or another private location.
 
+### Overriding a false alarm
+
+A block stays the default. If a finding is a false alarm (for example a
+public role address in a privacy notice), record a reviewed override. The
+blocked check prints an `id` for each finding, never the matched value, and
+the exact command to run:
+
+```bash
+leftblock allow ID [ID ...] --reason "Why this is not sensitive"
+```
+
+`allow` re-runs the checks on the staged changes, appends one entry per id
+to `.leftblock-allow.yml` at the repository root, and stages that file. It
+never commits. The reason is required and must be at least 10 characters.
+An entry looks like:
+
+```yaml
+version: 1
+allow:
+  - id: "3f2a9c1e7b4d5a60"
+    rule: "leftblock-personal-email"
+    file: "apps/web/privacy/page.tsx"
+    reason: "Public role address required in the privacy notice."
+    added: 2026-10-20
+```
+
+- **Scoped to line content.** The id hashes the rule, the file, and the exact
+  staged content of the flagged lines. Editing that line, or adding another
+  finding anywhere, blocks again.
+- **Staged to count.** Only the version of `.leftblock-allow.yml` in the Git
+  index is read, so the override is always part of the commit and its review.
+  A file that is only in the working tree has no effect.
+- **Visible every time.** Each run prints the file, rule, id, and reason of
+  every applied override.
+- **Fail closed.** Invalid YAML, an unsupported version, an entry missing
+  `id`, `rule`, or `file`, or a reason under 10 characters blocks the commit.
+  Scanner errors are never overridden, and a finding with no id (its lines
+  could not be read) must be removed instead.
+- **Configuration.** Without `--config`, `allow` uses the local install's
+  policy when present, otherwise `.leftblock.yml`; pass the same `--config`
+  you use for `check` if it differs.
+
+This mechanism is separate from Gitleaks' own suppressions: inline
+`gitleaks:allow` markers and a root `.gitleaksignore` are still honoured by
+Gitleaks itself, and they are outside this mechanism's reason, scope, and
+review trail.
+
 During an in-progress merge, command checkers skip only regular files whose
 complete blob and mode already exist at the same path in a parent. Changed
 resolutions and renamed destinations retain their full staged diff, so

{leftblock-0.3.3 → leftblock-0.3.4}/README.md

@@ -22,7 +22,7 @@ flowchart LR
     style Check fill:#e5f3ff,stroke:#175cd3
 ```
 
-Local check-only mode installs a Git **`pre-commit` hook**. Receipt mode installs a **`commit-msg` hook**, which runs later but still before Git creates the commit object. The local hook never offers an override or adds a receipt. The default Gitleaks command scans the staged diff, not every working-tree file or all existing history. Staging may already write blobs to the local object database, so blocking a commit does not erase every local copy.
+Local check-only mode installs a Git **`pre-commit` hook**. Receipt mode installs a **`commit-msg` hook**, which runs later but still before Git creates the commit object. The local hook offers no interactive override and adds no receipt; a false alarm can be handled only by a recorded, reasoned override that is committed and reviewable (see [Overriding a false alarm](#overriding-a-false-alarm)). The default Gitleaks command scans the staged diff, not every working-tree file or all existing history. Staging may already write blobs to the local object database, so blocking a commit does not erase every local copy.
 
 This is a layered defense, not a guarantee that a repository contains no sensitive information. Scanners can miss formats or context, allowlists and configuration affect coverage, and hooks can be bypassed with `--no-verify` or disabled. In receipt mode, interactive approval can intentionally override findings. Missing scanners, invalid configuration, or other checker errors block the commit without an override. Use review, narrowly scoped exceptions, and independent checks before pushing or deploying as additional layers.
 
@@ -91,7 +91,7 @@ configures the integration; it does not install scanner binaries.
 In the intended Python environment:
 
 ```bash
-python -m pip install leftblock==0.3.3
+python -m pip install leftblock==0.3.4
 python -m leftblock.cli --help
 ```
 
@@ -129,11 +129,59 @@ leftblock check --config /absolute/path/to/policy.yml
 
 Use the actual policy path for the repository. The command returns a
 nonzero status for findings, unavailable scanners, or an invalid setup;
-it never offers an override. Before adopting a hook in another project,
+it offers no interactive override, only the recorded override described
+below. Before adopting a hook in another project,
 verify that a synthetic sensitive fixture is blocked and a clean fixture
 passes in a throwaway repository. Keep private policy files in local Git
 metadata or another private location.
 
+### Overriding a false alarm
+
+A block stays the default. If a finding is a false alarm (for example a
+public role address in a privacy notice), record a reviewed override. The
+blocked check prints an `id` for each finding, never the matched value, and
+the exact command to run:
+
+```bash
+leftblock allow ID [ID ...] --reason "Why this is not sensitive"
+```
+
+`allow` re-runs the checks on the staged changes, appends one entry per id
+to `.leftblock-allow.yml` at the repository root, and stages that file. It
+never commits. The reason is required and must be at least 10 characters.
+An entry looks like:
+
+```yaml
+version: 1
+allow:
+  - id: "3f2a9c1e7b4d5a60"
+    rule: "leftblock-personal-email"
+    file: "apps/web/privacy/page.tsx"
+    reason: "Public role address required in the privacy notice."
+    added: 2026-10-20
+```
+
+- **Scoped to line content.** The id hashes the rule, the file, and the exact
+  staged content of the flagged lines. Editing that line, or adding another
+  finding anywhere, blocks again.
+- **Staged to count.** Only the version of `.leftblock-allow.yml` in the Git
+  index is read, so the override is always part of the commit and its review.
+  A file that is only in the working tree has no effect.
+- **Visible every time.** Each run prints the file, rule, id, and reason of
+  every applied override.
+- **Fail closed.** Invalid YAML, an unsupported version, an entry missing
+  `id`, `rule`, or `file`, or a reason under 10 characters blocks the commit.
+  Scanner errors are never overridden, and a finding with no id (its lines
+  could not be read) must be removed instead.
+- **Configuration.** Without `--config`, `allow` uses the local install's
+  policy when present, otherwise `.leftblock.yml`; pass the same `--config`
+  you use for `check` if it differs.
+
+This mechanism is separate from Gitleaks' own suppressions: inline
+`gitleaks:allow` markers and a root `.gitleaksignore` are still honoured by
+Gitleaks itself, and they are outside this mechanism's reason, scope, and
+review trail.
+
 During an in-progress merge, command checkers skip only regular files whose
 complete blob and mode already exist at the same path in a parent. Changed
 resolutions and renamed destinations retain their full staged diff, so

leftblock-0.3.4/leftblock/allow.py

@@ -0,0 +1,210 @@
+"""Recorded, per-finding overrides kept in a committed .leftblock-allow.yml.
+
+An override approves one finding: one rule on one exact line content in one
+file. The id is a hash of that triple, so changing the line re-blocks it. The
+allow file is read from the Git index, so only a staged override counts and it
+always appears in the commit and its review.
+"""
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+from datetime import datetime, timezone
+
+import yaml
+
+ALLOW_FILE = ".leftblock-allow.yml"
+MIN_REASON = 10
+ALLOW_HEADER = (
+    "# LeftBlock overrides: each entry approves one finding (one rule on one exact\n"
+    "# line content in one file). Changing that line re-blocks it.\n"
+)
+
+
+class AllowError(Exception):
+    pass
+
+
+def _git_bytes(repo_root, *args):
+    return subprocess.run(
+        ["git", *args], cwd=repo_root, capture_output=True, check=False,
+        stdin=subprocess.DEVNULL,
+    )
+
+
+def finding_id(repo_root, rule, file, start, end):
+    """Hash of rule, file and the staged line content, or None if unreadable."""
+    if not isinstance(rule, str) or not isinstance(file, str):
+        return None
+    if type(start) is not int or type(end) is not int or start < 1 or end < start:
+        return None
+    proc = _git_bytes(repo_root, "show", ":" + file)
+    if proc.returncode:
+        return None
+    lines = proc.stdout.decode("utf-8", errors="replace").split("\n")
+    if end > len(lines):
+        return None
+    content = "\n".join(lines[start - 1:end])
+    digest = hashlib.sha256(f"{rule}\0{file}\0{content}".encode("utf-8"))
+    return digest.hexdigest()[:16]
+
+
+def attach_ids(repo_root, results):
+    """Replace StartLine/EndLine on findings with an id (when computable)."""
+    for result in results:
+        if result.error or not isinstance(result.findings, list):
+            continue
+        for finding in result.findings:
+            start, end = finding.pop("StartLine", None), finding.pop("EndLine", None)
+            if finding.get("File") == ALLOW_FILE:
+                continue  # the allow file can never approve itself
+            ident = finding_id(
+                repo_root, finding.get("RuleID"), finding.get("File"), start, end,
+            )
+            if ident:
+                finding["id"] = ident
+
+
+def parse_allowlist(text):
+    """Return entries from allow-file text; raise AllowError if invalid."""
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError:
+        raise AllowError("invalid YAML")
+    if not isinstance(data, dict) or data.get("version") != 1 or type(data.get("version")) is not int:
+        raise AllowError("unsupported version")
+    entries = data.get("allow")
+    if entries is None:
+        entries = []
+    if not isinstance(entries, list):
+        raise AllowError("allow must be a list")
+    for entry in entries:
+        if not isinstance(entry, dict):
+            raise AllowError("invalid entry")
+        for key in ("id", "rule", "file"):
+            if not isinstance(entry.get(key), str) or not entry[key].strip():
+                raise AllowError("entry missing " + key)
+        if not isinstance(entry.get("reason"), str) or len(entry["reason"].strip()) < MIN_REASON:
+            raise AllowError("entry reason too short")
+    return entries
+
+
+def load_allowlist(repo_root):
+    """Entries from the staged allow file; [] when it is not in the index."""
+    staged = _git_bytes(repo_root, "ls-files", "--stage", "--", ALLOW_FILE)
+    if staged.returncode:
+        raise AllowError("cannot read index")
+    if not staged.stdout.strip():
+        return []
+    proc = _git_bytes(repo_root, "show", ":" + ALLOW_FILE)
+    if proc.returncode:
+        raise AllowError("cannot read staged file")
+    try:
+        return parse_allowlist(proc.stdout.decode("utf-8"))
+    except UnicodeDecodeError:
+        raise AllowError("not UTF-8")
+
+
+def apply_allowlist(results, entries):
+    """Move allowed findings out of the results; return [(finding, reason)]."""
+    index = {
+        (e["id"], e["rule"], e["file"]): " ".join(e["reason"].split()) for e in entries
+    }
+    allowed = []
+    for result in results:
+        if result.error or result.clean or not isinstance(result.findings, list):
+            continue
+        remaining = []
+        for finding in result.findings:
+            key = (finding.get("id"), finding.get("RuleID"), finding.get("File"))
+            if key[0] and key in index:
+                allowed.append((finding, index[key]))
+            else:
+                remaining.append(finding)
+        if remaining:
+            result.findings = remaining
+        else:
+            result.clean, result.findings = True, None
+    return allowed
+
+
+def _quote(value):
+    # JSON strings are valid YAML double-quoted scalars.
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _render(entries):
+    out = [ALLOW_HEADER + "version: 1\n"]
+    if not entries:
+        return out[0] + "allow: []\n"
+    out.append("allow:\n")
+    for e in entries:
+        added = str(e.get("added", ""))
+        out.append(f"  - id: {_quote(e['id'])}\n")
+        out.append(f"    rule: {_quote(e['rule'])}\n")
+        out.append(f"    file: {_quote(e['file'])}\n")
+        out.append(f"    reason: {_quote(' '.join(e['reason'].split()))}\n")
+        if added:
+            plain = re.fullmatch(r"\d{4}-\d{2}-\d{2}", added)
+            out.append("    added: " + (added if plain else _quote(added)) + "\n")
+    return "".join(out)
+
+
+def record_overrides(repo_root, findings, reason):
+    """Append entries for findings (dicts with id/RuleID/File) to the allow file.
+
+    Returns the findings newly recorded. The working-tree file must be valid.
+    """
+    path = os.path.join(repo_root, ALLOW_FILE)
+    entries = []
+    if os.path.exists(path):
+        with open(path, "r", encoding="utf-8") as f:
+            entries = parse_allowlist(f.read())
+    known = {e["id"] for e in entries}
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    added = []
+    for finding in findings:
+        if finding["id"] in known:
+            continue
+        known.add(finding["id"])
+        entries.append({
+            "id": finding["id"], "rule": finding["RuleID"], "file": finding["File"],
+            "reason": reason, "added": today,
+        })
+        added.append(finding)
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(_render(entries))
+    return added
+
+
+def snapshot(repo_root):
+    """Working-tree bytes (or None) and the index entry (or None) of the file."""
+    path = os.path.join(repo_root, ALLOW_FILE)
+    content = None
+    if os.path.exists(path):
+        with open(path, "rb") as f:
+            content = f.read()
+    staged = _git_bytes(repo_root, "ls-files", "--stage", "--", ALLOW_FILE)
+    entry = None
+    if staged.returncode == 0 and staged.stdout.strip():
+        meta = staged.stdout.decode().split("\t")[0].split()
+        entry = (meta[0], meta[1])
+    return content, entry
+
+
+def restore(repo_root, snap):
+    """Put the allow file and its index entry back exactly as snapshotted."""
+    content, entry = snap
+    path = os.path.join(repo_root, ALLOW_FILE)
+    if content is None:
+        if os.path.exists(path):
+            os.remove(path)
+    else:
+        with open(path, "wb") as f:
+            f.write(content)
+    if entry is None:
+        _git_bytes(repo_root, "rm", "--cached", "-q", "--ignore-unmatch", "--", ALLOW_FILE)
+    else:
+        _git_bytes(repo_root, "update-index", "--add", "--cacheinfo", f"{entry[0]},{entry[1]},{ALLOW_FILE}")

{leftblock-0.3.3 → leftblock-0.3.4}/leftblock/cli.py

@@ -4,25 +4,33 @@ import os
 import json
 import subprocess
 import getpass
+import shlex
 import yaml
 from datetime import datetime, timezone
 from leftblock.merge import (
     MergeScopeError, build_scoped_index, checker_environment, index_entries, merge_state,
 )
+from leftblock import allow as allowlist
 from leftblock.core import (
     get_secret, compute_hmac, get_tree_hash, get_commit_tree_hash,
     load_config, validate_checkers, execute_checkers, get_trailer, run_cmd, SECRET_FILE_DEFAULT,
     CheckerResult,
 )
 
+def _label(text, color):
+    # Plain labels when output is captured (git GUIs, wrappers, CI) or NO_COLOR is set.
+    if os.environ.get("NO_COLOR") or not sys.stderr.isatty():
+        return text
+    return f"\033[{color}m{text}\033[0m"
+
 def print_info(msg):
-    print(f"\033[1;34m[leftblock]\033[0m {msg}", file=sys.stderr)
+    print(f"{_label('[leftblock]', '1;34')} {msg}", file=sys.stderr)
 
 def print_warn(msg):
-    print(f"\033[1;33m[leftblock]\033[0m {msg}", file=sys.stderr)
+    print(f"{_label('[leftblock]', '1;33')} {msg}", file=sys.stderr)
 
 def print_err(msg):
-    print(f"\033[1;31m[leftblock ERROR]\033[0m {msg}", file=sys.stderr)
+    print(f"{_label('[leftblock ERROR]', '1;31')} {msg}", file=sys.stderr)
 
 DEFAULT_LEFTBLOCK_YML = """\
 version: 1
@@ -110,7 +118,36 @@ def cmd_install(args):
     else:
         print_info(f"Shared secret already exists at {SECRET_FILE_DEFAULT}")
 
-def configured_checks(repo_root, config_path=None):
+def configured_checks(repo_root, config_path=None, overrides=True):
+    """Run the checkers, attach override ids and apply staged overrides."""
+    config, results = _run_configured_checks(repo_root, config_path)
+    allowlist.attach_ids(repo_root, results)
+    if not overrides:
+        return config, results
+    try:
+        entries = allowlist.load_allowlist(repo_root)
+    except allowlist.AllowError:
+        results.append(CheckerResult(
+            "leftblock-allow", False,
+            "Invalid .leftblock-allow.yml; inspection blocked.", error=True,
+        ))
+        return config, results
+    shown = set()
+    for finding, reason in allowlist.apply_allowlist(results, entries):
+        # Several matches on one line share an id; report each override once.
+        if finding["id"] in shown:
+            continue
+        shown.add(finding["id"])
+        print_info(
+            "Override applied: file " + json.dumps(finding["File"], ensure_ascii=True)
+            + ", rule " + json.dumps(finding["RuleID"], ensure_ascii=True)
+            + ", id " + finding["id"]
+            + ", reason " + json.dumps(reason, ensure_ascii=True)
+        )
+    return config, results
+
+
+def _run_configured_checks(repo_root, config_path=None):
     try:
         config = load_config(repo_root, config_path)
         checkers = validate_checkers(config)
@@ -166,6 +203,121 @@ def print_failures(failures):
             print_warn(str(result.findings))
 
 
+def default_local_policy(repo_root):
+    """The local check-only policy file when one is installed, else None."""
+    proc = run_cmd(
+        ["git", "rev-parse", "--path-format=absolute", "--git-common-dir"],
+        check=False, cwd=repo_root,
+    )
+    if proc.returncode or not proc.stdout.strip():
+        return None
+    path = os.path.join(proc.stdout.strip(), "leftblock", "policy.json")
+    return path if os.path.isfile(path) else None
+
+
+def finding_summary(findings):
+    """One-line list of rule, file and id, for callers that show only the last line."""
+    parts = []
+    for f in findings:
+        part = f"{f.get('RuleID', 'finding')} in {f.get('File', 'unknown file')}"
+        if f.get("id"):
+            part += f" [id {f['id']}]"
+        if part not in parts:
+            parts.append(part)
+    return "; ".join(parts)
+
+
+def print_override_instructions(failures, repo_root, config_path):
+    # Tools that drive `git commit` often surface only the final line, so the
+    # last ERROR line names every finding and the next step on its own.
+    findings = [
+        f for result in failures if isinstance(result.findings, list) for f in result.findings
+    ]
+    own = [f for f in findings if f.get("File") == allowlist.ALLOW_FILE]
+    findings = [f for f in findings if f.get("File") != allowlist.ALLOW_FILE]
+    ids = [f["id"] for f in findings if f.get("id")]
+    steps = []
+    if own:
+        print_warn(
+            f"A reason in {allowlist.ALLOW_FILE} contains a flagged value; "
+            "reword that reason (don't repeat the value)."
+        )
+        steps.append(f"reword the flagged reason in {allowlist.ALLOW_FILE}")
+    if len(ids) < len(findings):
+        print_warn("Findings without an id cannot be overridden and must be removed.")
+    if findings:
+        steps.append("remove the flagged content")
+    if ids:
+        command = f"{shlex.quote(sys.executable)} -I -B -m leftblock.cli allow {' '.join(dict.fromkeys(ids))}"
+        default = default_local_policy(repo_root) or os.path.join(repo_root, ".leftblock.yml")
+        if config_path and os.path.abspath(config_path) != os.path.abspath(default):
+            command += f" --config {shlex.quote(config_path)}"
+        command += ' --reason "<why this is not sensitive>"'
+        print_info(
+            "An override adds the finding to .leftblock-allow.yml and stages it, so it "
+            "appears in the commit and its review."
+        )
+        steps.append("if it is a false alarm, record a reviewed override: " + command)
+    advice = "; or ".join(steps)
+    print_err(f"Inspection blocked: {finding_summary(own + findings)}. {advice[:1].upper()}{advice[1:]}.")
+
+
+def cmd_allow(args):
+    """Record reviewed overrides for current findings in .leftblock-allow.yml."""
+    reason = " ".join((args.reason or "").split())
+    if len(reason) < allowlist.MIN_REASON:
+        print_err(f"--reason must explain the override (at least {allowlist.MIN_REASON} characters).")
+        sys.exit(1)
+    repo_root = run_cmd(["git", "rev-parse", "--show-toplevel"]).stdout.strip()
+    config_path = args.config or default_local_policy(repo_root)
+    tree_hash = get_tree_hash()
+    _, results = configured_checks(repo_root, config_path, overrides=False)
+    if get_tree_hash() != tree_hash:
+        print_err("Staged tree changed during inspection. Run it again.")
+        sys.exit(1)
+    if any(result.error for result in results):
+        print_err("A checker could not complete. No override recorded.")
+        sys.exit(1)
+    current = {
+        f["id"]: f for result in results if isinstance(result.findings, list)
+        for f in result.findings if f.get("id")
+    }
+    unknown = [i for i in args.ids if i not in current]
+    if unknown:
+        print_err("Not a current finding id: " + ", ".join(json.dumps(i) for i in unknown))
+        sys.exit(1)
+    snapshot = allowlist.snapshot(repo_root)
+    try:
+        added = allowlist.record_overrides(
+            repo_root, [current[i] for i in dict.fromkeys(args.ids)], reason,
+        )
+    except (OSError, allowlist.AllowError):
+        print_err(f"Existing {allowlist.ALLOW_FILE} is unreadable or invalid; fix it first.")
+        sys.exit(1)
+    run_cmd(["git", "add", "--", allowlist.ALLOW_FILE], cwd=repo_root)
+    # A reason that repeats the flagged value would get the allow file flagged.
+    _, after = configured_checks(repo_root, config_path, overrides=False)
+    own = [
+        f for result in after if isinstance(result.findings, list)
+        for f in result.findings if f.get("File") == allowlist.ALLOW_FILE
+    ]
+    if own or any(result.error for result in after):
+        allowlist.restore(repo_root, snapshot)
+        if own:
+            print_err(
+                f"The reason would itself be flagged (rule {own[0].get('RuleID')}). "
+                "Don't repeat the flagged value in the reason; describe it instead."
+            )
+        else:
+            print_err("A checker could not complete. No override recorded.")
+        sys.exit(1)
+    for finding in added:
+        print_info(f"Recorded override {finding['id']} for {finding['RuleID']} in {finding['File']}.")
+    if not added:
+        print_info("Those ids were already recorded.")
+    print_info(f"{allowlist.ALLOW_FILE} is staged; the commit must include it.")
+
+
 def cmd_check(args):
     """Noninteractive staged inspection for existing pre-commit hook managers."""
     repo_root = run_cmd(["git", "rev-parse", "--show-toplevel"]).stdout.strip()
@@ -177,7 +329,13 @@ def cmd_check(args):
     failures = [result for result in results if not result.clean]
     if failures:
         print_failures(failures)
-        print_err("Inspection blocked. No approval override is available for 'check'.")
+        if any(result.error for result in failures) and not any(
+            isinstance(result.findings, list) for result in failures
+        ):
+            problems = "; ".join(f"{result.name}: {result.findings}" for result in failures if result.error)
+            print_err(f"Inspection blocked: {problems} Fix this first; no override is available.")
+        else:
+            print_override_instructions(failures, repo_root, getattr(args, "config", None))
         sys.exit(1)
     print_info("All configured checks passed for staged changes.")
 
@@ -415,9 +573,14 @@ def main():
     install_p.add_argument("--check-only", action="store_true", help="Install a pre-commit check without signing (with --local)")
     install_p.add_argument("--gitleaks", help="Existing Gitleaks executable for a local check-only installation")
 
-    check_p = subparsers.add_parser("check", help="Inspect staged changes without signing or allowing overrides")
+    check_p = subparsers.add_parser("check", help="Inspect staged changes without signing")
     check_p.add_argument("--config", help="Explicit local checker policy; defaults to .leftblock.yml")
 
+    allow_p = subparsers.add_parser("allow", help="Record a reviewed override for current findings")
+    allow_p.add_argument("ids", nargs="+", metavar="ID", help="Finding id(s) shown by the blocked check")
+    allow_p.add_argument("--reason", default=None, help="Why the finding is not sensitive")
+    allow_p.add_argument("--config", help="Checker policy; defaults to the local install policy, else .leftblock.yml")
+
     hook_p = subparsers.add_parser("hook", help="Run checkers (used internally by git hook)")
     hook_p.add_argument("commit_msg_file", help="Path to the commit message file")
 
@@ -433,6 +596,8 @@ def main():
         cmd_install(args)
     elif args.command == "check":
         cmd_check(args)
+    elif args.command == "allow":
+        cmd_allow(args)
     elif args.command == "hook":
         cmd_hook(args)
     elif args.command == "verify":

{leftblock-0.3.3 → leftblock-0.3.4}/leftblock/core.py

@@ -113,10 +113,15 @@ def run_command_checker(checker: Dict[str, Any], cwd: str = None, env: Dict[str,
                     raise ValueError("Invalid report")
                 # Never carry matched values, source lines, descriptions or raw logs
                 # into the UI. Files/rule identifiers are the diagnostic boundary.
-                findings = [
-                    {key: item[key] for key in ("File", "RuleID") if isinstance(item.get(key), str)}
-                    for item in report
-                ]
+                # Line numbers are kept only to derive an override id and are
+                # dropped before display (see leftblock.allow.attach_ids).
+                findings = []
+                for item in report:
+                    finding = {key: item[key] for key in ("File", "RuleID") if isinstance(item.get(key), str)}
+                    for key in ("StartLine", "EndLine"):
+                        if type(item.get(key)) is int:
+                            finding[key] = item[key]
+                    findings.append(finding)
             except (OSError, ValueError, TypeError):
                 return CheckerResult(name, False, "Checker report unavailable or invalid; output suppressed.", error=True)
         return CheckerResult(name, False, findings)

{leftblock-0.3.3 → leftblock-0.3.4}/leftblock.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: leftblock
-Version: 0.3.3
+Version: 0.3.4
 Summary: LeftBlock: a pluggable inspection gate for Git commits
 License: MIT License
         
@@ -55,7 +55,7 @@ flowchart LR
     style Check fill:#e5f3ff,stroke:#175cd3
 ```
 
-Local check-only mode installs a Git **`pre-commit` hook**. Receipt mode installs a **`commit-msg` hook**, which runs later but still before Git creates the commit object. The local hook never offers an override or adds a receipt. The default Gitleaks command scans the staged diff, not every working-tree file or all existing history. Staging may already write blobs to the local object database, so blocking a commit does not erase every local copy.
+Local check-only mode installs a Git **`pre-commit` hook**. Receipt mode installs a **`commit-msg` hook**, which runs later but still before Git creates the commit object. The local hook offers no interactive override and adds no receipt; a false alarm can be handled only by a recorded, reasoned override that is committed and reviewable (see [Overriding a false alarm](#overriding-a-false-alarm)). The default Gitleaks command scans the staged diff, not every working-tree file or all existing history. Staging may already write blobs to the local object database, so blocking a commit does not erase every local copy.
 
 This is a layered defense, not a guarantee that a repository contains no sensitive information. Scanners can miss formats or context, allowlists and configuration affect coverage, and hooks can be bypassed with `--no-verify` or disabled. In receipt mode, interactive approval can intentionally override findings. Missing scanners, invalid configuration, or other checker errors block the commit without an override. Use review, narrowly scoped exceptions, and independent checks before pushing or deploying as additional layers.
 
@@ -124,7 +124,7 @@ configures the integration; it does not install scanner binaries.
 In the intended Python environment:
 
 ```bash
-python -m pip install leftblock==0.3.3
+python -m pip install leftblock==0.3.4
 python -m leftblock.cli --help
 ```
 
@@ -162,11 +162,59 @@ leftblock check --config /absolute/path/to/policy.yml
 
 Use the actual policy path for the repository. The command returns a
 nonzero status for findings, unavailable scanners, or an invalid setup;
-it never offers an override. Before adopting a hook in another project,
+it offers no interactive override, only the recorded override described
+below. Before adopting a hook in another project,
 verify that a synthetic sensitive fixture is blocked and a clean fixture
 passes in a throwaway repository. Keep private policy files in local Git
 metadata or another private location.
 
+### Overriding a false alarm
+
+A block stays the default. If a finding is a false alarm (for example a
+public role address in a privacy notice), record a reviewed override. The
+blocked check prints an `id` for each finding, never the matched value, and
+the exact command to run:
+
+```bash
+leftblock allow ID [ID ...] --reason "Why this is not sensitive"
+```
+
+`allow` re-runs the checks on the staged changes, appends one entry per id
+to `.leftblock-allow.yml` at the repository root, and stages that file. It
+never commits. The reason is required and must be at least 10 characters.
+An entry looks like:
+
+```yaml
+version: 1
+allow:
+  - id: "3f2a9c1e7b4d5a60"
+    rule: "leftblock-personal-email"
+    file: "apps/web/privacy/page.tsx"
+    reason: "Public role address required in the privacy notice."
+    added: 2026-10-20
+```
+
+- **Scoped to line content.** The id hashes the rule, the file, and the exact
+  staged content of the flagged lines. Editing that line, or adding another
+  finding anywhere, blocks again.
+- **Staged to count.** Only the version of `.leftblock-allow.yml` in the Git
+  index is read, so the override is always part of the commit and its review.
+  A file that is only in the working tree has no effect.
+- **Visible every time.** Each run prints the file, rule, id, and reason of
+  every applied override.
+- **Fail closed.** Invalid YAML, an unsupported version, an entry missing
+  `id`, `rule`, or `file`, or a reason under 10 characters blocks the commit.
+  Scanner errors are never overridden, and a finding with no id (its lines
+  could not be read) must be removed instead.
+- **Configuration.** Without `--config`, `allow` uses the local install's
+  policy when present, otherwise `.leftblock.yml`; pass the same `--config`
+  you use for `check` if it differs.
+
+This mechanism is separate from Gitleaks' own suppressions: inline
+`gitleaks:allow` markers and a root `.gitleaksignore` are still honoured by
+Gitleaks itself, and they are outside this mechanism's reason, scope, and
+review trail.
+
 During an in-progress merge, command checkers skip only regular files whose
 complete blob and mode already exist at the same path in a parent. Changed
 resolutions and renamed destinations retain their full staged diff, so

{leftblock-0.3.3 → leftblock-0.3.4}/leftblock.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 leftblock/__init__.py
+leftblock/allow.py
 leftblock/cli.py
 leftblock/core.py
 leftblock/hooks.py
@@ -19,4 +20,5 @@ tests/test_default_config.py
 tests/test_false_positives.py
 tests/test_install.py
 tests/test_local_install.py
+tests/test_recorded_overrides.py
 tests/test_sensitive_rules.py

{leftblock-0.3.3 → leftblock-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "leftblock"
-version = "0.3.3"
+version = "0.3.4"
 description = "LeftBlock: a pluggable inspection gate for Git commits"
 readme = "README.md"
 license = {file = "LICENSE"}

{leftblock-0.3.3 → leftblock-0.3.4}/tests/test_branding.py

@@ -196,7 +196,7 @@ class DistributionOwnershipTests(unittest.TestCase):
 
     def test_distribution_owns_only_leftblock_command(self):
         self.assertIn("\nName: leftblock\n", "\n" + self.metadata)
-        self.assertIn("\nVersion: 0.3.3\n", "\n" + self.metadata)
+        self.assertIn("\nVersion: 0.3.4\n", "\n" + self.metadata)
         self.assertIn("\nLicense-File: LICENSE\n", "\n" + self.metadata)
         self.assertEqual(dict(self.entry_points["console_scripts"]), {"leftblock": "leftblock.cli:main"})
 
@@ -208,7 +208,7 @@ class DistributionOwnershipTests(unittest.TestCase):
             self.assertIn(name, self.names)
         self.assertEqual(
             {name.split("/")[0] for name in self.names},
-            {"leftblock", "leftblock-0.3.3.dist-info"},
+            {"leftblock", "leftblock-0.3.4.dist-info"},
         )
         self.assertEqual(self.rules, (PROJECT_ROOT / "leftblock/data/gitleaks.toml").read_bytes())
         self.assertEqual(self.license, (PROJECT_ROOT / "LICENSE").read_bytes())

leftblock-0.3.4/tests/test_recorded_overrides.py

@@ -0,0 +1,253 @@
+"""Recorded per-finding overrides, using synthetic data and disposable repos."""
+
+import re
+import unittest
+
+import yaml
+
+from test_commit_gate import GITLEAKS, RepositoryFixture
+
+# Flagged by the shipped personal-email rule; the rule allowlists only
+# example.* and GitHub identities.
+EMAIL = "info" + "@" + "public-role.test"
+OTHER_EMAIL = "help" + "@" + "public-role.test"
+PAGE = "page.tsx"
+REASON = "Public role address for the site"
+
+
+@unittest.skipUnless(GITLEAKS, "Gitleaks must be installed for actual scanner tests")
+class RecordedOverrideTests(RepositoryFixture):
+    def setUp(self):
+        super().setUp()
+        proc = self.leftblock("install", "--local", "--check-only", "--gitleaks", GITLEAKS)
+        self.assertEqual(proc.returncode, 0, "Local install failed")
+
+    def write_stage(self, text, name=PAGE):
+        (self.repo / name).write_text(text)
+        self.git("add", name, check=True)
+
+    def check(self):
+        policy = self.repo / ".git" / "leftblock" / "policy.json"
+        return self.leftblock("check", "--config", str(policy))
+
+    def ids(self, proc):
+        return re.findall(r'"id": "([0-9a-f]{16})"', proc.stderr)
+
+    def blocked_id(self, text=None):
+        self.write_stage(text or f"a\nContact: {EMAIL}\n")
+        proc = self.check()
+        self.assertNotEqual(proc.returncode, 0)
+        ids = self.ids(proc)
+        self.assertEqual(len(ids), 1)
+        return ids[0]
+
+    def allow(self, *ids, reason=REASON):
+        return self.leftblock("allow", *ids, "--reason", reason)
+
+    def test_block_output_has_id_and_instructions_but_no_value(self):
+        ident = self.blocked_id()
+        proc = self.check()
+        out = proc.stdout + proc.stderr
+        self.assertIn(f"allow {ident}", out)
+        self.assertIn("record a reviewed override", out)
+        self.assertIn("--reason", out)
+        self.assertNotIn(EMAIL, out)
+        self.assertNotIn("public-role", out)
+        self.assertNotIn("No approval override", out)
+
+    def test_last_line_alone_names_the_finding_and_next_step(self):
+        # Wrappers such as `kbs commit` often show only the final line.
+        ident = self.blocked_id()
+        last = self.check().stderr.strip().splitlines()[-1]
+        self.assertIn("Inspection blocked", last)
+        self.assertIn(f"leftblock-personal-email in {PAGE} [id {ident}]", last)
+        self.assertIn("Remove the flagged content", last)
+        self.assertIn(f"allow {ident}", last)
+        self.assertNotIn("\033[", last)  # captured output carries no colour codes
+
+    def test_allow_stages_entry_then_check_passes_and_reports(self):
+        ident = self.blocked_id()
+        proc = self.allow(ident)
+        self.assertEqual(proc.returncode, 0, proc.stderr)
+        staged = self.git("show", ":.leftblock-allow.yml", check=True).stdout
+        data = yaml.safe_load(staged)
+        self.assertEqual(data["version"], 1)
+        entry = data["allow"][0]
+        self.assertEqual(
+            (entry["id"], entry["rule"], entry["file"], entry["reason"]),
+            (ident, "leftblock-personal-email", PAGE, REASON),
+        )
+        self.assertNotIn(EMAIL, staged)
+        check = self.check()
+        self.assertEqual(check.returncode, 0, check.stderr)
+        self.assertIn("Override applied", check.stderr)
+        self.assertIn(ident, check.stderr)
+        self.assertIn(REASON, check.stderr)
+        # Overrides stay visible on every run, and the commit goes through.
+        self.assertEqual(self.git("commit", "-m", "test: allowed").returncode, 0)
+
+    def test_allow_file_itself_is_not_flagged_and_dedupes(self):
+        ident = self.blocked_id()
+        self.assertEqual(self.allow(ident).returncode, 0)
+        self.assertEqual(self.allow(ident).returncode, 0)
+        data = yaml.safe_load((self.repo / ".leftblock-allow.yml").read_text())
+        self.assertEqual(len(data["allow"]), 1)
+        scan = self.check()
+        self.assertEqual(scan.returncode, 0, scan.stderr)
+        # Not the hex id, but the file as a whole: a numeric-looking id stays a string.
+        self.assertIsInstance(data["allow"][0]["id"], str)
+
+    def test_new_email_in_same_file_still_blocks(self):
+        ident = self.blocked_id()
+        self.assertEqual(self.allow(ident).returncode, 0)
+        self.write_stage(f"a\nContact: {EMAIL}\nAlso: {OTHER_EMAIL}\n")
+        proc = self.check()
+        self.assertNotEqual(proc.returncode, 0)
+        self.assertEqual(len(self.ids(proc)), 1)
+        self.assertNotIn(ident, self.ids(proc))
+
+    def test_changed_allowed_line_reblocks(self):
+        ident = self.blocked_id()
+        self.assertEqual(self.allow(ident).returncode, 0)
+        self.write_stage(f"a\nWrite to: {EMAIL}\n")
+        proc = self.check()
+        self.assertNotEqual(proc.returncode, 0)
+        self.assertNotIn(ident, self.ids(proc))
+
+    def test_line_numbers_inside_modified_committed_file(self):
+        self.write_stage("one\ntwo\nthree\n")
+        self.git("commit", "-m", "test: base", check=True)
+        ident = self.blocked_id(f"one\ntwo\nthree\nContact: {EMAIL}\n")
+        self.assertEqual(self.allow(ident).returncode, 0)
+        proc = self.check()
+        self.assertEqual(proc.returncode, 0, proc.stderr)
+
+    def test_reason_too_short_or_missing_is_refused(self):
+        ident = self.blocked_id()
+        for reason in ("", "   short  "):
+            with self.subTest(reason=reason):
+                proc = self.allow(ident, reason=reason)
+                self.assertEqual(proc.returncode, 1)
+        missing = self.leftblock("allow", ident)
+        self.assertEqual(missing.returncode, 1)
+        self.assertIn("at least 10 characters", missing.stderr)
+        self.assertNotIn("usage:", missing.stderr)
+        self.assertFalse((self.repo / ".leftblock-allow.yml").exists())
+
+    def index_blob(self):
+        return self.git("ls-files", "--stage", "--", ".leftblock-allow.yml").stdout
+
+    def test_reason_repeating_value_is_refused_and_restored_when_absent(self):
+        ident = self.blocked_id()
+        proc = self.allow(ident, reason=f"Public address {EMAIL} on the site")
+        self.assertEqual(proc.returncode, 1)
+        self.assertIn("The reason would itself be flagged (rule leftblock-personal-email)", proc.stderr)
+        self.assertIn("describe it instead", proc.stderr)
+        self.assertFalse((self.repo / ".leftblock-allow.yml").exists())
+        self.assertEqual(self.index_blob(), "")
+
+    def test_reason_repeating_value_restores_existing_entries(self):
+        first = self.blocked_id()
+        self.assertEqual(self.allow(first).returncode, 0)
+        path = self.repo / ".leftblock-allow.yml"
+        before, staged = path.read_bytes(), self.index_blob()
+        self.write_stage(f"x\nContact: {OTHER_EMAIL}\n", name="second.tsx")
+        proc = self.check()
+        second = [i for i in self.ids(proc) if i != first]
+        self.assertEqual(len(second), 1)
+        # Unstaged edit to the file must also survive a refused attempt.
+        path.write_bytes(before + b"# local note\n")
+        before = path.read_bytes()
+        refused = self.allow(second[0], reason=f"It is {OTHER_EMAIL} really")
+        self.assertEqual(refused.returncode, 1)
+        self.assertEqual(path.read_bytes(), before)
+        self.assertEqual(self.index_blob(), staged)
+
+    def test_finding_in_allow_file_has_no_id_and_friendly_message(self):
+        ident = self.blocked_id()
+        self.assertEqual(self.allow(ident).returncode, 0)
+        path = self.repo / ".leftblock-allow.yml"
+        path.write_text(path.read_text().replace(REASON, f"Address {EMAIL} is public"))
+        self.git("add", ".leftblock-allow.yml", check=True)
+        proc = self.check()
+        self.assertNotEqual(proc.returncode, 0)
+        self.assertEqual(self.ids(proc), [])
+        self.assertIn(
+            "A reason in .leftblock-allow.yml contains a flagged value; "
+            "reword that reason (don't repeat the value).", proc.stderr)
+        self.assertNotIn("allow ", proc.stderr.split("blocked")[-1])
+
+    def test_hand_edited_entry_with_empty_reason_blocks_as_invalid(self):
+        ident = self.blocked_id()
+        self.assertEqual(self.allow(ident).returncode, 0)
+        path = self.repo / ".leftblock-allow.yml"
+        data = yaml.safe_load(path.read_text())
+        data["allow"][0]["reason"] = ""
+        path.write_text(yaml.safe_dump(data))
+        self.git("add", ".leftblock-allow.yml", check=True)
+        proc = self.check()
+        self.assertNotEqual(proc.returncode, 0)
+        self.assertIn("Invalid .leftblock-allow.yml", proc.stderr)
+
+    def test_invalid_allow_files_block_even_on_clean_content(self):
+        self.write_stage("Harmless.\n")
+        path = self.repo / ".leftblock-allow.yml"
+        bad = (
+            "version: [",
+            "version: 2\nallow: []\n",
+            "version: 1\nallow:\n  - rule: r\n    file: f\n    reason: long enough reason\n",
+        )
+        for text in bad:
+            with self.subTest(text=text):
+                path.write_text(text)
+                self.git("add", ".leftblock-allow.yml", check=True)
+                proc = self.check()
+                self.assertNotEqual(proc.returncode, 0)
+                self.assertIn("Invalid .leftblock-allow.yml", proc.stderr)
+
+    def test_unstaged_allow_file_has_no_effect(self):
+        ident = self.blocked_id()
+        self.assertEqual(self.allow(ident).returncode, 0)
+        self.git("reset", "-q", "--", ".leftblock-allow.yml", check=True)
+        self.assertTrue((self.repo / ".leftblock-allow.yml").exists())
+        proc = self.check()
+        self.assertNotEqual(proc.returncode, 0)
+
+    def test_unknown_id_is_refused(self):
+        self.blocked_id()
+        proc = self.allow("0123456789abcdef")
+        self.assertEqual(proc.returncode, 1)
+        self.assertFalse((self.repo / ".leftblock-allow.yml").exists())
+
+    def test_allow_does_not_commit(self):
+        ident = self.blocked_id()
+        self.assertEqual(self.allow(ident).returncode, 0)
+        self.assert_not_committed()
+
+
+class OverrideNeverCoversErrorsTests(RepositoryFixture):
+    def test_missing_scanner_is_not_overridden(self):
+        self.stage(f"Contact: {EMAIL}\n")
+        self.policy("definitely-missing-scanner-binary --scan")
+        entry = {
+            "version": 1,
+            "allow": [{"id": "0123456789abcdef", "rule": "x", "file": "fixture.txt",
+                       "reason": "A long enough reason."}],
+        }
+        (self.repo / ".leftblock-allow.yml").write_text(yaml.safe_dump(entry))
+        self.git("add", ".leftblock-allow.yml", check=True)
+        self.assertNotEqual(self.leftblock("check").returncode, 0)
+        proc = self.leftblock("allow", "0123456789abcdef", "--reason", REASON)
+        self.assertEqual(proc.returncode, 1)
+
+    def test_error_result_with_matching_entry_stays_blocked(self):
+        from leftblock.allow import apply_allowlist
+        from leftblock.core import CheckerResult
+        result = CheckerResult("s", False, [{"File": "f", "RuleID": "r", "id": "a" * 16}], error=True)
+        entries = [{"id": "a" * 16, "rule": "r", "file": "f", "reason": "A long enough reason."}]
+        self.assertEqual(apply_allowlist([result], entries), [])
+        self.assertFalse(result.clean)
+
+
+if __name__ == "__main__":
+    unittest.main()