# 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 Event | Description |
|  --- | --- |
| **sessionStart** | Agent session initialization |
| **sessionEnd** | Agent session termination and cleanup |
| **userPromptSubmitted** | User prompts before submission to the AI |
| **preToolUse** | Tool execution requests before execution (can approve or deny) |
| **postToolUse** | Tool 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:

| Platform | Path |
|  --- | --- |
| **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:

| Platform | Path |
|  --- | --- |
| **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`):

```powershell
$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`):

```powershell
$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`):

```bash
#!/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**:

```bash
#!/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:

```bash
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](https://app.jamfnow.com/account/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:

```bash
#!/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
cmd.exe /c mkdir "%APPDATA%\Code\User\hooks" & copy /Y "hooks.json" "%APPDATA%\Code\User\hooks\hooks.json"
```
  - **Uninstall command**:

```cmd
cmd.exe /c del "%APPDATA%\Code\User\hooks\hooks.json"
```
6. Configure the **Detection Method**:
| Setting | Value |
|  --- | --- |
| Type | File |
| Path | `%APPDATA%\Code\User\hooks` |
| File name | `hooks.json` |
| Property | File or folder exists |
7. Configure **User Experience** settings:
| Setting | Value |
|  --- | --- |
| Installation behavior | Install for user |
| Logon requirement | Only when a user is logged on |
| Installation program visibility | Hidden |
| Maximum allowed run time | 5 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:
| Setting | Value |
|  --- | --- |
| Action | Install |
| Purpose | Required |
| Schedule | As 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:

```powershell
$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:

```bash
#!/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

- [GitHub Copilot Hooks Configuration Reference](https://docs.github.com/en/copilot/reference/hooks-configuration)
- [About Hooks – GitHub Copilot](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-hooks)
- [Using Hooks with Copilot Agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)
- [VS Code Agent Hooks (Preview)](https://code.visualstudio.com/docs/copilot/customization/hooks)
- [Using Hooks with GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-hooks)
- [Microsoft Intune Remediations](https://learn.microsoft.com/en-us/intune/intune-service/fundamentals/remediations)
- [VS Code Enterprise Policy Management](https://code.visualstudio.com/docs/setup/enterprise)
- [Jamf Composer User Guide](https://docs.jamf.com/composer/10.25.0/user-guide/Creating_Package_Sources.html)
- [Tanium Deploy User Guide](https://docs.tanium.com/deploy/deploy/index.html)