Triage Warden

AI-powered security incident triage and response platform

Triage Warden automates the analysis and response to security incidents using AI agents, configurable playbooks, and integrations with your existing security stack.

Features

• AI-Powered Triage: Automated analysis of phishing emails, malware alerts, and suspicious login attempts
• Configurable Playbooks: Define custom investigation and response workflows
• Policy Engine: Role-based approval workflows for sensitive actions
• Connector Framework: Integrate with VirusTotal, Splunk, CrowdStrike, Jira, Microsoft 365, and more
• Web Dashboard: Real-time incident management with approval workflows
• REST API: Programmatic access for automation and integration
• Audit Trail: Complete logging of all actions and decisions

Quick Example

# Analyze a phishing email
tw-cli incident create --type phishing --source "email-gateway" --data '{"subject": "Urgent: Update Account"}'

# Run AI triage
tw-cli triage run --incident INC-2024-001

# View the verdict
tw-cli incident get INC-2024-001 --format json

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        Web Dashboard                             │
│                    (HTMX + Askama Templates)                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                         REST API                                 │
│                     (Axum + Tower)                               │
└─────────────────────────────────────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
┌───────────────┐    ┌───────────────────┐    ┌───────────────┐
│ Policy Engine │    │   AI Triage Agent │    │    Actions    │
│    (Rust)     │    │     (Python)      │    │    (Rust)     │
└───────────────┘    └───────────────────┘    └───────────────┘
        │                       │                       │
        └───────────────────────┼───────────────────────┘
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Connector Layer                            │
│        (VirusTotal, Splunk, CrowdStrike, Jira, M365)            │
└─────────────────────────────────────────────────────────────────┘

Getting Started

1. Installation - Install Triage Warden
2. Quick Start - Create your first incident
3. Configuration - Configure connectors and policies

License

Triage Warden is licensed under the MIT License.

Getting Started

Welcome to Triage Warden! This guide will help you get up and running quickly.

Prerequisites

• Rust 1.75+ (for building from source)
• Python 3.11+ (for AI triage agents)
• SQLite or PostgreSQL (for data storage)
• uv (recommended Python package manager)

Installation Options

1. From Source - Build and run locally
2. Docker - Run in containers
3. Pre-built Binaries - Download releases

Next Steps

• Installation - Detailed installation instructions
• Quick Start - Create your first incident in 5 minutes
• Configuration - Configure connectors and settings

Installation

Building from Source

Prerequisites

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

Clone and Build

# Clone the repository
git clone https://github.com/zachyking/triage-warden.git
cd triage-warden

# Build Rust components
cargo build --release

# Install Python dependencies
cd python
uv sync

Verify Installation

# Check the CLI
./target/release/triage-warden --version

# Run tests
cargo test
cd python && uv run pytest

Docker

# Build the image
docker build -t triage-warden .

# Run with default settings
docker run -p 8080:8080 triage-warden

# Run with custom configuration
docker run -p 8080:8080 \
  -e TW_DATABASE_URL=postgres://user:pass@host/db \
  -e TW_VIRUSTOTAL_API_KEY=your-key \
  triage-warden

Pre-built Binaries

Download the latest release from the releases page.

Available platforms:

• Linux x86_64 (glibc)
• Linux x86_64 (musl)
• macOS x86_64
• macOS aarch64 (Apple Silicon)

# Example for macOS
curl -LO https://github.com/zachyking/triage-warden/releases/latest/download/triage-warden-macos-aarch64.tar.gz
tar xzf triage-warden-macos-aarch64.tar.gz
./triage-warden --version

Database Setup

SQLite (Default)

SQLite is used by default. The database file is created automatically:

# Default location
DATABASE_URL=sqlite://./triage_warden.db

# Custom location
DATABASE_URL=sqlite:///var/lib/triage-warden/data.db

PostgreSQL

For production deployments:

# Create database
createdb triage_warden

# Set connection string
export DATABASE_URL=postgres://user:password@localhost/triage_warden

# Run migrations
triage-warden db migrate

Next Steps

• Quick Start - Create your first incident
• Configuration - Configure the system

Quick Start

Get Triage Warden running and process your first incident in 5 minutes.

1. Start the Server

# Start with default settings (SQLite, mock connectors)
cargo run --bin tw-api

# Or use the release binary
./target/release/tw-api

The web dashboard is now available at http://localhost:8080.

2. Create an Incident

Via Web Dashboard

1. Open http://localhost:8080 in your browser
2. Click "New Incident"
3. Fill in the incident details:
   • Type: Phishing
   • Source: Email Gateway
   • Severity: Medium
4. Click Create

Via CLI

tw-cli incident create \
  --type phishing \
  --source "email-gateway" \
  --severity medium \
  --data '{
    "subject": "Urgent: Verify Your Account",
    "sender": "[email protected]",
    "recipient": "[email protected]"
  }'

Via API

curl -X POST http://localhost:8080/api/incidents \
  -H "Content-Type: application/json" \
  -d '{
    "incident_type": "phishing",
    "source": "email-gateway",
    "severity": "medium",
    "raw_data": {
      "subject": "Urgent: Verify Your Account",
      "sender": "[email protected]"
    }
  }'

3. Run AI Triage

# Trigger triage for the incident
tw-cli triage run --incident INC-2024-0001

The AI agent will:

1. Parse email headers and content
2. Check sender reputation
3. Analyze URLs and attachments
4. Generate a verdict with confidence score

4. View the Verdict

# Get incident with triage results
tw-cli incident get INC-2024-0001

# Example output:
# Incident: INC-2024-0001
# Type: phishing
# Status: triaged
# Verdict: malicious
# Confidence: 0.92
# Recommended Actions:
#   - quarantine_email
#   - block_sender
#   - notify_user

5. Execute Actions

Actions may require approval based on your policy configuration:

# Request to quarantine the email
tw-cli action execute --incident INC-2024-0001 --action quarantine_email

# If auto-approved:
# Action executed: quarantine_email (status: completed)

# If requires approval:
# Action pending approval from: Senior Analyst

Approve pending actions via the dashboard at /approvals.

Next Steps

• Configuration - Set up real connectors
• Playbooks - Create automated workflows
• Policy Engine - Configure approval rules

Configuration

Triage Warden is configured through environment variables and configuration files.

Environment Variables

Core Settings

Connector Selection

VirusTotal

TW_THREAT_INTEL_MODE=virustotal
TW_VIRUSTOTAL_API_KEY=your-api-key-here

Splunk

TW_SIEM_MODE=splunk
TW_SPLUNK_URL=https://splunk.company.com:8089
TW_SPLUNK_TOKEN=your-token-here

CrowdStrike

TW_EDR_MODE=crowdstrike
TW_CROWDSTRIKE_CLIENT_ID=your-client-id
TW_CROWDSTRIKE_CLIENT_SECRET=your-client-secret
TW_CROWDSTRIKE_REGION=us-1  # us-1, us-2, eu-1

Microsoft 365

TW_EMAIL_GATEWAY_MODE=m365
TW_M365_TENANT_ID=your-tenant-id
TW_M365_CLIENT_ID=your-client-id
TW_M365_CLIENT_SECRET=your-client-secret

Jira

TW_TICKETING_MODE=jira
TW_JIRA_URL=https://company.atlassian.net
[email protected]
TW_JIRA_API_TOKEN=your-api-token
TW_JIRA_PROJECT_KEY=SEC

AI Provider

TW_AI_PROVIDER=anthropic  # anthropic, openai
TW_ANTHROPIC_API_KEY=your-api-key
# or
TW_OPENAI_API_KEY=your-api-key

Configuration File

For complex configurations, use a TOML file:

# config.toml

[server]
host = "0.0.0.0"
port = 8080
log_level = "info"

[database]
url = "postgres://user:pass@localhost/triage_warden"
max_connections = 10

[connectors.threat_intel]
mode = "virustotal"
api_key = "${TW_VIRUSTOTAL_API_KEY}"
rate_limit = 4  # requests per minute

[connectors.siem]
mode = "splunk"
url = "https://splunk.company.com:8089"
token = "${TW_SPLUNK_TOKEN}"

[connectors.edr]
mode = "crowdstrike"
client_id = "${TW_CROWDSTRIKE_CLIENT_ID}"
client_secret = "${TW_CROWDSTRIKE_CLIENT_SECRET}"
region = "us-1"

[ai]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
max_tokens = 4096

[policy]
default_action_approval = "auto"  # auto, analyst, senior, manager
high_severity_approval = "senior"
critical_action_approval = "manager"

Load with:

tw-api --config config.toml

Policy Rules

Policy rules control action approval requirements. See Policy Engine for details.

# Example policy rule
[[policy.rules]]
name = "isolate_host_requires_manager"
action = "isolate_host"
severity = ["high", "critical"]
approval_level = "manager"

Logging

Configure structured logging:

# JSON output for production
TW_LOG_FORMAT=json

# Pretty output for development
TW_LOG_FORMAT=pretty

# Filter specific modules
RUST_LOG=tw_api=debug,tw_core=info

Next Steps

• Connectors - Detailed connector configuration
• Policy Engine - Configure approval workflows
• API Authentication - Set up API access

Web Dashboard

Browser-based interface for incident management.

Overview

The dashboard provides:

• Real-time incident monitoring
• Approval workflow management
• Playbook configuration
• System settings

Access at: http://localhost:8080

Features

Home Dashboard

The main dashboard displays:

• KPIs: Open incidents, pending approvals, triage rate
• Recent Incidents: Latest incidents with status
• Trend Charts: Incident volume over time
• Quick Actions: Create incident, run playbook

Incident Management

• List view with filtering and sorting
• Detail view with full incident context
• Action execution interface
• Triage results and reasoning

Approval Workflow

• Queue of pending approvals
• One-click approve/reject
• Bulk approval for related actions
• SLA countdown timers

Playbook Management

• Create and edit playbooks
• Visual step editor
• Test with sample data
• Execution history

Settings

• Connector configuration
• Policy rule management
• User administration
• System preferences

Navigation

Next Steps

• Incidents - Managing incidents
• Approvals - Approval workflow
• Playbooks - Playbook configuration
• Settings - System settings

Incidents

Managing incidents in the web dashboard.

Incident List

Access at /incidents

Filtering

• Status: Open, Triaged, Resolved
• Severity: Low, Medium, High, Critical
• Type: Phishing, Malware, Suspicious Login
• Date Range: Custom time period

Sorting

Click column headers to sort:

• Created (newest/oldest)
• Severity (highest/lowest)
• Status

Bulk Actions

Select multiple incidents for:

• Bulk resolve
• Bulk escalate
• Export to CSV

Incident Detail

Click an incident to view details.

Overview Tab

• Incident metadata
• AI verdict and confidence
• Recommended actions
• Timeline of events

Raw Data Tab

• Original incident data (JSON)
• Parsed email content (for phishing)
• Detection details (for malware)

Actions Tab

• Available actions
• Executed actions with results
• Pending approvals

Enrichment Tab

• Threat intelligence results
• SIEM correlation data
• Related incidents

Creating Incidents

Click "New Incident" button.

Required Fields

• Type: Select incident type
• Source: Origin of the incident
• Severity: Initial severity assessment

Optional Fields

• Description: Free-form description
• Raw Data: JSON payload
• Assignee: Initial assignment

Executing Actions

From the incident detail page:

1. Click "Actions" tab
2. Select action from dropdown
3. Fill in parameters
4. Click "Execute"

If approval is required:

• Action appears in pending state
• Notification sent to approvers
• Status updates when approved/rejected

Keyboard Shortcuts

Real-time Updates

The dashboard uses HTMX for live updates:

• New incidents appear automatically
• Status changes reflect immediately
• Approval decisions update in real-time

Approvals

Managing action approvals in the web dashboard.

Approval Queue

Access at /approvals

The queue shows all actions pending your approval based on your role level.

Queue Columns

• Action: Type of action requested
• Incident: Related incident
• Requested By: Who/what requested it
• Requested At: When requested
• SLA: Time remaining to respond

Filtering

• Approval Level: Analyst, Senior, Manager
• Action Type: Specific actions
• Incident Type: Phishing, malware, etc.

Approval Detail

Click an approval to see full context.

Context Section

• Full incident details
• AI reasoning (if from triage)
• Related actions already taken

Decision Section

• Approve: Execute the action
• Reject: Decline with reason
• Delegate: Assign to another approver

Approving Actions

Single Approval

1. Click on pending action
2. Review incident context
3. Click "Approve" or "Reject"
4. Add optional comment
5. Confirm decision

Bulk Approval

For related actions:

1. Select multiple actions (checkbox)
2. Click "Bulk Approve" or "Bulk Reject"
3. Add comment applying to all
4. Confirm

Rejection

When rejecting:

1. Click "Reject"
2. Required: Enter rejection reason
3. Optionally suggest alternative
4. Confirm

The requester is notified of rejection and reason.

SLA Indicators

Notifications

You receive notifications for:

• New actions requiring your approval
• SLA warnings (50%, 75% elapsed)
• Escalations to your level

Configure notification preferences in Settings.

Delegation

If unavailable:

1. Go to Settings > Delegation
2. Select delegate user
3. Set date range
4. Delegate receives your approvals

Audit Trail

All approvals are logged:

• Who approved/rejected
• When decision was made
• Time to approve
• Comments provided

View at Settings > Audit Logs.

Playbooks

Managing playbooks in the web dashboard.

Playbook List

Access at /playbooks

Views

• Active: Currently enabled playbooks
• Inactive: Disabled playbooks
• All: Complete list

Information Displayed

• Name and description
• Trigger conditions
• Last run time
• Success rate

Creating Playbooks

Click "New Playbook" button.

Basic Information

• Name: Unique identifier
• Description: What this playbook does
• Version: Semantic version

Triggers

Configure when playbook runs:

• Incident Type: Phishing, malware, etc.
• Auto Run: Run automatically on new incidents
• Conditions: Additional criteria

Variables

Define playbook variables:

quarantine_threshold: 0.7
notification_channel: "#security"

Step Editor

Visual editor for playbook steps.

Adding Steps

1. Click "Add Step"
2. Select action type
3. Configure parameters
4. Set output variable name

Step Types

• Action: Execute an action
• Condition: Branch logic
• AI Analysis: Get AI verdict
• Parallel: Run steps concurrently

Connections

• Drag to reorder steps
• Connect condition branches
• Set dependencies

Testing Playbooks

Dry Run

1. Click "Test"
2. Select or create test incident
3. Toggle "Dry Run"
4. View step-by-step execution

With Live Data

1. Click "Test"
2. Select real incident
3. Leave "Dry Run" off
4. Actions will execute (with approval)

Execution History

View past executions:

• Execution timestamp
• Incident processed
• Steps completed
• Final verdict
• Duration

Click execution for detailed trace.

Import/Export

Export

1. Select playbook
2. Click "Export"
3. Download YAML file

Import

1. Click "Import"
2. Upload YAML file
3. Review parsed playbook
4. Click "Create"

Playbook Versions

Playbooks are versioned:

1. Edit playbook
2. Bump version number
3. Save as new version
4. Old version kept for rollback

View version history and compare changes.

Settings

System configuration in the web dashboard.

Settings Tabs

Access at /settings

General

• Instance Name: Display name for this installation
• Time Zone: Default timezone for display
• Date Format: Date/time display format
• Theme: Light/dark mode preference

Connectors

Configure external integrations.

Threat Intelligence

• Mode: Mock or VirusTotal
• API Key (for VirusTotal)
• Rate limit settings

SIEM

• Mode: Mock or Splunk
• URL and authentication
• Default search index

EDR

• Mode: Mock or CrowdStrike
• OAuth credentials
• Region selection

Email Gateway

• Mode: Mock or Microsoft 365
• Azure AD configuration
• Tenant settings

Ticketing

• Mode: Mock or Jira
• Instance URL
• Project configuration

Policies

Manage policy rules.

Creating Rules

1. Click "Add Rule"
2. Enter rule name
3. Define matching criteria
4. Set decision (allow/deny/approval)
5. Save

Rule Priority

Drag rules to reorder. First matching rule wins.

Users

User management (admin only).

User List

• Username and email
• Role (viewer/analyst/senior/admin)
• Last login
• Status (active/disabled)

Creating Users

1. Click "Add User"
2. Enter email and username
3. Set initial role
4. Generate or set password
5. Send invitation email

Role Management

Assign roles:

• Viewer: Read-only access
• Analyst: Execute actions, approve analyst-level
• Senior: Approve senior-level
• Admin: Full access

Notifications

Configure notification preferences.

Channels

• Email: SMTP settings
• Slack: Webhook URL
• Teams: Connector URL
• PagerDuty: Integration key

Preferences

For each notification type:

• Enable/disable channel
• Set priority threshold
• Configure quiet hours

Audit Logs

View system audit trail.

Filtering

• Date range
• Event type
• User
• Resource

Export

Export logs to CSV for compliance.

API Keys

Manage API credentials.

Creating Keys

1. Click "Create API Key"
2. Enter name and description
3. Select scopes
4. Set expiration (optional)
5. Copy generated key

Revoking Keys

Click "Revoke" on any key. Revocation is immediate.

Backup & Restore

Database management.

Backup

1. Click "Create Backup"
2. Wait for completion
3. Download backup file

Restore

1. Click "Restore"
2. Upload backup file
3. Confirm restore
4. System restarts

About

System information:

• Version number
• Build information
• License status
• Support links

CLI Reference

Command-line interface for Triage Warden.

Installation

The CLI is built with the main project:

cargo build --release
./target/release/tw-cli --help

Global Options

tw-cli [OPTIONS] <COMMAND>

Options:
  -c, --config <FILE>     Configuration file path
  -v, --verbose           Enable verbose output
  -q, --quiet             Suppress non-error output
  --json                  Output as JSON
  -h, --help              Print help
  -V, --version           Print version

Environment Variables

Commands Overview

Quick Examples

# List open incidents
tw-cli incident list --status open

# Create incident
tw-cli incident create --type phishing --severity high

# Run triage
tw-cli triage run --incident INC-2024-001

# Execute action
tw-cli action execute --incident INC-2024-001 --action quarantine_email

# Approve pending action
tw-cli action approve act-abc123

# Start server
tw-cli serve --port 8080

Next Steps

• Commands - Detailed command reference

CLI Commands

Detailed reference for all CLI commands.

incident

Manage security incidents.

list

tw-cli incident list [OPTIONS]

Options:
  --status <STATUS>      Filter by status (open, triaged, resolved)
  --severity <SEVERITY>  Filter by severity
  --type <TYPE>          Filter by incident type
  --limit <N>            Maximum results (default: 20)
  --offset <N>           Skip first N results
  --sort <FIELD>         Sort field (created_at, severity)
  --desc                 Sort descending

get

tw-cli incident get <ID> [OPTIONS]

Options:
  --format <FORMAT>      Output format (table, json, yaml)
  --include-actions      Include action history
  --include-enrichment   Include enrichment data

create

tw-cli incident create [OPTIONS]

Options:
  --type <TYPE>          Incident type (required)
  --source <SOURCE>      Incident source (required)
  --severity <SEVERITY>  Initial severity (default: medium)
  --data <JSON>          Raw incident data as JSON
  --file <FILE>          Read data from file
  --auto-triage          Run triage after creation

