# Cursor Integration

Connect your Cursor IDE to Capsule Security for complete visibility into AI coding assistant activity, including prompts, responses, shell commands, and MCP tool usage.

## Overview

This integration uses Cursor's hooks system to capture AI coding assistant activity.

![Cursor Hooks](/assets/cursor-hooks.a099784396fab503bc54671f525479342dd230f3fe97d7c845ccb1f5bce637b6.9c1bb791.gif)

The following hooks are configured:

| Hook | Description |
|  --- | --- |
| **beforeSubmitPrompt** | User prompts before submission to the AI |
| **afterAgentResponse** | AI assistant responses |
| **afterAgentThought** | Agent reasoning and thought processes |
| **afterShellExecution** | Shell commands and their output |
| **afterMCPExecution** | MCP tool calls and results |


## Prerequisites

Before you begin, ensure you have:

- **Cursor IDE** installed (version 0.40 or later recommended)
- 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 Cloud Distribution (Enterprise Only)

Enterprise teams can leverage Cursor's native cloud distribution system to automatically synchronize hooks across their organization.

**Key Features:**

- Centralized management through the Cursor web dashboard
- Automatic synchronization to all team members (every 30 minutes)
- Operating system targeting for platform-specific hooks
- No manual deployment to individual machines required


**Setup:**

1. Access the Cursor web dashboard
2. Navigate to the team content section under Hooks
3. Upload or configure the hooks provided by Capsule Security
4. The platform automatically delivers configurations to all authenticated team members


## Install the hooks using MDM Distribution

For organizations using Mobile Device Management (MDM) tools, deploy hooks to the following system-wide locations:

| Platform | Path |
|  --- | --- |
| **macOS** | `/Library/Application Support/Cursor/hooks.json` |
| **Linux/WSL** | `/etc/cursor/hooks.json` |
| **Windows** | `C:\ProgramData\Cursor\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 Kandji Distribution (macOS)

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

![Kandji](/assets/kandji.c85e00be11fccc4f7524cc80bd96b7b4845665f5e373d6a988cdb3c100ba0e52.9c1bb791.png)

**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 Cursor Hooks
  - **Install Type**: Select **ZIP File (unzip contents into specified directory)**
  - **Unzip Location**: `/Library/Application Support/Cursor/`
5. Configure the **Preinstall Script**:

```bash
#!/bin/bash

# Create the Cursor directory if it doesn't exist
mkdir -p "/Library/Application Support/Cursor"

# Set appropriate permissions
chmod 755 "/Library/Application Support/Cursor"

echo "Directory created successfully"
```
6. Download the **hooks.json** file from the Capsule Security portal:
  - Navigate to **Settings > Integrations**
  - Locate the Cursor 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
- The ZIP file will be extracted directly into `/Library/Application Support/Cursor/`
- Restart Cursor 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 Cursor 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/Cursor/`
  - Place the `hooks.json` file inside this directory
  - **Important**: Composer captures the exact file structure, so the `hooks.json` file must already be in `/Library/Application Support/Cursor/` before dragging into Composer
  - Drag only the `Cursor` 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 installation location:
    - Confirm the destination is set to `/` (root) so files install to `/Library/Application Support/Cursor/`
    - Verify the `hooks.json` file is mapped to be installed in 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

# Create the Cursor directory if it doesn't exist
mkdir -p "/Library/Application Support/Cursor"

# Set appropriate permissions
chmod 755 "/Library/Application Support/Cursor"

echo "Directory created successfully"
exit 0
```
6. Build the package:
  - Click **Build as PKG**
  - Save the package with a descriptive name (e.g., `CapsuleCursorHooks.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 Cursor 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 Cursor 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\CapsuleCursorHooks\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 Cursor Hooks
  - **Publisher**: Capsule Security
  - **Description**: Deploys Cursor hooks configuration for Capsule Security monitoring
5. Add a **Deployment Type** with **Script Installer**:
  - **Content location**: `\\sccm-server\sources\Software\CapsuleCursorHooks\`
  - **Install command**:

```cmd
cmd.exe /c mkdir "C:\ProgramData\Cursor" & copy /Y "hooks.json" "C:\ProgramData\Cursor\hooks.json"
```
  - **Uninstall command**:

```cmd
cmd.exe /c del "C:\ProgramData\Cursor\hooks.json"
```
6. Configure the **Detection Method**:
| Setting | Value |
|  --- | --- |
| Type | File |
| Path | `C:\ProgramData\Cursor` |
| File name | `hooks.json` |
| Property | File or folder exists |
7. Configure **User Experience** settings:
| Setting | Value |
|  --- | --- |
| Installation behavior | Install for system |
| Logon requirement | Whether or not 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 **Device 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 system-wide path `C:\ProgramData\Cursor\` so it applies to all users on the machine
- Since this is a system-level deployment, target **Device Collections** rather than User 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 Cursor on target devices after deployment for the hooks to take effect
- Consider using SCCM Maintenance Windows to control when deployments occur


## Restart Cursor

After placing the configuration file, restart Cursor to activate the hooks.

### Steps

1. Close all Cursor windows
2. Reopen Cursor
3. Verify the hooks are active:
  - Open Cursor Settings
  - Navigate to the **Hooks** tab
  - Confirm the hooks are listed and enabled


## Verify the Integration

Test that events are being captured in Capsule.

### Steps

1. Open a project in Cursor
2. Use the AI assistant (Cmd+K or Agent Chat) 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, please contact the Capsule Security support team for assistance.

## Support

For help with this integration:

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


## References

- [Cursor Hooks Documentation](https://cursor.com/docs/agent/hooks)
- [Cloud Distribution (Enterprise Only)](https://cursor.com/docs/agent/hooks#cloud-distribution-enterprise-only)
- [MDM Distribution](https://cursor.com/docs/agent/hooks#mdm-distribution)
- [Jamf Composer User Guide - Creating Package Sources](https://docs.jamf.com/composer/10.25.0/user-guide/Creating_Package_Sources.html)
- [Jamf Composer User Guide - Building Packages](https://docs.jamf.com/composer/10.25.0/user-guide/Building_Packages_from_Package_Sources.html)