agentblaster 0.1.0__py3-none-any.whl

agentblaster/rate_limits.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import time
+from threading import Lock
+from typing import Any, Callable
+
+
+def request_interval_seconds(rate_limits: dict[str, Any]) -> float | None:
+    intervals: list[float] = []
+    requests_per_second = _number(_first_present(rate_limits.get("requests_per_second"), rate_limits.get("rps")))
+    requests_per_minute = _number(
+        _first_present(
+            rate_limits.get("requests_per_minute"),
+            rate_limits.get("rpm"),
+            rate_limits.get("max_requests_per_minute"),
+        )
+    )
+    if requests_per_second and requests_per_second > 0:
+        intervals.append(1 / requests_per_second)
+    if requests_per_minute and requests_per_minute > 0:
+        intervals.append(60 / requests_per_minute)
+    return max(intervals) if intervals else None
+
+
+def rate_limit_max_concurrency(rate_limits: dict[str, Any]) -> int | None:
+    value = _number(_first_present(rate_limits.get("max_concurrency"), rate_limits.get("concurrency")))
+    if value is None or value <= 0:
+        return None
+    return int(value)
+
+
+class RateLimitPacer:
+    """Thread-safe request pacer for provider-level request rate limits."""
+
+    def __init__(
+        self,
+        rate_limits: dict[str, Any],
+        *,
+        sleep_fn: Callable[[float], None] = time.sleep,
+        monotonic_fn: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.interval_seconds = request_interval_seconds(rate_limits)
+        self._sleep = sleep_fn
+        self._monotonic = monotonic_fn
+        self._lock = Lock()
+        self._next_allowed_at = 0.0
+
+    def wait(self) -> float:
+        if self.interval_seconds is None:
+            return 0.0
+        with self._lock:
+            now = self._monotonic()
+            wait_seconds = max(self._next_allowed_at - now, 0.0)
+            scheduled_at = max(now, self._next_allowed_at)
+            self._next_allowed_at = scheduled_at + self.interval_seconds
+        if wait_seconds > 0:
+            self._sleep(wait_seconds)
+        return round(wait_seconds * 1000, 3)
+
+
+def _number(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _first_present(*values):
+    for value in values:
+        if value is not None:
+            return value
+    return None

agentblaster/readiness.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from agentblaster.capabilities import check_suite_compatibility
+from agentblaster.contract_check import provider_contract_plan
+from agentblaster.metric_coverage import metric_coverage_for_provider
+from agentblaster.models import ProviderConfig, SuiteDefinition
+from agentblaster.policy import SecurityPolicy
+from agentblaster.provider_audit import audit_providers
+
+READINESS_SCHEMA_VERSION = "agentblaster.benchmark-readiness.v1"
+
+
+def build_readiness_dossier(
+    *,
+    provider: ProviderConfig,
+    suite: SuiteDefinition,
+    policy: SecurityPolicy,
+    model: str | None = None,
+    strict_unknown: bool = False,
+) -> dict[str, Any]:
+    """Build a no-network benchmark readiness dossier for one provider and suite."""
+    provider_audit = audit_providers([provider], policy).model_dump(mode="json")
+    capability_report = check_suite_compatibility(provider, suite, strict_unknown=strict_unknown).model_dump(mode="json")
+    contract_plan = provider_contract_plan(provider, model=model)
+    metric_coverage = metric_coverage_for_provider(provider)
+    provider_auth_posture = _provider_auth_posture(provider_audit)
+    secret_backend_posture = _compact_secret_backend_posture(provider_audit.get("secret_backend_posture"))
+    blocking_findings = _blocking_findings(provider_audit, capability_report, contract_plan)
+    contract_capability_evidence = contract_plan.get("capability_evidence", {})
+    warnings = _warnings(provider_audit, capability_report, metric_coverage, contract_plan)
+    return {
+        "schema_version": READINESS_SCHEMA_VERSION,
+        "provider": provider.name,
+        "suite": suite.name,
+        "model": model or provider.default_model or "<required>",
+        "ready": not blocking_findings,
+        "strict_unknown": strict_unknown,
+        "summary": {
+            "policy_ok": provider_audit["policy_ok"] == provider_audit["total_providers"] and provider_audit["errors"] == 0,
+            "suite_compatible": capability_report["compatible"],
+            "contract_checks_planned": contract_plan["summary"]["planned"],
+            "contract_capabilities_directly_checked": len(
+                contract_capability_evidence.get("directly_checked", [])
+                if isinstance(contract_capability_evidence.get("directly_checked"), list)
+                else []
+            ),
+            "contract_capabilities_proxy_checked": len(
+                contract_capability_evidence.get("proxy_checked", [])
+                if isinstance(contract_capability_evidence.get("proxy_checked"), list)
+                else []
+            ),
+            "contract_capabilities_not_covered": len(
+                contract_capability_evidence.get("not_covered", [])
+                if isinstance(contract_capability_evidence.get("not_covered"), list)
+                else []
+            ),
+            "metric_coverage_score": metric_coverage["summary"]["coverage_score"],
+            "provider_auth_writable_backends": sum(1 for item in provider_auth_posture if item["api_key_ref_writable_backend"]),
+            "provider_auth_plaintext_fallbacks": sum(1 for item in provider_auth_posture if item["api_key_ref_plaintext_fallback"]),
+            "provider_auth_prewrite_policy_guards_recommended": sum(
+                1 for item in provider_auth_posture if item["prewrite_policy_guard_recommended"]
+            ),
+            "provider_auth_keyring_required": sum(
+                1 for entry in provider_audit["providers"] if entry.get("keyring_backend_required")
+            ),
+            "keyring_dependency_available": secret_backend_posture.get("keyring_dependency_available"),
+            "blocking_findings": len(blocking_findings),
+            "warnings": len(warnings),
+        },
+        "blocking_findings": blocking_findings,
+        "warnings": warnings,
+        "provider_auth_posture": provider_auth_posture,
+        "secret_backend_posture": secret_backend_posture,
+        "provider_audit": provider_audit,
+        "suite_capabilities": capability_report,
+        "contract_plan": contract_plan,
+        "contract_capability_evidence": contract_capability_evidence,
+        "metric_coverage": metric_coverage,
+        "security_notes": [
+            "Readiness dossier is static and does not contact endpoints, resolve secrets, or read raw traces.",
+            "Contract checks are planned only; use providers contract-check --execute explicitly for live checks.",
+            "Remote execution remains governed by policy and explicit allow-remote flags on execution commands.",
+        ],
+    }
+
+
+def write_readiness_json(report: dict[str, Any], output: Path) -> Path:
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(report, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return output
+
+
+def format_readiness_report(report: dict[str, Any]) -> str:
+    lines = [
+        "AgentBlaster benchmark readiness dossier",
+        f"provider: {report['provider']}",
+        f"suite: {report['suite']}",
+        f"model: {report['model']}",
+        f"ready: {str(report['ready']).lower()}",
+        f"strict_unknown: {str(report['strict_unknown']).lower()}",
+        "summary:",
+    ]
+    for key, value in report["summary"].items():
+        lines.append(f"- {key}: {value}")
+    lines.append("blocking_findings:")
+    if not report["blocking_findings"]:
+        lines.append("- none")
+    else:
+        for finding in report["blocking_findings"]:
+            lines.append(f"- {finding['source']}:{finding['code']} {finding['message']}")
+    lines.append("warnings:")
+    if not report["warnings"]:
+        lines.append("- none")
+    else:
+        for warning in report["warnings"]:
+            lines.append(f"- {warning['source']}:{warning['code']} {warning['message']}")
+    lines.append("provider_auth_posture:")
+    auth_posture = report.get("provider_auth_posture", [])
+    if not auth_posture:
+        lines.append("- none")
+    else:
+        for posture in auth_posture:
+            lines.append(
+                f"- {posture['provider']}: "
+                f"secret={posture['api_key_ref_kind'] or 'none'} "
+                f"configured={_bool_text(posture['api_key_ref_configured'])} "
+                f"writable={_bool_text(posture['api_key_ref_writable_backend'])} "
+                f"plaintext={_bool_text(posture['api_key_ref_plaintext_fallback'])} "
+                f"prewrite_policy_guard_recommended={_bool_text(posture['prewrite_policy_guard_recommended'])}"
+            )
+    secret_backend = report.get("secret_backend_posture") if isinstance(report.get("secret_backend_posture"), dict) else {}
+    lines.append("secret_backend_posture:")
+    if secret_backend:
+        lines.append(f"- keyring_optional: {_bool_text(bool(secret_backend.get('keyring_optional')))}")
+        lines.append(
+            f"- keyring_dependency_available: {_bool_text(bool(secret_backend.get('keyring_dependency_available')))}"
+        )
+        lines.append(f"- recommended_enterprise_backends: {','.join(secret_backend.get('recommended_enterprise_backends', []) or [])}")
+    else:
+        lines.append("- none")
+    return "\n".join(lines) + "\n"
+
+
+def _provider_auth_posture(provider_audit: dict[str, Any]) -> list[dict[str, Any]]:
+    posture: list[dict[str, Any]] = []
+    for entry in provider_audit["providers"]:
+        posture.append(
+            {
+                "provider": entry["name"],
+                "api_key_ref_kind": entry["api_key_ref_kind"],
+                "api_key_ref_configured": entry["api_key_ref_configured"],
+                "api_key_ref_writable_backend": entry["api_key_ref_writable_backend"],
+                "api_key_ref_plaintext_fallback": entry["api_key_ref_plaintext_fallback"],
+                "prewrite_policy_guard_recommended": entry["prewrite_policy_guard_recommended"],
+            }
+        )
+    return posture
+
+
+def _compact_secret_backend_posture(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return {}
+    supported = value.get("supported_secret_ref_kinds") if isinstance(value.get("supported_secret_ref_kinds"), list) else []
+    recommended = (
+        value.get("recommended_enterprise_backends") if isinstance(value.get("recommended_enterprise_backends"), list) else []
+    )
+    return {
+        "env_reference_portable": bool(value.get("env_reference_portable")),
+        "keyring_optional": bool(value.get("keyring_optional")),
+        "keyring_dependency_available": bool(value.get("keyring_dependency_available")),
+        "dotenv_plaintext_fallback_supported": bool(value.get("dotenv_plaintext_fallback_supported")),
+        "dotenv_plaintext_fallback_enterprise_default": bool(value.get("dotenv_plaintext_fallback_enterprise_default")),
+        "supported_secret_ref_kinds": [str(item) for item in supported[:6]],
+        "recommended_enterprise_backends": [str(item) for item in recommended[:6]],
+    }
+
+
+def _bool_text(value: bool) -> str:
+    return str(value).lower()
+
+
+def _blocking_findings(
+    provider_audit: dict[str, Any],
+    capability_report: dict[str, Any],
+    contract_plan: dict[str, Any],
+) -> list[dict[str, str]]:
+    findings: list[dict[str, str]] = []
+    for entry in provider_audit["providers"]:
+        for finding in entry["findings"]:
+            if finding["severity"] == "error":
+                findings.append({"source": "provider_audit", "code": finding["code"], "message": finding["message"]})
+    for finding in capability_report["missing"]:
+        findings.append({"source": "suite_capabilities", "code": f"missing_{finding['key']}", "message": finding["message"]})
+    if capability_report["strict_unknown"]:
+        for finding in capability_report["unknown"]:
+            findings.append({"source": "suite_capabilities", "code": f"unknown_{finding['key']}", "message": finding["message"]})
+    if contract_plan["model"] == "<required>":
+        findings.append({"source": "contract_plan", "code": "model_required", "message": "model is required before executing contract or benchmark checks"})
+    return findings
+
+
+def _warnings(
+    provider_audit: dict[str, Any],
+    capability_report: dict[str, Any],
+    metric_coverage: dict[str, Any],
+    contract_plan: dict[str, Any],
+) -> list[dict[str, str]]:
+    warnings: list[dict[str, str]] = []
+    for entry in provider_audit["providers"]:
+        for finding in entry["findings"]:
+            if finding["severity"] == "warning":
+                warnings.append({"source": "provider_audit", "code": finding["code"], "message": finding["message"]})
+    if not capability_report["strict_unknown"]:
+        for finding in capability_report["unknown"]:
+            warnings.append({"source": "suite_capabilities", "code": f"unknown_{finding['key']}", "message": finding["message"]})
+    capability_evidence = contract_plan.get("capability_evidence") if isinstance(contract_plan.get("capability_evidence"), dict) else {}
+    not_covered = capability_evidence.get("not_covered") if isinstance(capability_evidence.get("not_covered"), list) else []
+    for item in not_covered:
+        if isinstance(item, dict) and item.get("capability"):
+            capability = str(item["capability"])
+            warnings.append(
+                {
+                    "source": "contract_capability_evidence",
+                    "code": f"not_covered_{capability}",
+                    "message": f"contract-check planning does not prove capability: {capability}",
+                }
+            )
+    unavailable = [field["field"] for field in metric_coverage["fields"] if field["status"] == "unavailable"]
+    if unavailable:
+        warnings.append(
+            {
+                "source": "metric_coverage",
+                "code": "unavailable_metrics",
+                "message": "unavailable normalized metrics: " + ", ".join(sorted(unavailable)[:12]),
+            }
+        )
+    return warnings

agentblaster/redaction.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, MutableMapping, Sequence
+from typing import Any
+
+SECRET_HEADER_NAMES = {
+    "authorization",
+    "x-api-key",
+    "api-key",
+    "openai-api-key",
+    "anthropic-api-key",
+}
+
+SECRET_PATTERNS = [
+    re.compile(r"sk-ant-[A-Za-z0-9_\-]{16,}"),
+    re.compile(r"sk-(?!ant-)[A-Za-z0-9_\-]{16,}"),
+    re.compile(r"gh[opusr]_[A-Za-z0-9_]{16,}"),
+    re.compile(r"Bearer\s+[A-Za-z0-9._\-]{16,}", re.IGNORECASE),
+]
+
+
+def redact_text(value: str) -> str:
+    redacted = value
+    for pattern in SECRET_PATTERNS:
+        redacted = pattern.sub("[REDACTED]", redacted)
+    return redacted
+
+
+def redact_mapping_headers(headers: Mapping[str, Any]) -> dict[str, Any]:
+    redacted: dict[str, Any] = {}
+    for key, value in headers.items():
+        if key.lower() in SECRET_HEADER_NAMES:
+            redacted[key] = "[REDACTED]"
+        elif isinstance(value, str):
+            redacted[key] = redact_text(value)
+        else:
+            redacted[key] = redact_value(value)
+    return redacted
+
+
+def redact_value(value: Any) -> Any:
+    if isinstance(value, str):
+        return redact_text(value)
+    if isinstance(value, Mapping):
+        return redact_mapping_headers(value)
+    if isinstance(value, Sequence) and not isinstance(value, bytes | bytearray | str):
+        return [redact_value(item) for item in value]
+    return value
+
+
+def redact_in_place(value: MutableMapping[str, Any]) -> MutableMapping[str, Any]:
+    for key in list(value.keys()):
+        if key.lower() in SECRET_HEADER_NAMES:
+            value[key] = "[REDACTED]"
+        else:
+            value[key] = redact_value(value[key])
+    return value

agentblaster/redaction_scan.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from zipfile import BadZipFile, ZipFile
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from agentblaster.errors import ConfigError
+
+
+SCAN_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("anthropic_api_key", re.compile(r"sk-ant-[A-Za-z0-9_\-]{16,}")),
+    ("openai_api_key", re.compile(r"sk-(?!ant-)[A-Za-z0-9_\-]{16,}")),
+    ("github_token", re.compile(r"gh[opusr]_[A-Za-z0-9_]{16,}")),
+    ("bearer_token", re.compile(r"Bearer\s+[A-Za-z0-9._\-]{16,}", re.IGNORECASE)),
+    ("aws_access_key_id", re.compile(r"AKIA[0-9A-Z]{16}")),
+    ("macos_user_path", re.compile(r"/Users/[A-Za-z0-9._\-]+(?:/[^\s\"']*)?")),
+    ("macos_volume_path", re.compile(r"/Volumes/[A-Za-z0-9._\-]+(?:/[^\s\"']*)?")),
+    ("private_local_path", re.compile(r"/private/[A-Za-z0-9._\-/]+")),
+    ("windows_user_path", re.compile(r"[A-Za-z]:[\\/]+Users[\\/]+[A-Za-z0-9._\-]+(?:[\\/]+[^\s\"']*)?")),
+]
+TEXT_SUFFIXES = {
+    ".csv",
+    ".html",
+    ".json",
+    ".jsonl",
+    ".log",
+    ".md",
+    ".svg",
+    ".txt",
+    ".yaml",
+    ".yml",
+    ".xml",
+}
+ZIP_SUFFIXES = {".zip"}
+REDACTION_SCAN_SCHEMA_VERSION = "agentblaster.redaction-scan.v1"
+
+
+class RedactionScanFinding(BaseModel):
+    """Secret-like pattern finding without the matched secret value."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    entry: str | None = None
+    line: int | None = None
+    pattern: str
+    message: str
+
+
+class RedactionScanReport(BaseModel):
+    """Redaction scan report for release/publishing gates."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: str = REDACTION_SCAN_SCHEMA_VERSION
+    ok: bool
+    total_paths: int = Field(ge=0)
+    scanned_items: int = Field(ge=0)
+    skipped_items: int = Field(ge=0)
+    findings: list[RedactionScanFinding] = Field(default_factory=list)
+    security_notes: list[str] = Field(default_factory=list)
+
+
+def scan_paths(paths: list[Path], *, max_bytes: int = 2_000_000) -> RedactionScanReport:
+    if not paths:
+        raise ConfigError("redaction scan requires at least one path")
+    findings: list[RedactionScanFinding] = []
+    scanned = 0
+    skipped = 0
+    for input_path in paths:
+        if not input_path.exists():
+            raise ConfigError(f"redaction scan path does not exist: {input_path}")
+        for path in _iter_files(input_path):
+            if path.suffix.lower() in ZIP_SUFFIXES:
+                zip_scanned, zip_skipped = _scan_zip(path, findings, max_bytes=max_bytes)
+                scanned += zip_scanned
+                skipped += zip_skipped
+                continue
+            if not _looks_textual(path):
+                skipped += 1
+                continue
+            try:
+                data = path.read_bytes()
+            except OSError as exc:
+                raise ConfigError(f"unable to read scan path {path}: {exc}") from exc
+            if len(data) > max_bytes:
+                skipped += 1
+                continue
+            text = _decode_text(data)
+            if text is None:
+                skipped += 1
+                continue
+            scanned += 1
+            findings.extend(_scan_text(text, path=_safe_report_path(path), entry=None))
+    return RedactionScanReport(
+        ok=not findings,
+        total_paths=len(paths),
+        scanned_items=scanned,
+        skipped_items=skipped,
+        findings=findings,
+        security_notes=[
+            "Redaction scan reports pattern names and locations only; matched secret values are never included.",
+            "This is a deterministic regex gate for common secret formats, not a complete DLP system.",
+        ],
+    )
+
+
+def format_redaction_scan_report(report: RedactionScanReport) -> str:
+    lines = [
+        f"schema_version: {report.schema_version}",
+        f"ok: {str(report.ok).lower()}",
+        f"total_paths: {report.total_paths}",
+        f"scanned_items: {report.scanned_items}",
+        f"skipped_items: {report.skipped_items}",
+        f"findings: {len(report.findings)}",
+    ]
+    for finding in report.findings:
+        location = finding.path if finding.entry is None else f"{finding.path}!{finding.entry}"
+        if finding.line is not None:
+            location = f"{location}:{finding.line}"
+        lines.append(f"{finding.pattern}	{location}	{finding.message}")
+    return "\n".join(lines) + "\n"
+
+
+def redaction_scan_json(report: RedactionScanReport) -> str:
+    return json.dumps(report.model_dump(mode="json"), indent=2, sort_keys=True) + "\n"
+
+
+def _iter_files(path: Path):
+    if path.is_file():
+        yield path
+        return
+    for child in sorted(item for item in path.rglob("*") if item.is_file()):
+        yield child
+
+
+def _looks_textual(path: Path) -> bool:
+    return path.suffix.lower() in TEXT_SUFFIXES or path.suffix == ""
+
+
+def _scan_zip(path: Path, findings: list[RedactionScanFinding], *, max_bytes: int) -> tuple[int, int]:
+    scanned = 0
+    skipped = 0
+    try:
+        with ZipFile(path) as archive:
+            for info in sorted(archive.infolist(), key=lambda item: item.filename):
+                if info.is_dir():
+                    continue
+                entry_report_label = _zip_entry_report_label(info.filename)
+                findings.extend(_scan_zip_entry_name(info.filename, path=_safe_report_path(path)))
+                entry_path = Path(info.filename)
+                if entry_path.suffix.lower() not in TEXT_SUFFIXES:
+                    skipped += 1
+                    continue
+                if info.file_size > max_bytes:
+                    skipped += 1
+                    continue
+                text = _decode_text(archive.read(info))
+                if text is None:
+                    skipped += 1
+                    continue
+                scanned += 1
+                findings.extend(_scan_text(text, path=_safe_report_path(path), entry=entry_report_label))
+    except (OSError, BadZipFile) as exc:
+        raise ConfigError(f"unable to scan zip artifact {path}: {exc}") from exc
+    return scanned, skipped
+
+
+def _scan_zip_entry_name(entry: str, *, path: str) -> list[RedactionScanFinding]:
+    findings: list[RedactionScanFinding] = []
+    normalized = entry.replace("\\", "/")
+    parts = [part for part in normalized.split("/") if part not in {"", "."}]
+    safe_entry = _safe_zip_entry_label(entry)
+    if normalized.startswith("/") or re.match(r"^[A-Za-z]:/", normalized) or ".." in parts:
+        findings.append(
+            RedactionScanFinding(
+                path=path,
+                entry=safe_entry,
+                line=None,
+                pattern="zip_unsafe_entry_path",
+                message="unsafe zip entry path detected; archive member name suppressed from extracted paths",
+            )
+        )
+    for name, pattern in SCAN_PATTERNS:
+        if pattern.search(entry):
+            findings.append(
+                RedactionScanFinding(
+                    path=path,
+                    entry=safe_entry,
+                    line=None,
+                    pattern=name,
+                    message="secret-like or local-path pattern detected in zip entry name; matched value suppressed",
+                )
+            )
+    return findings
+
+
+def _zip_entry_report_label(entry: str) -> str:
+    normalized = entry.replace("\\", "/")
+    parts = [part for part in normalized.split("/") if part not in {"", "."}]
+    unsafe = normalized.startswith("/") or re.match(r"^[A-Za-z]:/", normalized) or ".." in parts
+    sensitive = any(pattern.search(entry) for _, pattern in SCAN_PATTERNS)
+    if unsafe or sensitive:
+        return _safe_zip_entry_label(entry)
+    return entry
+
+
+def _safe_zip_entry_label(entry: str) -> str:
+    normalized = entry.replace("\\", "/")
+    parts = [part for part in normalized.split("/") if part not in {"", ".", ".."}]
+    label = parts[-1] if parts else "<redacted-entry>"
+    if any(pattern.search(label) for _, pattern in SCAN_PATTERNS):
+        return "<redacted-entry>"
+    return label or "<redacted-entry>"
+
+
+def _decode_text(data: bytes) -> str | None:
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
+def _safe_report_path(path: Path) -> str:
+    if path.is_absolute():
+        return path.name
+    return path.as_posix()
+
+
+def _scan_text(text: str, *, path: str, entry: str | None) -> list[RedactionScanFinding]:
+    findings: list[RedactionScanFinding] = []
+    for line_number, line in enumerate(text.splitlines(), start=1):
+        for name, pattern in SCAN_PATTERNS:
+            if pattern.search(line):
+                findings.append(
+                    RedactionScanFinding(
+                        path=path,
+                        entry=entry,
+                        line=line_number,
+                        pattern=name,
+                        message="secret-like pattern detected; matched value suppressed",
+                    )
+                )
+    return findings