update

tw-cli incident update <ID> [OPTIONS]

Options:
  --severity <SEVERITY>  Update severity
  --status <STATUS>      Update status
  --assignee <USER>      Assign to user

resolve

tw-cli incident resolve <ID> [OPTIONS]

Options:
  --resolution <TEXT>    Resolution notes
  --false-positive       Mark as false positive

action

Execute and manage actions.

execute

tw-cli action execute [OPTIONS]

Options:
  --incident <ID>        Associated incident
  --action <NAME>        Action to execute (required)
  --param <KEY=VALUE>    Action parameter (repeatable)
  --emergency            Emergency override (manager only)

list

tw-cli action list [OPTIONS]

Options:
  --incident <ID>        Filter by incident
  --status <STATUS>      Filter by status
  --pending              Show only pending approval

get

tw-cli action get <ID>

approve

tw-cli action approve <ID> [OPTIONS]

Options:
  --comment <TEXT>       Approval comment

reject

tw-cli action reject <ID> [OPTIONS]

Options:
  --reason <TEXT>        Rejection reason (required)

rollback

tw-cli action rollback <ID> [OPTIONS]

Options:
  --reason <TEXT>        Rollback reason

triage

Run AI triage.

run

tw-cli triage run [OPTIONS]

Options:
  --incident <ID>        Incident to triage (required)
  --playbook <NAME>      Specific playbook
  --model <MODEL>        AI model override
  --wait                 Wait for completion

status

tw-cli triage status <TRIAGE_ID>

playbook

Manage playbooks.

list

tw-cli playbook list [OPTIONS]

Options:
  --enabled              Only enabled playbooks
  --trigger-type <TYPE>  Filter by trigger type

get

tw-cli playbook get <ID>

add

tw-cli playbook add <FILE>

update

tw-cli playbook update <ID> <FILE>

delete

tw-cli playbook delete <ID>

run

tw-cli playbook run <ID> [OPTIONS]

Options:
  --incident <ID>        Incident to process
  --var <KEY=VALUE>      Override variable (repeatable)
  --dry-run              Don't execute actions

test

tw-cli playbook test <NAME> [OPTIONS]

Options:
  --incident <ID>        Use existing incident
  --data <JSON>          Use mock data
  --dry-run              Don't execute actions

validate

tw-cli playbook validate <FILE>

export

tw-cli playbook export <ID> [OPTIONS]

Options:
  -o, --output <FILE>    Output file (default: stdout)

policy

Manage policy rules.

list

tw-cli policy list

add

tw-cli policy add [OPTIONS]

Options:
  --name <NAME>          Rule name (required)
  --action <ACTION>      Action to match
  --pattern <PATTERN>    Action pattern (glob)
  --severity <SEVERITY>  Severity condition
  --approval-level <L>   Required approval level
  --allow                Auto-allow
  --deny                 Deny with reason
  --reason <TEXT>        Denial reason

delete

tw-cli policy delete <NAME>

test

tw-cli policy test [OPTIONS]

Options:
  --action <ACTION>      Action to test
  --severity <SEVERITY>  Incident severity
  --proposer-type <T>    Proposer type
  --confidence <N>       AI confidence score

connector

Manage connectors.

status

tw-cli connector status

test

tw-cli connector test <NAME>

configure

tw-cli connector configure <NAME> [OPTIONS]

Options:
  --mode <MODE>          Connector mode
  --api-key <KEY>        API key
  --url <URL>            Service URL

user

User management.

list

tw-cli user list

create

tw-cli user create [OPTIONS]

Options:
  --username <NAME>      Username (required)
  --email <EMAIL>        Email address
  --role <ROLE>          User role
  --service-account      Create as service account

update

tw-cli user update <ID> [OPTIONS]

Options:
  --role <ROLE>          New role
  --enabled              Enable user
  --disabled             Disable user

delete

tw-cli user delete <ID>

api-key

API key management.

list

tw-cli api-key list

create

tw-cli api-key create [OPTIONS]

Options:
  --name <NAME>          Key name (required)
  --scopes <SCOPES>      Comma-separated scopes
  --user <USER>          Associated user
  --expires <DATE>       Expiration date

revoke

tw-cli api-key revoke <PREFIX>

rotate

tw-cli api-key rotate <PREFIX>

webhook

Webhook management.

list

tw-cli webhook list

add

tw-cli webhook add <SOURCE> [OPTIONS]

Options:
  --secret <SECRET>      Webhook secret
  --auto-triage          Enable auto-triage
  --playbook <NAME>      Playbook to run

test

tw-cli webhook test <SOURCE>

delete

tw-cli webhook delete <SOURCE>

db

Database operations.

migrate

tw-cli db migrate

backup

tw-cli db backup [OPTIONS]

Options:
  -o, --output <FILE>    Backup file path

restore

tw-cli db restore <FILE>

serve

Start the API server.

tw-cli serve [OPTIONS]

Options:
  --host <HOST>          Bind address (default: 0.0.0.0)
  --port <PORT>          Port number (default: 8080)
  --config <FILE>        Configuration file

Architecture Overview

Triage Warden is built as a modular, layered system combining Rust for performance-critical components and Python for AI capabilities.

System Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                           Clients                                    │
│              (Web Browser, CLI, API Consumers)                       │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         API Layer (tw-api)                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │  REST API   │  │ Web Handlers│  │  Webhooks   │  │   Metrics   │ │
│  │   (Axum)    │  │(HTMX+Askama)│  │             │  │ (Prometheus)│ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
                                   │
        ┌──────────────────────────┼──────────────────────────┐
        ▼                          ▼                          ▼
┌───────────────┐        ┌───────────────────┐       ┌───────────────┐
│ Policy Engine │        │   Action Registry │       │  Event Bus    │
│   (tw-policy) │        │    (tw-actions)   │       │  (tw-core)    │
└───────────────┘        └───────────────────┘       └───────────────┘
        │                          │                          │
        └──────────────────────────┼──────────────────────────┘
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       Core Domain (tw-core)                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │  Incidents  │  │  Playbooks  │  │   Users     │  │   Audit     │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Database Layer (SQLx)                             │
│              (SQLite for dev, PostgreSQL for prod)                   │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                      Python Bridge (tw-bridge)                       │
│                          (PyO3 Bindings)                             │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       AI Layer (tw_ai)                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │Triage Agent │  │    Tools    │  │  Playbook   │  │  Evaluation │ │
│  │  (Claude)   │  │             │  │   Engine    │  │  Framework  │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Connector Layer (tw-connectors)                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │ VirusTotal  │  │   Splunk    │  │ CrowdStrike │  │    Jira     │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

Crate Structure

Key Design Decisions

Rust + Python Hybrid

• Rust: Core platform, API server, policy engine, actions
• Python: AI agents, LLM integrations, playbook execution
• Bridge: PyO3 enables Python to call Rust connectors and actions

Trait-Based Connectors

All connectors implement traits for testability:

#![allow(unused)]
fn main() {
#[async_trait]
pub trait ThreatIntelConnector: Send + Sync {
    async fn lookup_hash(&self, hash: &str) -> ConnectorResult<ThreatReport>;
    async fn lookup_url(&self, url: &str) -> ConnectorResult<ThreatReport>;
    async fn lookup_domain(&self, domain: &str) -> ConnectorResult<ThreatReport>;
}
}

Event-Driven Architecture

The event bus enables loose coupling:

#![allow(unused)]
fn main() {
event_bus.publish(Event::IncidentCreated { id, incident_type });
event_bus.publish(Event::ActionExecuted { action_id, result });
}

Policy-First Actions

All actions pass through the policy engine:

Request → Policy Evaluation → (Allowed | Denied | RequiresApproval) → Execute

Next Steps

• Components - Detailed component descriptions
• Data Flow - How data moves through the system
• Security Model - Authentication and authorization

Components

Detailed description of each major component in Triage Warden.

tw-api

The HTTP server and web interface.

REST API Routes

Web Handlers

Server-rendered pages using HTMX and Askama templates:

• Dashboard with KPIs
• Incident list and detail views
• Approval workflow interface
• Playbook management
• Settings configuration

Authentication

• Session-based auth for web dashboard
• API key auth for programmatic access
• Role-based access control (admin, analyst, viewer)

tw-core

Core domain logic and data access.

Domain Models

#![allow(unused)]
fn main() {
pub struct Incident {
    pub id: Uuid,
    pub incident_type: IncidentType,
    pub severity: Severity,
    pub status: IncidentStatus,
    pub source: String,
    pub raw_data: serde_json::Value,
    pub verdict: Option<Verdict>,
    pub confidence: Option<f64>,
    pub created_at: DateTime<Utc>,
}

pub struct Action {
    pub id: Uuid,
    pub incident_id: Uuid,
    pub action_type: ActionType,
    pub status: ActionStatus,
    pub approval_level: Option<ApprovalLevel>,
    pub executed_by: Option<String>,
}
}

Repositories

Database access layer with SQLite and PostgreSQL support:

• IncidentRepository
• ActionRepository
• PlaybookRepository
• UserRepository
• AuditRepository

Event Bus

Async event distribution:

#![allow(unused)]
fn main() {
pub enum Event {
    IncidentCreated { id: Uuid },
    IncidentUpdated { id: Uuid },
    ActionRequested { id: Uuid },
    ActionApproved { id: Uuid, approver: String },
    ActionExecuted { id: Uuid, success: bool },
}
}

tw-actions

Action handlers for incident response.

Email Actions

Lookup Actions

Host Actions

Notification Actions

tw-policy

Policy engine for action approval.

Rule Evaluation

#![allow(unused)]
fn main() {
pub struct PolicyRule {
    pub name: String,
    pub action_type: ActionType,
    pub conditions: Vec<Condition>,
    pub approval_level: ApprovalLevel,
}

pub enum PolicyDecision {
    Allowed,
    Denied { reason: String },
    RequiresApproval { level: ApprovalLevel },
}
}

Approval Levels

1. Auto - No approval required
2. Analyst - Any analyst can approve
3. Senior - Senior analyst required
4. Manager - SOC manager required

tw-connectors

External service integrations.

Connector Trait

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Connector: Send + Sync {
    fn name(&self) -> &str;
    fn connector_type(&self) -> &str;
    async fn health_check(&self) -> ConnectorResult<ConnectorHealth>;
    async fn test_connection(&self) -> ConnectorResult<bool>;
}
}

Available Connectors

tw-bridge

PyO3 bindings for Python integration.

Exposed Classes

from tw_bridge import ThreatIntelBridge, SIEMBridge, EDRBridge

# Use connectors from Python
threat_intel = ThreatIntelBridge("virustotal")
result = threat_intel.lookup_hash("abc123...")

tw_ai (Python)

AI triage and playbook execution.

Triage Agent

Claude-powered agent for incident analysis:

agent = TriageAgent(model="claude-sonnet-4-20250514")
verdict = await agent.analyze(incident)
# Returns: Verdict(classification="malicious", confidence=0.92, ...)

Playbook Engine

YAML-based playbook execution:

name: phishing_triage
steps:
  - action: parse_email
  - action: check_email_authentication
  - action: lookup_sender_reputation
  - condition: sender_reputation < 0.3
    action: quarantine_email

Data Flow

How data moves through Triage Warden from incident creation to resolution.

Incident Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Created   │────▶│   Triaging  │────▶│   Triaged   │────▶│  Resolved   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │                   │
       ▼                   ▼                   ▼                   ▼
   Webhook/API        AI Agent          Actions Executed      Closed
   receives data      analyzes          (with approval)

Detailed Flow

1. Incident Creation

External Source (Email Gateway, SIEM, EDR)
                    │
                    ▼
            Webhook Endpoint
            /api/webhooks/:source
                    │
                    ▼
         ┌──────────────────┐
         │  Parse & Validate │
         │  Incoming Data    │
         └──────────────────┘
                    │
                    ▼
         ┌──────────────────┐
         │ Create Incident   │
         │ Record in DB      │
         └──────────────────┘
                    │
                    ▼
         ┌──────────────────┐
         │ Publish Event:    │
         │ IncidentCreated   │
         └──────────────────┘

2. AI Triage

         ┌──────────────────┐
         │ Event: Incident   │
         │ Created           │
         └──────────────────┘
                    │
                    ▼
         ┌──────────────────┐
         │ Load Playbook     │
         │ (based on type)   │
         └──────────────────┘
                    │
                    ▼
         ┌──────────────────┐
         │ Execute Playbook  │
         │ Steps             │
         └──────────────────┘
                    │
        ┌───────────┴───────────┐
        ▼                       ▼
┌───────────────┐       ┌───────────────┐
│ Enrichment    │       │ AI Analysis   │
│ Actions       │       │ (Claude)      │
│ - parse_email │       │               │
│ - lookup_*    │       │ Generates:    │
└───────────────┘       │ - Verdict     │
        │               │ - Confidence  │
        │               │ - Reasoning   │
        │               │ - Actions     │
        └───────┬───────└───────────────┘
                │
                ▼
         ┌──────────────────┐
         │ Update Incident   │
         │ with Verdict      │
         └──────────────────┘

3. Action Execution

         ┌──────────────────┐
         │ Action Request    │
         │ (from agent or    │
         │  human)           │
         └──────────────────┘
                    │
                    ▼
         ┌──────────────────┐
         │ Build Action      │
         │ Context           │
         └──────────────────┘
                    │
                    ▼
         ┌──────────────────┐
         │ Policy Engine     │
         │ Evaluation        │
         └──────────────────┘
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
   ┌────────┐  ┌────────┐  ┌────────┐
   │Allowed │  │Denied  │  │Requires│
   │        │  │        │  │Approval│
   └────────┘  └────────┘  └────────┘
        │           │           │
        ▼           ▼           ▼
   Execute      Return       Queue for
   Action       Error        Approval
        │                       │
        │                       ▼
        │              ┌──────────────┐
        │              │ Notify       │
        │              │ Approvers    │
        │              └──────────────┘
        │                       │
        │                       ▼
        │              ┌──────────────┐
        │              │ Wait for     │
        │              │ Approval     │
        │              └──────────────┘
        │                       │
        │        ┌──────────────┴──────────────┐
        │        ▼                             ▼
        │   ┌────────┐                    ┌────────┐
        │   │Approved│                    │Rejected│
        │   └────────┘                    └────────┘
        │        │                             │
        │        ▼                             ▼
        │   Execute Action               Update Status
        │        │
        └────────┴─────────┐
                           ▼
                  ┌──────────────┐
                  │ Connector    │
                  │ Execution    │
                  │ (External    │
                  │  Service)    │
                  └──────────────┘
                           │
                           ▼
                  ┌──────────────┐
                  │ Update       │
                  │ Action       │
                  │ Status       │
                  └──────────────┘
                           │
                           ▼
                  ┌──────────────┐
                  │ Audit Log    │
                  │ Entry        │
                  └──────────────┘

Data Stores

Primary Database

Event Bus (In-Memory)

Transient event distribution for real-time updates:

• Incident lifecycle events
• Action status changes
• Approval notifications
• System health events

External Data Flow

Inbound (Webhooks)

Email Gateway ──────┐
SIEM Alerts ────────┼──▶ Webhook Handler ──▶ Incident Creation
EDR Events ─────────┘

Outbound (Connectors)

                           ┌──▶ VirusTotal (threat intel)
Action Execution ──────────┼──▶ Splunk (SIEM queries)
                           ├──▶ CrowdStrike (host actions)
                           ├──▶ M365 (email actions)
                           └──▶ Jira (ticketing)

Metrics Flow

Rust Components ──┬──▶ Prometheus Registry ──▶ /metrics endpoint
Python Components ─┘

Exposed metrics:

• triage_warden_incidents_total{type, severity}
• triage_warden_actions_total{action, status}
• triage_warden_triage_duration_seconds{type}
• triage_warden_connector_requests_total{connector, status}

Security Model

Triage Warden implements defense-in-depth with multiple security layers.

Authentication

Web Dashboard

Session-based authentication with secure cookies:

• Session tokens: Random 256-bit tokens
• Cookie settings: HttpOnly, Secure, SameSite=Lax
• Session duration: 8 hours (configurable)
• CSRF protection: Per-request tokens on all state-changing forms

API Access

API key authentication for programmatic access:

curl -H "Authorization: Bearer tw_abc123_secretkey" \
  https://api.example.com/api/incidents

API key features:

• Prefix stored in plain text for lookup (tw_abc123)
• Secret portion hashed with Argon2
• Scopes limit allowed operations
• Expiration dates supported

Authorization

Role-Based Access Control (RBAC)

Policy-Based Action Control

The policy engine evaluates every action request:

#![allow(unused)]
fn main() {
// Policy evaluation flow
ActionRequest
    → Build ActionContext (action_type, target, severity, proposer)
    → Evaluate policy rules
    → Return PolicyDecision
        - Allowed: Execute immediately
        - Denied: Return error with reason
        - RequiresApproval: Queue for specified approval level
}

Example Policy Rules

# Low-risk actions auto-approve
[[policy.rules]]
name = "auto_approve_lookups"
action_patterns = ["lookup_*"]
decision = "allowed"

# High-severity host isolation requires manager
[[policy.rules]]
name = "isolate_requires_manager"
action = "isolate_host"
severity = ["high", "critical"]
approval_level = "manager"

# Block dangerous actions on production
[[policy.rules]]
name = "no_delete_in_prod"
action_patterns = ["delete_*"]
environment = "production"
decision = "denied"
reason = "Deletion not allowed in production"

Multi-Tenant Isolation

Triage Warden supports multi-tenancy with strong data isolation guarantees.

Row-Level Security (RLS)

PostgreSQL Row-Level Security provides database-level tenant isolation:

-- Each table has RLS policies that filter by tenant
-- Application sets tenant context at the start of each request
SELECT set_tenant_context('tenant-uuid-here');

-- All subsequent queries automatically filtered
SELECT * FROM incidents;  -- Only returns current tenant's data

Key Features:

Tenant Context Management

The application manages tenant context through several mechanisms:

1. Request Middleware: Resolves tenant from subdomain, header, or JWT
2. Session Variable: Sets app.current_tenant on each database connection
3. Context Guard: RAII pattern ensures cleanup

#![allow(unused)]
fn main() {
// Using the tenant context guard
async fn handle_request(pool: &TenantAwarePool, tenant_id: Uuid) {
    let _guard = TenantContextGuard::new(pool, tenant_id).await?;

    // All queries here are automatically filtered by tenant
    let incidents = incident_repo.list_all().await?;

    // Context cleared when guard drops
}
}

Admin Operations

Admin operations that need to bypass RLS use a separate connection pool:

• Admin pool: Superuser role that bypasses RLS policies
• Use cases: Tenant management, cross-tenant reporting, maintenance
• Access control: Restricted to Admin role users only

Tables Protected by RLS

All tenant-scoped data tables have RLS enabled:

• incidents, actions, approvals, audit_logs
• users, api_keys, sessions
• playbooks, policies, connectors
• notification_channels, settings

System tables (tenants, feature_flags) do NOT have RLS.

Debugging RLS Issues

-- Check current tenant context
SELECT get_current_tenant();

-- View RLS policies for a table
SELECT * FROM pg_policies WHERE tablename = 'incidents';

