GitHub Copilot Integration Guide

This guide explains how to integrate AI Guardian with GitHub Copilot using its hook system.

Overview

AI Guardian integrates with GitHub Copilot through native hooks that intercept prompts and tool usage before they're sent to the AI. This provides real-time protection by scanning for secrets and enforcing security policies during AI interactions.

Protection Levels

✅ Real-time scanning: - Scans user prompts before submission (userPromptSubmitted hook) - Scans tool inputs before execution (preToolUse hook) - Blocks operations containing secrets or accessing denied directories - Enforces MCP/Skill permissions

Prerequisites

Required

1. GitHub Copilot - Installed and activated
2. GitHub Copilot subscription (Individual, Business, or Enterprise)
3. VS Code with GitHub Copilot extension, or

4. GitHub Copilot CLI

5. Gitleaks - Secret scanning engine

   # macOS
   brew install gitleaks
   
   # Linux (Ubuntu/Debian)
   curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz | tar -xz
   sudo mv gitleaks /usr/local/bin/
   
   # Windows (using scoop)
   scoop install gitleaks
   

6. AI Guardian - Installed via uv or pip

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

Installation

Method 1: Automatic Setup (Recommended)

Use the ai-guardian setup command:

# Auto-detect and setup GitHub Copilot hooks
ai-guardian setup --ide copilot

# Or with confirmation prompt
ai-guardian setup --ide copilot --yes

The setup command will: 1. Detect your GitHub Copilot configuration 2. Add ai-guardian hooks to ~/.github/hooks/hooks.json 3. Create a backup of your existing configuration 4. Merge with any existing hooks

Method 2: Manual Setup

Step 1: Locate GitHub Copilot hooks configuration

The hooks configuration file is typically at:

~/.github/hooks/hooks.json

Step 2: Create or edit hooks.json

If the file doesn't exist, create it:

mkdir -p ~/.github/hooks
cat > ~/.github/hooks/hooks.json << 'EOF'
{
  "userPromptSubmitted": [
    {
      "command": "ai-guardian"
    }
  ],
  "preToolUse": [
    {
      "command": "ai-guardian"
    }
  ]
}
EOF

If the file exists, merge the hooks:

{
  "userPromptSubmitted": [
    {
      "command": "ai-guardian"
    }
  ],
  "preToolUse": [
    {
      "command": "ai-guardian"
    }
  ]
}

Step 3: Verify installation

Test that ai-guardian is accessible:

which ai-guardian
# Should output: /path/to/bin/ai-guardian

Configuration

Hook Configuration

GitHub Copilot hooks are configured in ~/.github/hooks/hooks.json:

{
  "userPromptSubmitted": [
    {
      "command": "ai-guardian",
      "description": "Scan prompts for secrets before submission"
    }
  ],
  "preToolUse": [
    {
      "command": "ai-guardian",
      "description": "Check tool permissions and scan inputs"
    }
  ]
}

Available Hooks

GitHub Copilot supports these hooks:

Hook	Purpose	AI Guardian Support
userPromptSubmitted	Before sending prompt to AI	✅ Supported
preToolUse	Before tool execution	✅ Supported
postToolUse	After tool execution	⏭️ Future

AI Guardian Configuration

Configure ai-guardian behavior in ~/.config/ai-guardian/ai-guardian.json:

{
  "tool_policy": {
    "default_action": "allow",
    "rules": [
      {
        "tool_pattern": "mcp__*",
        "action": "block",
        "reason": "MCP servers require explicit approval"
      }
    ]
  },
  "prompt_injection": {
    "enabled": true,
    "confidence_threshold": 0.8
  }
}

See Configuration Guide for details.

Usage

Once installed, AI Guardian runs automatically:

Normal Operation

When you use GitHub Copilot:

1. Type a prompt: AI Guardian scans for secrets
2. Copilot suggests code: AI Guardian checks tool usage
3. Clean content: Request proceeds normally
4. Secrets detected: Request blocked with error message

Example: Blocked Request

User prompt: "Deploy using API key: sk_live_abc123..."

🛡️ Secret Detected

Protection: Secret Scanning
Secret Type: stripe-api-key
Location: prompt:line 1
Scanner: Gitleaks
Pattern source: Default Gitleaks rules

Why blocked: Hard-coded secrets in prompts create security risks.
Secrets should never be included in AI prompts or source code.

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

Recommendation:
- Store secrets in environment variables or secret managers
- Use placeholder values in examples (e.g., "sk_test_example_key")
- Never paste real API keys, tokens, or passwords

⚠️ Secret value NOT shown in this message for security

Config: ~/.config/ai-guardian/ai-guardian.json
Section: secret_scanning.enabled

Example: Allowed Request

User prompt: "Refactor this function for better readability"

✓ No secrets detected
✓ Request allowed

Response Format

GitHub Copilot expects specific JSON responses:

userPromptSubmitted Hook

Input from Copilot:

{
  "timestamp": 1704614400000,
  "cwd": "/path/to/project",
  "prompt": "User's prompt text",
  "source": "user"
}

AI Guardian Response (exit code only): - Exit code 0: Allow prompt - Exit code 2: Block prompt (with error message on stderr)

preToolUse Hook

Input from Copilot:

{
  "timestamp": 1704614600000,
  "cwd": "/path/to/project",
  "toolName": "bash",
  "toolArgs": "{\"command\":\"npm test\",\"description\":\"Run tests\"}"
}

AI Guardian Response (JSON):

{
  "permissionDecision": "allow",
  "permissionDecisionReason": "Tool is allowed"
}

Or when blocked:

