SDK API reference¶
ai_guardian.sdk
¶
AI Guardian SDK — programmatic security checking for Python agent programs.
Provides opt-in protection for programs where IDE hooks don't apply (LangChain, custom scripts, direct LLM API calls, etc.).
This SDK is additive — it cannot bypass or weaken existing hook-based enforcement. Hooks remain the enforcement layer for IDE sessions.
Usage
from ai_guardian.sdk import monitor
Direct mode (default) — in-process, no daemon¶
with monitor() as session: session.check_content(text) session.check_file("/path/to/file") session.check_command("curl http://example.com")
REST mode — delegates to daemon, auto-starts if needed¶
with monitor(mode="rest") as session: session.check_content(text)
Config overlay — deep-merge on top of global + project config¶
from ai_guardian import configure configure(overlay={"secret_scanning": {"enabled": True}}) with monitor() as session: session.check_content(text)
Or via environment variables (CI/CD):¶
AI_GUARDIAN_CONFIG_OVERLAY=/path/to/overlay.json¶
AI_GUARDIAN_CONFIG_INLINE='{"preferred_ui":"headless"}'¶
CheckResult
dataclass
¶
Result of a security check.
SecurityViolation
¶
Bases: Exception
Raised when a blocked finding is detected.
GuardSession
¶
Base session with shared action-handling logic.
results
property
¶
All results collected during this session.
secret_redaction_enabled
property
¶
Whether to redact secrets in live content (not traces).
SDK defaults to False — content flows unchanged between agent
turns. Set to True via config to sanitize content same as hooks.
Trace sanitization is independent of this flag.
check_content(text, *, filename='input', source_command=None, context=None)
¶
Check text for secrets, prompt injection, context poisoning.
check_file(file_path, content=None, *, context=None)
¶
Check file path access and optionally scan file content.
check_command(command, *, context=None)
¶
Check a bash command for threats.
sanitize(text, *, context=None)
¶
Sanitize text, redacting secrets and PII.
sanitize_batch(texts)
¶
Batch-sanitize texts, reusing compiled patterns across all entries.
Returns sanitized strings in the same order as texts.
Default implementation loops over :meth:sanitize; subclasses
override to amortize pattern compilation.
get_violations(*, tool_use_id=None, session_id=None, violation_type=None, limit=50)
¶
Query hook-triggered violations with sanitized output.
Returns violation records with secrets/PII redacted so results are safe to store in external databases.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_use_id
|
Optional[str]
|
Filter by tool_use_id from hook context |
None
|
session_id
|
Optional[str]
|
Filter by session_id from hook context |
None
|
violation_type
|
Optional[str]
|
Filter by violation type |
None
|
limit
|
int
|
Maximum number of violations to return |
50
|
Returns:
| Type | Description |
|---|---|
List[Dict[str, Any]]
|
List of sanitized violation dicts with: violation_type, message, |
List[Dict[str, Any]]
|
tool_name, tool_use_id, session_id, timestamp, severity |
monitor(mode='direct', config=None, cwd=None, target_dir=None, **kwargs)
¶
Create a guarded session for security checks.
Blocked findings raise SecurityViolation; detected-but-not-blocked
findings emit warnings.warn. Per-scanner actions in the global
config control which findings are blocked vs. detected.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mode
|
str
|
"direct" (in-process, no daemon) or "rest" (daemon, auto-start) |
'direct'
|
config
|
Optional[Dict[str, Any]]
|
Optional config dict override. If None, loads from ai-guardian.json
(respects |
None
|
cwd
|
Optional[str]
|
Project directory for config discovery and language detection. If None, falls back to os.getcwd(). |
None
|
target_dir
|
Optional[str]
|
Directory whose allowlists to trust. When set,
ai-guardian discovers |
None
|
Yields:
| Type | Description |
|---|---|
|
GuardSession with check_content(), check_file(), check_command(), |
|
|
sanitize() methods. |