Skip to content

Security Design

AI Guardian's security architecture is built on defense-in-depth principles with self-protecting mechanisms that prevent AI agents from disabling their own security controls.

Architecture Principles

  • Defense in Depth: One layer in a multi-layered security strategy
  • Three-layer model: MCP advisor (proactive, optional) → Skill instructions (guidance) → Hooks (enforcement, mandatory)
  • Fail-open: If scanning errors occur, allows operation (availability over security)
  • In-memory scanning: Uses /dev/shm on Linux for performance
  • Secure cleanup: Overwrites temp files before deletion
  • No logging: Secrets are never logged or stored
  • Privacy-first: Heuristic detection runs locally, no external calls
  • MCP security boundary: MCP tools expose yes/no decisions only — never rules, patterns, or allowlists (see MCP Server)

Self-Protecting Security Architecture

AI Guardian uses hardcoded deny patterns that protect its own critical files from being modified by AI agents. This prevents AI from disabling security features or bypassing protection.

Protected Files

  1. Configuration files - Prevents AI from disabling security features
  2. ~/.config/ai-guardian/ai-guardian.json (global config)
  3. .ai-guardian/ai-guardian.json (project config, NEW in v1.8.0)
  4. ./.ai-guardian.json (legacy)

  5. Any file matching *ai-guardian.json

  6. IDE hook files - Prevents AI from removing ai-guardian hooks

  7. ~/.claude/settings.json (Claude Code)

  8. ~/.cursor/hooks.json (Cursor IDE)

  9. Package source code - Prevents AI from editing protection logic

  10. */ai_guardian/* (all package files)

  11. */site-packages/ai_guardian/*

  12. Directory protection markers - Prevents AI from removing .ai-read-deny files

  13. */.ai-read-deny (all directory markers)
  14. **/.ai-read-deny (recursive protection)

How Self-Protection Works

The protection works through an unbreakable loop:

  1. Deny patterns are checked in the PreToolUse hook BEFORE any tool executes
  2. If a tool tries to modify a protected file, the operation is BLOCKED
  3. The tool never executes, so the file is never modified
  4. AI cannot edit the source code to remove the protection because editing is blocked by the same protection

OpenCode Tool Payloads

OpenCode's plugin API reports built-in tools with lowercase names and camelCase arguments, such as read with filePath. The OpenCode adapter canonicalizes these fields before the shared PreToolUse policy runs, and direct policy callers apply the same normalization. This keeps global and project AI Guardian configuration reads and mutations under the same immutable protection as other supported agents while leaving ordinary project file operations available.

Agent-Originated CLI Boundary

The same immutable PreToolUse layer also protects the AI Guardian command-line interface from agent shell execution. This boundary:

  • Applies to Bash, Shell, PowerShell, and the normalized shell payloads from all supported hook adapters.
  • Blocks direct, path-qualified, Python-module, and common launcher/wrapper invocations before a child process starts.
  • Blocks read-only commands as well as commands that change daemon, tray, hook, configuration, scanner, or model state.
  • Uses command-position-aware parsing, so documentation text, filenames, repository paths, and ordinary project commands that mention AI Guardian are not treated as launches.
  • Runs independently of the configurable permissions rules, including when ordinary tool permissions are disabled.
  • Defaults to deny. A developer may explicitly set developer_session.enabled to true in the protected global configuration before starting the trusted development runtime. Missing, malformed, project-level, overlay, or later agent-supplied values remain denied.
  • The setting is captured when the daemon starts; if a daemon is already running, start the development session with a newly started daemon so a normal-session setting cannot be upgraded in place.
  • The opt-in affects only agent-originated AI Guardian CLI execution. Protected files, hooks, caches, MCP identity checks, and other immutable protections remain enforced.

The boundary only applies to agent-originated tool calls. Installed IDE hook processes, the verified read-only mcp__ai-guardian__* advisor namespace, and a human running the CLI directly in a terminal remain functional. The denial is reported with a safe self-protection reason and does not expose matching rules or permission configuration guidance.

The developer-session marker is a global-only configuration setting, not a project permission, hook payload field, SDK overlay, or AI Guardian command-line option. The normal generated configuration leaves the secure default unchanged.

Agent-Originated Host CLI Boundary

The immutable PreToolUse layer also protects the active supported host CLI from agent-originated self-invocation. self_protection.block_host_agent_cli is a global-only setting that defaults to enabled and is evaluated independently of ordinary tool permissions.

