D&R-Driven AI Sessions¶

D&R-Driven AI Sessions allow you to automatically spawn Claude AI sessions in response to detections, events, or any condition matched by a Detection & Response rule. This enables powerful automated investigation, triage, and response workflows.

Overview¶

When a D&R rule matches, the start ai agent response action launches a Claude session with:

A prompt containing the context you specify
Access to tools and MCP servers you configure
Optional event data extracted and included automatically

The session runs autonomously, performing the investigation or analysis you've defined, and the results can be captured via outputs or stored for later review.

The `start ai agent` Action¶

There are two ways to configure the action: inline mode (all parameters in the rule) or definition mode (referencing a pre-configured AI agent from the Hive).

Inline Mode¶

Specify all session parameters directly in the D&R rule:

respond:
  - action: start ai agent
    prompt: "Your instructions to Claude..."
    anthropic_secret: hive://secret/my-anthropic-key

Required Parameters (Inline Mode)¶

Parameter	Description
`prompt`	The instructions for Claude. Supports template strings to include event data.
`anthropic_secret`	Your Anthropic API key. Use `hive://secret/<name>` to reference a Hive Secret.

Optional Parameters (Inline Mode)¶

Parameter	Description
`name`	Session name. Supports template strings. Useful for identifying sessions in logs.
`lc_api_key_secret`	LimaCharlie API key for org-level API access. Use `hive://secret/<name>`.
`lc_uid_secret`	LimaCharlie User ID. Required when `lc_api_key_secret` is a user API key (as opposed to an org API key). Use `hive://secret/<name>`.
`idempotent_key`	Unique key to prevent duplicate sessions. Supports template strings.
`debounce_key`	Serializes sessions: only one active session per key. New requests queue behind the active session and re-fire when it ends. Supports template strings.
`data`	Extract event data fields to include in the prompt as JSON.
`profile`	Inline session configuration (tools, model, limits, etc.).
`profile_name`	Reference a saved profile by name. Currently only supported for user sessions; for D&R sessions, use inline `profile` instead.

Note: You can specify either profile (inline) or profile_name (reference), but not both.

Definition Mode¶

Reference a pre-configured AI agent definition stored in the Hive:

respond:
  - action: start ai agent
    definition: hive://ai_agent/my-triage-bot

In definition mode, all session configuration (prompt, anthropic key, profile, etc.) comes from the referenced AI agent record. No other parameters are required.

You can optionally override debounce_key at the action level, even in definition mode:

respond:
  - action: start ai agent
    definition: hive://ai_agent/my-triage-bot
    debounce_key: "investigate-{{ .routing.sid }}"

Configuration Options¶

Prompt Templating¶

The prompt parameter supports LimaCharlie's template syntax. You can include event data directly in your instructions:

- action: start ai agent
  prompt: |
    A suspicious process was detected on {{ .routing.hostname }}.

    Process: {{ .event.FILE_PATH }}
    Command Line: {{ .event.COMMAND_LINE }}
    User: {{ .event.USER_NAME }}

    Please investigate this activity and determine if it's malicious.
  anthropic_secret: hive://secret/anthropic-key

Data Extraction¶

Use the data parameter to extract specific fields and include them as structured JSON:

- action: start ai agent
  prompt: "Analyze this detection and provide a severity assessment."
  anthropic_secret: hive://secret/anthropic-key
  data:
    hostname: "{{ .routing.hostname }}"
    sensor_id: "{{ .routing.sid }}"
    process_path: "{{ .event.FILE_PATH }}"
    command_line: "{{ .event.COMMAND_LINE }}"
    parent_process: "{{ .event.PARENT/FILE_PATH }}"
    detection_name: "{{ .detect.cat }}"

The extracted data is appended to the prompt as a JSON code block.

Idempotent Sessions¶

Prevent duplicate sessions for the same event using idempotent_key:

- action: start ai agent
  prompt: "Investigate this detection..."
  anthropic_secret: hive://secret/anthropic-key
  idempotent_key: "{{ .detect.detect_id }}"

If a session with the same idempotent key was recently created (within 24 hours), the action is skipped.