-- Check if RLS is enabled
SELECT relname, relrowsecurity
FROM pg_class
WHERE relname IN ('incidents', 'tenants');

Data Protection

At Rest

• Database encryption: SQLite with SQLCipher (optional), PostgreSQL with TDE
• Credential storage: All API keys/tokens hashed with Argon2id
• Secrets management: Environment variables or external secret stores

In Transit

• TLS 1.3: Required for all external connections
• Certificate validation: Strict validation for connectors
• Internal traffic: TLS optional for localhost development

Sensitive Data Handling

#![allow(unused)]
fn main() {
// Credentials redacted in logs
impl std::fmt::Debug for ApiKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "ApiKey {{ prefix: {}, secret: [REDACTED] }}", self.prefix)
    }
}
}

Audit Trail

All security-relevant actions logged:

Audit log retention: 90 days (configurable)

Connector Security

Credential Management

Connector credentials stored encrypted:

# Environment variables (recommended)
TW_VIRUSTOTAL_API_KEY=your-key

# Or encrypted in database
tw-cli connector set virustotal --api-key "$(read -s)"

Rate Limiting

Built-in rate limiting prevents API abuse:

Circuit Breaker

Automatic failure handling:

#![allow(unused)]
fn main() {
// After 5 consecutive failures, circuit opens
// Requests fail fast for 30 seconds
// Then half-open state allows test requests
}

Input Validation

API Requests

• JSON schema validation on all endpoints
• Size limits on request bodies (1MB default)
• Type coercion disabled (strict typing)

Webhook Payloads

• HMAC signature verification
• Replay attack prevention (timestamp validation)
• Payload size limits

#![allow(unused)]
fn main() {
// Webhook signature verification
fn verify_webhook(payload: &[u8], signature: &str, secret: &str) -> bool {
    let expected = hmac_sha256(secret, payload);
    constant_time_compare(signature, &expected)
}
}

Secure Defaults

• HTTPS enforced in production
• Secure cookie flags enabled
• CORS restricted to configured origins
• Debug endpoints disabled in production
• Verbose errors only in development

Security Headers

Default response headers:

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'self'

Vulnerability Disclosure

Report security vulnerabilities to: [email protected]

We follow responsible disclosure practices and aim to respond within 48 hours.

Database Schema

Triage Warden supports both SQLite (development/small deployments) and PostgreSQL (production). This document describes the database schema used by both backends.

Overview

The database consists of 13 tables organized into four logical groups:

• Core Incident Management: incidents, audit_logs, actions, approvals
• Configuration: playbooks, connectors, policies, notification_channels, settings
• Authentication: users, sessions, api_keys
• Multi-Tenancy: tenants, feature_flags

Multi-Tenancy

All tenant-scoped tables include a tenant_id foreign key that references the tenants table. In PostgreSQL, Row-Level Security (RLS) policies automatically filter all queries by the current tenant context.

tenants

Tenant organizations in a multi-tenant deployment.

Indexes: slug (unique), status

feature_flags

Feature flag configuration for gradual rollouts.

Note: The tenants and feature_flags tables are NOT protected by RLS.

Entity Relationship Diagram

┌──────────────┐       ┌──────────────┐       ┌──────────────┐
│    users     │       │   api_keys   │       │   sessions   │
├──────────────┤       ├──────────────┤       ├──────────────┤
│ id (PK)      │◄──────│ user_id (FK) │       │ id (PK)      │
│ email        │       │ id (PK)      │       │ data         │
│ username     │       │ key_hash     │       │ expiry_date  │
│ password_hash│       │ scopes       │       └──────────────┘
│ role         │       └──────────────┘
└──────────────┘

┌──────────────┐       ┌──────────────┐       ┌──────────────┐
│  incidents   │       │  audit_logs  │       │   actions    │
├──────────────┤       ├──────────────┤       ├──────────────┤
│ id (PK)      │◄──────│ incident_id  │       │ id (PK)      │
│ source       │       │ id (PK)      │       │ incident_id  │──┐
│ severity     │       │ action       │       │ action_type  │  │
│ status       │◄──────│ actor        │       │ target       │  │
│ alert_data   │       │ details      │       │ approval_status│ │
│ enrichments  │       │ created_at   │       └──────────────┘  │
│ analysis     │       └──────────────┘                         │
│ proposed_actions│                                             │
│ ticket_id    │       ┌──────────────┐                         │
│ tags         │       │  approvals   │◄────────────────────────┘
│ metadata     │       ├──────────────┤
└──────────────┘       │ id (PK)      │
                       │ action_id    │
                       │ incident_id  │
                       │ status       │
                       └──────────────┘

Core Tables

incidents

Stores security incidents created from incoming alerts.

Indexes: (tenant_id, status), (tenant_id, severity), (tenant_id, created_at), status, severity, created_at, updated_at

RLS: Protected by Row-Level Security in PostgreSQL.

Incident Status Values

• new - Newly created from alert
• enriching - Gathering threat intelligence
• analyzing - AI analysis in progress
• pending_review - Awaiting analyst review
• pending_approval - Actions awaiting approval
• executing - Actions being executed
• resolved - Incident resolved
• false_positive - Marked as false positive
• escalated - Escalated to higher tier
• closed - Administratively closed

audit_logs

Immutable audit trail for all incident actions.

Indexes: incident_id, created_at

actions

Stores proposed and executed response actions.

Indexes: incident_id, approval_status, created_at

Approval Status Values

• pending - Awaiting approval decision
• auto_approved - Automatically approved by policy
• approved - Manually approved
• denied - Manually denied
• executed - Successfully executed
• failed - Execution failed

approvals

Tracks multi-level approval workflows.

Indexes: action_id, status, expires_at

Configuration Tables

playbooks

Automation workflow definitions.

Indexes: name, trigger_type, enabled, created_at

connectors

External integration configurations.

Indexes: name, connector_type, status, enabled

policies

Approval and automation policy rules.

Indexes: name, action, priority, enabled

notification_channels

Alert notification configurations.

Indexes: name, channel_type, enabled

settings

Key-value configuration store.

Authentication Tables

users

User accounts for dashboard and API access.

Indexes: email, username, role, enabled

sessions

User session storage (tower-sessions compatible).

Indexes: expiry_date

api_keys

API key authentication.

Indexes: user_id, key_prefix, expires_at

Database-Specific Notes

SQLite

• UUIDs stored as TEXT
• Timestamps stored as ISO 8601 TEXT
• Boolean stored as INTEGER (0/1)
• JSON stored as TEXT
• Uses CHECK constraints for enums

PostgreSQL

• Native UUID type
• Native TIMESTAMPTZ type
• Native BOOLEAN type
• Native JSONB type with indexing
• Uses custom ENUM types for status fields
• Row-Level Security (RLS) enabled on all tenant-scoped tables

Row-Level Security

PostgreSQL deployments use RLS for defense-in-depth tenant isolation:

-- RLS policy example (automatically applied to all queries)
CREATE POLICY incidents_select_tenant_isolation ON incidents
    FOR SELECT
    USING (tenant_id = current_setting('app.current_tenant', true)::uuid);

To set the tenant context:

-- Set before executing tenant-scoped queries
SELECT set_tenant_context('00000000-0000-0000-0000-000000000001'::uuid);

-- Or use the session variable directly
SET app.current_tenant = '00000000-0000-0000-0000-000000000001';

Helper functions:

Migrations

Migrations are managed by SQLx and located in:

• SQLite: crates/tw-core/src/db/migrations/sqlite/
• PostgreSQL: crates/tw-core/src/db/migrations/postgres/

Run migrations automatically on startup or manually:

# SQLite
tw-cli db migrate --database-url "sqlite:data/triage.db"

# PostgreSQL
tw-cli db migrate --database-url "postgres://user:pass@host/db"

Connectors

Connectors integrate Triage Warden with external security tools and services.

Overview

Each connector type has a trait interface and multiple implementations:

Configuration

Select connector implementations via environment variables:

# Use real connectors
TW_THREAT_INTEL_MODE=virustotal
TW_SIEM_MODE=splunk
TW_EDR_MODE=crowdstrike
TW_EMAIL_GATEWAY_MODE=m365
TW_TICKETING_MODE=jira

# Or use mocks for testing
TW_THREAT_INTEL_MODE=mock
TW_SIEM_MODE=mock

Connector Trait

All connectors implement the base Connector trait:

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Connector: Send + Sync {
    /// Unique identifier for this connector instance
    fn name(&self) -> &str;

    /// Type of connector (threat_intel, siem, edr, etc.)
    fn connector_type(&self) -> &str;

    /// Check connector health
    async fn health_check(&self) -> ConnectorResult<ConnectorHealth>;

    /// Test connection to the service
    async fn test_connection(&self) -> ConnectorResult<bool>;
}

pub enum ConnectorHealth {
    Healthy,
    Degraded { message: String },
    Unhealthy { message: String },
}
}

Error Handling

Connectors return ConnectorResult<T> with detailed error types:

#![allow(unused)]
fn main() {
pub enum ConnectorError {
    /// Service returned an error
    RequestFailed(String),

    /// Resource not found
    NotFound(String),

    /// Authentication failed
    AuthenticationFailed(String),

    /// Rate limit exceeded
    RateLimited { retry_after: Option<Duration> },

    /// Network or connection error
    NetworkError(String),

    /// Invalid response from service
    InvalidResponse(String),
}
}

Health Monitoring

Check connector health via the API:

curl http://localhost:8080/api/connectors/health

{
  "connectors": [
    { "name": "virustotal", "type": "threat_intel", "status": "healthy" },
    { "name": "splunk", "type": "siem", "status": "healthy" },
    { "name": "crowdstrike", "type": "edr", "status": "degraded", "message": "High latency" }
  ]
}

Next Steps

• Threat Intelligence - VirusTotal configuration
• SIEM - Splunk configuration
• EDR - CrowdStrike configuration
• Email Gateway - Microsoft 365 configuration
• Ticketing - Jira configuration

Threat Intelligence Connector

Query threat intelligence services for reputation data on hashes, URLs, domains, and IP addresses.

Interface

#![allow(unused)]
fn main() {
#[async_trait]
pub trait ThreatIntelConnector: Connector {
    /// Look up file hash reputation
    async fn lookup_hash(&self, hash: &str) -> ConnectorResult<ThreatReport>;

    /// Look up URL reputation
    async fn lookup_url(&self, url: &str) -> ConnectorResult<ThreatReport>;

    /// Look up domain reputation
    async fn lookup_domain(&self, domain: &str) -> ConnectorResult<ThreatReport>;

    /// Look up IP address reputation
    async fn lookup_ip(&self, ip: &str) -> ConnectorResult<ThreatReport>;
}

pub struct ThreatReport {
    pub indicator: String,
    pub indicator_type: IndicatorType,
    pub malicious: bool,
    pub confidence: f64,
    pub categories: Vec<String>,
    pub first_seen: Option<DateTime<Utc>>,
    pub last_seen: Option<DateTime<Utc>>,
    pub sources: Vec<ThreatSource>,
}
}

VirusTotal

Configuration

TW_THREAT_INTEL_MODE=virustotal
TW_VIRUSTOTAL_API_KEY=your-api-key-here

Rate Limits

The connector automatically handles rate limiting with exponential backoff.

Supported Lookups

Example Usage

#![allow(unused)]
fn main() {
let connector = VirusTotalConnector::new(api_key)?;

let report = connector.lookup_hash("44d88612fea8a8f36de82e1278abb02f").await?;
println!("Malicious: {}", report.malicious);
println!("Confidence: {:.2}", report.confidence);
println!("Categories: {:?}", report.categories);
}

Response Mapping

VirusTotal detection ratios map to confidence scores:

Mock Connector

For testing without external API calls:

TW_THREAT_INTEL_MODE=mock

The mock connector returns predictable results based on indicator patterns:

Python Bridge

Access from Python via the bridge:

from tw_bridge import ThreatIntelBridge

# Create bridge (uses TW_THREAT_INTEL_MODE env var)
bridge = ThreatIntelBridge()

# Or specify mode explicitly
bridge = ThreatIntelBridge("virustotal")

# Lookup hash
result = bridge.lookup_hash("44d88612fea8a8f36de82e1278abb02f")
print(f"Malicious: {result['malicious']}")
print(f"Confidence: {result['confidence']}")

# Lookup URL
result = bridge.lookup_url("https://example.com/suspicious")

# Lookup domain
result = bridge.lookup_domain("malware-site.com")

Caching

Results are cached to reduce API calls:

Cache is stored in the database and shared across instances.

Adding Custom Providers

Implement the ThreatIntelConnector trait:

#![allow(unused)]
fn main() {
pub struct CustomThreatIntelConnector {
    client: reqwest::Client,
    api_key: String,
}

#[async_trait]
impl Connector for CustomThreatIntelConnector {
    fn name(&self) -> &str { "custom" }
    fn connector_type(&self) -> &str { "threat_intel" }
    // ... implement health_check, test_connection
}

#[async_trait]
impl ThreatIntelConnector for CustomThreatIntelConnector {
    async fn lookup_hash(&self, hash: &str) -> ConnectorResult<ThreatReport> {
        // Custom implementation
    }
    // ... implement other methods
}
}

See Adding Connectors for full details.

SIEM Connector

Query SIEM platforms for log data, run searches, and correlate events.

Interface

#![allow(unused)]
fn main() {
#[async_trait]
pub trait SIEMConnector: Connector {
    /// Run a search query
    async fn search(&self, query: &str, time_range: TimeRange) -> ConnectorResult<SearchResults>;

    /// Get events by ID
    async fn get_events(&self, event_ids: &[String]) -> ConnectorResult<Vec<SIEMEvent>>;

    /// Get related events (correlation)
    async fn get_related_events(
        &self,
        indicator: &str,
        indicator_type: IndicatorType,
        time_range: TimeRange,
    ) -> ConnectorResult<Vec<SIEMEvent>>;
}

pub struct SIEMEvent {
    pub id: String,
    pub timestamp: DateTime<Utc>,
    pub source: String,
    pub event_type: String,
    pub severity: String,
    pub raw_data: serde_json::Value,
}

pub struct SearchResults {
    pub events: Vec<SIEMEvent>,
    pub total_count: u64,
    pub search_id: String,
}
}

Splunk

Configuration

TW_SIEM_MODE=splunk
TW_SPLUNK_URL=https://splunk.company.com:8089
TW_SPLUNK_TOKEN=your-token-here

Token Permissions

The Splunk token requires these capabilities:

• search - Run searches
• list_inputs - Health check
• rest_access - REST API access

Example Searches

#![allow(unused)]
fn main() {
let connector = SplunkConnector::new(url, token)?;

// Search for events
let results = connector.search(
    r#"index=security sourcetype=firewall action=blocked"#,
    TimeRange::last_hours(24),
).await?;

// Find related events by IP
let related = connector.get_related_events(
    "192.168.1.100",
    IndicatorType::IpAddress,
    TimeRange::last_hours(1),
).await?;
}

Search Query Translation

Common queries translated to SPL:

Performance Tips

• Use specific indexes in queries
• Limit time ranges when possible
• Use | head 1000 to limit results

Mock Connector

For testing:

TW_SIEM_MODE=mock

The mock returns sample security events matching the query pattern.

Python Bridge

from tw_bridge import SIEMBridge

bridge = SIEMBridge("splunk")

# Run a search
results = bridge.search(
    query='index=security action=blocked',
    hours=24
)

for event in results['events']:
    print(f"{event['timestamp']}: {event['source']}")

# Get related events
related = bridge.get_related_events(
    indicator="192.168.1.100",
    indicator_type="ip",
    hours=1
)

Adding Custom SIEM

Implement the SIEMConnector trait:

#![allow(unused)]
fn main() {
pub struct ElasticSIEMConnector {
    client: elasticsearch::Elasticsearch,
}

#[async_trait]
impl SIEMConnector for ElasticSIEMConnector {
    async fn search(&self, query: &str, time_range: TimeRange) -> ConnectorResult<SearchResults> {
        // Translate to Elasticsearch DSL and execute
    }
    // ... implement other methods
}
}

EDR Connector

Integrate with Endpoint Detection and Response platforms for host information and response actions.

Interface

#![allow(unused)]
fn main() {
#[async_trait]
pub trait EDRConnector: Connector {
    /// Get host information
    async fn get_host(&self, host_id: &str) -> ConnectorResult<HostInfo>;

    /// Search for hosts
    async fn search_hosts(&self, query: &str) -> ConnectorResult<Vec<HostInfo>>;

    /// Get recent detections for a host
    async fn get_detections(&self, host_id: &str) -> ConnectorResult<Vec<Detection>>;

    /// Isolate a host from the network
    async fn isolate_host(&self, host_id: &str) -> ConnectorResult<ActionResult>;

    /// Remove host isolation
    async fn unisolate_host(&self, host_id: &str) -> ConnectorResult<ActionResult>;

    /// Trigger a scan on the host
    async fn scan_host(&self, host_id: &str) -> ConnectorResult<ActionResult>;
}

pub struct HostInfo {
    pub id: String,
    pub hostname: String,
    pub platform: String,
    pub os_version: String,
    pub agent_version: String,
    pub last_seen: DateTime<Utc>,
    pub isolation_status: IsolationStatus,
    pub tags: Vec<String>,
}

pub struct Detection {
    pub id: String,
    pub timestamp: DateTime<Utc>,
    pub severity: String,
    pub tactic: String,
    pub technique: String,
    pub description: String,
    pub process_name: Option<String>,
    pub file_path: Option<String>,
}
}

CrowdStrike

Configuration

TW_EDR_MODE=crowdstrike
TW_CROWDSTRIKE_CLIENT_ID=your-client-id
TW_CROWDSTRIKE_CLIENT_SECRET=your-client-secret
TW_CROWDSTRIKE_REGION=us-1  # us-1, us-2, eu-1, usgov-1

API Scopes Required

The API client requires these scopes:

• Hosts: Read - Get host information
• Hosts: Write - Isolation actions
• Detections: Read - Get detections
• Real Time Response: Write - Scan actions

OAuth2 Token Management

The connector automatically handles token refresh:

#![allow(unused)]
fn main() {
// Token refreshed automatically when expired
let connector = CrowdStrikeConnector::new(client_id, client_secret, region)?;

// All subsequent calls use valid token
let host = connector.get_host("abc123").await?;
}

Example Usage

#![allow(unused)]
fn main() {
// Get host information
let host = connector.get_host("aid:abc123").await?;
println!("Hostname: {}", host.hostname);
println!("Last seen: {}", host.last_seen);

// Check for detections
let detections = connector.get_detections("aid:abc123").await?;
for d in detections {
    println!("{}: {} - {}", d.timestamp, d.severity, d.description);
}

// Isolate compromised host
let result = connector.isolate_host("aid:abc123").await?;
if result.success {
    println!("Host isolated successfully");
}
}

Action Confirmation

Isolation and scan actions require policy approval. See Policy Engine.

Mock Connector

TW_EDR_MODE=mock

The mock provides sample hosts and detections for testing.

Python Bridge

from tw_bridge import EDRBridge

bridge = EDRBridge("crowdstrike")

# Get host info
host = bridge.get_host("aid:abc123")
print(f"Hostname: {host['hostname']}")
print(f"Platform: {host['platform']}")

