ai-guardian 1.7.0

AI IDE security hook: blocks directories, scans secrets, and protects AI interactions

AI Guardian

AI IDE security hook: controls MCP/skill permissions, blocks directories, detects prompt injection, scans secrets

AI Guardian provides comprehensive protection for AI IDE interactions through multiple security layers. It is not a silver bullet — use it as one layer in a defense-in-depth strategy. See Security Design for limitations and architecture.

Quick Start

pip install ai-guardian
ai-guardian setup --ide claude --create-config --mcp --install-scanner

This single command:

• Installs a scanner engine (gitleaks)
• Creates ai-guardian.json config with secure defaults
• Installs IDE hooks (PreToolUse, PostToolUse, UserPromptSubmit)
• Sets up the MCP security advisor for AI-aware protection

Security Profiles

Choose a profile that matches your environment:

ai-guardian setup --ide claude --create-config --profile @minimal --mcp --install-scanner
ai-guardian setup --ide claude --create-config --profile @strict --mcp --install-scanner

Profile	Secrets	PII	Prompt Injection	SSRF
@minimal	block	warn	low	warn
@standard (default)	block	block	medium	block
@strict	block	block	high	block

Features

Feature	Description	Docs
Secret Scanning	Multi-layered detection of API keys, tokens, passwords	docs/security/SECRET_SCANNING.md
PII Detection	Detect personally identifiable information	docs/security/SECRET_SCANNING.md
Prompt Injection	Heuristic detection with configurable sensitivity	docs/security/PROMPT_INJECTION.md
Unicode Attack Detection	Zero-width chars, bidi override, homoglyphs	docs/security/UNICODE_ATTACKS.md
SSRF Protection	Block private IPs, cloud metadata, dangerous schemes	docs/security/SSRF_PROTECTION.md
Config File Scanning	Detect exfiltration of sensitive config files	docs/security/CREDENTIAL_EXFILTRATION.md
Directory Blocking	.ai-read-deny markers + config-based rules	docs/security/DIRECTORY_RULES.md
Tool Permissions	Allow/deny lists for Skills, MCP, Bash, Write	docs/TOOL_POLICY.md
Violation Logging	JSON audit trail of all blocked operations	docs/VIOLATION_LOGGING.md
Sanitize Command	Clean sensitive data from files	docs/security/SECRET_REDACTION.md
Interactive Console	TUI for managing configuration visually	docs/CONSOLE.md
Scanner Management	Install and manage 7 scanner engines	docs/SCANNER_INSTALLATION.md
Pre-commit Hook	Scan staged files for secrets before commit	docs/PRE_COMMIT.md
Inline Annotations	Suppress false positives with ai-guardian:allow and block annotations	docs/ANNOTATIONS.md
Self-Protection	Prevents AI from disabling its own security controls	docs/SECURITY_DESIGN.md
MCP Security Advisor	Read-only security tools for AI agents (proactive checks)	docs/MCP_SERVER.md

Default Behavior (No Configuration File)

ai-guardian provides protection immediately with zero configuration:

Feature	Default	Notes
Secret scanning	Enabled	Requires gitleaks/scanner installed
Prompt injection detection	Enabled	Heuristic detector
Config file scanning	Enabled	Detects exfiltration patterns
SSRF protection	Enabled	Blocks private IPs, metadata endpoints
Immutable file protection	Enabled	Cannot be disabled
.ai-read-deny markers	Enabled	Always respected
Violation logging	Enabled	Logs to ~/.local/state/ai-guardian/violations.jsonl
Tool/Skill permissions	Allow all	Configure permissions to restrict
Directory rules	Allow all	Configure directory_rules to restrict

Configuration

Config file: ~/.config/ai-guardian/ai-guardian.json (or $XDG_CONFIG_HOME/ai-guardian/)

ai-guardian setup --create-config                          # Secure defaults (Skills/MCP blocked)
ai-guardian setup --create-config --permissive              # Permissive (all tools allowed)
ai-guardian setup --create-config --profile @minimal        # Personal projects, low friction
ai-guardian setup --create-config --profile @strict         # Enterprise SOC2/compliance
ai-guardian setup --list-profiles                           # List available profiles

• Example config: ai-guardian-example.json
• JSON Schema: ai-guardian-config.schema.json (IDE autocomplete + runtime validation)
• Full reference: docs/CONFIGURATION.md

Configuration Locations (Precedence Order)

1. Project config (highest): ./.ai-guardian.json
2. User config: ~/.config/ai-guardian/ai-guardian.json
3. Remote configs: Fetched from URLs in remote_configs
4. Defaults: Built-in defaults

Setup Command

ai-guardian setup                    # Auto-detect IDE
ai-guardian setup --ide claude       # Claude Code
ai-guardian setup --ide cursor       # Cursor IDE
ai-guardian setup --ide copilot      # GitHub Copilot
ai-guardian setup --dry-run          # Preview changes
ai-guardian setup --ide claude --mcp # Enable MCP security advisor (opt-in)
ai-guardian setup --remote-config-url https://example.com/policy.json