The boundary:

  • Resolves the active CLI from the detected adapter/session identity and the canonical supported-integration registry, including executable aliases such as agy and kiro-cli.
  • Blocks direct, path-qualified, package-launcher, and supported shell-wrapper forms before a child process starts.
  • Keeps command-position awareness so documentation text, filenames, repository paths, unrelated commands, and human terminal use remain allowed.
  • Does not block the parent host process, normal plugin/bridge startup, trusted hook/daemon operations, or the verified read-only AI Guardian MCP namespace.
  • Remains active when ordinary permissions are disabled and cannot be overridden by ordinary permission rules, project configuration, hook payloads, or command arguments.

Missing or malformed values remain enabled. An explicit global false disables only this dedicated host-CLI guard; the existing agent-originated ai-guardian CLI guard, protected configuration, hooks, cache, package, and MCP identity protections remain active.

Supported Agent Configuration Protection

The PreToolUse policy also protects the configuration that controls supported CLI/IDE agents. A canonical inventory is built from the supported-agent registry, setup metadata, MCP/path resolvers, documented environment-variable relocations, explicit config-file selections, and the active workspace. It covers user/global and project/workspace settings, hooks, MCP registrations, plugins, extensions, generated bridges, and managed artifacts.

This check runs before ordinary permissions and remains active when permissions are disabled or a permissive, warning, or log-only rule matches. It covers normalized file mutation tools and shell mutation forms such as redirection, in-place editing, deletion, and rename/move. Ordinary project files outside the inventory remain editable.

agent_config_protection.enabled is global-only and defaults to enabled when missing or malformed. An explicit global disable does not affect immutable AI Guardian configuration, cache, package, hook, MCP identity, or CLI protections. Denials report only a safe supported-agent configuration reason; they do not expose matching patterns or permission guidance to the agent.

Example Attack Scenarios (All Blocked)

# Try 1: Edit config file
Edit(file_path="~/.config/ai-guardian/ai-guardian.json")
# BLOCKED by "*ai-guardian.json" pattern

# Try 2: Remove Claude hooks
Edit(file_path="~/.claude/settings.json")
# BLOCKED by "*/.claude/settings.json" pattern

# Try 3: Edit source code to disable protection
Edit(file_path="~/.local/lib/.../ai_guardian/tool_policy.py")
# BLOCKED by "*/ai_guardian/*" pattern

# Try 4: Use sed to bypass
Bash(command="sed -i 's/IMMUTABLE/DISABLED/' ~/.local/lib/.../ai_guardian/tool_policy.py")
# BLOCKED by "*sed*ai_guardian*" pattern

# Try 5: Use echo redirect to overwrite
Bash(command="echo '{}' > ~/.config/ai-guardian/ai-guardian.json")
# BLOCKED by "*>*ai-guardian*" pattern

# Try 6: Delete config file
Bash(command="rm ~/.config/ai-guardian/ai-guardian.json")
# BLOCKED by "*rm*ai-guardian.json*" pattern

# Try 7: Bypass directory protection by removing marker
Bash(command="rm ~/secrets/.ai-read-deny")
# BLOCKED by "*rm*.ai-read-deny*" pattern

# Try 8: Rename directory protection marker
Bash(command="mv .ai-read-deny .ai-read-deny.bak")
# BLOCKED by "*mv*.ai-read-deny*" pattern

Why Filesystem Permissions Don't Work

AI Guardian's config directory is always in the user's HOME directory: - Default: ~/.config/ai-guardian/ - XDG: $XDG_CONFIG_HOME/ai-guardian/ - Custom: $AI_GUARDIAN_CONFIG_DIR (or $AI_GUARDIAN_HOME)

All paths resolve to the HOME directory, which is always writable by the user (and therefore by AI agents). Filesystem permissions cannot protect these files.

Solution: Hardcoded protection at the tool invocation level is the only cross-platform approach that works reliably.

What Happens When Protection Triggers

Immutable Protection

Protection: Configuration File
Tool: Edit
File Path: ~/.claude/settings.json
Pattern: */.claude/settings.json

Why blocked: This is an ai-guardian or IDE hook configuration file.
Modifying these files could disable security protections.

This operation has been blocked for security.
DO NOT attempt to bypass this protection - it prevents security control tampering.

Recommendation:
- Configuration files must be edited manually (not by AI agents)
- Use your text editor to modify these files
- This prevents AI from disabling its own security controls

Protected categories:
- ai-guardian configuration files
- IDE hook configuration (Claude, Cursor)
- ai-guardian package source code
- .ai-read-deny marker files

This protection is immutable and cannot be disabled via configuration.
It ensures ai-guardian security controls cannot be bypassed.

User Override

If you need to edit these files: - Use your text editor manually (vim, nano, VS Code, etc.) - The protection only blocks AI agent access via tools - You retain full control over your configuration

If a user manually edits the source code to remove the protection: - This is an intentional choice by the user - Same as uninstalling ai-guardian entirely - Not an AI bypass (requires manual intervention)

