fix: keep the secrets-baseline plugin path portable across machines

`detect-secrets scan` rewrites `plugins_used[*].path` to the absolute
`file://` URI of the developer's machine on every run, so committing the
baseline as written poisons it for every other contributor. Add a small
normalizer (`tools/normalize_secrets_baseline.py`) that rewrites the
`KpmPasswordDetector` entry to a stable repo-relative URI, chain it into
`make scan-init` and `make scan-update`, drop the existing absolute path
from the committed baseline, and document the behaviour in the runbook.
The KPM-aware audit wrapper already pre-imports the plugin module, so
detect-secrets never has to resolve the URI at runtime.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: CuberHuber

.secrets.baseline

@@ -6,9 +6,10 @@
 # accepts `--plugin` natively.
 # See docs/runbooks/secrets.md for the full procedure.
 
-BASELINE := .secrets.baseline
-PLUGIN   := tools/detect_secrets_plugins/kpm_password.py
-WRAPPER  := tools/detect_secrets_audit.py
+BASELINE  := .secrets.baseline
+PLUGIN    := tools/detect_secrets_plugins/kpm_password.py
+WRAPPER   := tools/detect_secrets_audit.py
+NORMALIZE := uv run python tools/normalize_secrets_baseline.py $(BASELINE)
 
 SCAN := uv run detect-secrets scan \
   --plugin $(PLUGIN) \
@@ -44,9 +45,11 @@ scan:
 
 scan-update:
 	$(SCAN) --baseline $(BASELINE)
+	@$(NORMALIZE)
 
 scan-init:
 	$(SCAN) > $(BASELINE)
+	@$(NORMALIZE)
 
 hook:
 	uv run pre-commit run detect-secrets --all-files

Makefile

@@ -46,7 +46,9 @@ uv run detect-secrets scan \
 git add .secrets.baseline
 ```
 
-Shortcut: `make scan-init` (does the scan; staging stays manual).
+Shortcut: `make scan-init` (does the scan and normalizes the
+custom-plugin path in the baseline so it stays portable across
+machines; staging stays manual).
 
 ## Update
 
@@ -63,7 +65,9 @@ uv run detect-secrets scan \
 git add .secrets.baseline
 ```
 
-Shortcut: `make scan-update` (does the merge; staging stays manual).
+Shortcut: `make scan-update` (does the merge and normalizes the
+custom-plugin path in the baseline so it stays portable across
+machines; staging stays manual).
 
 Commit the baseline change in the same commit as the code change
 that introduced the new finding.

docs/runbooks/secrets.md

@@ -0,0 +1,50 @@
+"""Rewrite the custom plugin path in ``.secrets.baseline`` to a portable form.
+
+``detect-secrets scan`` stores the absolute ``file://`` URI of every
+``--plugin`` argument in ``plugins_used``. The URI is whatever path was
+on the developer's machine, so committing the baseline as written
+poisons it for every other contributor and CI runner.
+
+This normalizer rewrites the ``KpmPasswordDetector`` entry's ``path``
+field to a stable, repository-relative URI. The KPM-aware audit wrapper
+pre-imports the plugin module before any baseline-driven lookup, so the
+URI is never resolved at runtime — only its textual stability matters.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Final, final
+
+_PORTABLE_PLUGIN_PATH: Final[str] = (
+    "file://tools/detect_secrets_plugins/kpm_password.py"
+)
+_PLUGIN_NAME: Final[str] = "KpmPasswordDetector"
+
+
+@final
+class PortableSecretsBaseline:
+    """A ``.secrets.baseline`` whose plugin paths are repo-relative."""
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+
+    def normalize(self) -> None:
+        with open(self._path, encoding="utf-8") as fh:
+            data: dict[str, Any] = json.load(fh)
+        for plugin in data.get("plugins_used", []):
+            if plugin.get("name") == _PLUGIN_NAME:
+                plugin["path"] = _PORTABLE_PLUGIN_PATH
+        with open(self._path, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=2)
+            fh.write("\n")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        raise SystemExit(
+            "usage: uv run python tools/normalize_secrets_baseline.py <baseline-path>"
+        )
+    PortableSecretsBaseline(Path(sys.argv[1])).normalize()