ai-guardian 1.6.1

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 --install-scanner --ide claude
ai-guardian scanner list

You're done! ai-guardian now protects against secrets, prompt injection, SSRF, and config exfiltration.

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
Self-Protection	Prevents AI from disabling its own security controls	docs/SECURITY_DESIGN.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 --dry-run     # Preview without creating

• 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 --remote-config-url https://example.com/policy.json

Run ai-guardian setup after upgrading to get the latest hooks. See docs/CONFIGURATION.md for detailed setup options including remote configuration and hook ordering.

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
       |
  [AI Guardian Hook]
       |
  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

PostToolUse hooks scan tool outputs using the same pipeline. See 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	Pattern server auth token	None

Requirements

• Python 3.9+
• Scanner engine: gitleaks, betterleaks, leaktk, trufflehog, detect-secrets, secretlint, or gitguardian

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

pytest                                          # Run all tests
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

---

Private Repository - Will be made public after testing