fix(security): make suppression fingerprints content-addressed

Hash rule, path, normalized matched content, and duplicate occurrence instead of absolute line numbers. Document the one-time migration required for existing line-based suppressions.

Co-Authored-By: Codex <codex@openai.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: solomonneas

docs/security.md

@@ -36,7 +36,8 @@ Supported fields:
 - `fail_on`: `none`, `low`, `medium`, `high`, or `critical`.
 - `include_templates`: whether public template files are scanned.
 - `enabled_checks`: any of `automation`, `mcp`, `permissions`, `prompt-injection`, `secrets`, and `supply-chain`.
-- `include_paths` and `exclude_paths`: relative path prefixes.
+- `include_paths`: relative path prefixes.
+- `exclude_paths`: relative path prefixes or glob patterns such as `.brigade/**`.
 - `severity_threshold`: minimum severity retained in reports.
 - `output_path`: relative path for the latest local evidence bundle.
 - `[suppressions]` and `[suppression_reasons]`: reviewed finding fingerprints and reasons.
@@ -56,7 +57,15 @@ brigade security unsuppress <finding-id-or-fingerprint>
 brigade security doctor
 ```
 
-Findings include stable `id`, `fingerprint`, `rule_id`, `severity`, `category`, `path`, `line`, `safe_excerpt`, `remediation_hint`, and optional `response_options` fields. Secret-looking values are redacted before JSON reports, Markdown reports, SARIF, work imports, docs, or session artifacts are written.
+Findings include stable `id`, `fingerprint`, `rule_id`, `severity`, `category`, `path`, `line`, `occurrence`, `safe_excerpt`, `remediation_hint`, and optional `response_options` fields. Secret-looking values are redacted before JSON reports, Markdown reports, SARIF, work imports, docs, or session artifacts are written.
+
+### Finding fingerprints and suppressions
+
+Finding fingerprints are content-addressed, not line-addressed. A fingerprint hashes `rule_id`, repo-relative `path`, a normalized redacted 96-character excerpt of the matched content, and a zero-based `occurrence` index for genuine duplicates of the same rule and text in one file. Absolute line numbers are reported for review but do not affect fingerprint identity, so suppressions survive unrelated edits above a finding.
+
+When the same rule matches identical redacted text twice in one file, the first match uses `occurrence = 0`, the second `occurrence = 1`, and so on. Occurrence order follows ascending scan line number, which keeps duplicate strings distinct without tying identity to a single absolute line.
+
+**One-time migration from line-based fingerprints:** older releases mixed category, title, path, line, and excerpt into each fingerprint. Existing `[suppressions]` entries keyed by those fingerprints do not match the new content-addressed IDs and are not rewritten automatically. After upgrading, review and suppress each still-accepted finding once under its new fingerprint, then remove the stale entry from `.brigade/security.toml`. Later line shifts keep the new suppression intact. Old evidence bundles retain their original fingerprints and are not rewritten or reconciled.
 
 Secret findings include a small response playbook. Typical options are moving active credentials into a gitignored `.env` file or environment variable, scrubbing tracked files and rotating exposed values, showing the redacted finding to the operator so they can preserve the real value in KeePass before deciding, and redacting or archiving chat/session transcripts when a session log contains an exposed key.
 

src/brigade/security_cmd/scan_engine.py

@@ -906,11 +906,39 @@ def _secret_response_options(path: Path, target: Path) -> list[str]:
     return options
 
 
-def _fingerprint(*, category: str, title: str, rel_path: Path, line: int, evidence: str) -> str:
-    stable = "\n".join([category, title, str(rel_path), str(line), _short(evidence, limit=96)])
+def _normalized_matched_content(evidence: str) -> str:
+    return _short(evidence, limit=96)
+
+
+def _fingerprint(*, rule_id: str, rel_path: str, matched_content: str, occurrence: int) -> str:
+    stable = "\n".join([rule_id, rel_path, matched_content, str(occurrence)])
     return hashlib.sha256(stable.encode()).hexdigest()[:16]
 
 
+def _assign_fingerprints(findings: list[dict[str, Any]]) -> None:
+    groups: dict[tuple[str, str, str], list[dict[str, Any]]] = {}
+    for finding in findings:
+        key = (
+            str(finding.get("rule_id") or ""),
+            str(finding.get("path") or ""),
+            str(finding.get("_fingerprint_content") or finding.get("safe_excerpt") or finding.get("evidence") or ""),
+        )
+        groups.setdefault(key, []).append(finding)
+    for (_, _, matched_content), items in groups.items():
+        items.sort(key=lambda finding: (int(finding.get("line") or 0), str(finding.get("id") or "")))
+        for occurrence, finding in enumerate(items):
+            fingerprint = _fingerprint(
+                rule_id=str(finding.get("rule_id") or ""),
+                rel_path=str(finding.get("path") or ""),
+                matched_content=matched_content,
+                occurrence=occurrence,
+            )
+            finding["occurrence"] = occurrence
+            finding["fingerprint"] = fingerprint
+            finding["id"] = f"security-{fingerprint}"
+            finding.pop("_fingerprint_content", None)
+
+
 def _finding(
     findings: list[dict[str, Any]],
     *,
@@ -928,13 +956,11 @@ def _finding(
     rel = path.relative_to(target)
     file_classification = classification or _classification_for(path, target)
     safe_excerpt = _short(evidence)
-    fingerprint = _fingerprint(category=category, title=title, rel_path=rel, line=line, evidence=safe_excerpt)
-    finding_id = f"security-{fingerprint}"
+    matched_content = _normalized_matched_content(evidence)
+    rule = _rule_id(category, title)
     findings.append(
         {
-            "id": finding_id,
-            "fingerprint": fingerprint,
-            "rule_id": _rule_id(category, title),
+            "rule_id": rule,
             "severity": severity,
             "category": category,
             "title": title,
@@ -944,6 +970,7 @@ def _finding(
             "confidence": file_classification.confidence,
             "evidence": safe_excerpt,
             "safe_excerpt": safe_excerpt,
+            "_fingerprint_content": matched_content,
             "suggestion": suggestion,
             "remediation_hint": suggestion,
             "response_options": response_options or [],
@@ -1305,6 +1332,7 @@ def scan_target(
         _scan_package_json(findings, target=target, path=path, text=text, classification=classification)
         _scan_github_actions(findings, target=target, path=path, text=text, classification=classification)
         _scan_python_project(findings, target=target, path=path, text=text, classification=classification)
+    _assign_fingerprints(findings)
     findings = _filter_findings(
         findings,
         enabled_checks=enabled_checks,

src/brigade/security_cmd/template_audit_ops.py

@@ -205,6 +205,7 @@ def harness_wiring_payload(target: Path) -> dict[str, Any]:
             text=text,
             classification=_classification_for(path, target),
         )
+    _assign_fingerprints(findings)
     findings = _filter_findings(
         findings,
         enabled_checks=SECURITY_CHECKS,

tests/test_security_cmd.py

@@ -821,6 +821,104 @@ def recording_confidence(path, target):
     assert confidence_calls == ["script.sh"]
 
 
+def test_security_suppression_fingerprint_survives_line_shift(tmp_path, capsys):
+    readme = tmp_path / "README.md"
+    needle = "npx -y @example/unpinned-package\n"
+    readme.write_text("# Title\n\n" + needle)
+    first = security_cmd.scan_target(tmp_path)
+    finding = next(item for item in first["findings"] if item["category"] == "supply-chain")
+    fingerprint = finding["fingerprint"]
+
+    assert security_cmd.suppress(target=tmp_path, fingerprint=fingerprint, reason="reviewed docs example") == 0
+    capsys.readouterr()
+
+    readme.write_text("# Title\n\n| col | val |\n| --- | --- |\n| a | b |\n\n" + needle)
+    second = security_cmd.scan_target(tmp_path, suppressions=security_cmd.load_config(tmp_path).suppressions)
+
+    assert second["finding_count"] == 0
+    assert second["suppressed_count"] == 1
+    suppressed = second["suppressed_findings"][0]
+    assert suppressed["fingerprint"] == fingerprint
+    assert suppressed["line"] != finding["line"]
+
+
+def test_security_fingerprint_distinguishes_identical_duplicates(tmp_path):
+    line = "npx -y @example/unpinned-package\n"
+    (tmp_path / "dup.txt").write_text(line + "middle section\n" + line)
+
+    report = security_cmd.scan_target(tmp_path)
+    findings = [item for item in report["findings"] if item["category"] == "supply-chain"]
+
+    assert len(findings) == 2
+    assert findings[0]["fingerprint"] != findings[1]["fingerprint"]
+    assert findings[0]["occurrence"] == 0
+    assert findings[1]["occurrence"] == 1
+    assert findings[0]["safe_excerpt"] == findings[1]["safe_excerpt"]
+
+    suppressed = security_cmd.scan_target(tmp_path, suppressions=(findings[0]["fingerprint"],))
+    assert suppressed["finding_count"] == 1
+    assert suppressed["suppressed_count"] == 1
+    assert suppressed["findings"][0]["fingerprint"] == findings[1]["fingerprint"]
+    assert suppressed["suppressed_findings"][0]["fingerprint"] == findings[0]["fingerprint"]
+
+
+def test_security_line_based_suppression_requires_one_time_migration(tmp_path, capsys):
+    import hashlib
+
+    from brigade.security_cmd import scan_engine as scan_engine
+
+    readme = tmp_path / "README.md"
+    needle = "npx -y @example/unpinned-package\n"
+    readme.write_text("# Title\n\n" + needle)
+    current = security_cmd.scan_target(tmp_path)
+    finding = next(item for item in current["findings"] if item["category"] == "supply-chain")
+
+    legacy = hashlib.sha256(
+        "\n".join(
+            [
+                finding["category"],
+                finding["title"],
+                finding["path"],
+                str(finding["line"]),
+                scan_engine._short(needle.strip(), limit=96),
+            ]
+        ).encode()
+    ).hexdigest()[:16]
+    assert legacy != finding["fingerprint"]
+
+    config = tmp_path / ".brigade" / "security.toml"
+    config.parent.mkdir(parents=True)
+    config.write_text(
+        "\n".join(
+            [
+                'policy = "personal"',
+                'scan_profile = "local-only-audit"',
+                'fail_on = "none"',
+                "include_templates = false",
+                'enabled_checks = ["supply-chain"]',
+                "include_paths = []",
+                "exclude_paths = []",
+                'severity_threshold = "low"',
+                'output_path = ".brigade/security/latest"',
+                "",
+                "[suppressions]",
+                f'fingerprints = ["{legacy}"]',
+                "",
+                "[suppression_reasons]",
+                f'{legacy} = "legacy line-based suppression"',
+                "",
+            ]
+        )
+    )
+
+    with_legacy = security_cmd.scan(target=tmp_path, fail_on="none", json_output=True)
+    assert with_legacy == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["finding_count"] == 1
+    assert payload["suppressed_count"] == 0
+    assert payload["findings"][0]["fingerprint"] == finding["fingerprint"]
+
+
 def test_security_review_suppress_and_unsuppress(tmp_path, capsys):
     (tmp_path / ".env").write_text("SERVICE_TOKEN=abcd1234abcd1234abcd1234\n")
     output_dir = tmp_path / ".brigade" / "security" / "latest"