spanforge.secrets — Secrets scanning engine

Module: spanforge.secrets
Added in: 2.0.3 (Phase 2: sf-secrets)

spanforge.secrets provides a standalone, zero-network-call secrets detection engine with a 20-pattern registry, Shannon entropy scoring, and SARIF 2.1.0 output. The SDK client (spanforge.sdk.secrets.SFSecretsClient) wraps the engine with auto-block policy and optional remote service support.

Quick example

from spanforge.secrets import SecretsScanner

scanner = SecretsScanner()
result = scanner.scan(open("config.env").read())

if result.detected:
    print(f"{len(result.hits)} secret(s) found")
    for hit in result.hits:
        print(f"  {hit.secret_type}  confidence={hit.confidence:.2f}")

# SARIF for GitHub Code Scanning
if result.detected:
    import json
    print(json.dumps(result.to_sarif(), indent=2))

API

SecretsScanner

class SecretsScanner:
    def __init__(
        self,
        confidence_threshold: float = 0.85,
        allowlist: list[str] | None = None,
    ) -> None: ...

scan()

def scan(self, text: str, *, confidence_threshold: float | None = None) -> SecretsScanResult

Scan text for secrets. Returns a SecretsScanResult. Thread-safe. The optional confidence_threshold override applies to this call only.

scan_batch()

async def scan_batch(self, texts: list[str]) -> list[SecretsScanResult]

Scan multiple texts in parallel using asyncio.gather. Falls back to sequential execution when the event loop is not running.

SecretsScanResult

@dataclass
class SecretsScanResult:
    detected: bool
    hits: list[SecretHit]
    auto_blocked: bool
    redacted_text: str

    def to_dict(self) -> dict: ...
    def to_sarif(self) -> dict: ...

to_dict() — Returns a JSON-serialisable dict suitable for logging or --format json CLI output.

to_sarif() — Returns a SARIF 2.1.0 log object (as a dict) that can be uploaded to GitHub Code Scanning or consumed by VS Code's SARIF viewer.

SecretHit

@dataclass(frozen=True)
class SecretHit:
    secret_type: str
    start: int
    end: int
    confidence: float
    redacted_value: str

entropy_score()

def entropy_score(s: str) -> float

Compute the Shannon entropy of s in bits per character. A score ≥ 3.5 for a string of ≥ 32 characters is used as a secondary confidence booster inside the scanner. Available as a standalone utility for custom scoring logic.

from spanforge.secrets import entropy_score

print(entropy_score("AKIAIOSFODNN7EXAMPLE"))   # ~3.8 — high entropy
print(entropy_score("YOUR_KEY_HERE"))           # ~2.1 — low entropy (placeholder)

Confidence model

Registered secret types

SDK client — spanforge.sdk.secrets

from spanforge.sdk.secrets import SFSecretsClient
from spanforge.sdk import sf_secrets  # singleton

SFSecretsClient wraps SecretsScanner with:

• Auto-block policy — raises SFSecretsBlockedError when a zero-tolerance type is detected and SPANFORGE_SECRETS_AUTO_BLOCK=true
• Remote forwarding — POST /v1/scan/secrets when SPANFORGE_SF_SECRETS_ENDPOINT is set; falls back to local scan on error
• Inherits retry logic and circuit breaker from SFServiceClient

from spanforge.sdk import sf_secrets
from spanforge.sdk._exceptions import SFSecretsBlockedError

try:
    result = sf_secrets.scan(open("deploy.sh").read())
    print("Clean:", not result.detected)
except SFSecretsBlockedError as exc:
    print(f"Blocked — detected: {exc.secret_types}")

Exceptions

Environment variables

scan_async(text, *, threshold=None) → Coroutine[SecretsScanResult]

Async variant of scan(). Runs the scan in a thread-pool executor so it does not block the event loop. Suitable for use inside async def handlers.

import asyncio
from spanforge.sdk import sf_secrets

async def check_output(text: str):
    result = await sf_secrets.scan_async(text)
    if result.detected:
        print(f"Found secrets: {[h.secret_type for h in result.hits]}")

asyncio.run(check_output(response_text))

Accepts the same parameters and returns the same SecretsScanResult as scan().

See also

• Configuration reference
• CLI reference — secrets scan
• Runbook — Secrets Scanning
• spanforge.identity — identity and JWT audit events
• spanforge.redact — PII detection and redaction