# Get detections
detections = bridge.get_detections("aid:abc123")
for d in detections:
    print(f"{d['severity']}: {d['description']}")

# Isolate host (requires policy approval)
result = bridge.isolate_host("aid:abc123")
if result['success']:
    print("Host isolated")

Response Actions

Isolation Behavior

When isolated:

• Host cannot communicate on network
• Falcon agent maintains connection to cloud
• User may see isolation notification

Rate Limits

Email Gateway Connector

Manage email security operations including search, quarantine, and sender blocking.

Interface

#![allow(unused)]
fn main() {
#[async_trait]
pub trait EmailGatewayConnector: Connector {
    /// Search for emails
    async fn search_emails(&self, query: EmailSearchQuery) -> ConnectorResult<Vec<EmailMessage>>;

    /// Get specific email by ID
    async fn get_email(&self, message_id: &str) -> ConnectorResult<EmailMessage>;

    /// Move email to quarantine
    async fn quarantine_email(&self, message_id: &str) -> ConnectorResult<ActionResult>;

    /// Release email from quarantine
    async fn release_email(&self, message_id: &str) -> ConnectorResult<ActionResult>;

    /// Block sender
    async fn block_sender(&self, sender: &str) -> ConnectorResult<ActionResult>;

    /// Unblock sender
    async fn unblock_sender(&self, sender: &str) -> ConnectorResult<ActionResult>;

    /// Get threat data for email
    async fn get_threat_data(&self, message_id: &str) -> ConnectorResult<EmailThreatData>;
}

pub struct EmailMessage {
    pub id: String,
    pub internet_message_id: String,
    pub sender: String,
    pub recipients: Vec<String>,
    pub subject: String,
    pub received_at: DateTime<Utc>,
    pub has_attachments: bool,
    pub attachments: Vec<EmailAttachment>,
    pub urls: Vec<String>,
    pub headers: HashMap<String, String>,
    pub threat_assessment: Option<ThreatAssessment>,
}

pub struct EmailSearchQuery {
    pub sender: Option<String>,
    pub recipient: Option<String>,
    pub subject_contains: Option<String>,
    pub timerange: TimeRange,
    pub has_attachments: Option<bool>,
    pub threat_type: Option<String>,
    pub limit: usize,
}
}

Microsoft 365

Configuration

TW_EMAIL_GATEWAY_MODE=m365
TW_M365_TENANT_ID=your-tenant-id
TW_M365_CLIENT_ID=your-client-id
TW_M365_CLIENT_SECRET=your-client-secret

App Registration

Create an Azure AD app registration with these API permissions:

Example Usage

#![allow(unused)]
fn main() {
let connector = M365Connector::new(tenant_id, client_id, client_secret)?;

// Search for suspicious emails
let query = EmailSearchQuery {
    sender: Some("[email protected]".to_string()),
    timerange: TimeRange::last_hours(24),
    ..Default::default()
};
let emails = connector.search_emails(query).await?;

// Quarantine malicious email
let result = connector.quarantine_email("AAMkAGI2...").await?;

// Block sender
let result = connector.block_sender("[email protected]").await?;
}

Quarantine Behavior

When quarantined:

• Email moved to quarantine folder
• User notified (configurable)
• Admin can release if false positive

Mock Connector

TW_EMAIL_GATEWAY_MODE=mock

Provides sample emails with various threat characteristics:

• Phishing with malicious URLs
• Malware with executable attachments
• BEC/impersonation attempts
• Clean legitimate emails

Python Bridge

from tw_bridge import EmailGatewayBridge

bridge = EmailGatewayBridge("m365")

# Search emails
emails = bridge.search_emails(
    sender="[email protected]",
    hours=24
)

for email in emails:
    print(f"From: {email['sender']}")
    print(f"Subject: {email['subject']}")
    print(f"Attachments: {len(email['attachments'])}")

# Quarantine email
result = bridge.quarantine_email("AAMkAGI2...")
if result['success']:
    print("Email quarantined")

# Block sender
result = bridge.block_sender("[email protected]")

Response Actions

Threat Data

Get detailed threat information:

#![allow(unused)]
fn main() {
let threat_data = connector.get_threat_data("AAMkAGI2...").await?;

println!("Delivery action: {}", threat_data.delivery_action);
println!("Threat types: {:?}", threat_data.threat_types);
println!("Detection methods: {:?}", threat_data.detection_methods);
}

Fields:

• delivery_action: Delivered, Quarantined, Blocked
• threat_types: Phishing, Malware, Spam, BEC
• detection_methods: URLAnalysis, AttachmentScanning, ImpersonationDetection
• urls_clicked: URLs clicked by recipient (if tracking enabled)

Ticketing Connector

Create and manage security incident tickets in external ticketing systems.

Interface

#![allow(unused)]
fn main() {
#[async_trait]
pub trait TicketingConnector: Connector {
    /// Create a new ticket
    async fn create_ticket(&self, ticket: CreateTicketRequest) -> ConnectorResult<Ticket>;

    /// Get ticket by ID
    async fn get_ticket(&self, ticket_id: &str) -> ConnectorResult<Ticket>;

    /// Update ticket fields
    async fn update_ticket(&self, ticket_id: &str, update: UpdateTicketRequest) -> ConnectorResult<Ticket>;

    /// Add comment to ticket
    async fn add_comment(&self, ticket_id: &str, comment: &str) -> ConnectorResult<()>;

    /// Search tickets
    async fn search_tickets(&self, query: TicketSearchQuery) -> ConnectorResult<Vec<Ticket>>;
}

pub struct CreateTicketRequest {
    pub title: String,
    pub description: String,
    pub priority: TicketPriority,
    pub ticket_type: String,
    pub labels: Vec<String>,
    pub assignee: Option<String>,
    pub custom_fields: HashMap<String, String>,
}

pub struct Ticket {
    pub id: String,
    pub key: String,
    pub title: String,
    pub description: String,
    pub status: String,
    pub priority: TicketPriority,
    pub assignee: Option<String>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub url: String,
}
}

Jira

Configuration

TW_TICKETING_MODE=jira
TW_JIRA_URL=https://company.atlassian.net
[email protected]
TW_JIRA_API_TOKEN=your-api-token
TW_JIRA_PROJECT_KEY=SEC

API Token

Generate an API token at: https://id.atlassian.com/manage-profile/security/api-tokens

Required permissions:

• Create issues
• Edit issues
• Add comments
• Browse project

Example Usage

#![allow(unused)]
fn main() {
let connector = JiraConnector::new(url, email, token, project_key)?;

// Create security ticket
let request = CreateTicketRequest {
    title: "Phishing Incident - INC-2024-001".to_string(),
    description: "Phishing email detected and quarantined.\n\n## Details\n...".to_string(),
    priority: TicketPriority::High,
    ticket_type: "Security Incident".to_string(),
    labels: vec!["phishing".to_string(), "triage-warden".to_string()],
    assignee: Some("[email protected]".to_string()),
    custom_fields: HashMap::new(),
};

let ticket = connector.create_ticket(request).await?;
println!("Created: {} - {}", ticket.key, ticket.url);

// Add investigation notes
connector.add_comment(
    &ticket.id,
    "## Investigation Notes\n\n- Sender reputation: Malicious\n- URLs: 2 phishing links"
).await?;
}

Issue Types

Configure the Jira project with these issue types:

Custom Fields

Map custom fields in configuration:

TW_JIRA_FIELD_SEVERITY=customfield_10001
TW_JIRA_FIELD_INCIDENT_ID=customfield_10002
TW_JIRA_FIELD_VERDICT=customfield_10003

Mock Connector

TW_TICKETING_MODE=mock

Simulates ticket operations with in-memory storage.

Python Bridge

from tw_bridge import TicketingBridge

bridge = TicketingBridge("jira")

# Create ticket
ticket = bridge.create_ticket(
    title="Phishing Incident - INC-2024-001",
    description="Phishing email detected...",
    priority="high",
    ticket_type="Security Incident",
    labels=["phishing", "triage-warden"]
)
print(f"Created: {ticket['key']}")
print(f"URL: {ticket['url']}")

# Add comment
bridge.add_comment(
    ticket_id=ticket['id'],
    comment="Investigation complete. Verdict: Malicious"
)

# Update status
bridge.update_ticket(
    ticket_id=ticket['id'],
    status="Done"
)

# Search tickets
tickets = bridge.search_tickets(
    query="project = SEC AND labels = phishing",
    limit=10
)

Ticket Templates

Define templates for consistent ticket creation:

# config/ticket_templates.toml

[templates.phishing]
title = "Phishing: {subject}"
description = """
## Incident Summary
- **Type**: Phishing
- **Severity**: {severity}
- **Incident ID**: {incident_id}

## Details
{details}

## Recommended Actions
{recommended_actions}
"""
labels = ["phishing", "triage-warden"]

[templates.malware]
title = "Malware Alert: {hostname}"
description = """
## Incident Summary
- **Type**: Malware
- **Host**: {hostname}
- **Detection**: {detection}

## IOCs
{iocs}
"""
labels = ["malware", "triage-warden"]

Integration with Incidents

Tickets are automatically linked to incidents:

#![allow(unused)]
fn main() {
// Create ticket action stores the ticket key
let action = execute_action("create_ticket", incident_id, params).await?;

// Incident updated with ticket reference
incident.metadata["ticket_key"] = "SEC-1234";
incident.metadata["ticket_url"] = "https://company.atlassian.net/browse/SEC-1234";
}

Actions

Actions are the executable operations that Triage Warden can perform in response to incidents.

Overview

Actions fall into several categories:

Action Trait

All actions implement the Action trait:

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Action: Send + Sync {
    /// Action name (used in playbooks and API)
    fn name(&self) -> &str;

    /// Human-readable description
    fn description(&self) -> &str;

    /// Required and optional parameters
    fn required_parameters(&self) -> Vec<ParameterDef>;

    /// Whether this action supports rollback
    fn supports_rollback(&self) -> bool;

    /// Execute the action
    async fn execute(&self, context: ActionContext) -> Result<ActionResult, ActionError>;

    /// Rollback the action (if supported)
    async fn rollback(&self, context: ActionContext) -> Result<ActionResult, ActionError> {
        Err(ActionError::RollbackNotSupported)
    }
}
}

Action Context

Actions receive an ActionContext with:

#![allow(unused)]
fn main() {
pub struct ActionContext {
    /// Unique execution ID
    pub execution_id: Uuid,

    /// Parameters passed to the action
    pub parameters: HashMap<String, serde_json::Value>,

    /// Related incident (if any)
    pub incident_id: Option<Uuid>,

    /// User or agent requesting the action
    pub proposer: String,

    /// Connectors available for use
    pub connectors: ConnectorRegistry,
}
}

Action Result

Actions return an ActionResult:

#![allow(unused)]
fn main() {
pub struct ActionResult {
    /// Whether the action succeeded
    pub success: bool,

    /// Action name
    pub action_name: String,

    /// Human-readable summary
    pub message: String,

    /// Execution duration
    pub duration: Duration,

    /// Output data (action-specific)
    pub output: HashMap<String, serde_json::Value>,

    /// Whether rollback is available
    pub rollback_available: bool,
}
}

Policy Integration

All actions pass through the policy engine before execution:

Action Request → Policy Evaluation → Decision
                                       ├─ Allowed → Execute
                                       ├─ Denied → Return Error
                                       └─ RequiresApproval → Queue

See Policy Engine for approval configuration.

Executing Actions

Via API

curl -X POST http://localhost:8080/api/incidents/{id}/actions \
  -H "Content-Type: application/json" \
  -d '{
    "action": "quarantine_email",
    "parameters": {
      "message_id": "AAMkAGI2...",
      "reason": "Phishing detected"
    }
  }'

Via CLI

tw-cli action execute \
  --incident INC-2024-001 \
  --action quarantine_email \
  --param message_id=AAMkAGI2... \
  --param reason="Phishing detected"

Via Playbook

steps:
  - action: quarantine_email
    parameters:
      message_id: "{{ incident.raw_data.message_id }}"
      reason: "Automated response to phishing"

Available Actions

• Email Actions - Email parsing and response
• Host Actions - Endpoint containment
• Lookup Actions - Threat intelligence enrichment
• Notification Actions - Alerts and escalation

Email Actions

Actions for analyzing and responding to email-based threats.

Analysis Actions

parse_email

Extract headers, body, attachments, and URLs from raw email.

Parameters:

Output:

{
  "headers": {
    "From": "[email protected]",
    "To": "[email protected]",
    "Subject": "Important Document",
    "Date": "2024-01-15T10:30:00Z",
    "Message-ID": "<[email protected]>",
    "X-Originating-IP": "[192.168.1.100]"
  },
  "sender": "[email protected]",
  "recipients": ["[email protected]"],
  "subject": "Important Document",
  "body_text": "Please review the attached document...",
  "body_html": "<html>...",
  "attachments": [
    {
      "filename": "document.pdf",
      "content_type": "application/pdf",
      "size": 102400,
      "sha256": "abc123..."
    }
  ],
  "urls": [
    "https://example.com/document",
    "https://suspicious-site.com/login"
  ]
}

check_email_authentication

Validate SPF, DKIM, and DMARC authentication results.

Parameters:

Output:

{
  "spf": {
    "result": "pass",
    "domain": "example.com"
  },
  "dkim": {
    "result": "pass",
    "domain": "example.com",
    "selector": "default"
  },
  "dmarc": {
    "result": "pass",
    "policy": "reject"
  },
  "authentication_passed": true,
  "risk_indicators": []
}

Risk Indicators:

• spf_fail - SPF validation failed
• dkim_fail - DKIM signature invalid
• dmarc_fail - DMARC policy violation
• header_mismatch - From/Reply-To mismatch
• suspicious_routing - Unusual mail routing

Response Actions

quarantine_email

Move email to quarantine via email gateway.

Parameters:

Output:

{
  "quarantine_id": "quar-abc123",
  "message_id": "AAMkAGI2...",
  "quarantined_at": "2024-01-15T10:35:00Z"
}

Rollback: release_email - Releases email from quarantine

block_sender

Add sender to organization blocklist.

Parameters:

Output:

{
  "block_id": "block-abc123",
  "sender": "[email protected]",
  "scope": "organization",
  "blocked_at": "2024-01-15T10:35:00Z"
}

Rollback: unblock_sender - Removes sender from blocklist

Usage Examples

Phishing Response Playbook

name: phishing_response
steps:
  - action: parse_email
    output: parsed

  - action: check_email_authentication
    parameters:
      headers: "{{ parsed.headers }}"
    output: auth

  - action: lookup_sender_reputation
    parameters:
      sender: "{{ parsed.sender }}"
    output: reputation

  - condition: "reputation.score < 0.3 or not auth.authentication_passed"
    action: quarantine_email
    parameters:
      message_id: "{{ incident.raw_data.message_id }}"
      reason: "Failed authentication and low sender reputation"

  - condition: "reputation.score < 0.2"
    action: block_sender
    parameters:
      sender: "{{ parsed.sender }}"
      scope: organization

CLI Example

# Quarantine suspicious email
tw-cli action execute \
  --action quarantine_email \
  --param message_id="AAMkAGI2..." \
  --param reason="Phishing indicators detected"

# Block malicious sender
tw-cli action execute \
  --action block_sender \
  --param sender="[email protected]" \
  --param scope=organization

Host Actions

Actions for endpoint containment and investigation.

isolate_host

Network-isolate a compromised host via EDR.

Parameters:

Output:

{
  "isolation_id": "iso-abc123",
  "host_id": "aid:xyz789",
  "hostname": "WORKSTATION-01",
  "isolated_at": "2024-01-15T10:40:00Z",
  "status": "isolated"
}

Behavior:

• Host network access blocked
• EDR agent maintains cloud connectivity
• User notified (configurable)

Rollback: unisolate_host

Policy: Typically requires senior analyst or manager approval.

unisolate_host

Remove network isolation from a host.

Parameters:

Output:

{
  "host_id": "aid:xyz789",
  "hostname": "WORKSTATION-01",
  "unisolated_at": "2024-01-15T14:00:00Z",
  "status": "active"
}

scan_host

Trigger on-demand malware scan on a host.

Parameters:

Output:

{
  "scan_id": "scan-abc123",
  "host_id": "aid:xyz789",
  "scan_type": "quick",
  "started_at": "2024-01-15T10:45:00Z",
  "status": "running"
}

Note: Scan results are retrieved separately as they may take time.

Usage Examples

Malware Response Playbook

name: malware_response
steps:
  - action: isolate_host
    parameters:
      host_id: "{{ incident.raw_data.host_id }}"
      reason: "Malware detection - automated isolation"
    output: isolation

  - action: scan_host
    parameters:
      host_id: "{{ incident.raw_data.host_id }}"
      scan_type: full

  - action: create_ticket
    parameters:
      title: "Malware Incident - {{ incident.raw_data.hostname }}"
      priority: high

  - action: notify_user
    parameters:
      user: "{{ incident.raw_data.user }}"
      message: "Your workstation has been isolated due to a security incident"

CLI Example

# Isolate compromised host
tw-cli action execute \
  --action isolate_host \
  --param host_id="aid:xyz789" \
  --param reason="Active malware infection"

# This action typically requires approval
# Check approval status:
tw-cli action status act-123456

# After investigation, remove isolation:
tw-cli action execute \
  --action unisolate_host \
  --param host_id="aid:xyz789" \
  --param reason="Malware cleaned, host verified"

API Example

# Request host isolation
curl -X POST http://localhost:8080/api/incidents/INC-2024-001/actions \
  -H "Content-Type: application/json" \
  -d '{
    "action": "isolate_host",
    "parameters": {
      "host_id": "aid:xyz789",
      "reason": "Suspected compromise"
    }
  }'

# Response (if requires approval):
{
  "action_id": "act-abc123",
  "status": "pending_approval",
  "approval_level": "manager",
  "message": "Action requires SOC Manager approval"
}

Policy Configuration

Host actions are typically high-impact and require approval:

[[policy.rules]]
name = "isolate_requires_approval"
action = "isolate_host"
approval_level = "senior"

[[policy.rules]]
name = "critical_isolate_requires_manager"
action = "isolate_host"
severity = ["critical"]
approval_level = "manager"

Lookup Actions

Actions for enriching incidents with threat intelligence data.

lookup_sender_reputation

Query threat intelligence for sender domain and IP reputation.

Parameters:

Output:

{
  "sender": "[email protected]",
  "domain": "domain.com",
  "domain_reputation": {
    "score": 0.25,
    "categories": ["phishing", "newly-registered"],
    "first_seen": "2024-01-10",
    "registrar": "NameCheap"
  },
  "ip_reputation": {
    "ip": "192.168.1.100",
    "score": 0.3,
    "categories": ["spam", "proxy"],
    "country": "RU",
    "asn": "AS12345"
  },
  "overall_score": 0.25,
  "risk_level": "high"
}

Score Interpretation:

lookup_urls

Check URLs against threat intelligence.

Parameters:

Output:

{
  "results": [
    {
      "url": "https://legitimate-site.com/page",
      "malicious": false,
      "categories": ["business"],
      "confidence": 0.95
    },
    {
      "url": "https://phishing-site.com/login",
      "malicious": true,
      "categories": ["phishing", "credential-theft"],
      "confidence": 0.92,
      "threat_details": {
        "targeted_brand": "Microsoft",
        "first_seen": "2024-01-14"
      }
    }
  ],
  "malicious_count": 1,
  "total_count": 2
}