{
  "permissionDecision": "deny",
  "permissionDecisionReason": "Secrets detected in tool arguments"
}

Environment Variables

AI_GUARDIAN_IDE_TYPE

Override IDE detection:

export AI_GUARDIAN_IDE_TYPE=copilot

Or:

export AI_GUARDIAN_IDE_TYPE=github_copilot

Troubleshooting

Hooks Not Running

Problem: AI Guardian doesn't seem to be blocking anything

Solutions: 1. Verify hooks.json exists: cat ~/.github/hooks/hooks.json 2. Check ai-guardian is in PATH: which ai-guardian 3. Test manually:

echo '{"timestamp":1704614400000,"cwd":"/tmp","prompt":"test"}' | ai-guardian

4. Restart VS Code or Copilot CLI

Permission Errors

Problem: Permission denied when running ai-guardian

Solution: Ensure ai-guardian is executable:

chmod +x $(which ai-guardian)

JSON Parse Errors

Problem: Failed to parse hook input

Solution: GitHub Copilot might be sending unexpected format. Enable debug logging:

export AI_GUARDIAN_DEBUG=1

Then check stderr output for details.

Gitleaks Not Found

Problem: gitleaks: command not found

Solution: Install gitleaks (see Prerequisites)

False Positives

Problem: Legitimate content flagged as secrets

Solutions: 1. Add allowlist rules to .gitleaks.toml in your project 2. Use gitleaks:allow comment in code 3. Adjust pattern server configuration (if using)

Performance Issues

Problem: AI Guardian slows down Copilot responses

Solution: This is expected for security scanning. To optimize: 1. Use project-specific .gitleaks.toml with focused rules 2. Disable prompt injection detection if not needed 3. Use in-memory temp files (automatic on Linux with /dev/shm)

Security Considerations

What AI Guardian Protects Against

✅ Secrets in prompts: - API keys, tokens, passwords - Private keys (SSH, PGP, RSA) - Cloud credentials (AWS, GCP, Azure) - Database connection strings

✅ Directory blocking: - Files in directories with .ai-read-deny markers - Prevents access to sensitive codebases

✅ Tool permissions: - MCP server usage - Skill execution - Custom tool policies

What AI Guardian Does NOT Protect Against

❌ Secrets already in code (use separate static analysis) ❌ Secrets in git history (use git-secrets or TruffleHog) ❌ Network exfiltration (use network policies) ❌ Malicious tool installation (use code review)

Defense in Depth

Recommended layers: 1. AI Guardian hooks - Real-time prompt/tool scanning 2. Git pre-commit hooks - Commit-time verification 3. CI/CD scanning - Build-time secret detection 4. Secret rotation - Regular credential updates 5. Monitoring - Detect unusual AI usage patterns

Advanced Configuration

Custom Secret Patterns

Create .gitleaks.toml in your project:

title = "Custom Secret Rules"

[[rules]]
id = "company-api-key"
description = "Company API Key"
regex = '''company-api-[a-zA-Z0-9]{32}'''
tags = ["api", "company"]

Tool Policy Rules

Configure MCP/Skill permissions in ~/.config/ai-guardian/ai-guardian.json:

{
  "tool_policy": {
    "default_action": "allow",
    "rules": [
      {
        "tool_pattern": "mcp__database__*",
        "action": "block",
        "reason": "Database operations require manual approval"
      },
      {
        "tool_pattern": "Bash",
        "allowed_commands": ["ls", "cat", "grep"],
        "action": "conditional"
      }
    ]
  }
}

Prompt Injection Detection

Enable advanced prompt injection detection:

Note: Specific attack pattern examples are not included for security reasons. See the main README FAQ for guidance on researching prompt injection safely.

{
  "prompt_injection": {
    "enabled": true,
    "confidence_threshold": 0.8,
    "methods": ["heuristic", "vector"],
    "custom_patterns": [
      "company_specific_pattern_.*"
    ]
  }
}

Enterprise Deployment

Centralized Configuration

Use remote configuration for team-wide policies:

ai-guardian setup --ide copilot --remote-config-url https://company.com/ai-guardian-policy.json

Remote config example:

{
  "tool_policy": {
    "default_action": "block",
    "rules": [
      {
        "tool_pattern": "Bash",
        "action": "allow",
        "allowed_commands": ["git", "npm", "make"]
      }
    ]
  },
  "allowed_directories": [
    "/projects/public/*"
  ],
  "blocked_directories": [
    "/projects/secrets/*",
    "/projects/private/*"
  ]
}

Monitoring and Compliance

Track ai-guardian usage for compliance:

1. Enable audit logging (if available in your GitHub Copilot plan)
2. Monitor blocked requests via stderr logs
3. Review patterns to identify training needs
4. Adjust policies based on usage patterns

Comparison: Copilot vs Other IDEs

Feature	GitHub Copilot	Claude Code	Cursor
Hook Type	Native hooks	Native hooks	Native hooks
Trigger Point	Prompt + Tool	Prompt + Tool	Prompt + Tool
Response Format	JSON (tools), Exit code (prompts)	Exit codes	JSON
Setup Complexity	Medium	Low	Low
Permission Levels	allow/deny	allow/block	allow/deny

Resources

• GitHub Copilot Documentation
• GitHub Copilot Hooks Documentation
• AI Guardian Configuration
• Gitleaks Configuration

Getting Help

Issues with ai-guardian: - GitHub Issues: https://github.com/RedHatProductSecurity/ai-guardian/issues

Issues with GitHub Copilot: - GitHub Support: https://support.github.com/

Security concerns: - Open an issue with [SECURITY] prefix