Debounced Sessions¶

Use debounce_key to serialize sessions so only one runs at a time per key. When a session is already active for a given debounce key, new requests are queued. When the active session ends, the most recent queued request is automatically re-fired.

This is useful for workflows where multiple detections may fire in rapid succession but should be handled sequentially by a single agent (e.g., a triage bot processing cases one at a time).

- action: start ai agent
  prompt: "Investigate this case..."
  anthropic_secret: hive://secret/anthropic-key
  debounce_key: "triage-bot"

Unlike idempotent_key which silently drops duplicates, debounce_key guarantees the latest request will eventually be processed — it just waits for the current session to finish first. Only the most recent pending request is kept per key. The key supports template strings for dynamic serialization:

# Serialize per sensor — one active investigation per endpoint
debounce_key: "investigate-{{ .routing.sid }}"

Debounce vs Idempotent: Use idempotent_key when the same event should never create more than one session. Use debounce_key when each event should be processed, but sequentially rather than in parallel.

Session Profiles¶

Profiles let you configure Claude's behavior, available tools, and resource limits.

Inline Profile¶

- action: start ai agent
  prompt: "Investigate this activity..."
  anthropic_secret: hive://secret/anthropic-key
  profile:
    # Tool access
    allowed_tools:
      - Bash
      - Read
      - Grep
      - Glob
      - WebFetch
    denied_tools:
      - Write
      - Edit

    # Permission mode
    permission_mode: acceptEdits

    # Model configuration
    model: claude-sonnet-4-20250514
    max_turns: 50
    max_budget_usd: 5.0
    one_shot: true  # Complete initial task then terminate (this is the default for D&R sessions)
    ttl_seconds: 1800

    # Environment variables
    environment:
      LOG_LEVEL: debug
      API_KEY: hive://secret/external-api-key

    # MCP servers
    mcp_servers:
      limacharlie:
        type: http
        url: https://mcp.limacharlie.io
        headers:
          Authorization: hive://secret/lc-mcp-token

Profile Options¶

Option	Type	Description
`allowed_tools`	list	Tools Claude can use. If empty, all tools are allowed.
`denied_tools`	list	Tools Claude cannot use. Takes precedence over `allowed_tools`.
`permission_mode`	string	`acceptEdits` (default), `plan`, or `bypassPermissions`
`model`	string	Claude model to use (e.g., `claude-sonnet-4-20250514`)
`max_turns`	integer	Maximum conversation turns before auto-termination
`max_budget_usd`	float	Maximum spend limit in USD
`one_shot`	boolean	When `true`, session completes all work for the initial prompt (including tools, skills, and subagents) then terminates automatically. Default: `true` for D&R-triggered sessions.
`ttl_seconds`	integer	Maximum session lifetime in seconds. Capped at 24 hours.
`environment`	map	Environment variables. Values can use `hive://secret/`
`mcp_servers`	map	MCP server configurations (see below)

MCP Server Configuration¶

MCP (Model Context Protocol) servers extend Claude's capabilities by providing additional data sources and tools.

HTTP MCP Server¶

mcp_servers:
  limacharlie:
    type: http
    url: https://mcp.limacharlie.io
    headers:
      Authorization: hive://secret/lc-mcp-token

Stdio MCP Server¶

mcp_servers:
  custom-tool:
    type: stdio
    command: /usr/bin/my-tool
    args:
      - --config
      - /etc/my-tool.conf
    env:
      API_KEY: hive://secret/tool-api-key

Examples¶

Example 1: Basic Detection Investigation¶

Automatically investigate when a suspicious process is detected:

detect:
  event: NEW_PROCESS
  op: contains
  path: event/COMMAND_LINE
  value: -encodedcommand

respond:
  - action: report
    name: encoded-powershell-command
  - action: start ai agent
    prompt: |
      A PowerShell process with an encoded command was detected.

      Decode the command and analyze what it does.
      Check for persistence mechanisms, lateral movement, or data exfiltration.
      Provide a severity assessment and recommended response actions.
    anthropic_secret: hive://secret/anthropic-key
    data:
      command_line: "{{ .event.COMMAND_LINE }}"
      hostname: "{{ .routing.hostname }}"
      user: "{{ .event.USER_NAME }}"