lookup_attachments

Hash attachments and check against threat intelligence.

Parameters:

Output:

{
  "results": [
    {
      "filename": "invoice.pdf",
      "sha256": "abc123...",
      "malicious": false,
      "file_type": "PDF document",
      "confidence": 0.9
    },
    {
      "filename": "update.exe",
      "sha256": "def456...",
      "malicious": true,
      "file_type": "Windows executable",
      "confidence": 0.98,
      "threat_details": {
        "malware_family": "Emotet",
        "first_seen": "2024-01-12",
        "detection_engines": 45
      }
    }
  ],
  "malicious_count": 1,
  "total_count": 2
}

lookup_hash

Look up a single file hash.

Parameters:

Output:

{
  "hash": "abc123...",
  "hash_type": "sha256",
  "malicious": true,
  "confidence": 0.95,
  "malware_family": "Emotet",
  "categories": ["trojan", "banking"],
  "first_seen": "2024-01-12",
  "last_seen": "2024-01-15",
  "detection_ratio": "45/70"
}

lookup_ip

Query IP address reputation.

Parameters:

Output:

{
  "ip": "192.168.1.100",
  "malicious": true,
  "confidence": 0.8,
  "categories": ["c2", "malware-distribution"],
  "country": "RU",
  "asn": "AS12345",
  "asn_org": "Example ISP",
  "last_seen": "2024-01-15",
  "associated_malware": ["Cobalt Strike"]
}

Usage in Playbooks

name: email_triage
steps:
  - action: parse_email
    output: parsed

  - action: lookup_sender_reputation
    parameters:
      sender: "{{ parsed.sender }}"
    output: sender_rep

  - action: lookup_urls
    parameters:
      urls: "{{ parsed.urls }}"
    output: url_results

  - action: lookup_attachments
    parameters:
      attachments: "{{ parsed.attachments }}"
    output: attachment_results

  # Make decision based on lookups
  - condition: >
      sender_rep.risk_level == 'high' or
      url_results.malicious_count > 0 or
      attachment_results.malicious_count > 0
    set_verdict:
      classification: malicious
      confidence: 0.9

Caching

Lookup results are cached to reduce API calls:

Force fresh lookup with skip_cache: true parameter.

Notification Actions

Actions for alerting stakeholders and managing escalation.

notify_user

Send notification to an affected user.

Parameters:

Output:

{
  "notification_id": "notif-abc123",
  "recipient": "[email protected]",
  "channel": "email",
  "sent_at": "2024-01-15T10:50:00Z",
  "status": "delivered"
}

Templates:

# templates/notifications.yaml
security_alert:
  subject: "Security Alert: Action Required"
  body: |
    A security incident affecting your account has been detected.

    Incident ID: {{ incident_id }}
    Type: {{ incident_type }}

    {{ message }}

    If you did not initiate this activity, please contact IT Security.

notify_reporter

Send status update to the incident reporter.

Parameters:

Output:

{
  "notification_id": "notif-def456",
  "reporter": "[email protected]",
  "status": "delivered"
}

escalate

Route incident to appropriate approval level.

Parameters:

Output:

{
  "escalation_id": "esc-abc123",
  "incident_id": "INC-2024-001",
  "escalation_level": "senior",
  "assigned_to": "[email protected]",
  "due_date": "2024-01-15T12:50:00Z",
  "priority": "high",
  "sla_hours": 2
}

Default SLAs:

create_ticket

Create ticket in external ticketing system.

Parameters:

Output:

{
  "ticket_id": "12345",
  "ticket_key": "SEC-1234",
  "url": "https://company.atlassian.net/browse/SEC-1234",
  "created_at": "2024-01-15T10:55:00Z"
}

log_false_positive

Record a false positive for tuning.

Parameters:

Output:

{
  "fp_id": "fp-abc123",
  "incident_id": "INC-2024-001",
  "recorded_at": "2024-01-15T11:00:00Z",
  "used_for_training": true
}

run_triage_agent

Trigger AI triage agent on an incident.

Parameters:

Output:

{
  "triage_id": "triage-abc123",
  "incident_id": "INC-2024-001",
  "verdict": "malicious",
  "confidence": 0.92,
  "reasoning": "Multiple indicators of phishing...",
  "recommended_actions": [
    "quarantine_email",
    "block_sender",
    "notify_user"
  ],
  "completed_at": "2024-01-15T10:52:00Z"
}

Usage Examples

Escalation Playbook

name: auto_escalate
trigger:
  - verdict: malicious
  - confidence: ">= 0.9"
  - severity: critical

steps:
  - action: escalate
    parameters:
      incident_id: "{{ incident.id }}"
      escalation_level: manager
      reason: "High-confidence critical incident requiring immediate attention"
      notify_channels:
        - slack
        - pagerduty

  - action: create_ticket
    parameters:
      title: "CRITICAL: {{ incident.subject }}"
      priority: critical

CLI Examples

# Escalate to senior analyst
tw-cli action execute \
  --incident INC-2024-001 \
  --action escalate \
  --param escalation_level=senior \
  --param reason="Complex threat requiring expertise"

# Create ticket
tw-cli action execute \
  --incident INC-2024-001 \
  --action create_ticket \
  --param title="Phishing Investigation" \
  --param priority=high

# Record false positive
tw-cli action execute \
  --incident INC-2024-001 \
  --action log_false_positive \
  --param reason="Legitimate vendor communication"

Policy Engine

The policy engine controls action approval workflows and enforces security boundaries.

Overview

Every action request passes through the policy engine:

Action Request → Build Context → Evaluate Rules → Decision
                                                    ├─ Allowed → Execute
                                                    ├─ Denied → Reject
                                                    └─ RequiresApproval → Queue

Policy Decision Types

Action Context

The policy engine evaluates these attributes:

#![allow(unused)]
fn main() {
pub struct ActionContext {
    /// The action being requested
    pub action_type: String,

    /// Target of the action (host, email, user, etc.)
    pub target: String,

    /// Incident severity (if associated)
    pub severity: Option<Severity>,

    /// AI confidence score (if from triage)
    pub confidence: Option<f64>,

    /// Who/what is requesting the action
    pub proposer: Proposer,

    /// Additional context
    pub metadata: HashMap<String, Value>,
}

pub enum Proposer {
    User { id: String, role: Role },
    Agent { name: String },
    Playbook { name: String },
    System,
}
}

Default Policies

Without custom rules, these defaults apply:

Next Steps

• Rules - Configure custom policy rules
• Approval Levels - Understanding approval workflow

Policy Rules

Define rules to control when actions require approval.

Rule Structure

[[policy.rules]]
name = "rule_name"
description = "Human-readable description"

# Matching criteria
action = "action_name"           # Specific action
action_patterns = ["pattern_*"]  # Glob patterns

# Conditions (all must match)
severity = ["high", "critical"]  # Incident severity
confidence_min = 0.8             # Minimum AI confidence
proposer_type = "agent"          # Who's requesting
proposer_role = "analyst"        # Role (if user)

# Decision
decision = "allowed"             # or "denied" or "requires_approval"
approval_level = "senior"        # If requires_approval
reason = "Explanation"           # If denied

Rule Examples

Auto-Approve Lookups

[[policy.rules]]
name = "auto_approve_lookups"
description = "Lookup actions are always allowed"
action_patterns = ["lookup_*"]
decision = "allowed"

Require Approval for Response Actions

[[policy.rules]]
name = "response_needs_analyst"
description = "Response actions require analyst approval"
action_patterns = ["quarantine_*", "block_*"]
decision = "requires_approval"
approval_level = "analyst"

High-Severity Host Isolation

[[policy.rules]]
name = "critical_isolation_needs_manager"
description = "Critical severity host isolation requires manager"
action = "isolate_host"
severity = ["critical"]
decision = "requires_approval"
approval_level = "manager"

Block Dangerous Actions in Production

[[policy.rules]]
name = "no_delete_production"
description = "Deletion actions not allowed in production"
action_patterns = ["delete_*"]
environment = "production"
decision = "denied"
reason = "Deletion actions are not permitted in production"

Trust High-Confidence AI Decisions

[[policy.rules]]
name = "trust_high_confidence_ai"
description = "Auto-approve when AI is highly confident"
proposer_type = "agent"
confidence_min = 0.95
severity = ["low", "medium"]
action_patterns = ["quarantine_email", "block_sender"]
decision = "allowed"

Analyst Self-Service

[[policy.rules]]
name = "analyst_can_notify"
description = "Analysts can send notifications without approval"
action_patterns = ["notify_*"]
proposer_role = "analyst"
decision = "allowed"

Rule Evaluation Order

Rules are evaluated in order. First matching rule wins.

# More specific rules first
[[policy.rules]]
name = "critical_isolation"
action = "isolate_host"
severity = ["critical"]
approval_level = "manager"

# General fallback
[[policy.rules]]
name = "default_isolation"
action = "isolate_host"
approval_level = "senior"

Condition Operators

Severity Matching

severity = ["high", "critical"]  # Match any in list

Confidence Ranges

confidence_min = 0.8   # Minimum confidence
confidence_max = 0.95  # Maximum confidence

Pattern Matching

action_patterns = ["lookup_*"]        # Prefix match
action_patterns = ["*_email"]         # Suffix match
action_patterns = ["*block*"]         # Contains

Proposer Conditions

proposer_type = "user"      # user, agent, playbook, system
proposer_role = "analyst"   # Only for user proposers

Managing Rules

Via Configuration File

# config/policy.toml
tw-api --config config/policy.toml

Via API

# List rules
curl http://localhost:8080/api/policies

# Create rule
curl -X POST http://localhost:8080/api/policies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new_rule",
    "action": "isolate_host",
    "approval_level": "senior"
  }'

Via CLI

# List rules
tw-cli policy list

# Add rule
tw-cli policy add \
  --name "block_needs_approval" \
  --action "block_sender" \
  --approval-level analyst

Testing Rules

Simulate policy evaluation without executing:

tw-cli policy test \
  --action isolate_host \
  --severity critical \
  --proposer-type agent \
  --confidence 0.92

# Output:
# Decision: RequiresApproval
# Level: manager
# Matched Rule: critical_isolation_needs_manager

Approval Levels

Understanding the approval workflow in Triage Warden.

Approval Hierarchy

Manager (SOC Manager)
    │
    ▼
Senior (Senior Analyst)
    │
    ▼
Analyst (Security Analyst)
    │
    ▼
Auto (No approval needed)

Higher levels can approve actions at their level or below.

Level Definitions

Approval Workflow

1. Action Requested

tw-cli action execute --incident INC-001 --action isolate_host

2. Policy Evaluation

Policy engine evaluates and returns:

{
  "decision": "requires_approval",
  "approval_level": "senior",
  "reason": "Host isolation requires senior analyst approval"
}

3. Action Queued

Action stored with pending status:

{
  "action_id": "act-abc123",
  "incident_id": "INC-001",
  "action_type": "isolate_host",
  "status": "pending_approval",
  "approval_level": "senior",
  "requested_by": "[email protected]",
  "requested_at": "2024-01-15T10:30:00Z"
}

4. Approvers Notified

Notification sent to eligible approvers via configured channels.

5. Approval Decision

Approver reviews and decides:

Approve:

tw-cli action approve act-abc123 --comment "Verified threat"

Reject:

tw-cli action reject act-abc123 --reason "False positive, user traveling"

6. Execution or Rejection

• Approved: Action executes automatically
• Rejected: Action marked rejected, requester notified

Approval UI

Access pending approvals at /approvals in the web dashboard.

Features:

• Filterable list of pending actions
• Incident context display
• One-click approve/reject
• Bulk approval for related actions

SLA Tracking

Each approval level has a default SLA:

Overdue approvals are:

1. Highlighted in dashboard
2. Re-notified to approvers
3. Optionally escalated to next level

Delegation

Approvers can delegate when unavailable:

tw-cli approval delegate \
  --from [email protected] \
  --to [email protected] \
  --until 2024-01-20

Approval Groups

Configure approval groups for redundancy:

[approval_groups]
senior_analysts = [
  "[email protected]",
  "[email protected]",
  "[email protected]"
]

managers = [
  "[email protected]",
  "[email protected]"
]

Any member of the group can approve.

Audit Trail

All approval decisions are logged:

{
  "event": "action_approved",
  "action_id": "act-abc123",
  "approver": "[email protected]",
  "decision": "approved",
  "comment": "Verified threat indicators",
  "timestamp": "2024-01-15T10:45:00Z",
  "time_to_approve": "15m"
}

Emergency Override

In emergencies, managers can bypass approval:

tw-cli action execute \
  --incident INC-001 \
  --action isolate_host \
  --emergency \
  --reason "Active ransomware, immediate containment required"

Emergency overrides are:

• Logged with high visibility
• Require manager credentials
• Trigger additional notifications

Natural Language Queries

Query your security data using plain English instead of writing Splunk SPL, Elasticsearch KQL, or SQL by hand.

Overview

The NL Query Interface (Stage 4.1) lets analysts type questions like "show me critical incidents from the last 24 hours" and have Triage Warden translate them into structured queries against your SIEM, log store, or incident database.

The pipeline has four stages:

1. Intent classification -- determines what the analyst is trying to do
2. Entity extraction -- pulls out IPs, domains, hashes, date ranges, etc.
3. Query translation -- converts the parsed intent + entities into the target query language
4. Backend execution -- runs the query against Splunk, Elasticsearch, or SQL

Supported Intents

Intent classification uses keyword matching and regex patterns -- no LLM call is needed for routing.

Entity Extraction

The entity extractor recognizes security-specific tokens:

• IP addresses -- IPv4 (192.168.1.100)
• Domains -- evil-domain.com
• Hashes -- MD5 (32 hex chars), SHA-1 (40), SHA-256 (64)
• Incident IDs -- INC-2024-0042, #42
• Date ranges -- "last 24 hours", "past 7 days", 2024-01-01 to 2024-01-31
• Usernames, hostnames, CVE IDs

Query Translation

Once intent and entities are extracted, NLQueryTranslator builds a structured query object:

from tw_ai.nl_query import NLQueryTranslator

translator = NLQueryTranslator()
result = translator.translate(
    "show me failed logins from 10.0.0.50 in the last hour"
)
# result.intent.intent = QueryIntent.SEARCH_LOGS
# result.structured_query returns the backend-specific query

Backend Adapters

The translator outputs queries for three backends:

Conversation Context

Multi-turn conversations are supported via ConversationContext. When an analyst asks "now show me the same for last week", the system retains the entities from the previous turn.

from tw_ai.nl_query import ConversationContext

ctx = ConversationContext()
ctx.update("show me incidents from 10.0.0.50", entities=[...])
ctx.update("now filter to critical only", entities=[...])
# Second turn inherits the IP entity from the first

Security and Audit

All NL queries are sanitized before execution to prevent injection attacks. The QuerySanitizer strips dangerous characters and SQL keywords from user input.

Every query is logged to the QueryAuditLog with:

• Original natural language query
• Classified intent and confidence
• Translated structured query
• Execution timestamp and user ID

API Endpoint

When FastAPI is available, the NL query service exposes a REST endpoint:

curl -X POST http://localhost:8080/api/v1/nl/query \
  -H "Content-Type: application/json" \
  -d '{"query": "show me critical incidents from the last 24 hours"}'

Configuration

No special configuration is required. The NL query engine uses the same SIEM and database connections already configured in config/default.yaml.

To add custom keywords for intent classification:

from tw_ai.nl_query import IntentClassifier, QueryIntent

classifier = IntentClassifier(
    custom_keywords={
        QueryIntent.SEARCH_LOGS: ["splunk", "kibana"],
    }
)

Automated Threat Hunting

Proactively search for threats across your environment using hypothesis-driven hunts with built-in query templates mapped to MITRE ATT&CK.

Overview

The threat hunting module (Stage 5.1) provides:

• Hunt management -- create, schedule, and track hunts with hypotheses
• Built-in query library -- 20+ pre-built queries across 8 MITRE ATT&CK categories
• Multi-platform queries -- Splunk SPL and Elasticsearch KQL templates
• Finding promotion -- promote hunt findings directly to incidents

Hunt Lifecycle

A hunt progresses through these statuses:

Creating a Hunt

Via API

curl -X POST http://localhost:8080/api/v1/hunts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Detect Kerberoasting",
    "hypothesis": "Attackers may request TGS tickets for service accounts to crack offline",
    "hunt_type": "scheduled",
    "queries": [
      {
        "query_type": "splunk",
        "query": "index=wineventlog EventCode=4769 TicketEncryptionType=0x17 | stats count by ServiceName",
        "description": "Detect RC4-encrypted TGS requests",
        "timeout_secs": 300,
        "expected_baseline": 5
      }
    ],
    "schedule": {
      "cron_expression": "0 */4 * * *",
      "timezone": "UTC",
      "max_runtime_secs": 600
    },
    "mitre_techniques": ["T1558.003"],
    "data_sources": ["windows_event_logs"],
    "tags": ["credential-access", "priority-high"],
    "enabled": true
  }'

Hunt Types

Built-in Query Library

Access 20+ pre-built queries via the API:

curl http://localhost:8080/api/v1/hunts/queries/library

Queries span 8 MITRE ATT&CK categories:

• Initial Access
• Execution
• Persistence
• Credential Access
• Lateral Movement
• Collection
• Command and Control
• Exfiltration

Each built-in query includes Splunk SPL and Elasticsearch KQL templates, expected baselines for anomaly detection, and configurable parameters.

Executing a Hunt

Trigger a hunt manually:

curl -X POST http://localhost:8080/api/v1/hunts/{hunt_id}/execute

The response includes findings with severity levels, evidence data, and the query that produced each finding.

Viewing Results

# Get all results for a hunt
curl http://localhost:8080/api/v1/hunts/{hunt_id}/results

Each result includes:

• Total and critical finding counts
• Duration and execution status
• Individual findings with severity, evidence, and matched query

Promoting Findings to Incidents

When a hunt finding warrants investigation, promote it to a full incident:

curl -X POST http://localhost:8080/api/v1/hunts/{hunt_id}/findings/{finding_id}/promote

This creates a new incident with the finding's evidence, severity, and hunt metadata attached.

Query Languages

Python Hypothesis Generator

The Python tw_ai package includes an AI-powered hypothesis generator that suggests new hunts based on current threat intelligence and recent incident patterns.

Collaboration

Coordinate incident response across your team with assignments, comments, real-time events, activity feeds, and shift handoffs.

Overview

The collaboration module (Stage 4.3) adds team workflow features to incident management:

• Incident assignment -- manual and auto-assignment with rules
• Comments -- threaded discussion on incidents with mentions
• Real-time events -- live updates pushed to connected clients
• Activity feed -- chronological audit trail of all actions
• Shift handoff -- structured handoff reports between shifts

Incident Assignment

Manual Assignment

Assign an incident to an analyst through the web UI's assignment picker, or via the web endpoint:

curl -X POST http://localhost:8080/web/incidents/{id}/assign \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'assignee=analyst-uuid'

Auto-Assignment Rules

The system supports rule-based auto-assignment. Rules are defined in the application configuration and evaluated when new incidents arrive. Each rule specifies conditions and an assignee target:

