leftblock 0.3.5__tar.gz → 0.4.2__tar.gz

{leftblock-0.3.5 → leftblock-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: leftblock
-Version: 0.3.5
+Version: 0.4.2
 Summary: LeftBlock: a pluggable inspection gate for Git commits
 License: MIT License
         
@@ -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.5
+python -m pip install leftblock==0.4.2
 python -m leftblock.cli --help
 ```
 
@@ -154,6 +154,73 @@ with the existing hook manager instead of replacing it. An earlier hook
 without the current ownership record requires a reviewed migration even
 if it is still functional.
 
+#### Upgrades and the stable runtime link
+
+When `install --local --check-only` runs from a virtualenv, it also keeps two
+symlinks pointing at that environment:
+
+- `$LEFTBLOCK_HOME/current` (default `~/.local/share/leftblock/current`) points
+  at the virtualenv, and every managed hook runs `current/bin/python` instead
+  of a versioned interpreter path.
+- `~/.local/bin/leftblock` points at `current/bin/leftblock`. It is replaced
+  only if it is absent or already a symlink; a regular file is left alone.
+
+To upgrade, install the new version into a new virtualenv and run
+`leftblock install --local --check-only` once, in any repository. That
+repoints `current`, so every repository's hook uses the new runtime. The
+per-repository rules copy (in `.git/leftblock/`) is refreshed only when
+you re-run the install in that repository.
+
+If the runtime link is broken, the hook fails closed: it prints
+`LeftBlock is not installed at <path>` with the reinstall steps and exits 1.
+Outside a virtualenv, the hook keeps using the installing interpreter and no
+links are made.
+
+`leftblock --version` prints the installed version. A blocked check starts
+with `leftblock <version>, ruleset <id>`, where the ruleset id is the first 12
+hex characters of the SHA-256 of the gitleaks config file the checker names
+with `--config` (`unknown` when there is none), so a report can say exactly
+which rules ran.
+
+#### Dry run
+
+`leftblock check` is a dry run of the next commit: it inspects the staged
+changes with the same policy the hook uses and changes nothing. Without
+`--config` it uses the local install policy when one exists, otherwise
+`.leftblock.yml`. A blocked run ends by printing `Re-run this check:
+leftblock check` and the final summary line.
+
+#### Exit codes and JSON output
+
+`leftblock check` exits with:
+
+| Code | Meaning |
+|---|---|
+| 0 | Passed (overrides may have been applied) |
+| 1 | Blocked by findings |
+| 2 | A checker or the configuration could not complete, including an invalid `.leftblock-allow.yml`; this wins over 1 when both occur |
+
+`leftblock check --format json` also prints one JSON object on stdout and
+leaves the human-readable stderr output unchanged:
+
+```json
+{
+  "version": "0.3.5",
+  "result": "blocked",
+  "findings": [{"file": "page.tsx", "line": 2, "rule": "leftblock-personal-email",
+                "id": "3f2a9c1e7b4d5a60", "description": "Personal email address"}],
+  "overrides_applied": [{"file": "a.md", "rule": "leftblock-home-path-posix",
+                         "id": "0123456789abcdef", "reason": "Documented example path"}],
+  "errors": [],
+  "override_command": "leftblock allow 3f2a9c1e7b4d5a60 --reason \"<why this is not sensitive>\""
+}
+```
+
+`result` is `passed`, `blocked` or `error`; `errors` is `[{checker, message}]`;
+`override_command` is `null` when nothing can be overridden. Like the text
+output, it never contains matched values or source lines. The git hooks only
+need a nonzero status, so they are unaffected.
+
 To run a noninteractive staged check with an explicit policy:
 
 ```bash
@@ -172,8 +239,9 @@ metadata or another private location.
 
 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:
+blocked check prints each finding as `file:LINE: rule [id …] (description)`,
+where the description is the rule's own text from the ruleset, never the
+matched value, source line or secret, and then the exact command to run:
 
 ```bash
 leftblock allow ID [ID ...] --reason "Why this is not sensitive"
@@ -190,10 +258,14 @@ allow:
   - id: "3f2a9c1e7b4d5a60"
     rule: "leftblock-personal-email"
     file: "apps/web/privacy/page.tsx"
+    kind: "Personal email address"
     reason: "Public role address required in the privacy notice."
     added: 2026-10-20
 ```
 
+- **Category for reviewers.** `kind` is the rule's description, written so a
+  reviewer of the pull request sees what kind of finding was approved. It is
+  informational: it is not part of matching and may be omitted.
 - **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.
@@ -210,10 +282,34 @@ allow:
   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.
+#### Gitleaks' own suppressions
+
+Gitleaks skips a line carrying its inline allow comment and any entry in a
+`.gitleaksignore` file, with no recorded reason. LeftBlock closes the silent
+paths it can see: it reports, as ordinary findings that carry an id and can be
+overridden only through a recorded reason as above,
+
+- `leftblock-gitleaks-allow-marker`: any staged added line containing the
+  Gitleaks allow comment (the word `gitleaks`, a colon, then `allow`); and
+- `leftblock-gitleaksignore-change`: any staged addition or edit of a
+  `.gitleaksignore` file at any path (removing one is not a finding).
+
+Both are read from the staged diff (the merge-scoped index during a merge).
+Removing a suppression is the fix, not a finding.
+
+**Residual risk.** Tested with Gitleaks 8.30: a `.gitleaksignore` in the
+repository root that already exists, committed or only in the working tree, is
+still honoured by `protect --staged`, and no option turns that off. Passing
+`--gitleaks-ignore-path` with an empty file or directory adds to the sources it
+reads; it does not replace the root file. Ignore files in subdirectories and
+ones that exist only in the index are not read. LeftBlock therefore cannot
+stop an ignore file that was already there before the check ran, but every
+`leftblock check` warns when a root `.gitleaksignore` exists, so its skips are
+never silent. Review it (`git ls-files '*.gitleaksignore'`), and treat a file
+that is untracked or edited outside the index as outside this check. The
+installed policy passes `--ignore-gitleaks-allow`, so Gitleaks still scans
+lines that carry the inline comment: a real finding on such a line is reported
+alongside the marker finding.
 
 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
@@ -257,6 +353,12 @@ Python environment or Gitleaks executable. For manual composition, run
 `leftblock hook "$1"` in the `commit-msg` flow when receipts are needed.
 Preserve existing behavior and propagate any failure's exit status.
 
+A receipt records `Inspection-result: clean` when nothing was found, and
+`Inspection-result: allowed:N` when every finding was covered by `N` staged,
+reasoned overrides (see [Overriding a false alarm](#overriding-a-false-alarm)).
+Neither needs a passphrase. An interactive passphrase override of unrecorded
+findings is still recorded as `override:N-checkers`.
+
 Receipts use HMAC trailers, not Git GPG/SSH signatures; they do not appear
 in `git log --show-signature`. Every machine running `leftblock verify`
 needs the same secret, stored by default at `~/.config/leftblock/secret`
@@ -295,29 +397,33 @@ PEM private keys, and other standard secret formats.
 
 | Rule | What it catches |
 |---|---|
-| `leftblock-personal-email` | Personal email addresses (infrastructure identities like `git@github.com`, `@users.noreply.github.com` and `@example.*` placeholders are allowlisted) |
+| `leftblock-personal-email` | Personal email addresses (infrastructure identities like `git@github.com`, `@users.noreply.github.com`, no-reply addresses and `@example.*` placeholders are allowlisted) |
 | `leftblock-home-path-posix` | Home-folder paths `/Users/<name>`, `/home/<name>` |
 | `leftblock-home-path-windows` | `C:\Users\<name>` and `\Users\<name>` |
-| `leftblock-session-uuid` | Potential session UUIDs, with narrow exceptions for canonical Kanbus structural fields and example values |
-| `leftblock-actor-id` | `actor_id` / `user_id` / `author_id` JSON values |
+| `leftblock-session-uuid` | Potential session UUIDs (not flagged in Kanbus board data; example values and the `.kanbus.yml` `project_id` line are also allowed) |
+| `leftblock-actor-id` | `actor_id` / `user_id` / `author_id` JSON values (not flagged in Kanbus board data) |
 | `leftblock-openai-key` | `sk-`, `sk-proj-`, `sk-svcacct-` OpenAI keys |
 | `leftblock-anthropic-key` | `sk-ant-` Anthropic keys |
 | `leftblock-eth-private-key` | Ethereum-style private keys (`0x` + 64 hex) |
 | `leftblock-wif-key` | Bitcoin WIF private keys (compressed `K/L/M…`, uncompressed `5…`) |
 | `leftblock-bip39-mnemonic` | BIP-39 seed phrases (12–24 words) in seed/mnemonic/recovery context |
 
-Kanbus exceptions apply to complete identifier property lines in
-`project/issues/*.json` and `project/events/*.json`. Event actor attribution
-must occupy a root property line in the canonical two-space format.
-Coordination claim references must occupy the canonical payload depth.
-The legacy `project/.cache/index.json` allows only canonical issue ID/parent
-lines and issue-filename keys with numeric modification times; cached
-descriptions and comments still receive the normal checks.
-Provider session fields, nested actor values, prose and arbitrary arrays
-remain scanned. A project prefix alone grants no exception, and a second
-value on the same line cannot inherit one. These checks recognize syntax;
-they do not validate a full JSON schema or prove an identifier is public.
-Other secret rules still apply to values in the accepted fields.
+A blocked check prints a one-line hint after each rule's findings (once per
+rule): use a role or placeholder address for personal emails; a relative path,
+`$HOME` or `~` for home paths; drop or describe session and actor identifiers;
+and for API, private and wallet keys, remove the value **and rotate the key**,
+since it may already be exposed. Findings in Kanbus board data
+(`project/issues/*.json`, `project/events/*.json`) also say that Kanbus writes
+those files and that the content should be fixed through `kbs` (for example
+`kbs update` or `kbs comment`) rather than by hand.
+
+Kanbus is the mandated task tracker, so identifiers in its board data (actor
+ids, session UUIDs, and UUIDs in any field or prose) are not sensitive and never
+block a `kbs` write. Board data means `project/issues/*.json`,
+`project/events/*.json` and `project/.cache/index.json`; the exception is
+limited to the session-UUID and actor-id rules, so personal emails, home paths
+and API or wallet keys in those files are still detected, and the same content
+in any other path is still flagged.
 
 ### Crypto wallet material: what is and is not flagged
 

{leftblock-0.3.5 → leftblock-0.4.2}/README.md

@@ -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.5
+python -m pip install leftblock==0.4.2
 python -m leftblock.cli --help
 ```
 
@@ -121,6 +121,73 @@ with the existing hook manager instead of replacing it. An earlier hook
 without the current ownership record requires a reviewed migration even
 if it is still functional.
 
+#### Upgrades and the stable runtime link
+
+When `install --local --check-only` runs from a virtualenv, it also keeps two
+symlinks pointing at that environment:
+
+- `$LEFTBLOCK_HOME/current` (default `~/.local/share/leftblock/current`) points
+  at the virtualenv, and every managed hook runs `current/bin/python` instead
+  of a versioned interpreter path.
+- `~/.local/bin/leftblock` points at `current/bin/leftblock`. It is replaced
+  only if it is absent or already a symlink; a regular file is left alone.
+
+To upgrade, install the new version into a new virtualenv and run
+`leftblock install --local --check-only` once, in any repository. That
+repoints `current`, so every repository's hook uses the new runtime. The
+per-repository rules copy (in `.git/leftblock/`) is refreshed only when
+you re-run the install in that repository.
+
+If the runtime link is broken, the hook fails closed: it prints
+`LeftBlock is not installed at <path>` with the reinstall steps and exits 1.
+Outside a virtualenv, the hook keeps using the installing interpreter and no
+links are made.
+
+`leftblock --version` prints the installed version. A blocked check starts
+with `leftblock <version>, ruleset <id>`, where the ruleset id is the first 12
+hex characters of the SHA-256 of the gitleaks config file the checker names
+with `--config` (`unknown` when there is none), so a report can say exactly
+which rules ran.
+
+#### Dry run
+
+`leftblock check` is a dry run of the next commit: it inspects the staged
+changes with the same policy the hook uses and changes nothing. Without
+`--config` it uses the local install policy when one exists, otherwise
+`.leftblock.yml`. A blocked run ends by printing `Re-run this check:
+leftblock check` and the final summary line.
+
+#### Exit codes and JSON output
+
+`leftblock check` exits with:
+
+| Code | Meaning |
+|---|---|
+| 0 | Passed (overrides may have been applied) |
+| 1 | Blocked by findings |
+| 2 | A checker or the configuration could not complete, including an invalid `.leftblock-allow.yml`; this wins over 1 when both occur |
+
+`leftblock check --format json` also prints one JSON object on stdout and
+leaves the human-readable stderr output unchanged:
+
+```json
+{
+  "version": "0.3.5",
+  "result": "blocked",
+  "findings": [{"file": "page.tsx", "line": 2, "rule": "leftblock-personal-email",
+                "id": "3f2a9c1e7b4d5a60", "description": "Personal email address"}],
+  "overrides_applied": [{"file": "a.md", "rule": "leftblock-home-path-posix",
+                         "id": "0123456789abcdef", "reason": "Documented example path"}],
+  "errors": [],
+  "override_command": "leftblock allow 3f2a9c1e7b4d5a60 --reason \"<why this is not sensitive>\""
+}
+```
+
+`result` is `passed`, `blocked` or `error`; `errors` is `[{checker, message}]`;
+`override_command` is `null` when nothing can be overridden. Like the text
+output, it never contains matched values or source lines. The git hooks only
+need a nonzero status, so they are unaffected.
+
 To run a noninteractive staged check with an explicit policy:
 
 ```bash
@@ -139,8 +206,9 @@ metadata or another private location.
 
 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:
+blocked check prints each finding as `file:LINE: rule [id …] (description)`,
+where the description is the rule's own text from the ruleset, never the
+matched value, source line or secret, and then the exact command to run:
 
 ```bash
 leftblock allow ID [ID ...] --reason "Why this is not sensitive"
@@ -157,10 +225,14 @@ allow:
   - id: "3f2a9c1e7b4d5a60"
     rule: "leftblock-personal-email"
     file: "apps/web/privacy/page.tsx"
+    kind: "Personal email address"
     reason: "Public role address required in the privacy notice."
     added: 2026-10-20
 ```
 
+- **Category for reviewers.** `kind` is the rule's description, written so a
+  reviewer of the pull request sees what kind of finding was approved. It is
+  informational: it is not part of matching and may be omitted.
 - **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.
@@ -177,10 +249,34 @@ allow:
   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.
+#### Gitleaks' own suppressions
+
+Gitleaks skips a line carrying its inline allow comment and any entry in a
+`.gitleaksignore` file, with no recorded reason. LeftBlock closes the silent
+paths it can see: it reports, as ordinary findings that carry an id and can be
+overridden only through a recorded reason as above,
+
+- `leftblock-gitleaks-allow-marker`: any staged added line containing the
+  Gitleaks allow comment (the word `gitleaks`, a colon, then `allow`); and
+- `leftblock-gitleaksignore-change`: any staged addition or edit of a
+  `.gitleaksignore` file at any path (removing one is not a finding).
+
+Both are read from the staged diff (the merge-scoped index during a merge).
+Removing a suppression is the fix, not a finding.
+
+**Residual risk.** Tested with Gitleaks 8.30: a `.gitleaksignore` in the
+repository root that already exists, committed or only in the working tree, is
+still honoured by `protect --staged`, and no option turns that off. Passing
+`--gitleaks-ignore-path` with an empty file or directory adds to the sources it
+reads; it does not replace the root file. Ignore files in subdirectories and
+ones that exist only in the index are not read. LeftBlock therefore cannot
+stop an ignore file that was already there before the check ran, but every
+`leftblock check` warns when a root `.gitleaksignore` exists, so its skips are
+never silent. Review it (`git ls-files '*.gitleaksignore'`), and treat a file
+that is untracked or edited outside the index as outside this check. The
+installed policy passes `--ignore-gitleaks-allow`, so Gitleaks still scans
+lines that carry the inline comment: a real finding on such a line is reported
+alongside the marker finding.
 
 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
@@ -224,6 +320,12 @@ Python environment or Gitleaks executable. For manual composition, run
 `leftblock hook "$1"` in the `commit-msg` flow when receipts are needed.
 Preserve existing behavior and propagate any failure's exit status.
 
+A receipt records `Inspection-result: clean` when nothing was found, and
+`Inspection-result: allowed:N` when every finding was covered by `N` staged,
+reasoned overrides (see [Overriding a false alarm](#overriding-a-false-alarm)).
+Neither needs a passphrase. An interactive passphrase override of unrecorded
+findings is still recorded as `override:N-checkers`.
+
 Receipts use HMAC trailers, not Git GPG/SSH signatures; they do not appear
 in `git log --show-signature`. Every machine running `leftblock verify`
 needs the same secret, stored by default at `~/.config/leftblock/secret`
@@ -262,29 +364,33 @@ PEM private keys, and other standard secret formats.
 
 | Rule | What it catches |
 |---|---|
-| `leftblock-personal-email` | Personal email addresses (infrastructure identities like `git@github.com`, `@users.noreply.github.com` and `@example.*` placeholders are allowlisted) |
+| `leftblock-personal-email` | Personal email addresses (infrastructure identities like `git@github.com`, `@users.noreply.github.com`, no-reply addresses and `@example.*` placeholders are allowlisted) |
 | `leftblock-home-path-posix` | Home-folder paths `/Users/<name>`, `/home/<name>` |
 | `leftblock-home-path-windows` | `C:\Users\<name>` and `\Users\<name>` |
-| `leftblock-session-uuid` | Potential session UUIDs, with narrow exceptions for canonical Kanbus structural fields and example values |
-| `leftblock-actor-id` | `actor_id` / `user_id` / `author_id` JSON values |
+| `leftblock-session-uuid` | Potential session UUIDs (not flagged in Kanbus board data; example values and the `.kanbus.yml` `project_id` line are also allowed) |
+| `leftblock-actor-id` | `actor_id` / `user_id` / `author_id` JSON values (not flagged in Kanbus board data) |
 | `leftblock-openai-key` | `sk-`, `sk-proj-`, `sk-svcacct-` OpenAI keys |
 | `leftblock-anthropic-key` | `sk-ant-` Anthropic keys |
 | `leftblock-eth-private-key` | Ethereum-style private keys (`0x` + 64 hex) |
 | `leftblock-wif-key` | Bitcoin WIF private keys (compressed `K/L/M…`, uncompressed `5…`) |
 | `leftblock-bip39-mnemonic` | BIP-39 seed phrases (12–24 words) in seed/mnemonic/recovery context |
 
-Kanbus exceptions apply to complete identifier property lines in
-`project/issues/*.json` and `project/events/*.json`. Event actor attribution
-must occupy a root property line in the canonical two-space format.
-Coordination claim references must occupy the canonical payload depth.
-The legacy `project/.cache/index.json` allows only canonical issue ID/parent
-lines and issue-filename keys with numeric modification times; cached
-descriptions and comments still receive the normal checks.
-Provider session fields, nested actor values, prose and arbitrary arrays
-remain scanned. A project prefix alone grants no exception, and a second
-value on the same line cannot inherit one. These checks recognize syntax;
-they do not validate a full JSON schema or prove an identifier is public.
-Other secret rules still apply to values in the accepted fields.
+A blocked check prints a one-line hint after each rule's findings (once per
+rule): use a role or placeholder address for personal emails; a relative path,
+`$HOME` or `~` for home paths; drop or describe session and actor identifiers;
+and for API, private and wallet keys, remove the value **and rotate the key**,
+since it may already be exposed. Findings in Kanbus board data
+(`project/issues/*.json`, `project/events/*.json`) also say that Kanbus writes
+those files and that the content should be fixed through `kbs` (for example
+`kbs update` or `kbs comment`) rather than by hand.
+
+Kanbus is the mandated task tracker, so identifiers in its board data (actor
+ids, session UUIDs, and UUIDs in any field or prose) are not sensitive and never
+block a `kbs` write. Board data means `project/issues/*.json`,
+`project/events/*.json` and `project/.cache/index.json`; the exception is
+limited to the session-UUID and actor-id rules, so personal emails, home paths
+and API or wallet keys in those files are still detected, and the same content
+in any other path is still flagged.
 
 ### Crypto wallet material: what is and is not flagged
 

{leftblock-0.3.5 → leftblock-0.4.2}/leftblock/allow.py

@@ -19,7 +19,8 @@ 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"
+    "# line content in one file). Changing that line re-blocks it. `kind` is the\n"
+    "# rule's category, shown for reviewers; it is not part of matching.\n"
 )
 
 
@@ -52,12 +53,14 @@ def finding_id(repo_root, rule, file, start, end):
 
 
 def attach_ids(repo_root, results):
-    """Replace StartLine/EndLine on findings with an id (when computable)."""
+    """Replace StartLine/EndLine on findings with `line` and 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 type(start) is int and start >= 1:
+                finding["line"] = start
             if finding.get("File") == ALLOW_FILE:
                 continue  # the allow file can never approve itself
             ident = finding_id(
@@ -145,6 +148,8 @@ def _render(entries):
         out.append(f"  - id: {_quote(e['id'])}\n")
         out.append(f"    rule: {_quote(e['rule'])}\n")
         out.append(f"    file: {_quote(e['file'])}\n")
+        if e.get("kind"):
+            out.append(f"    kind: {_quote(e['kind'])}\n")
         out.append(f"    reason: {_quote(' '.join(e['reason'].split()))}\n")
         if added:
             plain = re.fullmatch(r"\d{4}-\d{2}-\d{2}", added)
@@ -153,7 +158,7 @@ def _render(entries):
 
 
 def record_overrides(repo_root, findings, reason):
-    """Append entries for findings (dicts with id/RuleID/File) to the allow file.
+    """Append entries for findings (dicts with id/RuleID/File, optional kind) to the allow file.
 
     Returns the findings newly recorded. The working-tree file must be valid.
     """
@@ -169,10 +174,13 @@ def record_overrides(repo_root, findings, reason):
         if finding["id"] in known:
             continue
         known.add(finding["id"])
-        entries.append({
+        entry = {
             "id": finding["id"], "rule": finding["RuleID"], "file": finding["File"],
             "reason": reason, "added": today,
-        })
+        }
+        if finding.get("kind"):
+            entry["kind"] = finding["kind"]  # informational, for reviewers only
+        entries.append(entry)
         added.append(finding)
     with open(path, "w", encoding="utf-8") as f:
         f.write(_render(entries))

leftblock-0.4.2/leftblock/bypass.py

@@ -0,0 +1,119 @@
+"""Findings for the two ways Gitleaks can be told to skip content silently.
+
+Gitleaks honours an inline allow comment and `.gitleaksignore`
+files without any recorded reason. LeftBlock reports staged additions of
+either as findings of its own, so they are blocked by default and can be
+overridden only through a recorded, reviewed override like any other finding.
+"""
+
+import re
+import subprocess
+
+# Split so this repository does not trip its own check.
+MARKER = "gitleaks" + ":allow"
+IGNORE_FILE = ".gitleaksignore"
+MARKER_RULE = "leftblock-gitleaks-allow-marker"
+IGNORE_RULE = "leftblock-gitleaksignore-change"
+# Descriptions are written into the allow file as `kind`, so they must not
+# contain the marker themselves.
+RULE_DESCRIPTIONS = {
+    MARKER_RULE: "Inline Gitleaks allow comment (skips the scanner with no recorded reason)",
+    IGNORE_RULE: "Change to .gitleaksignore (skips the scanner with no recorded reason)",
+}
+
+_HUNK = re.compile(r"^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+_ESCAPES = {"a": 7, "b": 8, "f": 12, "n": 10, "r": 13, "t": 9, "v": 11, '"': 34, "\\": 92}
+
+
+class BypassScanError(Exception):
+    pass
+
+
+def _git(repo_root, env, *args):
+    proc = subprocess.run(
+        ["git", *args], cwd=repo_root, env=env, capture_output=True, check=False,
+        stdin=subprocess.DEVNULL,
+    )
+    if proc.returncode:
+        raise BypassScanError("git " + args[0] + " failed")
+    return proc.stdout
+
+
+def _unquote(path):
+    """Decode a path as Git prints it (C-style quoting when it has odd bytes)."""
+    if not (path.startswith(b'"') and path.endswith(b'"') and len(path) >= 2):
+        return path
+    out, i, body = bytearray(), 0, path[1:-1]
+    while i < len(body):
+        c = body[i]
+        if c != 0x5C:
+            out.append(c)
+            i += 1
+        elif body[i + 1:i + 2].isdigit() and re.fullmatch(rb"[0-7]{3}", body[i + 1:i + 4]):
+            out.append(int(body[i + 1:i + 4], 8))
+            i += 4
+        else:
+            out.append(_ESCAPES.get(chr(body[i + 1]), body[i + 1]))
+            i += 2
+    return bytes(out)
+
+
+def _added_lines(diff):
+    """Yield (path, line_number, text) for each added line in a -U0 patch.
+
+    Hunk line counts decide which lines are content, so an added line that
+    itself starts with "++" or "@@" cannot be mistaken for a header.
+    """
+    path, line, old_left, new_left = None, 0, 0, 0
+    for raw in diff.split(b"\n"):
+        if old_left or new_left:
+            if raw.startswith(b"-"):
+                old_left -= 1
+            elif raw.startswith(b"+"):
+                new_left -= 1
+                if path is not None:
+                    yield path, line, raw[1:]
+                line += 1
+            continue
+        if raw.startswith(b"+++ "):
+            target = _unquote(raw[4:])
+            path = None if target == b"/dev/null" else target[2:].decode("utf-8", "replace")
+        elif raw.startswith(b"@@"):
+            hunk = _HUNK.match(raw.decode("utf-8", "replace"))
+            if hunk:
+                old_left = int(hunk.group(1) or 1)
+                line = int(hunk.group(2))
+                new_left = int(hunk.group(3) or 1)
+
+
+def bypass_findings(repo_root, env=None):
+    """Findings (File, RuleID, StartLine, EndLine, description) for staged bypasses.
+
+    Reads the staged diff through `env`, which carries the merge-scoped index
+    when one is in use. Raises BypassScanError when the diff cannot be read.
+    """
+    diff = _git(
+        repo_root, env, "-c", "core.quotePath=false", "diff", "--cached", "-U0",
+        "--no-color", "--no-ext-diff", "--no-renames", "--text",
+    )
+    findings = []
+    for path, number, text in _added_lines(diff):
+        if MARKER.encode() in text:
+            findings.append({
+                "File": path, "RuleID": MARKER_RULE, "StartLine": number, "EndLine": number,
+                "description": RULE_DESCRIPTIONS[MARKER_RULE],
+            })
+    names = _git(
+        repo_root, env, "diff", "--cached", "--name-only", "-z", "--no-renames",
+        "--diff-filter=AMT",
+    )
+    for raw in names.split(b"\0"):
+        path = raw.decode("utf-8", "replace")
+        if path and (path == IGNORE_FILE or path.endswith("/" + IGNORE_FILE)):
+            blob = _git(repo_root, env, "show", ":" + path)
+            lines = len(blob.decode("utf-8", "replace").split("\n"))
+            findings.append({
+                "File": path, "RuleID": IGNORE_RULE, "StartLine": 1, "EndLine": lines,
+                "description": RULE_DESCRIPTIONS[IGNORE_RULE],
+            })
+    return findings