Skip to content
Guides
/
/
GitHub Copilot
Last updated

GitHub Copilot Integration

Connect GitHub Copilot to Capsule Security for complete visibility into AI coding assistant activity, including prompts, tool execution, agent sessions, and MCP tool usage across VS Code, GitHub Copilot CLI, and the Copilot coding agent.

Overview

This integration uses GitHub Copilot's hooks system to capture AI coding assistant activity. Hooks are shell commands that execute at specific points in the Copilot agent lifecycle, enabling automated audit, security enforcement, and observability.

The following hooks are configured:

Hook EventDescription
sessionStartAgent session initialization
sessionEndAgent session termination and cleanup
userPromptSubmittedUser prompts before submission to the AI
preToolUseTool execution requests before execution (can approve or deny)
postToolUseTool execution results after successful completion

Prerequisites

Before you begin, ensure you have:

  • VS Code with the GitHub Copilot extension installed, or GitHub Copilot CLI installed
  • GitHub Copilot Business or GitHub Copilot Enterprise subscription
  • A Capsule Security account with admin access

Step 1: Obtain Your Configuration File

Contact the Capsule Security support team to receive a hooks.json configuration file customized for your organization.

Install the Hooks Using Repository Distribution

Deploy hooks at the repository level so every contributor is covered automatically when working within the project.

Setup:

  1. Place the hooks.json file provided by Capsule Security in your repository under .github/hooks/:

    .github/
└── hooks/
    └── capsule-hooks.json

  2. Commit and push to your repository's default branch

  3. The hooks configuration will be automatically loaded by:

    • GitHub Copilot coding agent when processing tasks on this repository
    • VS Code when opening a workspace that contains the repository
    • GitHub Copilot CLI when running from within the repository directory

Key Features:

  • Hooks are version-controlled alongside your codebase
  • Automatically applies to all contributors working on the repository
  • No individual machine configuration required
  • Updates propagate through normal git pull workflows

Key Considerations:

  • The hooks file must be present on the repository's default branch for the Copilot coding agent to use it
  • Workspace-level hooks take precedence over user-level hooks for the same event type
  • Contributors can see the hooks configuration in the repository

Install the Hooks Using MDM Distribution

For organizations using Mobile Device Management (MDM) tools, deploy hooks to system-wide or user-level locations on managed devices.

VS Code Hooks Paths

Deploy the hooks.json configuration to the VS Code hooks directory:

PlatformPath
macOS~/Library/Application Support/Code/User/hooks/hooks.json
Linux~/.config/Code/User/hooks/hooks.json
Windows%APPDATA%\Code\User\hooks\hooks.json

GitHub Copilot CLI Hooks Paths

For organizations also using the Copilot CLI, deploy the hooks configuration to the user home directory:

PlatformPath
macOS~/.github/hooks/hooks.json
Linux~/.github/hooks/hooks.json
Windows%USERPROFILE%\.github\hooks\hooks.json

Key Considerations:

  • MDM-based distribution is fully managed by your organization
  • Your internal IT or security team is responsible for configuration, deployment, and updates
  • Leverage your existing MDM infrastructure while maintaining control over hook distribution

Install the Hooks Using Microsoft Intune Distribution

For organizations using Microsoft Intune for endpoint management, deploy the hooks configuration using Intune's Remediation (Proactive Remediations) feature with PowerShell scripts.

Overview

Microsoft Intune can deploy and enforce the Capsule Security hooks configuration across all managed Windows, macOS, and Linux devices. This approach uses Intune's Remediation feature, which consists of a Detection Script that checks compliance and a Remediation Script that applies the configuration when needed.

Windows Deployment

