ai-guardian

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.

Security Disclaimer

AI Guardian is not a silver bullet and cannot guarantee detection of all security threats.

• Prompt injection detection may miss novel or obfuscated attacks
• Secret scanning depends on scanner patterns and may miss custom secret formats
• Attackers evolve continuously — new bypass techniques emerge constantly
• Fail-open by design — prioritizes availability over security (errors allow operations)

Use AI Guardian as ONE layer in a defense-in-depth security strategy, not as your only protection.

Combine with:

• Code review processes
• CI/CD security scanning
• Network security (firewalls, egress rules)
• Secret management (Vault, AWS Secrets Manager)

See Security Design for limitations and architecture.

Quick Start

1. Install

uv tool install ai-guardian        # recommended
# or: pip install ai-guardian

2. Configure

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

3. Start

ai-guardian daemon start -b        # background daemon (faster hook processing)
ai-guardian tray start -b          # system tray (optional — manage daemons visually)

4. Open the Console

ai-guardian console                      # browser console (Python 3.10+)
ai-guardian tui                           # compatibility alias for console

Manage settings, view violations, and scan projects. See docs/CONSOLE.md.

Done. Open your IDE and start coding — ai-guardian protects automatically.

MCP servers and Skills are blocked by default. Built-in tools (Bash, Read, Write, Edit) are allowed and scanned by hooks, but MCP servers and Skills require explicit allow rules. See Tool Policy for why and how to allow them.

Developer Install

For contributors cloning the repo:

git clone https://github.com/RedHatProductSecurity/ai-guardian.git
cd ai-guardian
uv venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
uv pip install -e .[dev]

# Run tests
uv run --extra dev python -m pytest tests/test_<module>.py -v

# Run linters
black --target-version py310 src/ai_guardian/ tests/
ruff check src/ai_guardian/ tests/ --fix

See CONTRIBUTING.md and AGENTS.md for full development guidelines.

Warning: The main branch contains unreleased development code. Always install stable releases from PyPI (uv tool install ai-guardian or pip install ai-guardian). Do not git clone + pip install -e . for production use.

Installation Options

One-Line Install

Creates config, installs a scanner, and automatically detects supported IDE configuration directories so their hooks can be installed. Use --ide to target one IDE explicitly, or --no-setup to skip hook setup:

From the tray, open IDE/CLI Setup.... Use Check hooks/MCP installation... to immediately verify locally installed integrations; if hooks or a required MCP registration are missing or unhealthy, the tray offers setup choices and reports the final verification status. The Manual setup (specific IDE) entries are for unusual, incompletely detected, or targeted repair cases, while Create Config... is for first-time or manual configuration. These explicit actions remain available even when no daemon is running or only remote daemons are connected; per-IDE setup also installs the MCP security advisor by default when that IDE supports it. The tray also checks automatically when it starts and then every 10 seconds while running. The initial check also sends an AI Guardian health-result notification; later healthy polling checks remain silent. Automatic checks only offer setup on local-daemon trays. When multiple integrations need setup, the tray shows an individual Install now or Never install choice for each one. These choices are kept per integration, so a newly detected IDE can still be offered later. When no global ai-guardian.json exists, the automatic setup prompt also shows a Security profile selector. @standard is selected and recommended by default; @minimal, @strict, and @moderator include concise guidance, and Skip configuration for now installs only the selected IDE hooks. If a profile is selected, the tray creates the global config only after confirmation and before installing hooks. Existing global or project-local configuration is never overwritten by this flow. Configuration creation failures leave hook setup untouched and the prompt is temporarily deferred. The web console's Configuration → Proactive Prompt State page provides a read-only view of these local prompt decisions. They are stored separately in the XDG state file proactive_prompts.json, rather than in ai-guardian.json. Entries named ide_setup_<combination> are prompt history; the synchronized ide_setup_status entry is the current installed-IDE and current/last-verified hook-health snapshot. Within prompt history, dismissed means the automatic prompt was declined for that exact combination, while snoozed means it is postponed until its stored time. Neither value says whether the hooks are currently healthy: the tray refreshes the snapshot from live hook verification before applying either decision. Dismissed and snoozed integrations continue to be rechecked, and a changed unhealthy result can make their prompt eligible again. Never install is the only automatic choice that stops rechecking; the tray keeps its last verified status visible and suppresses automatic setup until the choice is reset, while manual setup remains available. Use the per-IDE Reset button on that page, or ai-guardian ide-setup reset --ide <ide>, to clear one IDE's saved prompt decisions and Never install choice.

# Auto-detect installed IDEs (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/RedHatProductSecurity/ai-guardian/v1.20.0/install.sh | bash

# Linux / macOS (auto-detects uv → venv → pip)
curl -fsSL https://raw.githubusercontent.com/RedHatProductSecurity/ai-guardian/v1.20.0/install.sh | bash -s -- --ide claude

