AI Guardian Documentation¶
This directory contains detailed documentation for AI Guardian. The main README.md provides a quick overview; these docs cover configuration, features, and architecture in depth.
The documentation is published on Read the Docs.
Documentation site¶
The MkDocs site is generated and published by CI/CD through Read the Docs. A local preview is optional and is not required for documentation changes. To preview the site on demand:
To generate the static site locally on demand, run mkdocs build. The generated
site/ directory is not committed.
Getting Started¶
| Document | Description |
|---|---|
| Configuration Guide | Config file locations, options, precedence, and remote configs |
| Configuration Cookbook | Practical Q&A pairs for common configuration tasks |
| Scanner Installation | Install and manage pinned secret scanner engines |
| TOML Pattern Engine | Built-in Python scanner with 267 pre-compiled TOML patterns |
| Console Guide | Interactive TUI for managing configuration |
| Hook Ordering | How hooks work and ordering requirements |
| Troubleshooting | Daemon, tray, container, and OpenShell issue resolution |
Security Features¶
| Document | Description |
|---|---|
| Security Overview | Index of all security feature documentation |
| Secret Scanning | Secret detection, pattern server, false positives |
| Prompt Injection | Heuristic detection, sensitivity, allowlists |
| SSRF Protection | Private IP blocking, metadata endpoints, limitations |
| Unicode Attacks | Zero-width chars, bidi override, homoglyphs |
| Directory Rules | .ai-read-deny markers and config-based rules |
| Credential Exfiltration | Config file scanning for exfiltration patterns |
| Secret Redaction | Masking secrets in tool outputs |
| Image Scanning (OCR) | OCR-based secret/PII detection in images, IDE limitations |
| Inline Annotations | Suppress false positives with per-line or block annotations |
Observability¶
| Document | Description |
|---|---|
| Observability Guide | OTEL export, Grafana integration, span hierarchy, CLI trace export |
Architecture & Policy¶
| Document | Description |
|---|---|
| Security Design | Architecture principles, self-protection, known limitations |
| Tool Policy | Allow/deny lists for Skills, MCP, Bash, Write |
| Permissions Comparison | ai-guardian vs settings.json permissions |
| Violation Logging | JSON audit trail with unified policy decisions |
| Compliance Audit Logging | Sanitized all-decision audit trail for SOC 2, GDPR, and HIPAA |
AI Security Awareness¶
| Document | Description |
|---|---|
| MCP Server | MCP security advisor server — tools, setup, proactive levels, support bundles |
| MCP Security Scanning | Audit MCP server configs and source code for credential exposure, supply chain risks |
| Multi-Daemon Tray | Discover and manage daemons across local, Podman/Docker, and Kubernetes |
IDE Integration¶
| Document | Description |
|---|---|
| IDE/Agent Integration Checklist | Implementation, testing, documentation, and release checklist for integrations |
| Agent Support | Multi-agent hook adapters — capability matrix, setup, and architecture, including Grok Build |
| Pre-commit Hook | Scan staged files for secrets before commit |
| GitHub Copilot Setup | Setup guide for GitHub Copilot |
| Aider Setup | Git hook integration for Aider |
| AiderDesk Setup | Setup guide for AiderDesk |
| Multi-Engine Support | Scanner engine options and future plans |
| Pattern Server | Enterprise pattern server configuration |
Container¶
| Document | Description |
|---|---|
| Sandbox CLI | Named Docker/Podman and OpenShell sandbox lifecycle management and native command mappings |
| CLI/Runtime Integration Checklist | Onboarding and validation checklist for container and OpenShell CLI support |
| Container Image | UBI-based image with supported agent integrations, published to quay.io |
Development¶
| Document | Description |
|---|---|
| Developer Guide | Architecture, setup, testing, and development workflows |
| Scanner Integration Checklist | License, installation, testing, and documentation checklist for scanner engines and detectors |
| Contributing | Fork workflow, PR guidelines |
| Agent Instructions | Development guidelines, testing, CI/CD |
| Releasing | Release process and version management |
| Changelog | Version history |