Skip to content

Index

diapason.security

Security guardrails — scanners, engine wrapper, audit, SSRF.

AuditLogger

Append-only SQLite audit log for security events.

Parameters

db_path: Path to the SQLite database file. bus: Optional event bus — if provided, subscribes to security events (SECURITY_SCAN, SECURITY_ALERT, SECURITY_BLOCK).

close()

Close the SQLite connection.

count()

Return the total number of logged security events.

log(event)

Insert a security event into the audit log with Merkle hash chain.

query(*, event_type=None, since=None, limit=100)

Query logged security events with optional filters.

tail_hash()

Return the hash of the last row in the chain, or empty string.

verify_chain()

Verify the Merkle hash chain integrity.

Returns

tuple (True, None) if the chain is valid, or (False, row_id) where row_id is the first broken link.

BaseScanner

Bases: ABC

Base class for all security scanners.

Subclasses implement pattern-based scanning for secrets, PII, or other sensitive content.

redact(text) abstractmethod

Return text with sensitive matches replaced by redaction markers.

scan(text) abstractmethod

Scan text and return findings.

BoundaryGuard

Scans outbound content for secrets and PII at device boundaries.

Parameters

mode: Action on findings: "redact" replaces matches, "warn" logs but passes through, "block" raises. enabled: Master switch. When False, all content passes through. bus: Optional event bus for publishing SECURITY_ALERT events. scanners: Custom scanners. Defaults to SecretScanner + PIIScanner.

check_outbound(tool_call)

Scan tool call arguments before execution.

Returns a new ToolCall with redacted arguments if needed.

redact_for_storage(content)

Always redact secrets and PII before telemetry or trace storage.

scan_outbound(content, destination)

Scan text before it leaves the device.

Returns redacted text in "redact" mode, original text in "warn" mode, or raises SecurityBlockError in "block" mode when findings are detected.

GuardrailsEngine

Bases: InferenceEngine

Wraps an existing InferenceEngine with security scanning.

Not registered in EngineRegistry — instantiated dynamically to wrap any engine at runtime.

Parameters

engine: The wrapped inference engine. scanners: List of scanners to run. Defaults to SecretScanner + PIIScanner. mode: Action taken on findings: WARN, REDACT, or BLOCK. scan_input: Whether to scan input messages. scan_output: Whether to scan output content. bus: Optional event bus for publishing security events.

engine_id property

Delegate to the wrapped engine.

generate(messages, *, model, temperature=0.7, max_tokens=1024, **kwargs)

Scan input, call wrapped engine, scan output.

health()

Delegate to wrapped engine.

list_models()

Delegate to wrapped engine.

stream(messages, *, model, temperature=0.7, max_tokens=1024, **kwargs) async

Use the same safe boundaries as rich output, including long secrets.

stream_full(messages, *, model, temperature=0.7, max_tokens=1024, **kwargs) async

Stream verified text without releasing tools or terminal data early.

PIIScanner

Bases: BaseScanner

Detect personally identifiable information in text.

redact(text)

Replace PII matches with [REDACTED:{pattern_name}].

scan(text)

Scan text for PII patterns using Rust or the safe fallback.

RedactionMode

Bases: str, Enum

Action mode when findings are detected.

ScanFinding dataclass

A single finding from a security scanner.

ScanResult dataclass

Aggregated result from one or more scanners.

clean property

Return True if no findings were detected.

highest_threat property

Return the highest threat level among findings, or None.

SecretScanner

Bases: BaseScanner

Detect API keys, tokens, passwords, and other secrets in text.

redact(text)

Replace secret matches with [REDACTED:{pattern_name}].

scan(text)

Scan text for secret patterns using Rust or the safe fallback.

SecurityBlockError

Bases: Exception

Raised when mode is BLOCK and security findings are detected.

SecurityContext dataclass

Result of setup_security() — wrapped engine, policy, audit.

SecurityEvent dataclass

A recorded security event for audit logging.

SecurityEventType

Bases: str, Enum

Categories of security events.

ThreatLevel

Bases: str, Enum

Severity classification for security findings.

check_ssrf(url)

Check a URL for SSRF vulnerabilities.

Prefers the Rust backend, but falls back to the pure-Python implementation when the compiled extension is unavailable. The SSRF guard is security-critical, so it must never be silently skipped — or crash with ImportError — merely because Rust was not built.

filter_sensitive_paths(paths)

Return only non-sensitive paths from paths.

is_private_ip(ip_str)

Check if an IP address is private/reserved.

is_sensitive_file(path)

Return True if path matches a sensitive file pattern.

Checks both the filename and the full name against DEFAULT_SENSITIVE_PATTERNS using :func:fnmatch.fnmatch. Uses the Rust implementation when available, falls back to Python.

setup_security(config, engine, bus=None)

Apply security guardrails to an engine based on config.

Returns a SecurityContext. No-ops if config.security.enabled is False.