Rules are evaluated in priority order. The first matching rule wins.

Note: Auto-assignment rule management via API is planned for a future release. Rules are currently configured at the application level.

Assignee Targets

Comments

Add discussion, analysis notes, and action records to incidents.

Creating a Comment

curl -X POST http://localhost:8080/api/v1/comments \
  -H "Content-Type: application/json" \
  -d '{
    "incident_id": "incident-uuid",
    "content": "Found lateral movement evidence via PsExec. @senior-analyst please review.",
    "comment_type": "analysis",
    "mentions": ["senior-analyst-uuid"]
  }'

Comment Types

Filtering Comments

# All comments for an incident
curl "http://localhost:8080/api/v1/comments?incident_id={id}"

# Only analysis comments
curl "http://localhost:8080/api/v1/comments?incident_id={id}&comment_type=analysis"

# Comments by a specific analyst
curl "http://localhost:8080/api/v1/comments?author_id={analyst_id}"

Comments support pagination with page and per_page query parameters.

Real-time Events

The real-time event system pushes updates to connected clients when incidents are modified, comments are added, or assignments change. Events include:

• Incident status changes
• New comments and mentions
• Assignment updates
• Action execution results
• Field-level change tracking

Subscribers can filter events by incident ID, event type, or severity.

Activity Feed

Every action on an incident is recorded in the activity feed, providing a complete audit trail:

• Who did what and when
• What fields changed (with before/after values)
• Comment and assignment history
• Action execution records

Filter the activity feed by incident, user, or activity type.

Shift Handoff

Generate structured handoff reports at shift transitions:

curl -X POST http://localhost:8080/api/v1/handoffs \
  -H "Content-Type: application/json" \
  -d '{
    "shift_start": "2025-01-15T08:00:00Z",
    "shift_end": "2025-01-15T16:00:00Z",
    "notes": "Ongoing phishing campaign targeting finance department"
  }'

Handoff reports include:

• Summary of open incidents per severity
• Actions pending approval
• Recent escalations
• Custom notes from the outgoing team

Agentic AI Response

Control how much autonomy the AI has when responding to incidents, from fully manual to fully autonomous, with time-based rules and per-action overrides.

Overview

The Agentic AI Response system (Stage 5.4) provides configurable autonomy levels that determine which actions the AI can execute automatically and which require human approval. It includes:

• Four autonomy levels with increasing automation
• Per-action and per-severity overrides
• Time-based rules for different autonomy during business hours vs. off-hours
• Execution guardrails to prevent dangerous actions
• Full audit trail of every autonomy decision

Autonomy Levels

Risk Level Mapping

Each action has an inherent risk level that determines whether it can be auto-executed:

Configuration

Get Current Config

curl http://localhost:8080/api/v1/autonomy/config

Update Config

curl -X PUT http://localhost:8080/api/v1/autonomy/config \
  -H "Content-Type: application/json" \
  -d '{
    "default_level": "supervised",
    "per_action_overrides": {
      "isolate_host": "assisted",
      "create_ticket": "autonomous"
    },
    "per_severity_overrides": {
      "critical": "assisted",
      "low": "autonomous"
    },
    "time_based_rules": [
      {
        "name": "Business hours - supervised",
        "start_hour": 9,
        "end_hour": 17,
        "days_of_week": [1, 2, 3, 4, 5],
        "level": "supervised"
      },
      {
        "name": "Off-hours - autonomous",
        "start_hour": 17,
        "end_hour": 9,
        "days_of_week": [0, 1, 2, 3, 4, 5, 6],
        "level": "autonomous"
      }
    ],
    "emergency_contacts": ["[email protected]"]
  }'

Resolution Priority

When resolving the autonomy level for a given action, overrides are checked in this order:

1. Per-action overrides (highest priority)
2. Per-severity overrides
3. Time-based rules
4. Default level (fallback)

Resolve for a Specific Action

Check what the system would decide for a specific action + severity combination:

curl -X POST http://localhost:8080/api/v1/autonomy/resolve \
  -H "Content-Type: application/json" \
  -d '{"action": "isolate_host", "severity": "critical"}'

Response:

{
  "level": "assisted",
  "auto_execute": false,
  "reason": "Per-action override for 'isolate_host'"
}

Time-Based Rules

Time-based rules let you run with less autonomy during business hours (when analysts are available) and more autonomy during nights and weekends.

Hours wrap around midnight: start_hour: 22, end_hour: 6 means 10 PM to 6 AM.

Execution Guardrails

The guardrails system (configured in config/guardrails.yaml) provides hard limits regardless of autonomy level:

• Forbidden actions -- actions that can never be automated (e.g., delete_user, wipe_host)
• Protected assets -- targets that always require human approval (production systems, domain controllers)
• Rate limits -- maximum actions per hour/day to prevent runaway automation
• Blast radius limits -- caps on how many targets a single action can affect

See Guardrails Reference for full configuration details.

Audit Log

Every autonomy decision is logged for compliance and debugging:

curl "http://localhost:8080/api/v1/autonomy/audit?limit=20"

# Filter by incident
curl "http://localhost:8080/api/v1/autonomy/audit?incident_id={id}"

Each audit entry records:

• Action and severity evaluated
• Resolved autonomy level
• Whether auto-execution was allowed
• Reason for the decision
• Whether the action was actually executed
• Execution outcome

Attack Surface Integration

Correlate incidents with known vulnerabilities and external exposures using integrations with vulnerability scanners and attack surface monitoring platforms.

Overview

The attack surface module (Stage 5.2) connects Triage Warden to:

• Vulnerability scanners -- Qualys, Tenable, and Rapid7 for known vulnerability data
• Attack surface monitors -- Censys and SecurityScorecard for external exposure discovery
• Risk scoring -- combined risk assessment using vulnerability and exposure data

Vulnerability Scanners

Supported Platforms

VulnerabilityScanner Trait

All scanners implement the same trait, making them interchangeable:

#![allow(unused)]
fn main() {
pub trait VulnerabilityScanner: Connector {
    async fn get_vulnerabilities_for_asset(&self, asset_id: &str) -> ConnectorResult<Vec<Vulnerability>>;
    async fn get_scan_results(&self, scan_id: &str) -> ConnectorResult<ScanResult>;
    async fn get_recent_vulnerabilities(&self, since: DateTime<Utc>, limit: Option<usize>) -> ConnectorResult<Vec<Vulnerability>>;
    async fn get_vulnerability_by_cve(&self, cve_id: &str) -> ConnectorResult<Option<Vulnerability>>;
}
}

Vulnerability Data

Each vulnerability includes:

Scan Results

Query scan results for summary data:

Attack Surface Monitoring

Supported Platforms

AttackSurfaceMonitor Trait

#![allow(unused)]
fn main() {
pub trait AttackSurfaceMonitor: Connector {
    async fn get_exposures(&self, domain: &str) -> ConnectorResult<Vec<ExternalExposure>>;
    async fn get_asset_exposure(&self, asset_id: &str) -> ConnectorResult<Vec<ExternalExposure>>;
    async fn get_risk_score(&self, domain: &str) -> ConnectorResult<Option<f32>>;
}
}

Exposure Types

The system detects these categories of external exposure:

Each exposure includes a risk score (0.0 to 100.0) and structured details.

Risk Scoring

Risk scores from vulnerability scanners and ASM platforms are combined during incident triage to assess the exposure of affected assets. When the AI agent triages an incident involving a compromised host, it can check:

1. What known vulnerabilities exist on the host
2. Whether public exploits are available for those vulnerabilities
3. What external exposures exist for the host or its domain
4. The overall risk score for the affected domain

This context helps the agent make more accurate severity assessments and recommend appropriate response actions.

Configuration

Add vulnerability scanner and ASM connectors in config/default.yaml:

connectors:
  qualys:
    connector_type: qualys
    enabled: true
    base_url: https://qualysapi.qualys.com
    api_key: ${QUALYS_USERNAME}
    api_secret: ${QUALYS_PASSWORD}
    timeout_secs: 60

  censys:
    connector_type: censys
    enabled: true
    base_url: https://search.censys.io
    api_key: ${CENSYS_API_ID}
    api_secret: ${CENSYS_SECRET}
    timeout_secs: 30

Content Packages

Share playbooks, hunts, knowledge articles, and saved queries between Triage Warden instances using distributable content packages.

Overview

The content package system (Stage 5.5) provides:

• Import/export of playbooks, hunts, knowledge, and queries
• Package validation before import
• Conflict resolution when imported content already exists
• Semantic versioning and compatibility tracking

Package Format

A content package consists of a manifest and a list of content items:

{
  "manifest": {
    "name": "phishing-response-kit",
    "version": "1.2.0",
    "description": "Playbooks and hunts for phishing incident response",
    "author": "Security Team",
    "license": "MIT",
    "tags": ["phishing", "email", "social-engineering"],
    "compatibility": ">=2.0.0"
  },
  "contents": [
    {
      "type": "playbook",
      "name": "phishing-triage",
      "data": { "stages": [...] }
    },
    {
      "type": "hunt",
      "name": "credential-harvesting-detection",
      "data": { "hypothesis": "...", "queries": [...] }
    },
    {
      "type": "knowledge",
      "title": "Phishing Indicators Guide",
      "content": "Common phishing indicators include..."
    },
    {
      "type": "query",
      "name": "failed-logins-by-source",
      "query_type": "siem",
      "query": "event.type:authentication AND event.outcome:failure | stats count by source.ip"
    }
  ]
}

Content Types

Manifest Fields

Importing Packages

curl -X POST http://localhost:8080/api/v1/packages/import \
  -H "Content-Type: application/json" \
  -d '{
    "package": { ... },
    "conflict_resolution": "skip"
  }'

Response:

{
  "imported": 3,
  "skipped": 1,
  "errors": []
}

Conflict Resolution

When an imported item has the same name as an existing one:

Validating Packages

Check a package for errors before importing:

curl -X POST http://localhost:8080/api/v1/packages/validate \
  -H "Content-Type: application/json" \
  -d '{ "manifest": { ... }, "contents": [ ... ] }'

Response:

{
  "valid": true,
  "warnings": ["Package author is not specified"],
  "errors": [],
  "content_count": 4
}

Validation checks:

• Package name and version are present
• All content items have non-empty names
• Warns on missing author or empty content list

Exporting Content

Export a Playbook

curl -X POST http://localhost:8080/api/v1/packages/export/playbook/{playbook_id} \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-playbook-package",
    "version": "1.0.0",
    "description": "Exported playbook",
    "author": "Security Team",
    "license": "MIT",
    "tags": ["phishing"]
  }'

Export a Hunt

curl -X POST http://localhost:8080/api/v1/packages/export/hunt/{hunt_id} \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-hunt-package",
    "version": "1.0.0",
    "description": "Exported hunt",
    "author": "Threat Hunting Team"
  }'

Both return the full package JSON that can be shared or imported into another instance.

AI Triage

Automated incident analysis using Claude AI agents.

Overview

The triage agent analyzes security incidents to:

1. Classify - Determine if the incident is malicious, suspicious, or benign
2. Assess confidence - Quantify certainty in the classification
3. Explain - Provide reasoning for the verdict
4. Recommend - Suggest response actions

How It Works

Incident → Playbook Selection → Tool Execution → AI Analysis → Verdict

1. Incident received - New incident created via webhook or API
2. Playbook selected - Based on incident type (phishing, malware, etc.)
3. Tools executed - Parse data, lookup reputation, check authentication
4. AI analysis - Claude analyzes gathered data
5. Verdict returned - Classification with confidence and recommendations

Example Verdict

{
  "incident_id": "INC-2024-001",
  "classification": "malicious",
  "confidence": 0.92,
  "category": "phishing",
  "reasoning": "Multiple indicators suggest this is a credential phishing attempt:\n1. Sender domain registered 2 days ago\n2. SPF and DKIM authentication failed\n3. URL leads to a fake Microsoft login page\n4. Subject uses urgency tactics",
  "recommended_actions": [
    {
      "action": "quarantine_email",
      "priority": 1,
      "reason": "Prevent user access to phishing content"
    },
    {
      "action": "block_sender",
      "priority": 2,
      "reason": "Sender has no legitimate history"
    },
    {
      "action": "notify_user",
      "priority": 3,
      "reason": "Educate user about phishing attempt"
    }
  ],
  "iocs": [
    {"type": "domain", "value": "phishing-site.com"},
    {"type": "ip", "value": "192.168.1.100"}
  ],
  "mitre_attack": ["T1566.001", "T1078"]
}

Triggering Triage

Automatic (Webhook)

Configure webhooks to auto-triage new incidents:

webhooks:
  email_gateway:
    auto_triage: true
    playbook: phishing_triage

Manual (CLI)

tw-cli triage run --incident INC-2024-001

Manual (API)

curl -X POST http://localhost:8080/api/incidents/INC-2024-001/triage

Next Steps

• Triage Agent - Agent architecture and configuration
• Verdict Types - Understanding classifications
• Confidence Scoring - How confidence is calculated

Triage Agent

The AI agent that analyzes security incidents.

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Triage Agent                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Claude    │  │   Tools     │  │  Playbook   │     │
│  │   Model     │  │   (Bridge)  │  │   Engine    │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                    Python Bridge                         │
│           (ThreatIntelBridge, SIEMBridge, etc.)         │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   Rust Connectors                        │
│        (VirusTotal, Splunk, CrowdStrike, etc.)          │
└─────────────────────────────────────────────────────────┘

Agent Configuration

# python/tw_ai/agents/config.py
class AgentConfig:
    model: str = "claude-sonnet-4-20250514"
    max_tokens: int = 4096
    temperature: float = 0.1
    max_tool_calls: int = 10
    timeout_seconds: int = 120

Environment variables:

TW_AI_PROVIDER=anthropic
TW_ANTHROPIC_API_KEY=your-key
TW_AI_MODEL=claude-sonnet-4-20250514

Available Tools

The agent has access to these tools via the Python bridge:

Agent Workflow

async def triage(self, incident: Incident) -> Verdict:
    # 1. Load appropriate playbook
    playbook = self.load_playbook(incident.incident_type)

    # 2. Execute playbook steps (tools)
    context = {}
    for step in playbook.steps:
        result = await self.execute_step(step, incident, context)
        context[step.output] = result

    # 3. Build analysis prompt
    prompt = self.build_analysis_prompt(incident, context)

    # 4. Get AI verdict
    response = await self.client.messages.create(
        model=self.config.model,
        messages=[{"role": "user", "content": prompt}],
        max_tokens=self.config.max_tokens
    )

    # 5. Parse and return verdict
    return self.parse_verdict(response)

System Prompt

The agent uses a specialized system prompt:

You are an expert security analyst assistant. Analyze the provided security
incident data and determine:

1. Classification: Is this malicious, suspicious, benign, or inconclusive?
2. Confidence: How certain are you (0.0 to 1.0)?
3. Category: What type of threat is this (phishing, malware, etc.)?
4. Reasoning: Explain your analysis step by step
5. Recommended Actions: What should be done to respond?

Use the tool results provided to inform your analysis. Be thorough but concise.
Cite specific evidence for your conclusions.

Tool Calling

The agent can call tools during analysis:

# Agent decides to check URL reputation
tool_result = await self.call_tool(
    name="lookup_urls",
    parameters={"urls": ["https://suspicious-site.com/login"]}
)

# Result used in analysis
# {
#   "results": [{
#     "url": "https://suspicious-site.com/login",
#     "malicious": true,
#     "categories": ["phishing"],
#     "confidence": 0.95
#   }]
# }

Customizing the Agent

Custom System Prompt

agent = TriageAgent(
    system_prompt="""
    You are a SOC analyst specializing in email security.
    Focus on phishing indicators and BEC patterns.
    Always check sender authentication carefully.
    """
)

Custom Tools

Register additional tools:

@agent.tool
async def custom_lookup(domain: str) -> dict:
    """Look up domain in internal threat database."""
    return await internal_db.query(domain)

Model Selection

# Use different models for different scenarios
if incident.severity == "critical":
    agent = TriageAgent(model="claude-opus-4-20250514")
else:
    agent = TriageAgent(model="claude-sonnet-4-20250514")

Error Handling

The agent handles failures gracefully:

try:
    verdict = await agent.triage(incident)
except ToolError as e:
    # Tool failed - continue with available data
    verdict = await agent.triage_partial(incident, failed_tools=[e.tool])
except AIError as e:
    # AI call failed - return inconclusive
    verdict = Verdict.inconclusive(reason=str(e))

Metrics

Agent metrics exported to Prometheus:

• triage_duration_seconds - Time to complete triage
• triage_tool_calls_total - Tool calls per triage
• triage_verdict_total - Verdicts by classification
• triage_confidence_histogram - Confidence score distribution

Verdict Types

Understanding the classification outcomes from AI triage.

Classifications

Malicious

The incident is a confirmed security threat.

Criteria:

• Multiple strong threat indicators
• High-confidence threat intelligence matches
• Clear malicious intent (credential theft, malware, etc.)

Example:

{
  "classification": "malicious",
  "confidence": 0.95,
  "category": "phishing",
  "reasoning": "Email contains credential phishing page targeting Microsoft 365. Sender domain registered yesterday, fails all email authentication. URL redirects to fake login mimicking Microsoft branding."
}

Response:

• Execute recommended containment actions
• Create incident ticket
• Notify affected users

Suspicious

The incident shows concerning indicators but lacks definitive proof.

Criteria:

• Some threat indicators present
• Mixed or conflicting signals
• Unusual but not clearly malicious behavior

Example:

{
  "classification": "suspicious",
  "confidence": 0.65,
  "category": "potential_phishing",
  "reasoning": "Email sender is unknown but domain is 6 months old with valid authentication. URL leads to legitimate document sharing service but file name uses urgency tactics. Recipient has not received email from this sender before."
}

Response:

• Queue for analyst review
• Gather additional context
• Consider temporary quarantine pending review

Benign

The incident is not a security threat.

Criteria:

• No threat indicators found
• Known good sender/source
• Normal expected behavior

Example:

{
  "classification": "benign",
  "confidence": 0.92,
  "category": "legitimate_email",
  "reasoning": "Email from known vendor with established sending history. All authentication passes. Attachment is a standard invoice PDF matching expected format. No suspicious URLs or indicators."
}

Response:

• Close incident
• Release from quarantine if held
• Update detection rules if false positive

Inconclusive

Insufficient data to make a determination.

Criteria:

• Missing critical information
• Tool failures preventing analysis
• Conflicting strong indicators

Example:

{
  "classification": "inconclusive",
  "confidence": 0.3,
  "category": "unknown",
  "reasoning": "Unable to analyze attachment - file corrupted. Sender reputation service unavailable. Email authentication results are mixed (SPF pass, DKIM fail). Need manual review of attachment content.",
  "missing_data": [
    "attachment_analysis",
    "sender_reputation"
  ]
}

Response:

• Escalate to analyst
• Retry failed tool calls
• Request additional information

Confidence Scores

Confidence ranges and their meaning:

Category Types

Email Threats

Endpoint Threats

Access Threats

Using Verdicts

Automation Rules

# Auto-respond to high-confidence malicious
- trigger:
    classification: malicious
    confidence: ">= 0.9"
  actions:
    - quarantine_email
    - block_sender
    - create_ticket