# Force a specific install method
curl -fsSL https://raw.githubusercontent.com/RedHatProductSecurity/ai-guardian/v1.20.0/install.sh | bash -s -- --uv --ide claude    # uv tool install (fastest)
curl -fsSL https://raw.githubusercontent.com/RedHatProductSecurity/ai-guardian/v1.20.0/install.sh | bash -s -- --venv --ide claude  # venv + pip
curl -fsSL https://raw.githubusercontent.com/RedHatProductSecurity/ai-guardian/v1.20.0/install.sh | bash -s -- --pip --ide claude   # bare pip

# Windows (PowerShell)
irm https://raw.githubusercontent.com/RedHatProductSecurity/ai-guardian/v1.20.0/install.ps1 | iex

# Install without changing IDE hooks
curl -fsSL https://raw.githubusercontent.com/RedHatProductSecurity/ai-guardian/v1.20.0/install.sh | bash -s -- --no-setup

Container

A pre-built container image is published to quay.io/redhatproductsecurity/ai-guardian with ai-guardian and the supported agent integrations. Redistributable headless CLIs are bundled; proprietary or GUI-only agents are configured at startup without being embedded:

For provider-backed sessions, OpenShell is preferred when available, but remains experimental (upstream pre-1.0); validate compatibility first. Provider credentials remain in the gateway, with deny-by-default network/filesystem policy and per-sandbox isolation. Docker/Podman is the simpler fallback; credentials passed to it are available inside and may be readable by the agent.

# Recommended — run.sh handles auth, port mapping, config sharing, and ToS consent
curl -fsSL https://raw.githubusercontent.com/RedHatProductSecurity/ai-guardian/v1.20.0/container/run.sh -o run.sh
chmod +x run.sh
OPENAI_API_KEY=... \
    ./run.sh --agent codex --repo $(pwd)

# Preferred OpenShell sandbox (experimental, upstream pre-1.0; published or local image)
# OpenShell currently supports Codex only; Claude support is deferred until 0.1.3.
# Complete the gateway/provider setup in docs/Sandbox.md first.
podman pull quay.io/redhatproductsecurity/ai-guardian-openshell:latest
ai-guardian sandbox create --runtime openshell \
    --image quay.io/redhatproductsecurity/ai-guardian-openshell:latest \
    --cli codex --repo $(pwd)

# Or build and select a local OpenShell image
podman build -f container/Dockerfile.openshell \
    -t localhost/ai-guardian-openshell:latest container/
ai-guardian sandbox create --runtime openshell \
    --base localhost/ai-guardian-openshell:latest \
    --cli codex --repo $(pwd)
# A source-wheel build is documented in container/README.md; it includes the
# current development setup behavior instead of the stable PyPI fallback.

# Launch Codex directly instead of opening the shell
ai-guardian sandbox create --runtime openshell --cli codex --repo $(pwd) -- codex

# Or manually with podman/docker
podman pull quay.io/redhatproductsecurity/ai-guardian:latest
podman run -it -p 63152:63152 \
    -v $(pwd):/workspace:z \
    -e AI_GUARDIAN_AGENT=codex \
    -e OPENAI_API_KEY=<your-openai-key> \
    quay.io/redhatproductsecurity/ai-guardian:latest

For Codex authentication in a Docker/Podman sandbox, the host ~/.codex/auth.json is not mounted automatically. Authenticate inside the sandbox or follow the container Codex authentication guide for headless OAuth, API-key, and explicit credential-copy options.

For a named sandbox that can be managed across sessions, use the CLI subcommand. It supports both Docker/Podman containers and OpenShell:

ai-guardian sandbox create --runtime container --name guardian-codex --repo .
ai-guardian sandbox list
ai-guardian sandbox stop guardian-codex
ai-guardian sandbox start guardian-codex
ai-guardian sandbox connect guardian-codex
ai-guardian sandbox exec guardian-codex -- ai-guardian daemon status
ai-guardian sandbox logs guardian-codex --follow
ai-guardian sandbox config save guardian-codex
ai-guardian sandbox delete guardian-codex

New sandbox creation defaults to OpenShell (experimental; upstream pre-1.0); check compatibility first, or use --runtime container explicitly when a plain Docker/Podman sandbox is required. Named lifecycle commands automatically detect the runtime from AI Guardian labels and OpenShell metadata when --runtime is omitted. An unqualified list includes both runtimes. OpenShell operations use the installed openshell CLI and its active gateway; set OPENSHELL_CLI when a different executable is required. The sandbox command is also the supported entry point for interactive, fully provisioned OpenShell sessions, including policy composition and gateway-provider setup.