Setup Steps:

  1. Download the hooks.json file from the Capsule Security portal:

    • Navigate to Settings > Integrations
    • Locate the GitHub Copilot integration
    • Download the hooks.json file

  2. Log in to the Microsoft Intune admin center (https://intune.microsoft.com)

  3. Navigate to Devices > Remediations (under Monitor)

  4. Click Create script package and configure:

    • Name: Capsule Security – GitHub Copilot Hooks
    • Description: Deploys Capsule Security hooks configuration for GitHub Copilot in VS Code

  5. Add the Detection Script (Detect-CapsuleHooks.ps1):

    $hooksDir = "$env:APPDATA\Code\User\hooks"
$hooksFile = "$hooksDir\hooks.json"

if (Test-Path $hooksFile) {
    Write-Output "Capsule hooks configuration exists."
    exit 0
} else {
    Write-Output "Capsule hooks configuration is missing."
    exit 1
}

  6. Add the Remediation Script (Remediate-CapsuleHooks.ps1):

    $hooksDir = "$env:APPDATA\Code\User\hooks"
$hooksFile = "$hooksDir\hooks.json"

if (-not (Test-Path $hooksDir)) {
    New-Item -ItemType Directory -Path $hooksDir -Force | Out-Null
}

$hooksConfig = @'
<PASTE YOUR HOOKS.JSON CONTENT HERE>
'@

Set-Content -Path $hooksFile -Value $hooksConfig -Encoding UTF8

Write-Output "Capsule hooks configuration deployed successfully."
exit 0

    Replace <PASTE YOUR HOOKS.JSON CONTENT HERE> with the contents of the hooks.json file provided by Capsule Security.

  7. Configure the script settings:

    • Run this script using the logged-on credentials: Yes
    • Enforce script signature check: No
    • Run script in 64-bit PowerShell: Yes

  8. Assign the script package to the appropriate device groups or user groups

  9. Deploy the configuration

macOS Deployment

For macOS devices managed by Intune, deploy the hooks configuration using a Shell Script policy.

Setup Steps:

  1. Log in to the Microsoft Intune admin center

  2. Navigate to Devices > macOS > Shell scripts

  3. Click Add and configure:

    • Name: Capsule Security – GitHub Copilot Hooks (macOS)

  4. Upload the following shell script (deploy-capsule-hooks.sh):

    #!/bin/bash

HOOKS_DIR="$HOME/Library/Application Support/Code/User/hooks"

mkdir -p "$HOOKS_DIR"

cat > "$HOOKS_DIR/hooks.json" << 'HOOKSEOF'
<PASTE YOUR HOOKS.JSON CONTENT HERE>
HOOKSEOF

chmod 644 "$HOOKS_DIR/hooks.json"

echo "Capsule hooks configuration deployed successfully."
exit 0

    Replace <PASTE YOUR HOOKS.JSON CONTENT HERE> with the contents of the hooks.json file provided by Capsule Security.

  5. Configure the script settings:

    • Run script as signed-in user: Yes
    • Hide script notifications on devices: Yes
    • Script frequency: Every 1 day (to enforce ongoing compliance)
    • Max number of times to retry if script fails: 3

  6. Assign to the appropriate device groups

Monitoring Deployment

After deploying the remediation scripts, monitor status in the Intune admin center:

  1. Navigate to Devices > Remediations
  2. Select the Capsule Security – GitHub Copilot Hooks package
  3. Review the deployment status:
    • Without issues: Hooks already deployed or VS Code not installed
    • With issues: Hooks missing, remediation pending
    • Remediated: Script successfully deployed the hooks configuration

Key Considerations:

  • Remediation scripts run every 24 hours by default, ensuring ongoing compliance
  • The detection script verifies the hooks file exists; update it to validate file content if needed
  • Deploy to user context (not system context) so the hooks file lands in the correct user-specific path
  • For environments using both VS Code and Copilot CLI, create separate remediation packages for each hooks path

Install the Hooks Using Kandji Distribution (macOS)

For organizations using Kandji MDM, deploy the hooks configuration using a Custom App.

Setup Steps:

  1. Log in to your Kandji tenant
  2. Navigate to Library > Custom Apps
  3. Click Add New and select Custom App
  4. Configure the installation:
    • Name: Capsule Security GitHub Copilot Hooks
    • Install Type: Select ZIP File (unzip contents into specified directory)
    • Unzip Location: /Library/Application Support/Code/User/hooks/
  5. Configure the Preinstall Script:
    #!/bin/bash

HOOKS_DIR="/Library/Application Support/Code/User/hooks"

mkdir -p "$HOOKS_DIR"
chmod 755 "$HOOKS_DIR"

echo "Directory created successfully"
  6. Download the hooks.json file from the Capsule Security portal:
    • Navigate to Settings > Integrations
    • Locate the GitHub Copilot integration
    • Download the hooks.json file
  7. Create a ZIP archive containing the hooks.json file:
    zip hooks.zip hooks.json
  8. Upload the hooks.zip file to the Custom App
  9. Assign the Custom App to the appropriate devices or Smart Groups
  10. Deploy the configuration

Key Considerations:

  • The preinstall script ensures the target directory exists with proper permissions
  • Restart VS Code on target devices after deployment
  • Updates can be deployed by modifying the Custom App and incrementing the version

Install the Hooks Using Jamf Pro Distribution (macOS)

For organizations using Jamf Pro, deploy the hooks configuration using Jamf Composer to create a package with a preinstall script.

Setup Steps:

  1. Download the hooks.json file from the Capsule Security portal:

    • Navigate to Settings > Integrations
    • Locate the GitHub Copilot integration
    • Download the hooks.json file

  2. Open Jamf Composer on your Mac

  3. Create a new package source by dragging:

    • Open Finder and create the directory structure locally: /Library/Application Support/Code/User/hooks/
    • Place the hooks.json file inside this directory
    • Drag only the hooks folder directly into Composer's Sources panel on the left sidebar
    • A new package source will be created automatically with the correct directory structure

  4. Configure the package destination:

    • In the left sidebar, right-click on the newly created package source
    • Select Edit Package or Package Settings
    • Verify the destination is set to / (root) so files install to the correct location

  5. Add a Preinstall Script:

    • Expand the Package under Sources
    • Right-click on Scripts and select Add Shell Script > preinstall
    • Paste the following script:
    #!/bin/bash

mkdir -p "/Library/Application Support/Code/User/hooks"
chmod 755 "/Library/Application Support/Code/User/hooks"

echo "Directory created successfully"
exit 0

  6. Build the package:

    • Click Build as PKG
    • Save the package with a descriptive name (e.g., CapsuleCopilotHooks.pkg)

  7. Upload the package to Jamf Pro:

    • Log in to your Jamf Pro console
    • Navigate to Settings > Computer Management > Packages
    • Click New and upload the .pkg file
    • Configure display name and category

  8. Create a Policy to deploy the package:

    • Navigate to Computers > Policies
    • Click New
    • Configure the policy:
      • Name: Deploy Capsule Security GitHub Copilot Hooks
      • Trigger: Recurring Check-in (or your preferred trigger)
      • Execution Frequency: Once per computer
    • Under Packages, click Configure and add your package
    • Set Action to Install

  9. Configure the Scope:

    • Click the Scope tab
    • Add target computers, computer groups, or departments

  10. Save and deploy the policy

Key Considerations:

  • The preinstall script ensures the target directory exists with proper permissions before file deployment
  • Packages must be in .pkg format to support preinstall scripts
  • To update the configuration, create a new package version and update the policy
  • Consider using Smart Groups for dynamic targeting and rollout

Install the Hooks Using Microsoft SCCM Distribution (Windows)

For organizations using Microsoft System Center Configuration Manager (SCCM), deploy the hooks configuration as an SCCM Application with a script installer.

Setup Steps:

  1. Download the hooks.json file from the Capsule Security portal:

    • Navigate to Settings > Integrations
    • Locate the GitHub Copilot integration
    • Download the hooks.json file

  2. Place the hooks.json file on a network share accessible by your SCCM distribution points:

    \\sccm-server\sources\Software\CapsuleCopilotHooks\hooks.json

  3. Open the SCCM Console and navigate to Software Library > Application Management > Applications

  4. Click Create Application and select Manually specify the application information:

    • Name: Capsule Security GitHub Copilot Hooks
    • Publisher: Capsule Security
    • Description: Deploys Capsule Security hooks configuration for GitHub Copilot in VS Code

  5. Add a Deployment Type with Script Installer:

    • Content location: \\sccm-server\sources\Software\CapsuleCopilotHooks\

    • Install command:

      cmd.exe /c mkdir "%APPDATA%\Code\User\hooks" & copy /Y "hooks.json" "%APPDATA%\Code\User\hooks\hooks.json"

    • Uninstall command:

      cmd.exe /c del "%APPDATA%\Code\User\hooks\hooks.json"

  6. Configure the Detection Method:

    SettingValue
    TypeFile
    Path%APPDATA%\Code\User\hooks
    File namehooks.json
    PropertyFile or folder exists

  7. Configure User Experience settings:

    SettingValue
    Installation behaviorInstall for user
    Logon requirementOnly when a user is logged on
    Installation program visibilityHidden
    Maximum allowed run time5 minutes

  8. Distribute Content:

    • Right-click the application and select Distribute Content
    • Select your distribution point groups
    • Complete the wizard

  9. Create a Deployment:

    • Right-click the application and select Deploy
    • Choose the target User Collection
    • Configure:
    SettingValue
    ActionInstall
    PurposeRequired
    ScheduleAs soon as possible (or a maintenance window)

Key Considerations:

  • The hooks file is deployed to the user-level path %APPDATA%\Code\User\hooks\ consistent with VS Code's user configuration directory
  • Since this is a per-user deployment, target User Collections rather than Device Collections
  • To update the configuration, replace the hooks.json file on the network share and create a new deployment or use SCCM's content update and redeployment workflow
  • Restart VS Code on target devices after deployment for the hooks to take effect
  • For environments also using GitHub Copilot CLI, create an additional SCCM application targeting %USERPROFILE%\.github\hooks\hooks.json
  • Consider using SCCM Maintenance Windows to control when deployments occur

Install the Hooks Using Tanium Distribution

For organizations using Tanium for endpoint management, deploy the hooks configuration using Tanium Deploy packages.

Windows Deployment

Setup Steps:

  1. Download the hooks.json file from the Capsule Security portal:

    • Navigate to Settings > Integrations
    • Locate the GitHub Copilot integration
    • Download the hooks.json file

  2. Log in to the Tanium Console

  3. Navigate to Tanium Deploy > Packages

  4. Click Create Package and configure:

    • Name: Capsule Security – GitHub Copilot Hooks (Windows)
    • Description: Deploys Capsule Security hooks configuration for GitHub Copilot in VS Code

  5. Upload the hooks.json file to the package files

  6. Set the Command to run the following PowerShell script:

    $userProfiles = Get-ChildItem "C:\Users" -Directory | Where-Object { $_.Name -notin @('Public', 'Default', 'Default User') }

foreach ($profile in $userProfiles) {
    $hooksDir = Join-Path $profile.FullName "AppData\Roaming\Code\User\hooks"
    if (-not (Test-Path $hooksDir)) {
        New-Item -ItemType Directory -Path $hooksDir -Force | Out-Null
    }
    Copy-Item -Path "hooks.json" -Destination "$hooksDir\hooks.json" -Force
}

Write-Output "Capsule hooks configuration deployed successfully."
exit 0

  7. Create a Deployment:

    • Navigate to Tanium Deploy > Deployments
    • Click Create Deployment
    • Select the Capsule Security – GitHub Copilot Hooks (Windows) package
    • Target the appropriate Computer Groups
    • Deploy

macOS Deployment

Setup Steps:

  1. Navigate to Tanium Deploy > Packages

  2. Click Create Package and configure:

    • Name: Capsule Security – GitHub Copilot Hooks (macOS)
    • Description: Deploys Capsule Security hooks configuration for GitHub Copilot on macOS

  3. Upload the hooks.json file to the package files

  4. Set the Command to run the following script:

    #!/bin/bash
for USER_HOME in /Users/*/; do
    USERNAME=$(basename "$USER_HOME")
    if [ "$USERNAME" = "Shared" ] || [ "$USERNAME" = ".localized" ]; then
        continue
    fi
    HOOKS_DIR="$USER_HOME/Library/Application Support/Code/User/hooks"
    mkdir -p "$HOOKS_DIR"
    cp hooks.json "$HOOKS_DIR/hooks.json"
    chmod 644 "$HOOKS_DIR/hooks.json"
    chown "$USERNAME" "$HOOKS_DIR/hooks.json"
done
exit 0

  5. Create a Deployment targeting macOS endpoints using the appropriate Computer Groups

Key Considerations:

  • Tanium packages run as SYSTEM (Windows) or root (macOS) by default, so the scripts iterate over all user profiles to deploy to user-level paths
  • For environments also using GitHub Copilot CLI, create an additional package targeting %USERPROFILE%\.github\hooks\hooks.json (Windows) or ~/.github/hooks/hooks.json (macOS)
  • Use Tanium Computer Groups or saved questions to target specific OS versions or departments
  • For recurring enforcement, configure deployments with a recurring schedule
  • You can verify deployment across the fleet using Tanium Interact questions

Restart VS Code

After placing the configuration file, restart VS Code to activate the hooks.

Steps

  1. Close all VS Code windows

  2. Reopen VS Code

  3. Verify the hooks are active:

    • Right-click in the Chat view and select Diagnostics
    • Look for the hooks section to confirm they are loaded and enabled

Verify the Integration

Test that events are being captured in Capsule.

Steps

  1. Open a project in VS Code

  2. Use the Copilot agent mode (Copilot Chat with agent capabilities) to execute a task

  3. Log in to the Capsule Security portal

  4. Navigate to Inventory > Agents and confirm your agent is displayed

  5. Click on your agent and review the audit logs to verify events are being captured

  6. To view the full conversation, navigate to Observability → Filter Activity Type - Session

Troubleshooting

If events are not appearing:

  1. Check hook file location: Verify the hooks.json file is in the correct path for your platform

  2. Verify file syntax: Ensure the hooks file contains valid JSON

  3. Check VS Code diagnostics: Right-click in the Chat view and select Diagnostics to check for hook loading errors

  4. Verify script permissions: Ensure any hook scripts referenced in the configuration are executable (chmod +x)

  5. Contact Capsule Security support if issues persist

Support

For help with this integration:

  • Email: support@capsule.security
  • Include: Your organization ID, integration status, and any error messages

References

Previous page
Next page