DefenseClaw

DefenseClaw is Cisco’s open-source secure agent framework announced at RSA 2026 as part of their agentic AI security suite. It provides a structured runtime for building and deploying security automation agents that interact with Cisco security products (Umbrella, SecureX, XDR) as well as third-party tools. Agents handle inventory collection, threat response workflows, policy enforcement, and cross-platform event correlation.

Installation

pip (Python 3.11+)

pip install defenseclaw

# Install with all integration extras
pip install "defenseclaw[cisco,splunk,crowdstrike,sentinel]"

# Verify installation
defenseclaw --version
defenseclaw doctor   # check connectivity and credentials

From Source

git clone https://github.com/cisco-security/defenseclaw
cd defenseclaw
pip install -e ".[dev]"

# Run tests
pytest tests/

Docker

docker pull cisco/defenseclaw:latest

docker run --rm -it \
  -v $(pwd)/agents:/app/agents \
  -v $(pwd)/config:/app/config \
  -e CISCO_CLIENT_ID=$CISCO_CLIENT_ID \
  -e CISCO_CLIENT_SECRET=$CISCO_CLIENT_SECRET \
  cisco/defenseclaw:latest

Helm (Kubernetes)

helm repo add cisco-security https://charts.cisco.com/security
helm repo update
helm install defenseclaw cisco-security/defenseclaw \
  --set cisco.clientId=$CISCO_CLIENT_ID \
  --set cisco.clientSecret=$CISCO_CLIENT_SECRET \
  --namespace security-ops --create-namespace

Configuration

Authentication Setup

# Initialize config directory
defenseclaw config init

# Configure Cisco XDR credentials
defenseclaw config set cisco.client_id "your-client-id"
defenseclaw config set cisco.client_secret "your-client-secret"
defenseclaw config set cisco.region "us"   # us | eu | apjc

# Configure third-party integrations
defenseclaw config set splunk.url "https://splunk.company.com:8089"
defenseclaw config set splunk.token "your-hec-token"
defenseclaw config set crowdstrike.client_id "cs-client-id"
defenseclaw config set crowdstrike.client_secret "cs-client-secret"

Config File (~/.defenseclaw/config.yaml)

cisco:
  client_id: "${CISCO_CLIENT_ID}"
  client_secret: "${CISCO_CLIENT_SECRET}"
  region: us
  products:
    - umbrella
    - xdr
    - secure_endpoint
    - secure_firewall

agent:
  runtime: secure          # secure | standard
  log_level: info
  audit_all_actions: true  # required for compliance
  max_concurrent: 10

integrations:
  splunk:
    url: "${SPLUNK_URL}"
    token: "${SPLUNK_HEC_TOKEN}"
    index: security-ops
  pagerduty:
    api_key: "${PAGERDUTY_API_KEY}"
    default_service: security-incidents

inventory:
  scan_interval: 3600      # seconds between inventory sweeps
  auto_tag: true
  tag_rules_file: ./tag-rules.yaml

Verify Connectivity

defenseclaw doctor --verbose

# Test specific integration
defenseclaw doctor --integration cisco-xdr
defenseclaw doctor --integration splunk

Core Commands

Command	Description
defenseclaw agent run <file>	Execute an agent definition file
defenseclaw agent list	List all available built-in agents
defenseclaw agent validate <file>	Validate agent definition syntax
defenseclaw agent logs <id>	Tail logs for a running agent
defenseclaw inventory scan	Run full security inventory sweep
defenseclaw inventory show	Display current inventory summary
defenseclaw inventory export --format csv	Export inventory to CSV/JSON
defenseclaw workflow run <name>	Execute a named workflow
defenseclaw workflow list	List all available workflows
defenseclaw policy check <resource>	Evaluate policy against a resource
defenseclaw policy enforce	Run policy enforcement across inventory
defenseclaw event correlate --last 1h	Correlate security events in time range
defenseclaw config show	Display active configuration
defenseclaw config set <key> <value>	Set a configuration value
defenseclaw status	Show framework and integration health

Advanced Usage

Writing a Custom Agent

# Scaffold a new agent
defenseclaw agent new --name threat-hunt-agent --type investigation

# Edit the generated agent definition
cat agents/threat-hunt-agent.yaml

name: threat-hunt-agent
description: Hunt for lateral movement indicators in endpoint telemetry
version: 1.0.0
runtime: secure

tools:
  - cisco.xdr.events
  - cisco.secure_endpoint.processes
  - splunk.search
  - pagerduty.create_incident

permissions:
  read: [events, endpoints, processes]
  write: [incidents, annotations]
  execute: [isolate_endpoint]   # requires explicit approval