OpenShell create opens an independent interactive sandbox shell after setup, matching the native OpenShell experience while leaving the sandbox available after the shell exits; container create remains detached.

The OpenShell status, stop, exec, and logs forms are thin aliases of the corresponding native commands. connect uses an independent openshell sandbox exec --name ... --tty shell so exiting it does not terminate the sandbox's main process. start and restart additionally ensure that the AI Guardian daemon and gateway service are available; delete removes that service before the native sandbox. create and list add AI Guardian defaults and managed-resource filtering. See the Sandbox CLI guide for the full command reference, including timestamped configuration snapshots and recreating a sandbox with --restore-config latest.

The OpenShell subcommand exposes the daemon's internal port through the gateway-managed ai-guardian service. The gateway gives each sandbox a separate URL, so multiple sandboxes can use the same internal port:

openshell service expose NAME 63152 ai-guardian
openshell service get NAME ai-guardian
# Example: http://NAME--ai-guardian.openshell.localhost:PORT/

Tray and NiceGUI discovery query the gateway for these service URLs. --port is a container-only option; OpenShell selects the service port through the gateway and does not use a host-side forward process.

OpenShell must be installed and initialized on the host first, with a reachable gateway and configured compute driver; follow the official OpenShell installation guide. On Fedora/Linux, verify the systemd user service with systemctl --user status openshell-gateway. On macOS, verify the Homebrew service with brew services list. In both cases, run openshell status before using the OpenShell subcommand. When the gateway uses rootless Podman on Linux, start its API socket first with systemctl --user enable --now podman.socket; see the container guide for socket-path troubleshooting.

The OpenShell subcommand opens a shell by default. Its --repo option uploads an isolated snapshot rather than binding the host checkout; the shell starts in /sandbox/repo, and a read/write GitHub provider can push the sandbox copy without writing files back to the host. Pass -- codex to launch Codex directly instead of opening the shell.

OpenShell integration is experimental and currently supports Codex only. Claude Code with Vertex AI remains deferred pending credential-bound qualification on OpenShell 0.1.3; the upstream GCP metadata fix is necessary but not sufficient. Pi, Copilot, and OpenCode remain outside the current OpenShell contract.

OpenCode is supported through the host integration and the normal Docker/Podman image, whose V1 executable is pinned at 1.18.34. OpenCode is outside the OpenShell runtime scope; see the OpenCode support record for the V1/V2 plugin contracts and exact limitations.

The providers_v2_enabled setting was specific to OpenShell 0.1.2 and is not used by the qualified 0.1.3 baseline. OpenShell 0.1.2 and earlier are below AI Guardian's supported range.

A Codex OAuth login does not require a separate API key. Choose OAuth or API key in the tray's Create sandbox form, or pass --openshell-auth oauth/--openshell-auth api-key to select the matching codex/openai profile and ai-guardian-codex/ai-guardian-openai provider. The subcommand converts the gateway-provided OAuth placeholders into Codex's native sandbox-local auth.json; real host tokens are not uploaded. When host files must be uploaded, the subcommand uses a compatible staging flow and starts the selected CLI with sandbox exec after setup. For API-key authentication, the entrypoint runs codex login --with-api-key with the provider-injected placeholder so Codex can read its native auth.json; the real host key is never written into the sandbox. Inside OpenShell, the subcommand sets Codex's sandbox-local sandbox_mode = "danger-full-access" so Codex does not create a nested bubblewrap sandbox. OpenShell remains the outer filesystem and network boundary; regular Docker/Podman launches retain Codex's normal inner sandbox. See the official OpenShell Codex example.

For a Codex-only sandbox, no GitHub policy is required. The subcommand applies the shared base policy and selected Codex policy automatically. Add the read-only or read/write GitHub policy only when the sandbox needs GitHub access.

# Pinned release
podman pull quay.io/redhatproductsecurity/ai-guardian:v1.20.0
podman run -it -p 63152:63152 -e AI_GUARDIAN_AGENT=codex quay.io/redhatproductsecurity/ai-guardian:v1.20.0

# Or build from source
podman build -t ai-guardian container/
podman run -it -p 63152:63152 -e AI_GUARDIAN_AGENT=codex ai-guardian

See container/README.md for agent selection, host config/profile behavior, OpenShell, Vertex AI auth, and multi-arch details. The container guide also includes read-only and read/write OpenShell policy overlays, selected-CLI policy fragments, and provider setup.

What Setup Does

The setup 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

Daemon & Tray

The daemon provides faster hook processing. The tray discovers and manages daemons across local, Podman/Docker containers, and Kubernetes pods:

ai-guardian daemon start -b       # Start headless daemon (background: -b)
ai-guardian tray start -b         # Start system tray in background
ai-guardian pause [MINUTES]      # Pause global scanning (0/omitted: indefinite)
ai-guardian resume                # Resume global scanning
ai-guardian tray stop             # Stop the tray
ai-guardian tray --install --autostart  # Add desktop shortcut + launch on login