Example 2: Automated Triage with LimaCharlie MCP¶

Use the LimaCharlie MCP server to query additional context:

detect:
  target: detection
  event: "*"
  op: is greater than
  path: priority
  value: 3

respond:
  - action: start ai agent
    prompt: |
      A high-priority detection was triggered. Use the LimaCharlie MCP tools to:

      1. Get information about the sensor where this occurred
      2. Query recent events from the same sensor
      3. Check if the same detection occurred on other sensors
      4. Look up any relevant threat intelligence

      Produce a summary report with:
      - What happened
      - Scope of impact
      - Recommended immediate actions
      - Suggested long-term mitigations
    anthropic_secret: hive://secret/anthropic-key
    lc_api_key_secret: hive://secret/lc-api-key
    idempotent_key: "{{ .detect.detect_id }}"
    profile:
      max_turns: 100
      max_budget_usd: 10.0
      mcp_servers:
        limacharlie:
          type: http
          url: https://mcp.limacharlie.io
          headers:
            Authorization: hive://secret/lc-mcp-token

Example 3: Threat Hunting Automation¶

Automatically investigate IoC matches from threat intelligence:

detect:
  event: DNS_REQUEST
  op: lookup
  path: event/DOMAIN_NAME
  resource: lookup/threat-domains

respond:
  - action: report
    name: threat-intel-domain-match
  - action: start ai agent
    name: "threat-hunt-{{ .routing.sid }}"
    prompt: |
      A DNS request to a known malicious domain was detected.

      Using the available tools:
      1. Identify the process that made the DNS request
      2. Examine the process's network connections
      3. Check for any files written by the process
      4. Look for persistence mechanisms
      5. Identify if other sensors communicated with this domain

      Document all findings and provide a detailed incident report.
    anthropic_secret: hive://secret/anthropic-key
    lc_api_key_secret: hive://secret/lc-api-key
    profile:
      allowed_tools:
        - Bash
        - Read
        - Grep
        - Glob
        - WebFetch
      denied_tools:
        - Write
        - Edit
      max_turns: 150
      ttl_seconds: 3600

Example 4: Custom Enrichment¶

Use external tools via MCP for enrichment:

respond:
  - action: start ai agent
    prompt: |
      Enrich this alert with external threat intelligence.

      Check the file hash against VirusTotal.
      Look up the IP address geolocation and reputation.
      Cross-reference with MITRE ATT&CK techniques.
    anthropic_secret: hive://secret/anthropic-key
    data:
      file_hash: "{{ .event.HASH }}"
      ip_address: "{{ .event.IP_ADDRESS }}"
    profile:
      mcp_servers:
        virustotal:
          type: http
          url: https://vt-mcp.example.com
          headers:
            x-apikey: hive://secret/vt-api-key
        mitre:
          type: http
          url: https://mitre-mcp.example.com

Example 5: Definition Mode with Hive AI Agent¶

Instead of putting all session configuration inline in every D&R rule, you can store a reusable AI agent definition in the ai_agent hive and reference it by name.

Step 1: Create the AI Agent Record¶

Store the agent definition in the ai_agent hive (via the API, CLI, or infrastructure-as-code):