steps:
  - name: collect_telemetry
    tool: cisco.xdr.events
    params:
      lookback: "24h"
      event_types: [network, process, file]

  - name: analyze_lateral_movement
    tool: splunk.search
    params:
      query: "index=security sourcetype=cisco:xdr | stats count by src_ip, dest_ip"

  - name: alert_on_findings
    tool: pagerduty.create_incident
    condition: "findings.count > 0"
    params:
      title: "Lateral movement detected"
      severity: high

# Run the custom agent
defenseclaw agent run agents/threat-hunt-agent.yaml

# Run with dry-run to preview actions
defenseclaw agent run agents/threat-hunt-agent.yaml --dry-run

Inventory Management

Command	Description
defenseclaw inventory scan --source cisco-xdr	Scan inventory from XDR only
defenseclaw inventory tag --rule auto	Apply auto-tagging rules
defenseclaw inventory diff --since 24h	Show changes in last 24 hours
defenseclaw inventory search --tag production	Search inventory by tag
defenseclaw inventory asset <id>	Show full detail for an asset
defenseclaw inventory export --format json	Export as JSON

Event Correlation

# Correlate across all connected platforms
defenseclaw event correlate \
  --last 4h \
  --sources "cisco-xdr,crowdstrike,splunk" \
  --output correlation-report.json

# Correlate by indicator
defenseclaw event correlate \
  --ioc "185.220.101.5" \
  --ioc-type ip \
  --last 7d

# Create correlation rule
defenseclaw rule create \
  --name "brute-force-then-login" \
  --description "Failed logins followed by success from same IP" \
  --file rules/brute-force.yaml

Policy Enforcement

# Check a specific endpoint against policy
defenseclaw policy check endpoint:abc-123 --policy endpoint-hardening

# Run enforcement (remediate policy violations)
defenseclaw policy enforce \
  --policy endpoint-hardening \
  --auto-remediate \
  --dry-run   # preview before applying

# Schedule regular enforcement
defenseclaw policy schedule \
  --policy all \
  --cron "0 6 * * *" \
  --notify security-team@company.com

Common Workflows

Automated Threat Response

# 1. Set up threat detection workflow
cat > workflows/threat-response.yaml << 'EOF'
name: auto-threat-response
trigger:
  type: event
  source: cisco-xdr
  filter: severity >= high

steps:
  - action: enrich_ioc
    tool: cisco.umbrella.investigate
  - action: check_endpoint
    tool: cisco.secure_endpoint.status
  - action: isolate_if_compromised
    tool: cisco.secure_endpoint.isolate
    condition: "endpoint.threat_score > 85"
    requires_approval: true
  - action: create_ticket
    tool: servicenow.create_incident
  - action: notify_team
    tool: pagerduty.create_incident
EOF

# 2. Register and activate workflow
defenseclaw workflow register workflows/threat-response.yaml
defenseclaw workflow activate threat-response

Security Inventory Audit

# 1. Run full inventory sweep
defenseclaw inventory scan --verbose

# 2. Check for policy drift
defenseclaw policy check --all --output policy-drift.json

# 3. Generate compliance summary
defenseclaw report compliance \
  --framework CIS \
  --output compliance-report.html

# 4. Export findings to SIEM
defenseclaw inventory export \
  --format splunk-hec \
  --destination $SPLUNK_HEC_URL

Cross-Platform Incident Investigation

# Investigate an alert across all connected platforms
defenseclaw investigate \
  --alert-id XDR-2026-001234 \
  --enrich \
  --timeline \
  --output investigation-report.html

# Pull timeline for a specific asset
defenseclaw investigate asset \
  --id endpoint:workstation-042 \
  --last 72h \
  --format json

Tips and Best Practices

• Enable audit_all_actions: true in config to maintain a complete audit trail of agent actions — required for most compliance frameworks
• Use --dry-run before any enforcement or remediation workflow to preview impact; DefenseClaw’s enforcement actions are often irreversible
• Start with read-only permissions in custom agents and add write/execute permissions incrementally after testing
• Set requires_approval: true on any action that isolates endpoints or modifies firewall rules in production environments
• Use the secure runtime (not standard) for agents that handle sensitive telemetry — it sandboxes agent execution
• Tag inventory assets systematically using tag-rules.yaml so policy rules and automation target the right asset groups
• Leverage defenseclaw doctor after any config change or integration update to catch connectivity issues before they affect live workflows
• Pin agent definitions to version numbers in CI/CD pipelines to prevent unexpected behavior from upstream agent registry updates
• Rotate Cisco client secrets every 90 days and update them in your secrets manager rather than directly in config.yaml
• Monitor agent resource usage with defenseclaw status — runaway correlation queries can exhaust API rate limits across connected platforms