The tray auto-discovers running daemons and shows per-daemon submenus with Statistics, Console, Pause/Resume, and Start/Stop controls. On first launch, the tray will offer to create a desktop shortcut automatically. See Multi-Daemon Tray for full documentation.

Linux + Podman: Container discovery requires the Podman socket to be active and DOCKER_HOST set:

systemctl --user enable --now podman.socket
export DOCKER_HOST=unix://$(podman info --format '{{.Host.RemoteSocket.Path}}')
ai-guardian tray start -b

macOS with Podman Desktop sets DOCKER_HOST automatically. See Multi-Daemon Tray for details.

Breaking change in v1.8.0: daemon start no longer launches the tray automatically. Run ai-guardian tray start -b separately, or use ai-guardian tray --install --autostart for a permanent desktop shortcut with login startup.

Security Profiles

Choose a profile that matches your environment:

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

Features

Default Behavior (No Configuration File)

ai-guardian provides protection immediately with zero configuration:

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 --create-config --profile @moderator      # Human-in-the-loop, ask on every finding
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)
• Ignore file schema: aiguardignore.schema.json (VS Code Taplo validation for .aiguardignore.toml)
• Full reference: docs/CONFIGURATION.md

Configuration Locations (Precedence Order)

1. User config: ~/.config/ai-guardian/ai-guardian.json (base)
2. Project config: .ai-guardian/ai-guardian.json (merged on top of user config, see docs)
3. Remote configs (highest, permissions only): Fetched from URLs in remote_configs
4. Defaults: Built-in defaults when no config exists

Setup Command

ai-guardian setup                    # Auto-detect IDE
ai-guardian setup --yes              # Configure all detected unconfigured IDEs/CLIs
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 security advisor installed by default
ai-guardian setup --remote-config-url https://example.com/policy.json
ai-guardian ide-setup sync           # Refresh local IDE/hook status in XDG state
ai-guardian ide-setup sync --json     # Print the synchronized status as JSON
ai-guardian ide-setup reset --ide claude  # Reset Claude setup prompt decisions

Run ai-guardian setup after upgrading to get the latest hooks. Without --ide, it checks installed integrations, skips healthy ones, and prompts when one or more still need setup; --yes configures all pending integrations. If --create-config is supplied (optionally with --profile), the security configuration is created first and then reused for every selected integration. The MCP security advisor server is installed by default — the AI can check security proactively before acting. Use --no-mcp to skip. See docs/AGENT_SUPPORT.md#setup for automatic detection details and docs/MCP_SERVER.md for MCP options.

OpenAI Codex coverage

OpenAI Codex (CLI + Desktop) means Codex CLI and Codex mode selected in the ChatGPT desktop app. Regular ChatGPT mode in that app is not currently protected by AI Guardian's Codex lifecycle hooks. The ChatGPT desktop app, Codex CLI, and Codex IDE extension can share MCP configuration, but shared MCP availability does not imply hook enforcement.

Action Modes

Each security policy supports three enforcement levels:

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

Integration

See Agent Support for the current capability matrix, IDE/Agent Integration Checklist for host integrations, and CLI/Runtime Integration Checklist for container and OpenShell support.

• 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

CLAUDE_CONFIG_DIR, CODEX_HOME, CURSOR_CONFIG_DIR, COPILOT_HOME, and GEMINI_CLI_HOME are honored by setup, MCP registration, verification, and supported session discovery. AI_GUARDIAN_CONFIG_DIR takes precedence over AI_GUARDIAN_HOME, which takes precedence over XDG. See the IDE-specific path reference for the complete variable list, precedence rules, and project-local behavior.

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.10+
• Windows: Python 3.10, 3.13, and 3.14 are tested; other versions may work but are not CI-verified
• 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.

Optional Dependencies

ai-guardian works out of the box with built-in Python-native scanners, the NiceGUI browser console, and heuristic prompt injection detection. These optional packages enable extra functionality:

tkinter Install by Platform

Contributing

We welcome contributions! See Developer Install for setup and CONTRIBUTING.md for complete guidelines.

• Bug reports & feature requests -- use GitHub Discussions
• Code contributions -- fork + PR (not affected by interaction limits)

Documentation

Full documentation is also available at ai-guardian.readthedocs.io with search and versioned navigation.

Source docs are 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.

Q: How are multiple rules evaluated? Both permissions.rules and directory_rules use last-match-wins: rules are checked in array order and the last matching rule determines the outcome. Place broad deny rules first, then specific allow rules after. Common mistake: putting an allow rule before a deny-all — the deny-all wins because it comes last. See docs/TOOL_POLICY.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