# Queue suspicious for review
- trigger:
    classification: suspicious
  actions:
    - escalate:
        level: analyst
        reason: "Suspicious activity requires review"

Metrics

Track verdict distribution:

# Verdict counts by classification
sum by (classification) (triage_verdict_total)

# Average confidence by category
avg by (category) (triage_confidence)

Confidence Scoring

How the AI agent determines confidence in its verdicts.

Confidence Factors

The agent considers multiple factors when calculating confidence:

Evidence Quality

Evidence Quantity

Data Completeness

Calculation Example

Phishing Email Analysis:

Base confidence: 0.5

Evidence found:
+ SPF failed: +0.15
+ DKIM failed: +0.15
+ Sender domain < 7 days old: +0.2
+ URL matches phishing pattern: +0.25
+ VirusTotal flags URL as phishing: +0.2

Evidence count (5): +0.2

Data completeness: All tools succeeded: +0

Final confidence: 0.5 + 0.15 + 0.15 + 0.2 + 0.25 + 0.2 + 0.2 = 1.0 (capped at 0.99)

Verdict: malicious, confidence: 0.99

Confidence Thresholds

Policy decisions use confidence thresholds:

# Auto-quarantine high confidence malicious
[[policy.rules]]
name = "auto_quarantine_confident"
classification = "malicious"
confidence_min = 0.9
action = "quarantine_email"
decision = "allowed"

# Require review for lower confidence
[[policy.rules]]
name = "review_uncertain"
confidence_max = 0.7
decision = "requires_approval"
approval_level = "analyst"

Confidence Calibration

The agent is calibrated so confidence correlates with accuracy:

Monitoring Calibration

Track calibration with metrics:

# Accuracy at confidence level
triage_accuracy_by_confidence{confidence_bucket="0.9-1.0"}

Improving Calibration

1. Feedback loop - Log false positives to improve
2. Periodic review - Sample low-confidence verdicts
3. Model updates - Retrain with corrected examples

Handling Low Confidence

When confidence is low:

Option 1: Escalate

- condition: confidence < 0.6
  action: escalate
  parameters:
    level: analyst
    reason: "Low confidence verdict requires human review"

Option 2: Gather More Data

- condition: confidence < 0.6
  action: request_additional_data
  parameters:
    - "sender_history"
    - "recipient_context"

Option 3: Conservative Default

- condition: confidence < 0.6
  action: quarantine_email
  parameters:
    reason: "Quarantined pending review due to uncertainty"

Confidence in UI

Dashboard displays confidence visually:

Improving Confidence

Actions that help the agent be more confident:

1. Complete data - Ensure all tools succeed
2. Rich context - Provide incident metadata
3. Historical data - Include past incidents with similar patterns
4. Clear playbooks - Well-defined analysis steps

Playbooks

Playbooks define automated investigation and response workflows.

Overview

A playbook is a sequence of steps that:

1. Gather and analyze incident data
2. Enrich with threat intelligence
3. Determine verdict and response
4. Execute approved actions

Playbook Structure

name: phishing_triage
description: Automated phishing email analysis
version: "1.0"

# When this playbook applies
triggers:
  incident_type: phishing
  auto_run: true

# Variables available to steps
variables:
  quarantine_threshold: 0.7
  block_threshold: 0.3

# Execution steps
steps:
  - name: Parse Email
    action: parse_email
    parameters:
      raw_email: "{{ incident.raw_data.raw_email }}"
    output: parsed

  - name: Check Authentication
    action: check_email_authentication
    parameters:
      headers: "{{ parsed.headers }}"
    output: auth

  - name: Check Sender
    action: lookup_sender_reputation
    parameters:
      sender: "{{ parsed.sender }}"
    output: sender_rep

  - name: Check URLs
    action: lookup_urls
    parameters:
      urls: "{{ parsed.urls }}"
    output: url_results
    condition: "{{ parsed.urls | length > 0 }}"

  - name: Quarantine if Malicious
    action: quarantine_email
    parameters:
      message_id: "{{ incident.raw_data.message_id }}"
      reason: "Automated quarantine - phishing detected"
    condition: >
      sender_rep.score < variables.quarantine_threshold or
      url_results.malicious_count > 0 or
      not auth.authentication_passed

# Final verdict generation
verdict:
  use_ai: true
  model: claude-sonnet-4-20250514
  context:
    - parsed
    - auth
    - sender_rep
    - url_results

Triggers

Define when a playbook runs:

triggers:
  # Run for specific incident types
  incident_type: phishing

  # Auto-run on incident creation
  auto_run: true

  # Or require manual trigger
  auto_run: false

  # Conditions
  conditions:
    severity: ["medium", "high", "critical"]
    source: "email_gateway"

Steps

Basic Step

- name: Step Name
  action: action_name
  parameters:
    key: value
  output: variable_name

Conditional Step

- name: Block Known Bad
  action: block_sender
  parameters:
    sender: "{{ parsed.sender }}"
  condition: "{{ sender_rep.score < 0.2 }}"

Parallel Steps

- parallel:
    - action: lookup_urls
      parameters:
        urls: "{{ parsed.urls }}"
      output: url_results

    - action: lookup_attachments
      parameters:
        attachments: "{{ parsed.attachments }}"
      output: attachment_results

Loop Steps

- name: Check Each URL
  loop: "{{ parsed.urls }}"
  action: lookup_url
  parameters:
    url: "{{ item }}"
  output: url_results
  aggregate: list

Variables

Built-in Variables

Step Outputs

Each step's output is available to subsequent steps:

- action: parse_email
  output: parsed

- action: lookup_urls
  parameters:
    urls: "{{ parsed.urls }}"  # Use previous output

Templates

Use Jinja2-style templates:

parameters:
  message: "Alert for {{ incident.id }}: {{ parsed.subject }}"
  priority: "{{ 'high' if incident.severity == 'critical' else 'medium' }}"

Next Steps

• Creating Playbooks - Write your own playbooks
• Built-in Playbooks - Ready-to-use playbooks

Creating Playbooks

Guide to writing custom playbooks for your security workflows.

Getting Started

1. Create Playbook File

mkdir -p playbooks
touch playbooks/my_playbook.yaml

2. Define Basic Structure

name: my_playbook
description: Description of what this playbook does
version: "1.0"

triggers:
  incident_type: phishing
  auto_run: true

steps:
  - name: First Step
    action: parse_email
    output: result

3. Register Playbook

tw-cli playbook add playbooks/my_playbook.yaml

Step Types

Action Step

Execute a registered action:

- name: Parse Email Content
  action: parse_email
  parameters:
    raw_email: "{{ incident.raw_data.raw_email }}"
  output: parsed
  on_error: continue  # or "fail" (default)

Condition Step

Branch based on conditions:

- name: Check if High Risk
  condition: "{{ sender_rep.score < 0.3 }}"
  then:
    - action: quarantine_email
      parameters:
        message_id: "{{ incident.raw_data.message_id }}"
  else:
    - action: log_event
      parameters:
        message: "Low risk, no action needed"

AI Analysis Step

Get AI verdict:

- name: AI Analysis
  type: ai_analysis
  model: claude-sonnet-4-20250514
  context:
    - parsed
    - auth_results
    - reputation
  prompt: |
    Analyze this email for phishing indicators.
    Consider the authentication results and sender reputation.
  output: ai_verdict

Notification Step

Send alerts:

- name: Alert Team
  action: notify_channel
  parameters:
    channel: slack
    message: |
      New {{ incident.severity }} incident detected
      ID: {{ incident.id }}
      Type: {{ incident.incident_type }}

Error Handling

Per-Step Error Handling

- name: Check Reputation
  action: lookup_sender_reputation
  parameters:
    sender: "{{ parsed.sender }}"
  output: reputation
  on_error: continue  # Don't fail playbook if this fails
  default_output:     # Use this if step fails
    score: 0.5
    risk_level: "unknown"

Global Error Handler

on_error:
  - action: notify_channel
    parameters:
      channel: slack
      message: "Playbook {{ playbook.name }} failed: {{ error.message }}"
  - action: escalate
    parameters:
      level: analyst
      reason: "Automated triage failed"

Variables and Templates

Define Variables

variables:
  high_risk_threshold: 0.3
  quarantine_enabled: true
  notification_channel: "#security-alerts"

Use Variables

- name: Check Risk
  condition: "{{ sender_rep.score < variables.high_risk_threshold }}"
  then:
    - action: quarantine_email
      condition: "{{ variables.quarantine_enabled }}"

Template Functions

parameters:
  # String manipulation
  domain: "{{ parsed.sender | split('@') | last }}"

  # Conditionals
  priority: "{{ 'critical' if incident.severity == 'critical' else 'high' }}"

  # Lists
  all_urls: "{{ parsed.urls | join(', ') }}"
  url_count: "{{ parsed.urls | length }}"

  # Defaults
  assignee: "{{ incident.assignee | default('unassigned') }}"

Testing Playbooks

Dry Run

tw-cli playbook test my_playbook \
  --incident INC-2024-001 \
  --dry-run

With Mock Data

tw-cli playbook test my_playbook \
  --data '{"raw_email": "From: [email protected]..."}'

Validate Syntax

tw-cli playbook validate playbooks/my_playbook.yaml

Best Practices

1. Use Descriptive Names

# Good
- name: Check sender domain reputation

# Bad
- name: step1

2. Handle Failures Gracefully

- name: External Lookup
  action: lookup_sender_reputation
  on_error: continue
  default_output:
    score: 0.5

3. Add Timeouts

- name: Slow External API
  action: custom_lookup
  timeout: 30s

4. Log Key Decisions

- name: Log Verdict
  action: log_event
  parameters:
    level: info
    message: "Verdict: {{ verdict.classification }} ({{ verdict.confidence }})"

5. Version Your Playbooks

name: phishing_triage
version: "2.1.0"
changelog:
  - "2.1.0: Added attachment analysis"
  - "2.0.0: Restructured for parallel lookups"

Example: Complete Playbook

name: comprehensive_phishing_triage
description: Full phishing email analysis with all checks
version: "2.0"

triggers:
  incident_type: phishing
  auto_run: true

variables:
  quarantine_threshold: 0.3
  block_threshold: 0.2

steps:
  # Parse email
  - name: Parse Email
    action: parse_email
    parameters:
      raw_email: "{{ incident.raw_data.raw_email }}"
    output: parsed

  # Parallel enrichment
  - name: Enrich Data
    parallel:
      - action: check_email_authentication
        parameters:
          headers: "{{ parsed.headers }}"
        output: auth

      - action: lookup_sender_reputation
        parameters:
          sender: "{{ parsed.sender }}"
        output: sender_rep

      - action: lookup_urls
        parameters:
          urls: "{{ parsed.urls }}"
        output: urls
        condition: "{{ parsed.urls | length > 0 }}"

      - action: lookup_attachments
        parameters:
          attachments: "{{ parsed.attachments }}"
        output: attachments
        condition: "{{ parsed.attachments | length > 0 }}"

  # AI Analysis
  - name: AI Verdict
    type: ai_analysis
    model: claude-sonnet-4-20250514
    context: [parsed, auth, sender_rep, urls, attachments]
    output: verdict

  # Response actions
  - name: Quarantine Malicious
    action: quarantine_email
    parameters:
      message_id: "{{ incident.raw_data.message_id }}"
    condition: >
      verdict.classification == 'malicious' and
      verdict.confidence >= variables.quarantine_threshold

  - name: Block Repeat Offender
    action: block_sender
    parameters:
      sender: "{{ parsed.sender }}"
    condition: >
      sender_rep.score < variables.block_threshold

  - name: Create Ticket
    action: create_ticket
    parameters:
      title: "{{ verdict.classification | title }}: {{ parsed.subject | truncate(50) }}"
      priority: "{{ incident.severity }}"
    condition: "{{ verdict.classification != 'benign' }}"

on_error:
  - action: escalate
    parameters:
      level: analyst
      reason: "Playbook execution failed"

Built-in Playbooks

Ready-to-use playbooks included with Triage Warden.

Email Security

phishing_triage

Comprehensive phishing email analysis.

Triggers: incident_type: phishing

Steps:

1. Parse email headers and body
2. Check SPF/DKIM/DMARC authentication
3. Look up sender reputation
4. Analyze URLs against threat intel
5. Check attachment hashes
6. AI analysis and verdict
7. Auto-quarantine if malicious (confidence > 0.8)

Usage:

tw-cli playbook run phishing_triage --incident INC-2024-001

spam_triage

Quick spam classification.

Triggers: incident_type: spam

Steps:

1. Parse email
2. Check spam indicators (bulk headers, suspicious patterns)
3. Classify as spam/not spam
4. Auto-archive low-confidence spam

bec_detection

Business Email Compromise detection.

Triggers: incident_type: bec

Steps:

1. Parse email
2. Check for executive impersonation
3. Analyze reply-to mismatch
4. Check for urgency indicators
5. Verify sender against directory
6. AI analysis for social engineering patterns

Endpoint Security

malware_triage

Malware alert analysis.

Triggers: incident_type: malware

Steps:

1. Get host information from EDR
2. Look up file hash
3. Check related processes
4. Query SIEM for lateral movement
5. AI verdict
6. Auto-isolate if critical severity + high confidence

suspicious_login

Anomalous login investigation.

Triggers: incident_type: suspicious_login

Steps:

1. Get login details
2. Check for impossible travel
3. Query user's recent activity
4. Check IP reputation
5. Verify device fingerprint
6. AI analysis

Customizing Built-in Playbooks

Override Variables

tw-cli playbook run phishing_triage \
  --incident INC-2024-001 \
  --var quarantine_threshold=0.9 \
  --var auto_block=false

Fork and Modify

# Export built-in playbook
tw-cli playbook export phishing_triage > my_phishing.yaml

# Edit as needed
vim my_phishing.yaml

# Register custom version
tw-cli playbook add my_phishing.yaml

Extend with Hooks

# my_phishing.yaml
extends: phishing_triage

# Add steps after parent playbook
after_steps:
  - name: Custom Logging
    action: log_to_siem
    parameters:
      event: phishing_verdict
      data: "{{ verdict }}"

# Override variables
variables:
  quarantine_threshold: 0.85

Playbook Comparison

Monitoring Playbooks

Execution Metrics

# Playbook execution count
sum by (playbook) (playbook_executions_total)

# Average duration
avg by (playbook) (playbook_duration_seconds)

# Success rate
sum(playbook_executions_total{status="success"}) /
sum(playbook_executions_total)

Alerts

# Alert on playbook failures
- alert: PlaybookFailureRate
  expr: |
    sum(rate(playbook_executions_total{status="failed"}[5m])) /
    sum(rate(playbook_executions_total[5m])) > 0.1
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Playbook failure rate above 10%"

REST API

Programmatic access to Triage Warden functionality.

Base URL

http://localhost:8080/api

Authentication

See Authentication for details.

API Key

curl -H "Authorization: Bearer tw_abc123_secretkey" \
  http://localhost:8080/api/incidents

Session Cookie

For browser-based access, use session authentication via /login.

Response Format

All responses are JSON:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}

Error Responses

{
  "error": {
    "code": "not_found",
    "message": "Incident not found",
    "details": { ... }
  }
}

HTTP Status Codes

Endpoints Overview

Incidents

Actions

Playbooks

Webhooks

System

Pagination

List endpoints support pagination:

curl "http://localhost:8080/api/incidents?page=2&per_page=50"

Parameters:

• page - Page number (default: 1)
• per_page - Items per page (default: 20, max: 100)

Filtering

Filter list results:

curl "http://localhost:8080/api/incidents?status=open&severity=high"

Common filters:

• status - Filter by status
• severity - Filter by severity
• type - Filter by incident type
• created_after - Created after date
• created_before - Created before date

Sorting

curl "http://localhost:8080/api/incidents?sort=-created_at"

• Prefix with - for descending order
• Default: -created_at (newest first)

Rate Limiting

API requests are rate limited:

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705320000

Next Steps

• Authentication - API authentication
• Incidents - Incident endpoints
• Actions - Action endpoints
• Playbooks - Playbook endpoints
• Webhooks - Webhook integration

API Authentication

Authenticate with the Triage Warden API.

API Keys

Creating an API Key

# Via CLI
tw-cli api-key create --name "automation-script" --scopes read,write

# Output:
# API Key created successfully
# Key: tw_abc123_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# WARNING: Store this key securely. It cannot be retrieved again.

Using API Keys

Include in the Authorization header:

curl -H "Authorization: Bearer tw_abc123_secretkey" \
  http://localhost:8080/api/incidents

API Key Scopes

Managing API Keys

# List keys
tw-cli api-key list

# Revoke key
tw-cli api-key revoke tw_abc123

# Rotate key
tw-cli api-key rotate tw_abc123

Session Authentication

For web dashboard access:

Login

curl -X POST http://localhost:8080/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=analyst&password=secret&csrf_token=xxx" \
  -c cookies.txt

Using Session

curl -b cookies.txt http://localhost:8080/api/incidents

Logout

curl -X POST http://localhost:8080/logout -b cookies.txt

CSRF Protection

State-changing requests require CSRF tokens:

1. Get token from login page or API
2. Include in request header or body

# Header
curl -X POST http://localhost:8080/api/incidents \
  -H "X-CSRF-Token: abc123" \
  -b cookies.txt \
  -d '{"type": "phishing"}'

# Form body
curl -X POST http://localhost:8080/api/incidents \
  -d "csrf_token=abc123&type=phishing" \
  -b cookies.txt

Webhook Authentication

Webhooks use HMAC signatures:

Configuring Webhook Secret

tw-cli webhook add email-gateway \
  --url http://localhost:8080/api/webhooks/email-gateway \
  --secret "your-secret-key"

Verifying Signatures

Triage Warden validates the X-Webhook-Signature header:

X-Webhook-Signature: sha256=abc123...

Signature is computed as:

HMAC-SHA256(secret, timestamp + "." + body)

Signature Verification Example

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str, timestamp: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{payload.decode()}".encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Service Accounts

For automated systems:

# Create service account
tw-cli user create \
  --username automation-bot \
  --role analyst \
  --service-account

# Generate API key for service account
tw-cli api-key create \
  --user automation-bot \
  --name "ci-cd-integration" \
  --scopes read,write

Security Best Practices

1. Rotate keys regularly - Set up automated rotation
2. Use minimal scopes - Only grant necessary permissions
3. Secure storage - Use secret managers, not code
4. Monitor usage - Review audit logs for suspicious activity
5. IP allowlisting - Restrict API access by IP (optional)

# Enable IP allowlist
tw-cli config set api.allowed_ips "10.0.0.0/8,192.168.1.0/24"

Error Responses

401 Unauthorized

Missing or invalid credentials:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing authentication"
  }
}

403 Forbidden

Valid credentials but insufficient permissions:

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient permissions for this operation"
  }
}

Incidents API

Create, read, update, and manage security incidents.

List Incidents

GET /api/incidents

Query Parameters

Example

curl "http://localhost:8080/api/incidents?status=open&severity=high&per_page=10" \
  -H "Authorization: Bearer tw_xxx"

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "incident_number": "INC-2024-0001",
      "incident_type": "phishing",
      "severity": "high",
      "status": "open",
      "source": "email_gateway",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 42
  }
}

