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.
BaseScanner
¶
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.
RedactionMode
¶
Bases: str, Enum
Action mode when findings are detected.
ScanFinding
dataclass
¶
A single finding from a security scanner.
ScanResult
dataclass
¶
SecretScanner
¶
Bases: BaseScanner
Detect API keys, tokens, passwords, and other secrets in text.
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.