Run ai-guardian setup after upgrading to get the latest hooks. Use --mcp to enable the MCP security advisor server — the AI can then check security proactively before acting. See docs/MCP_SERVER.md for details and docs/CONFIGURATION.md for other setup options.

Action Modes

Each security policy supports three enforcement levels:

Mode	Execution	User Warning	Use Case
block	Blocked	Error shown	Enforce policy (default)
warn	Allowed	Warning shown	Educate during rollout
log-only	Allowed	Silent	Monitor silently

See docs/CONFIGURATION.md for per-feature action mode configuration.

Integration

IDE	Prompt Scanning	File Scanning	Output Scanning	Status
Claude Code CLI	Yes	Yes	PostToolUse (ready)	Full support
VS Code Claude	Yes	Yes	PostToolUse (ready)	Full support
Cursor IDE	Yes	Yes	Yes	Full support
GitHub Copilot	Yes	Yes	Planned	Full support
Aider	No	Yes (commit-time)	No	Git hook

• GitHub Copilot Setup
• Aider Setup
• Multi-Engine Support
• Hook Ordering

How It Works

User prompt / Tool use
       |
  [MCP Advisor] -----> AI checks proactively (optional)
       |
  [AI Guardian Hook] -- Enforcement (mandatory)
       |
  MCP/Skill check --> Not allowed? --> BLOCK
       |
  Directory check --> .ai-read-deny? --> BLOCK
       |
  Prompt injection --> Detected? -----> BLOCK
       |
  Secret scan ------> Found? --------> BLOCK
       |
  ALLOW --> Send to AI / Execute tool

The MCP advisor lets the AI check before acting (advisory). Hooks enforce during execution (mandatory). PostToolUse hooks scan tool outputs using the same pipeline. See docs/MCP_SERVER.md for the MCP server and docs/SECURITY_DESIGN.md for full architecture.

Environment Variables

Variable	Description	Default
AI_GUARDIAN_CONFIG_DIR	Custom config directory	~/.config/ai-guardian
AI_GUARDIAN_STATE_DIR	State directory (logs, violations)	~/.local/state/ai-guardian
AI_GUARDIAN_CACHE_DIR	Cache directory (patterns)	~/.cache/ai-guardian
AI_GUARDIAN_IDE_TYPE	Override IDE auto-detection	Auto-detect
AI_GUARDIAN_PATTERN_TOKEN	Default pattern server auth token (all sections)	None

Each detection feature (secret_scanning, secret_redaction, ssrf_protection, config_file_scanning) can use its own pattern server with independent auth via token_env or token_file. See docs/PATTERN_SERVER.md.

Requirements

• Python 3.9+
• Scanner engine: gitleaks, betterleaks, leaktk, trufflehog, detect-secrets, secretlint, or gitguardian
• GNOME Linux: AppIndicator extension for system tray icon (setup steps)

See docs/SCANNER_INSTALLATION.md for installation instructions.

Installation

pip install ai-guardian                   # Basic
pip install ai-guardian[skill-discovery]  # With auto-discovery from GitHub/GitLab

Or from source:

git clone https://github.com/itdove/ai-guardian.git
cd ai-guardian && pip install -e .

Testing

pip install ai-guardian[dev]                     # Install test dependencies
pytest                                          # Run all tests
pytest --cov=ai_guardian --cov-report=term      # With coverage

Or using uv:

uv run --extra dev python -m pytest             # Run all tests
uv run --extra dev python -m pytest --cov=ai_guardian --cov-report=term  # With coverage

See AGENTS.md for testing guidelines and CI/CD details.

Contributing

We welcome contributions via a fork-based workflow:

gh repo fork itdove/ai-guardian --clone
cd ai-guardian
git checkout -b feature-name
# Make changes, commit, push
gh pr create --web

See CONTRIBUTING.md for complete guidelines.

Documentation

Full documentation is available in the docs/ folder:

• Configuration Guide
• Security Documentation
• Console Guide
• Tool Policy
• Scanner Installation
• Security Design
• All Documentation

FAQ

Q: Why no prompt injection examples in the docs? Publishing attack patterns makes them easier to misuse and would cause ai-guardian to block its own documentation. Use test: prefixed strings for testing. See OWASP LLM Top 10 for research.

Q: What's permissions vs permissions_directories vs directory_rules? permissions = which tools can run. permissions_directories = auto-discover tool permissions from repos. directory_rules = which paths can be accessed. See docs/TOOL_POLICY.md and docs/security/DIRECTORY_RULES.md.

License

Apache 2.0 - see LICENSE file for details.

Acknowledgments

• Gitleaks - Secret detection engine
• Claude Code - AI-powered IDE
• Cursor - AI code editor
• LeakTK - Community secret detection patterns
• Hermes Security Patterns - Security research