Copilot Hooks

Akto Guardrails for GitHub Copilot provides security validation for AI-assisted development across VS Code and the CLI. It intercepts prompts when submitted and tool executions before and after they run, validates against security policies, blocks risky behavior, and reports events to your Akto dashboard.

Key Features

✅ Zero Installation - No standalone apps to install
✅ Transparent Integration - Uses GitHub Copilot's native hook mechanism in both VS Code and CLI
✅ Real-time Tool Blocking - Can block dangerous tool executions before they run
✅ Centralized Monitoring - All events reported to Akto dashboard
✅ Flexible Deployment - Supports Argus and Atlas modes
✅ Configurable Behavior - Blocking or observation modes
⚠️ Prompt Monitoring Only - GitHub Copilot limitation prevents blocking prompts at submission

How Hooks Works

GitHub Copilot's hook system executes custom scripts at three critical points in both VS Code and the CLI:

3 Hook Points:

userPromptSubmitted - Monitors prompts when submitted to Copilot (reporting only, cannot block)
preToolUse - Validates tool use before execution and can block dangerous operations
postToolUse - Ingests tool execution results for monitoring and audit

GitHub Copilot Limitation: The userPromptSubmitted hook cannot block prompt execution. Prompts flagged by guardrails will still reach the LLM. Only preToolUse can prevent operations from executing. For complete prompt blocking, consider using a network proxy.

File Structure

<project-root>/
└── .github/
    └── hooks/
        ├── akto-validate-prompt-wrapper.sh       # Prompt monitoring wrapper (macOS/Linux)
        ├── akto-validate-prompt-wrapper.ps1      # Prompt monitoring wrapper (Windows)
        ├── akto-validate-prompt.py               # Prompt monitoring logic
        ├── akto-validate-pre-tool-wrapper.sh     # Pre-tool validation wrapper (macOS/Linux)
        ├── akto-validate-pre-tool-wrapper.ps1    # Pre-tool validation wrapper (Windows)
        ├── akto-validate-pre-tool.py             # Pre-tool validation and blocking logic
        ├── akto-validate-post-tool-wrapper.sh    # Post-tool ingestion wrapper (macOS/Linux)
        ├── akto-validate-post-tool-wrapper.ps1   # Post-tool ingestion wrapper (Windows)
        ├── akto-validate-post-tool.py            # Post-tool ingestion logic
        ├── akto_machine_id.py                    # Device ID utility
        └── hooks.json                            # Hook configuration

Key Files:

Wrapper scripts (.sh / .ps1): Set environment variables, invoke Python scripts
- ⚠️ Contains AKTO_DATA_INGESTION_URL placeholder - Must be set to your Akto instance URL
- .sh used on macOS/Linux; .ps1 used on Windows
Python scripts (.py): Core validation logic and Akto API communication
akto_machine_id.py: Generates unique device identifiers for Atlas mode
hooks.json: Links hooks to wrapper scripts — uses bash key on macOS/Linux and powershell key on Windows

Note: hooks.json is loaded from the project root's .github/hooks/ directory.

Setup Guide

Prerequisites

GitHub CLI installed or VS Code
Akto instance URL
Python 3

macOS / Linux: bash or zsh

Windows: PowerShell 5.1+ (built-in on Windows 10/11, including Azure Virtual Desktop pooled sessions)

Installation Steps

Create the Hooks Directory

macOS / Linux:

mkdir -p .github/hooks

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path .github\hooks

Download Hook Scripts

macOS / Linux:

# Base URL for downloading hooks
HOOKS_BASE="https://raw.githubusercontent.com/akto-api-security/akto/master/apps/mcp-endpoint-shield/github-cli-hooks"

# Download prompt monitoring hooks
curl -o .github/hooks/akto-validate-prompt-wrapper.sh \
  "${HOOKS_BASE}/akto-validate-prompt-wrapper.sh"
curl -o .github/hooks/akto-validate-prompt.py \
  "${HOOKS_BASE}/akto-validate-prompt.py"

# Download pre-tool validation hooks
curl -o .github/hooks/akto-validate-pre-tool-wrapper.sh \
  "${HOOKS_BASE}/akto-validate-pre-tool-wrapper.sh"
curl -o .github/hooks/akto-validate-pre-tool.py \
  "${HOOKS_BASE}/akto-validate-pre-tool.py"

# Download post-tool ingestion hooks
curl -o .github/hooks/akto-validate-post-tool-wrapper.sh \
  "${HOOKS_BASE}/akto-validate-post-tool-wrapper.sh"