ai_agent:
  detection-investigator:
    data:
      # Credentials (use hive://secret/ references)
      anthropic_secret: hive://secret/anthropic-key
      lc_api_key_secret: hive://secret/lc-api-key

      # Prompt with instructions
      prompt: |
        You are a detection investigator. A detection has fired and you need to
        investigate it and document your findings.

        Using the provided event data:
        1. Get details about the sensor where this occurred
        2. Check the process tree and parent/child relationships
        3. Look for related network connections and file operations
        4. Check if similar activity exists on other sensors
        5. Assess severity and provide a recommendation

        Document all findings in a structured report.

      # Session name (supports template strings)
      name: "investigate-{{ .routing.hostname }}"

      # Extract event data fields to include in the prompt
      data:
        hostname: routing.hostname
        sensor_id: routing.sid
        detection_name: detect.cat

      # Session configuration
      model: claude-sonnet-4-20250514
      max_turns: 50
      max_budget_usd: 5.0
      ttl_seconds: 1800
      one_shot: true
      permission_mode: bypassPermissions

      # Tool restrictions
      allowed_tools:
        - Bash
        - Read
        - Grep
        - Glob
        - WebFetch
      denied_tools:
        - Write
        - Edit

      # MCP servers
      mcp_servers:
        limacharlie:
          type: http
          url: https://mcp.limacharlie.io
          headers:
            Authorization: hive://secret/lc-mcp-token

    usr_mtd:
      enabled: true

Step 2: Reference It from D&R Rules¶

The D&R rule becomes minimal — just a reference to the agent definition:

detect:
  target: detection
  event: "*"
  op: is greater than
  path: priority
  value: 3

respond:
  - action: start ai agent
    definition: hive://ai_agent/detection-investigator
    debounce_key: "investigate-{{ .routing.sid }}"

This approach keeps D&R rules clean and lets you update the agent's behavior (prompt, model, tools, etc.) in one place without modifying every rule that uses it. The debounce_key can be overridden at the action level even in definition mode.

AI Agent Record Fields¶

Field	Type	Required	Description
`prompt`	string	Yes	Instructions for Claude.
`anthropic_secret`	string	No	Anthropic API key or `hive://secret/` reference.
`lc_api_key_secret`	string	No	LimaCharlie API key or `hive://secret/` reference.
`lc_uid_secret`	string	No	LimaCharlie User ID or `hive://secret/` reference. Required when `lc_api_key_secret` is a user API key.
`name`	string	No	Session name. Supports template strings.
`data`	map	No	Event data extraction mapping.
`allowed_tools`	list	No	Tools Claude can use.
`denied_tools`	list	No	Tools Claude cannot use.
`permission_mode`	string	No	`acceptEdits`, `plan`, or `bypassPermissions`.
`model`	string	No	Claude model identifier.
`max_turns`	integer	No	Maximum conversation turns.
`max_budget_usd`	float	No	Maximum spend limit in USD.
`ttl_seconds`	integer	No	Maximum session lifetime in seconds.
`one_shot`	boolean	No	Auto-terminate after initial task.
`environment`	map	No	Environment variables (values can use `hive://secret/`).
`mcp_servers`	map	No	MCP server configurations.

Best Practices¶

Prompt Design¶

Be specific: Tell Claude exactly what you want it to investigate and how to report findings
Provide context: Include relevant event data in the prompt
Define outputs: Specify the format you want for results (markdown, JSON, etc.)
Set boundaries: Clearly state what actions Claude should NOT take

Resource Limits¶

Set max_turns: Prevent runaway sessions that consume excessive resources
Set max_budget_usd: Cap costs for each session
Use ttl_seconds: Automatically terminate long-running sessions

Security¶

Store secrets in Hive: Never hardcode API keys in D&R rules
Limit tools: Only allow tools Claude needs for the task
Use denied_tools: Explicitly block dangerous tools for sensitive operations
Restrict MCP access: Only configure MCP servers that are necessary

Deduplication and Serialization¶

Use idempotent_key: Prevent duplicate sessions for the same event
Use debounce_key: Serialize sessions so only one runs at a time per key, with queued requests re-fired on completion
Include unique identifiers: Use detect_id, this atom, or similar unique values
Combine with suppression: Use D&R suppression to limit how often sessions are spawned

Troubleshooting¶

Session Not Starting¶

Verify the Anthropic API key is valid and stored correctly in Hive Secrets
Check that the D&R rule is enabled and matching events
Review D&R rule syntax for errors

Session Failing¶

Check max_turns isn't too low for the task
Verify MCP server URLs and authentication
Review session logs for error messages

Unexpected Behavior¶

Review the prompt for ambiguity
Check that allowed_tools includes necessary tools
Verify denied_tools isn't blocking required capabilities