# Kiro Integration

Connect Kiro IDE to Capsule Security for complete visibility into AI coding assistant activity, including prompts, agent responses, tool execution, and session lifecycle.

## Overview

This integration uses Kiro's hook system to capture AI coding assistant activity.

The following activity is captured:

| Event | Description |
|  --- | --- |
| **Session Start** | Session initialization with agent metadata (MCP servers, skills, steering) |
| **User Prompt** | User messages submitted to the agent |
| **Agent Response** | Assistant responses |
| **Agent Reasoning** | The agent's internal reasoning |
| **Tool Invocation** | Tool calls with arguments, results, success status, exit code, and timing |


## Prerequisites

Before you begin, ensure you have:

- **Kiro IDE** installed
- A **Capsule Security** account with admin access


## Step 1: Generate the Installer

1. Log in to the **Capsule Security** portal
2. Navigate to **Integrations** and locate **Kiro**
3. Click **Install** — Capsule generates a platform-specific installer with:
  - An embedded authentication token scoped to your organization
  - The hook dispatcher for your platform (bash for macOS/Linux, PowerShell for Windows)
  - The Capsule hook definition that is fanned out to your Kiro workspaces
4. Select your target platform (**Mac**, **Linux**, or **Windows**) to download the installer. The portal displays the exact command to run in the next step.


## Step 2: Run the Installer

The installer runs under your user account only — no root or administrator privileges are required, and no system-wide files are modified. It performs three actions:

- Writes the Capsule hook dispatcher under `~/.kiro/scripts/` (macOS/Linux) or `%APPDATA%\Kiro\scripts\` (Windows)
- Adds the dispatcher to Kiro's `kiroAgent.trustedCommands` in your user `settings.json` (idempotent; the original file is snapshotted on first modification)
- Installs the Capsule hook (`capsule-stop.kiro.hook`) into every Kiro workspace registered on your machine. New workspaces are picked up automatically on the next agent turn


### macOS / Linux

Open a terminal and run the command shown in the portal:


```bash
bash ~/Downloads/capsule-kiro-install.sh
```

### Windows

Open PowerShell and run the command shown in the portal:


```powershell
powershell -ExecutionPolicy Bypass -File "$HOME\Downloads\capsule-kiro-install.ps1"
```

Re-running the installer is safe — all operations are idempotent.

## Step 3: Restart Kiro

For the hook to take effect:

1. Quit Kiro completely
2. Reopen Kiro and your workspace


## Step 4: Verify the Installation

1. Open any Kiro workspace and run a simple agent task, for example:

```
Create a new file called test.txt with the content "Hello World"
```
2. Let the agent complete the task — the Capsule hook fires at the end of the agent turn
3. Log in to the **Capsule Security** portal
4. Navigate to **Inventory > Agents** and confirm your Kiro agent appears
5. Click on the agent and review the audit logs to verify events are captured:
  - Session start event
  - User prompt
  - Agent response
  - Tool invocations
6. To view the full conversation, navigate to **Observability** and filter by **Activity Type — Session**


### Troubleshooting

If events do not appear:

1. **Confirm the installer completed without errors.** Re-run the installer from the portal if needed — re-runs are idempotent.
2. **Verify the dispatcher is trusted.** Open your Kiro `settings.json` (Kiro → Settings → Open Settings (JSON)) and confirm `kiroAgent.trustedCommands` includes the Capsule dispatcher path.
3. **Confirm the hook is present in your workspace.** Look for `.kiro/hooks/capsule-stop.kiro.hook` in your workspace root.
4. **Restart Kiro.** Hook changes only load on Kiro startup.
5. **Check token expiration.** Tokens default to 365 days. Expired tokens require regenerating the installer from the portal.
6. **Contact Capsule Security support** if issues persist.


## Policy Enforcement

Capsule's Kiro integration is observation-only at the hook layer. Policy decisions are made server-side based on Policies configured in your Capsule tenant. To enforce policies on Kiro activity:

1. Navigate to **Policies** in the portal
2. Define or assign policies that target Kiro agents
3. Capsule evaluates captured user prompts against policy rules and surfaces violations under **Detections**


## Security Considerations

1. **The installer runs locally** under your user account — no root or administrator privileges are required, and no system-wide files are modified
2. **Authentication tokens** are scoped to your tenant and embedded in the dispatcher; never share the installer script outside your organization
3. **Inspect the dispatcher** at `~/.kiro/scripts/` (Unix) or `%APPDATA%\Kiro\scripts\` (Windows) if your security team requires script review before execution
4. **Token lifetime** can be customized (1–365 days) under **Advanced settings** in the portal before downloading the installer. Shorter TTLs require more frequent reinstalls


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: your organization ID, the platform on which the installer was run, and any error messages from the installer or Kiro logs


## References

- [Kiro Hooks Documentation](https://kiro.dev/docs/hooks)
- [Capsule Policies](https://docs.capsulesecurity.io/guides/policy-testing)
- [Capsule Webhook Events](https://docs.capsulesecurity.io/guides/webhook-events)