Skip to content
Guides
/
/
Kiro
Last updated

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:

EventDescription
Session StartSession initialization with agent metadata (MCP servers, skills, steering)
User PromptUser messages submitted to the agent
Agent ResponseAssistant responses
Agent ReasoningThe agent's internal reasoning
Tool InvocationTool 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 ~/Downloads/capsule-kiro-install.sh

Windows

Open PowerShell and run the command shown in the portal:

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

Previous page
Next page