Maintainer Bypass for Development

GitHub maintainers of the AI Guardian project can edit source code with AI assistance:

# Prerequisites
# 1. Authenticate with GitHub CLI
gh auth login

# 2. Be a collaborator on the repository
# (check: gh api repos/RedHatProductSecurity/ai-guardian/collaborators/YOUR_USERNAME)

# Now AI can help edit source files
# Allowed for maintainers:
Edit src/ai_guardian/tools/policy.py
Write tests/test_new_feature.py
Edit README.md

# But config files remain protected (even for maintainers):
# BLOCKED: Edit ~/.config/ai-guardian/ai-guardian.json
# BLOCKED: Edit ~/.claude/settings.json
# BLOCKED: Write ~/.cache/ai-guardian/maintainer-status.json

How Maintainer Bypass Works

  1. GitHub OAuth Authentication - Uses gh CLI to verify your GitHub identity
  2. Collaborator Check - Confirms write access via GitHub API
  3. Scoped Bypass - Only allows editing source code, never config files
  4. Automatic - Works transparently when you're a maintainer
  5. Cached - Status cached for 24 hours to avoid API rate limits

Security Model

The bypass prevents two distinct threat models:

  • Threat A (Non-Maintainers): Blocked by GitHub collaborator check
  • AI can't fake OAuth credentials

  • GitHub API verifies real permissions

  • Threat B (Malicious Prompts to Maintainers): Blocked by scoped protection

  • Config files always protected (even for maintainers)
  • Cache files always protected (prevents poisoning)
  • Malicious prompts can't disable security features

Troubleshooting

If maintainer bypass isn't working:

  1. Check GitHub authentication: gh auth status
  2. Verify collaborator access: gh api repos/RedHatProductSecurity/ai-guardian/collaborators/YOUR_USERNAME
  3. Clear cache: rm ~/.cache/ai-guardian/maintainer-status.json
  4. Check repo URL: git config --get remote.origin.url (must be github.com)

Fork-Friendly: Works on your own fork too! If you're a maintainer of yourname/ai-guardian, you can edit your fork's source code.

Known Limitations

AI Guardian is not perfect and has known limitations.

Prompt Injection Detection

  • Heuristic pattern matching can be bypassed with novel techniques
  • New attack vectors emerge faster than detection patterns update
  • Trade-off between false positives (blocking legitimate text) and false negatives (missing attacks)

Secret Scanning

  • Depends on Gitleaks community-maintained patterns
  • May miss organization-specific or custom secret formats
  • Requires regular updates to detect new secret types

Fail-Open Design

  • Prioritizes availability over absolute security
  • Detection errors allow operations to proceed (won't block legitimate work)
  • Not suitable for zero-trust environments requiring fail-closed behavior

Shell Mode (! Prefix) Bypass

Commands run with the ! prefix in Claude Code (e.g., ! cat .env) execute locally and bypass all ai-guardian hooks (UserPromptSubmit, PreToolUse, PostToolUse). The command text and output are added directly to the AI's conversation context without any security scanning.

This means: - Secrets typed in ! commands reach the AI model undetected - PII in ! command output is not redacted - Prompt injection in ! command output is not checked - No violation is logged at the time of execution

Do NOT use ! commands to: - Display files containing secrets (! cat .env, ! cat ~/.aws/credentials) - Run commands that output credentials (! aws sts get-caller-identity) - Paste or echo sensitive data (! echo "API_KEY=...") - Read untrusted files that could contain prompt injection

Instead use: Regular commands (without !) which go through Claude's Bash tool and are scanned by ai-guardian's PreToolUse and PostToolUse hooks.

Mitigation: Transcript scanning (v1.7.0, Issue #430) provides after-the-fact detection by scanning the conversation transcript for secrets, PII, and prompt injection on each UserPromptSubmit event. However, this is detection-only — it cannot block content already in the AI's context.

What AI Guardian Protects Against

Common threats it catches: - Known prompt injection patterns (instruction override, role manipulation, etc.) - Standard secret formats (GitHub tokens, AWS keys, API keys, etc.) - Accidental exposure of sensitive directories - Unauthorized MCP server and skill access

Threats it may miss: - Novel or zero-day prompt injection techniques - Custom/proprietary secret formats - Obfuscated or encoded attacks - Social engineering attacks - Compromised AI models

Bottom line: Use AI Guardian as part of a comprehensive security strategy, not as sole protection.

Immutable Remote Configurations

Remote configurations can mark sections and permission rules as immutable to prevent local configs from overriding them. See Configuration Guide for details on:

  • Per-matcher immutability
  • Section immutability
  • Enterprise policy enforcement examples