curl -o .github/hooks/akto-validate-post-tool.py \
  "${HOOKS_BASE}/akto-validate-post-tool.py"

# Download utility
curl -o .github/hooks/akto_machine_id.py \
  "${HOOKS_BASE}/akto_machine_id.py"

# Download hooks configuration
curl -o .github/hooks/hooks.json \
  "${HOOKS_BASE}/hooks.json"

# Make executable
chmod +x .github/hooks/*.py .github/hooks/*.sh

Windows (PowerShell):

$HOOKS_BASE = "https://raw.githubusercontent.com/akto-api-security/akto/master/apps/mcp-endpoint-shield/github-cli-hooks"

$files = @(
  "akto-validate-prompt-wrapper.ps1", "akto-validate-prompt.py",
  "akto-validate-pre-tool-wrapper.ps1", "akto-validate-pre-tool.py",
  "akto-validate-post-tool-wrapper.ps1", "akto-validate-post-tool.py",
  "akto_machine_id.py", "hooks.json"
)

foreach ($file in $files) {
  Invoke-WebRequest -Uri "$HOOKS_BASE/$file" -OutFile ".github\hooks\$file"
}

Configure Akto Ingestion URL ⚠️ CRITICAL STEP

All wrapper scripts contain the variable AKTO_DATA_INGESTION_URL that must be set to your actual Akto instance URL.

macOS / Linux — automated replacement:

# Set your Akto ingestion URL
AKTO_URL="https://your-akto-instance.com"

# Update all wrapper scripts
sed -i.bak "s|{{AKTO_DATA_INGESTION_URL}}|${AKTO_URL}|g" .github/hooks/*-wrapper.sh

# Verify replacement
grep "AKTO_DATA_INGESTION_URL" .github/hooks/*-wrapper.sh

Windows (PowerShell) — automated replacement:

$AKTO_URL = "https://your-akto-instance.com"

Get-ChildItem ".github\hooks\*-wrapper.ps1" | ForEach-Object {
  (Get-Content $_.FullName) -replace '{{AKTO_DATA_INGESTION_URL}}', $AKTO_URL |
    Set-Content $_.FullName
}

# Verify replacement
Select-String "AKTO_DATA_INGESTION_URL" .github\hooks\*-wrapper.ps1

Manual replacement (alternative):

Edit each wrapper script and replace:

{{AKTO_DATA_INGESTION_URL}}

With your actual Akto instance URL, e.g. https://your-akto-instance.com.

Files to update on macOS/Linux:

akto-validate-prompt-wrapper.sh
akto-validate-pre-tool-wrapper.sh
akto-validate-post-tool-wrapper.sh

Files to update on Windows:

akto-validate-prompt-wrapper.ps1
akto-validate-pre-tool-wrapper.ps1
akto-validate-post-tool-wrapper.ps1

Verify hooks.json Configuration

The hooks.json file should already be configured after downloading. Verify it contains all three hooks:

{
  "version": 1,
  "hooks": {
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "bash ./.github/hooks/akto-validate-prompt-wrapper.sh",
        "powershell": "powershell -ExecutionPolicy Bypass -File .github/hooks/akto-validate-prompt-wrapper.ps1",
        "comment": "Validate prompts against Akto Guardrails (monitoring only - cannot block per GitHub limitation)",
        "timeoutSec": 30
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "bash ./.github/hooks/akto-validate-pre-tool-wrapper.sh",
        "powershell": "powershell -ExecutionPolicy Bypass -File .github/hooks/akto-validate-pre-tool-wrapper.ps1",
        "comment": "Validate and block tool execution based on Akto Guardrails policies",
        "timeoutSec": 30
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "bash ./.github/hooks/akto-validate-post-tool-wrapper.sh",
        "powershell": "powershell -ExecutionPolicy Bypass -File .github/hooks/akto-validate-post-tool-wrapper.ps1",
        "comment": "Ingest tool execution results to Akto for monitoring and analytics",
        "timeoutSec": 30
      }
    ]
  }
}

Windows note: The powershell key is used automatically on Windows. The .ps1 wrapper sets all required environment variables before invoking the Python script — equivalent to what the .sh wrappers do on macOS/Linux.

Note: timeoutSec is in seconds (30 = 30 seconds). Hooks are loaded from .github/hooks/hooks.json in the directory you run copilot from.

Configure Hook Behavior (Optional)

Edit wrapper scripts to customize:

macOS / Linux — in each *-wrapper.sh:

export MODE="atlas"                    # "argus" or "atlas"
export AKTO_DATA_INGESTION_URL="..."  # Your Akto instance URL
export AKTO_SYNC_MODE="true"          # "true" (blocking) or "false" (observe only)
export AKTO_TIMEOUT="5"               # Timeout in seconds
export AKTO_CONNECTOR="github_copilot_cli"
export CONTEXT_SOURCE="ENDPOINT"

Windows — in each *-wrapper.ps1:

$env:MODE = "atlas"
$env:AKTO_DATA_INGESTION_URL = "..."  # Your Akto instance URL
$env:AKTO_SYNC_MODE = "true"
$env:AKTO_TIMEOUT = "5"
$env:AKTO_CONNECTOR = "github_copilot_cli"
$env:CONTEXT_SOURCE = "ENDPOINT"

Mode Options:

Argus: Standard validation and reporting
Atlas: Includes device-specific metadata

Sync Mode:

true: Validates in real-time; preToolUse blocks dangerous tool executions
false: Monitoring only; all tool executions pass through but are logged

Verify Installation

macOS / Linux:

# Check hooks.json is valid JSON
python3 -m json.tool .github/hooks/hooks.json

# Verify scripts are executable
ls -la .github/hooks/

# Test a hook manually
echo '{"prompt":"test","cwd":"/test","timestamp":1704614400000}' | \
  python3 .github/hooks/akto-validate-prompt.py

# Run a Copilot command from the project root
copilot

Windows (PowerShell):

# Check hooks.json is valid JSON
python -m json.tool .github\hooks\hooks.json

# List hook files
Get-ChildItem .github\hooks\

# Test a hook manually
'{"prompt":"test","cwd":"C:\\test","timestamp":1704614400000}' | python .github\hooks\akto-validate-prompt.py

# Run a Copilot command from the project root
copilot

Check logs to confirm hooks are working:

macOS / Linux:

# Default log location: ~/akto/.github/akto/copilot/logs/
tail -f ~/akto/.github/akto/copilot/logs/validate-prompt.log
tail -f ~/akto/.github/akto/copilot/logs/validate-pre-tool.log
tail -f ~/akto/.github/akto/copilot/logs/validate-post-tool.log

Windows (PowerShell):

# Default log location: C:\Users\<username>\akto\.github\akto\copilot\logs\
Get-Content "$env:USERPROFILE\akto\.github\akto\copilot\logs\validate-prompt.log" -Wait -Tail 20
Get-Content "$env:USERPROFILE\akto\.github\akto\copilot\logs\validate-pre-tool.log" -Wait -Tail 20
Get-Content "$env:USERPROFILE\akto\.github\akto\copilot\logs\validate-post-tool.log" -Wait -Tail 20

Configuration Reference

Wrapper Script Variables

export MODE="atlas"                                  # "argus" or "atlas"
export AKTO_DATA_INGESTION_URL="{{AKTO_DATA_INGESTION_URL}}"  # ⚠️ MUST REPLACE
export AKTO_SYNC_MODE="true"                         # "true" or "false"
export AKTO_TIMEOUT="5"                              # Timeout in seconds
export AKTO_CONNECTOR="github_copilot_cli"           # Connector identifier
export CONTEXT_SOURCE="ENDPOINT"                     # Context source tag

Environment Variables (Optional)

Override defaults via environment variables (e.g. in ~/.bashrc or ~/.zshrc):

export MODE="atlas"
export AKTO_DATA_INGESTION_URL="https://your-akto-instance.com"
export AKTO_SYNC_MODE="true"
export AKTO_TIMEOUT="5"

Troubleshooting

Hooks Not Executing

# Check you're running from the project root
ls -la .github/hooks/hooks.json

# Verify scripts are executable
ls -la .github/hooks/
chmod +x .github/hooks/*.py .github/hooks/*.sh

# Check JSON syntax
python3 -m json.tool .github/hooks/hooks.json

Ingestion URL Not Configured

macOS / Linux:

# Check current URL value in wrapper scripts
grep "AKTO_DATA_INGESTION_URL" .github/hooks/*-wrapper.sh

# Replace with actual URL
AKTO_URL="https://your-akto-instance.com"
sed -i.bak "s|{{AKTO_DATA_INGESTION_URL}}|${AKTO_URL}|g" .github/hooks/*-wrapper.sh

Windows (PowerShell):

# Check current URL value
Select-String "AKTO_DATA_INGESTION_URL" .github\hooks\*-wrapper.ps1

# Replace with actual URL
$AKTO_URL = "https://your-akto-instance.com"
Get-ChildItem ".github\hooks\*-wrapper.ps1" | ForEach-Object {
  (Get-Content $_.FullName) -replace '{{AKTO_DATA_INGESTION_URL}}', $AKTO_URL |
    Set-Content $_.FullName
}

Windows: Hooks Not Running

Step 1 — Verify .ps1 wrapper files were downloaded:

Get-ChildItem .github\hooks\*-wrapper.ps1

If missing, re-run the Windows download step above.

Step 2 — Unblock downloaded files:

Files downloaded via Invoke-WebRequest are marked as "from the internet" by Windows. Under RemoteSigned execution policy (default on Windows 10/11), these are blocked. Run:

Get-ChildItem ".github\hooks\*" | Unblock-File

Step 3 — Check execution policy:

Get-ExecutionPolicy
# If "Restricted", hooks cannot run at all.
# If "RemoteSigned", unblocking files (step 2) fixes it.
# "Bypass" or "Unrestricted" — execution policy is not the issue.

The hooks.json already includes -ExecutionPolicy Bypass in the powershell command, which overrides the policy per-invocation regardless of system settings.

Check Logs for Errors

# View logs
cat .github/akto/copilot/logs/*.log

# Check for errors
grep -i error .github/akto/copilot/logs/*.log 2>/dev/null || true

Events Not in Dashboard

# Test API connectivity
curl -X POST "${AKTO_DATA_INGESTION_URL}/api/http-proxy?akto_connector=github_copilot_cli" \
  -H "Content-Type: application/json" \
  -d '{"test": "event"}'

# Verify URL in wrapper scripts
grep "AKTO_DATA_INGESTION_URL" .github/hooks/*-wrapper.sh

Hook Timing Out

Increase timeoutSec in hooks.json (value in seconds, e.g. "timeoutSec": 60). Ensure AKTO_DATA_INGESTION_URL is reachable from your machine.

Permission Denied on Scripts

# Fix permissions
chmod +x .github/hooks/*.py .github/hooks/*.sh

# Verify Python 3 is available
python3 --version

Uninstallation

Complete Removal

# 1. Remove hook configuration and scripts
rm -rf .github/hooks/

# 2. Remove Akto logs (optional - keeps historical data if skipped)
rm -rf ~/akto-main/akto/.github/akto/

# 3. No restart needed - Copilot reads hooks.json on each invocation

Selective Removal (Keep Logs)

# Remove only hooks and configuration
rm -rf .github/hooks/

# Logs preserved in ~/akto-main/akto/.github/akto/copilot/logs/

Backup Before Removal

# Backup configuration and logs before removal
mkdir -p ~/akto-backup
cp -r .github/hooks/ ~/akto-backup/copilot-hooks/ 2>/dev/null
cp -r ~/akto-main/akto/.github/akto/ ~/akto-backup/copilot-akto-logs/ 2>/dev/null

# Then proceed with removal steps above

Verify Removal

# Check that hooks are removed
test -f .github/hooks/hooks.json && echo "⚠️  hooks.json still exists" || echo "✅ hooks.json removed"
test -d .github/hooks && echo "⚠️  Hook scripts still exist" || echo "✅ Hook scripts removed"

Enterprise Deployment

Automated Deployment Script

macOS / Linux:

#!/bin/bash
# deploy-copilot-cli-hooks.sh

set -e
AKTO_URL="${1:-https://your-akto-instance.com}"
PROJECT_DIR="${2:-.}"

echo "Installing Akto Guardrails for GitHub Copilot..."

# Create directory
mkdir -p "${PROJECT_DIR}/.github/hooks"

# Download hooks
HOOKS_BASE="https://raw.githubusercontent.com/akto-api-security/akto/master/apps/mcp-endpoint-shield/github-cli-hooks"
for FILE in \
  akto-validate-prompt-wrapper.sh akto-validate-prompt.py \
  akto-validate-pre-tool-wrapper.sh akto-validate-pre-tool.py \
  akto-validate-post-tool-wrapper.sh akto-validate-post-tool.py \
  akto_machine_id.py hooks.json; do
  curl -s "${HOOKS_BASE}/${FILE}" -o "${PROJECT_DIR}/.github/hooks/${FILE}"
done

# Make executable
chmod +x "${PROJECT_DIR}/.github/hooks"/*.py "${PROJECT_DIR}/.github/hooks"/*.sh

# Configure URL
sed -i.bak "s|{{AKTO_DATA_INGESTION_URL}}|${AKTO_URL}|g" \
  "${PROJECT_DIR}/.github/hooks"/*-wrapper.sh

echo "Installation complete! Akto instance: ${AKTO_URL}"
echo "Test with: cd ${PROJECT_DIR} && gh copilot suggest 'list files'"

Windows (PowerShell) — works on Azure Virtual Desktop pooled sessions:

# deploy-copilot-cli-hooks.ps1
param(
  [string]$AktoUrl = "https://your-akto-instance.com",
  [string]$ProjectDir = "."
)

$HOOKS_BASE = "https://raw.githubusercontent.com/akto-api-security/akto/master/apps/mcp-endpoint-shield/github-cli-hooks"
$hooksDir = Join-Path $ProjectDir ".github\hooks"

New-Item -ItemType Directory -Force -Path $hooksDir | Out-Null

$files = @(
  "akto-validate-prompt-wrapper.ps1", "akto-validate-prompt.py",
  "akto-validate-pre-tool-wrapper.ps1", "akto-validate-pre-tool.py",
  "akto-validate-post-tool-wrapper.ps1", "akto-validate-post-tool.py",
  "akto_machine_id.py", "hooks.json"
)

foreach ($file in $files) {
  Invoke-WebRequest -Uri "$HOOKS_BASE/$file" -OutFile (Join-Path $hooksDir $file)
}

# Configure URL
Get-ChildItem (Join-Path $hooksDir "*-wrapper.ps1") | ForEach-Object {
  (Get-Content $_.FullName) -replace '{{AKTO_DATA_INGESTION_URL}}', $AktoUrl |
    Set-Content $_.FullName
}

Write-Host "Installation complete! Akto instance: $AktoUrl"
Write-Host "Test with: cd $ProjectDir; gh copilot suggest 'list files'"

Deploy to developers (Windows):

Invoke-WebRequest -Uri https://your-org.com/deploy-copilot-cli-hooks.ps1 -OutFile deploy.ps1
powershell -File deploy.ps1 -AktoUrl https://your-akto-instance.com -ProjectDir C:\path\to\project

Quick Setup Summary

# 1. Create directory (from your project root)
mkdir -p .github/hooks

# 2. Download all hook scripts from GitHub (see step 2 above)

# 3. ⚠️ Configure Akto URL (REQUIRED)
AKTO_URL="https://your-akto-instance.com"
sed -i.bak "s|{{AKTO_DATA_INGESTION_URL}}|${AKTO_URL}|g" .github/hooks/*-wrapper.sh

# 4. Make executable
chmod +x .github/hooks/*.py .github/hooks/*.sh

# 5. Verify hooks.json is present and valid
python3 -m json.tool .github/hooks/hooks.json

# 6. Test (run from project root)
copilot

Resources

GitHub Copilot CLI: https://github.com/features/copilot/cli
GitHub: https://github.com/akto-api-security/akto
Support: [email protected]
Community: https://www.akto.io/community

PreviousClaude CLI Hooks NextGithub Copilot Enterprise

Last updated 1 hour ago

hashtagKey Features

hashtagHow Hooks Works

hashtagFile Structure

hashtagSetup Guide

hashtagPrerequisites

hashtagInstallation Steps

hashtagConfiguration Reference

hashtagWrapper Script Variables

hashtagEnvironment Variables (Optional)

hashtagTroubleshooting

hashtagHooks Not Executing

hashtagIngestion URL Not Configured

hashtagWindows: Hooks Not Running

hashtagCheck Logs for Errors

hashtagEvents Not in Dashboard

hashtagHook Timing Out

hashtagPermission Denied on Scripts

hashtagUninstallation

hashtagComplete Removal

hashtagSelective Removal (Keep Logs)

hashtagBackup Before Removal

hashtagVerify Removal

hashtagEnterprise Deployment

hashtagAutomated Deployment Script

hashtagQuick Setup Summary

hashtagResources

Key Features

How Hooks Works

File Structure

Setup Guide

Prerequisites

Installation Steps

Configuration Reference

Wrapper Script Variables

Environment Variables (Optional)

Troubleshooting

Hooks Not Executing

Ingestion URL Not Configured

Windows: Hooks Not Running

Check Logs for Errors

Events Not in Dashboard

Hook Timing Out

Permission Denied on Scripts

Uninstallation

Complete Removal

Selective Removal (Keep Logs)

Backup Before Removal

Verify Removal

Enterprise Deployment

Automated Deployment Script

Quick Setup Summary

Resources