Get Incident

GET /api/incidents/:id

Example

curl "http://localhost:8080/api/incidents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer tw_xxx"

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "incident_number": "INC-2024-0001",
    "incident_type": "phishing",
    "severity": "high",
    "status": "triaged",
    "source": "email_gateway",
    "raw_data": {
      "message_id": "AAMkAGI2...",
      "sender": "[email protected]",
      "subject": "Urgent: Update Account"
    },
    "verdict": {
      "classification": "malicious",
      "confidence": 0.92,
      "category": "phishing",
      "reasoning": "Multiple phishing indicators..."
    },
    "recommended_actions": [
      "quarantine_email",
      "block_sender"
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z",
    "triaged_at": "2024-01-15T10:35:00Z"
  }
}

Create Incident

POST /api/incidents

Request Body

{
  "incident_type": "phishing",
  "source": "email_gateway",
  "severity": "medium",
  "raw_data": {
    "message_id": "AAMkAGI2...",
    "sender": "[email protected]",
    "recipient": "[email protected]",
    "subject": "Important Document",
    "received_at": "2024-01-15T10:00:00Z"
  }
}

Example

curl -X POST "http://localhost:8080/api/incidents" \
  -H "Authorization: Bearer tw_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "incident_type": "phishing",
    "source": "email_gateway",
    "severity": "medium",
    "raw_data": {...}
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "incident_number": "INC-2024-0002",
    "status": "open",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

Update Incident

PUT /api/incidents/:id

Request Body

{
  "severity": "high",
  "status": "resolved",
  "resolution": "False positive - legitimate vendor email"
}

Delete Incident

DELETE /api/incidents/:id

Note: Requires admin role.

Run Triage

POST /api/incidents/:id/triage

Trigger AI triage on an incident.

Request Body (Optional)

{
  "playbook": "custom_phishing",
  "force": true
}

Response

{
  "data": {
    "triage_id": "triage-abc123",
    "status": "completed",
    "verdict": {
      "classification": "malicious",
      "confidence": 0.92
    },
    "duration_ms": 45000
  }
}

Execute Action

POST /api/incidents/:id/actions

Execute an action on an incident.

Request Body

{
  "action": "quarantine_email",
  "parameters": {
    "message_id": "AAMkAGI2...",
    "reason": "Phishing detected"
  }
}

Response (Immediate Execution)

{
  "data": {
    "action_id": "act-abc123",
    "status": "completed",
    "result": {
      "success": true,
      "message": "Email quarantined successfully"
    }
  }
}

Response (Pending Approval)

{
  "data": {
    "action_id": "act-abc123",
    "status": "pending_approval",
    "approval_level": "senior",
    "message": "Action requires senior analyst approval"
  }
}

Get Incident Actions

GET /api/incidents/:id/actions

List all actions for an incident.

Response

{
  "data": [
    {
      "id": "act-abc123",
      "action_type": "quarantine_email",
      "status": "completed",
      "executed_at": "2024-01-15T10:40:00Z",
      "executed_by": "system"
    },
    {
      "id": "act-def456",
      "action_type": "block_sender",
      "status": "pending_approval",
      "approval_level": "analyst",
      "requested_at": "2024-01-15T10:41:00Z"
    }
  ]
}

Actions API

Manage action execution and approvals.

List Actions

GET /api/actions

Query Parameters

Example

curl "http://localhost:8080/api/actions?status=pending_approval" \
  -H "Authorization: Bearer tw_xxx"

Response

{
  "data": [
    {
      "id": "act-abc123",
      "incident_id": "550e8400-e29b-41d4-a716-446655440000",
      "action_type": "isolate_host",
      "status": "pending_approval",
      "approval_level": "senior",
      "parameters": {
        "host_id": "aid:xyz789",
        "reason": "Malware detected"
      },
      "requested_by": "triage_agent",
      "requested_at": "2024-01-15T10:45:00Z"
    }
  ]
}

Get Action

GET /api/actions/:id

Response

{
  "data": {
    "id": "act-abc123",
    "incident_id": "550e8400-e29b-41d4-a716-446655440000",
    "action_type": "isolate_host",
    "status": "pending_approval",
    "approval_level": "senior",
    "parameters": {
      "host_id": "aid:xyz789",
      "reason": "Malware detected"
    },
    "requested_by": "triage_agent",
    "requested_at": "2024-01-15T10:45:00Z",
    "incident": {
      "incident_number": "INC-2024-0001",
      "incident_type": "malware",
      "severity": "high"
    }
  }
}

Approve Action

POST /api/actions/:id/approve

Request Body

{
  "comment": "Verified threat, approved for isolation"
}

Response

{
  "data": {
    "id": "act-abc123",
    "status": "completed",
    "approved_by": "[email protected]",
    "approved_at": "2024-01-15T11:00:00Z",
    "result": {
      "success": true,
      "message": "Host isolated successfully"
    }
  }
}

Errors

403 Forbidden - Insufficient approval level:

{
  "error": {
    "code": "insufficient_approval_level",
    "message": "This action requires senior analyst approval",
    "required_level": "senior",
    "your_level": "analyst"
  }
}

Reject Action

POST /api/actions/:id/reject

Request Body

{
  "reason": "False positive - user confirmed legitimate activity"
}

Response

{
  "data": {
    "id": "act-abc123",
    "status": "rejected",
    "rejected_by": "[email protected]",
    "rejected_at": "2024-01-15T11:00:00Z",
    "rejection_reason": "False positive - user confirmed legitimate activity"
  }
}

Execute Action Directly

POST /api/actions/execute

Execute an action without associating with an incident.

Request Body

{
  "action": "block_sender",
  "parameters": {
    "sender": "[email protected]"
  }
}

Response

{
  "data": {
    "action_id": "act-ghi789",
    "status": "completed",
    "result": {
      "success": true,
      "message": "Sender blocked"
    }
  }
}

Get Action Types

GET /api/actions/types

List all available action types.

Response

{
  "data": [
    {
      "name": "quarantine_email",
      "description": "Move email to quarantine",
      "category": "email",
      "supports_rollback": true,
      "parameters": [
        {
          "name": "message_id",
          "type": "string",
          "required": true
        },
        {
          "name": "reason",
          "type": "string",
          "required": false
        }
      ]
    },
    {
      "name": "isolate_host",
      "description": "Network-isolate a host",
      "category": "endpoint",
      "supports_rollback": true,
      "default_approval_level": "senior",
      "parameters": [...]
    }
  ]
}

Rollback Action

POST /api/actions/:id/rollback

Rollback a previously executed action.

Request Body

{
  "reason": "False positive confirmed"
}

Response

{
  "data": {
    "rollback_action_id": "act-jkl012",
    "original_action_id": "act-abc123",
    "status": "completed",
    "result": {
      "success": true,
      "message": "Host unisolated successfully"
    }
  }
}

Errors

400 Bad Request - Action doesn't support rollback:

{
  "error": {
    "code": "rollback_not_supported",
    "message": "Action type 'notify_user' does not support rollback"
  }
}

Playbooks API

Manage and execute playbooks.

List Playbooks

GET /api/playbooks

Response

{
  "data": [
    {
      "id": "pb-abc123",
      "name": "phishing_triage",
      "description": "Automated phishing email analysis",
      "version": "2.0",
      "enabled": true,
      "triggers": {
        "incident_type": "phishing",
        "auto_run": true
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-10T00:00:00Z"
    }
  ]
}

Get Playbook

GET /api/playbooks/:id

Response

{
  "data": {
    "id": "pb-abc123",
    "name": "phishing_triage",
    "description": "Automated phishing email analysis",
    "version": "2.0",
    "enabled": true,
    "triggers": {
      "incident_type": "phishing",
      "auto_run": true
    },
    "variables": {
      "quarantine_threshold": 0.7
    },
    "steps": [
      {
        "name": "Parse Email",
        "action": "parse_email",
        "parameters": {
          "raw_email": "{{ incident.raw_data.raw_email }}"
        },
        "output": "parsed"
      }
    ],
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-10T00:00:00Z"
  }
}

Create Playbook

POST /api/playbooks

Request Body

{
  "name": "custom_playbook",
  "description": "My custom investigation playbook",
  "triggers": {
    "incident_type": "phishing",
    "auto_run": false
  },
  "steps": [
    {
      "name": "Parse Email",
      "action": "parse_email",
      "output": "parsed"
    }
  ]
}

Response

{
  "data": {
    "id": "pb-def456",
    "name": "custom_playbook",
    "version": "1.0",
    "created_at": "2024-01-15T12:00:00Z"
  }
}

Update Playbook

PUT /api/playbooks/:id

Request Body

{
  "description": "Updated description",
  "enabled": false
}

Delete Playbook

DELETE /api/playbooks/:id

Note: Built-in playbooks cannot be deleted.

Run Playbook

POST /api/playbooks/:id/run

Execute a playbook on an incident.

Request Body

{
  "incident_id": "550e8400-e29b-41d4-a716-446655440000",
  "variables": {
    "quarantine_threshold": 0.9
  }
}

Response

{
  "data": {
    "execution_id": "exec-abc123",
    "playbook_id": "pb-abc123",
    "incident_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "started_at": "2024-01-15T12:00:00Z",
    "completed_at": "2024-01-15T12:00:45Z",
    "steps_completed": 5,
    "steps_total": 5,
    "verdict": {
      "classification": "malicious",
      "confidence": 0.92
    }
  }
}

Get Playbook Executions

GET /api/playbooks/:id/executions

Response

{
  "data": [
    {
      "execution_id": "exec-abc123",
      "incident_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "duration_ms": 45000,
      "started_at": "2024-01-15T12:00:00Z"
    }
  ]
}

Validate Playbook

POST /api/playbooks/validate

Validate playbook YAML without creating it.

Request Body

{
  "content": "name: test\nsteps:\n  - action: parse_email"
}

Response (Valid)

{
  "data": {
    "valid": true,
    "warnings": []
  }
}

Response (Invalid)

{
  "data": {
    "valid": false,
    "errors": [
      {
        "line": 3,
        "message": "Unknown action: invalid_action"
      }
    ]
  }
}

Export Playbook

GET /api/playbooks/:id/export

Download playbook as YAML file.

Response

name: phishing_triage
description: Automated phishing email analysis
version: "2.0"
...

Webhooks API

Receive events from external security tools.

Endpoint

POST /api/webhooks/:source

Where :source identifies the sending system (e.g., email-gateway, edr, siem).

Authentication

Webhooks are authenticated via HMAC signatures:

X-Webhook-Signature: sha256=abc123...
X-Webhook-Timestamp: 1705320000

Registering Webhook Sources

Via CLI

tw-cli webhook add email-gateway \
  --secret "your-secret-key" \
  --auto-triage true \
  --playbook phishing_triage

Via API

curl -X POST "http://localhost:8080/api/webhooks" \
  -H "Authorization: Bearer tw_xxx" \
  -d '{
    "source": "email-gateway",
    "secret": "your-secret-key",
    "auto_triage": true,
    "playbook": "phishing_triage"
  }'

Payload Formats

Generic Format

{
  "event_type": "security_alert",
  "timestamp": "2024-01-15T10:00:00Z",
  "source": "email-gateway",
  "data": {
    "alert_id": "alert-123",
    "severity": "high",
    "details": {...}
  }
}

Microsoft Defender for Office 365

{
  "eventType": "PhishingEmail",
  "id": "AAMkAGI2...",
  "creationTime": "2024-01-15T10:00:00Z",
  "severity": "high",
  "category": "Phish",
  "entityType": "Email",
  "data": {
    "sender": "[email protected]",
    "subject": "Urgent Action Required",
    "recipients": ["[email protected]"]
  }
}

CrowdStrike Falcon

{
  "metadata": {
    "eventType": "DetectionSummaryEvent",
    "eventCreationTime": 1705320000000
  },
  "event": {
    "DetectId": "ldt:abc123",
    "Severity": 4,
    "HostnameField": "WORKSTATION-01",
    "DetectName": "Malicious File Detected"
  }
}

Splunk Alert

{
  "result": {
    "host": "server-01",
    "source": "WinEventLog:Security",
    "sourcetype": "WinEventLog",
    "_raw": "...",
    "EventCode": "4625"
  },
  "search_name": "Failed Login Alert",
  "trigger_time": 1705320000
}

Response

Success

{
  "status": "accepted",
  "incident_id": "550e8400-e29b-41d4-a716-446655440000",
  "incident_number": "INC-2024-0001"
}

Queued for Processing

{
  "status": "queued",
  "queue_id": "queue-abc123",
  "message": "Event queued for processing"
}

Configuring Auto-Triage

When auto_triage is enabled, incidents created from webhooks are automatically triaged:

# webhook_config.yaml
sources:
  email-gateway:
    secret: "${EMAIL_GATEWAY_SECRET}"
    auto_triage: true
    playbook: phishing_triage
    severity_mapping:
      critical: critical
      high: high
      medium: medium
      low: low

  edr:
    secret: "${EDR_SECRET}"
    auto_triage: true
    playbook: malware_triage

Testing Webhooks

Send Test Event

# Generate signature
TIMESTAMP=$(date +%s)
BODY='{"event_type":"test","data":{}}'
SIGNATURE=$(echo -n "${TIMESTAMP}.${BODY}" | openssl dgst -sha256 -hmac "your-secret")

# Send request
curl -X POST "http://localhost:8080/api/webhooks/email-gateway" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=${SIGNATURE}" \
  -H "X-Webhook-Timestamp: ${TIMESTAMP}" \
  -d "${BODY}"

Verify Configuration

tw-cli webhook test email-gateway

Error Handling

Invalid Signature

{
  "error": {
    "code": "invalid_signature",
    "message": "Webhook signature verification failed"
  }
}

Unknown Source

{
  "error": {
    "code": "unknown_source",
    "message": "Webhook source 'unknown' is not registered"
  }
}

Replay Attack

{
  "error": {
    "code": "timestamp_expired",
    "message": "Webhook timestamp is too old (>5 minutes)"
  }
}

Monitoring Webhooks

Metrics

# Webhook receive rate
rate(webhook_received_total[5m])

# Error rate by source
rate(webhook_errors_total[5m])

Logs

tw-cli logs --filter webhook --tail 100

API Error Codes

All API errors return a consistent JSON structure with an error code, message, and optional details.

Error Response Format

{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": { ... },
  "request_id": "optional-request-id"
}

Error Codes Reference

Authentication Errors (4xx)

Client Errors (4xx)

Server Errors (5xx)

Detailed Error Examples

Validation Error

When field validation fails, the response includes detailed field-level errors:

{
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": {
    "name": {
      "code": "required",
      "message": "Name is required"
    },
    "email": {
      "code": "invalid_format",
      "message": "Invalid email format"
    }
  }
}

Not Found Error

{
  "code": "NOT_FOUND",
  "message": "Not found: Incident 550e8400-e29b-41d4-a716-446655440000 not found"
}

Conflict Error

Returned when attempting an action that conflicts with current state:

{
  "code": "CONFLICT",
  "message": "Conflict: Action is not pending approval (current status: Approved)"
}

Rate Limit Error

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded"
}

Include a Retry-After header when available.

Unauthorized Error

{
  "code": "UNAUTHORIZED",
  "message": "Unauthorized: No authentication provided"
}

Error Handling Best Practices

Client Implementation

import requests

def handle_api_error(response):
    error = response.json()
    code = error.get('code')

    if code == 'RATE_LIMIT_EXCEEDED':
        # Implement exponential backoff
        retry_after = int(response.headers.get('Retry-After', 60))
        time.sleep(retry_after)
        return retry_request()

    elif code == 'SESSION_EXPIRED':
        # Re-authenticate
        refresh_session()
        return retry_request()

    elif code == 'VALIDATION_ERROR':
        # Handle field-specific errors
        for field, details in error.get('details', {}).items():
            print(f"Field '{field}': {details['message']}")

    elif code in ['INTERNAL_ERROR', 'DATABASE_ERROR']:
        # Log and alert on server errors
        log_error(error)
        raise ServerError(error['message'])

Retry Strategy

For transient errors (5xx, RATE_LIMIT_EXCEEDED), implement exponential backoff:

import time
import random

def retry_with_backoff(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except (RateLimitError, ServiceUnavailableError) as e:
            if attempt == max_retries - 1:
                raise
            delay = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

HTTP Status Code Summary

Configuration Guide

Complete guides for configuring Triage Warden.

Initial Setup

After installation, configure Triage Warden in this order:

1. Environment Variables - Set required environment variables
2. Connectors - Connect to your security tools
3. Notifications - Set up alert channels
4. Playbooks - Create automation workflows
5. Policies - Define approval and safety rules
6. SSO Integrations - Configure enterprise identity providers

Quick Configuration

First Run

After starting Triage Warden, log in with the default credentials:

• Username: admin
• Password: admin

Important: Change the default password immediately!

Essential Settings

Navigate to Settings and configure:

1. General

   • Organization name
   • Timezone
   • Operation mode (Assisted → Supervised → Autonomous)

2. AI/LLM

   • Select provider (Anthropic, OpenAI, or Local)
   • Enter API key
   • Choose model

3. Connectors (at minimum)

   • Threat intelligence (VirusTotal recommended)
   • Your primary SIEM or alert source

4. Notifications

   • At least one channel for critical alerts

Configuration Methods

Web UI (Recommended)

Most settings can be configured through the web dashboard at Settings.

Pros:

• User-friendly interface
• Validation feedback
• Immediate effect

Environment Variables

For deployment configuration and secrets:

# Required
DATABASE_URL=postgres://...
TW_ENCRYPTION_KEY=...

# Optional overrides
TW_LLM_PROVIDER=anthropic
TW_LLM_MODEL=claude-3-sonnet

See Environment Variables Reference for full list.

Configuration Files

For complex configurations:

# config/default.yaml
server:
  bind_address: "0.0.0.0:8080"

guardrails:
  max_actions_per_incident: 10
  blocked_actions: []

Configuration Hierarchy

Configuration is loaded in this order (later overrides earlier):

1. Built-in defaults
         ↓
2. config/default.yaml
         ↓
3. config/{environment}.yaml
         ↓
4. Environment variables
         ↓
5. Database settings (via UI)

Validation

Triage Warden validates configuration at startup:

# Validate without starting
triage-warden serve --validate-only

# Check specific configuration
triage-warden config check

Common Validation Errors

Backup Configuration

Before making changes, backup current settings:

# Export settings via API
curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:8080/api/settings/export > settings-backup.json

# Restore settings
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @settings-backup.json \
  http://localhost:8080/api/settings/import

Next Steps

• Set up connectors
• Configure notifications
• Create playbooks
• Configure SSO

Environment Variables Reference

Complete reference of all environment variables for Triage Warden.

Required Variables

These must be set for Triage Warden to start.

Database

Connection String Format:

postgres://username:password@hostname:port/database?sslmode=require

SSL Modes:

• disable - No SSL (development only)
• require - SSL required, no certificate verification
• verify-ca - Verify server certificate against CA
• verify-full - Verify server certificate and hostname

Security

Generating Keys:

# Encryption key (32 bytes, base64)
openssl rand -base64 32

# JWT/Session secret (hex)
openssl rand -hex 32

Server Configuration