GitHub - cisco-ai-defense/defenseclaw: Security Governance for Agentic AI

6 min read Original article ↗ 
     ____         ____                       ____  _
    / __ \  ___  / __/___   ___   ___  ___  / ___|| | __ _ __      __
   / / / / / _ \/ /_// _ \ / _ \ / __|/ _ \| |    | |/ _` |\ \ /\ / /
  / /_/ / /  __/ __//  __/| | | |\__ \  __/| |___ | | (_| | \ V  V /
 /_____/  \___/_/   \___/ |_| |_||___/\___| \____||_|\__,_|  \_/\_/

Security governance for OpenClaw and agentic AI runtimes.
Scan capabilities before use, inspect runtime traffic, and export durable audit evidence.

License: Apache 2.0 Python 3.10+ Go 1.26.2 CI Discord: Join us

Cisco AI Defense AI Security Framework Ask DeepWiki

Govern Inspect Prove
Skills, MCP servers, plugins, and generated code before they run Prompts, completions, tool calls, and sandbox activity at runtime SQLite audit history, JSONL, OTLP, Splunk, webhooks, and TUI views

DefenseClaw combines a Python operator CLI, a Go gateway sidecar, and an OpenClaw TypeScript plugin. Together they enforce a simple operating rule: untrusted agent capabilities are scanned, governed, logged, and blocked when policy says they are unsafe.

Highlights

  • Admission control - scan skills, MCP servers, plugins, and code before they run.
  • Runtime guardrails - inspect prompts, completions, and tool calls with regex rules, policy, optional LLM judge, and Cisco AI Defense inspection.
  • CodeGuard - built-in static checks for secrets, dangerous execution, unsafe deserialization, weak crypto, injection patterns, and risky file access.
  • OpenShell sandbox support - Linux sandbox setup with network, filesystem, syscall, and policy controls.
  • Audit and observability - SQLite audit store, JSONL gateway logs, OTLP export, Splunk HEC, webhooks, and local Grafana/Splunk bundles.
  • Operator UX - a CLI and TUI for setup, health checks, alerts, block/allow lists, scanner results, and policy workflows.

Scope and Limitations

DefenseClaw is an enforcement and evidence layer for agentic AI deployments. It improves safety by combining scanner results, runtime inspection, policy decisions, sandbox controls, and audit trails, but it does not prove that an agent, skill, plugin, or model interaction is risk-free.

High-risk deployments should pair DefenseClaw with human review, least-privilege credentials, sandboxing, CI gates, and production monitoring. In observe mode, findings are logged without blocking. In action mode, configured HIGH and CRITICAL findings can block prompts, tool calls, or component admission.

Documentation

Guide Description
Quick Start First successful local setup and scan flow
Install macOS, Linux, DGX Spark, source builds, and release installation
CLI Reference Python CLI commands and operator workflows
API Reference Gateway REST API and sidecar endpoints
Architecture Component model, data flow, and responsibilities
Guardrail LLM and tool inspection architecture
Guardrail Rule Packs Rule packs, suppressions, and tuning
Sandbox OpenShell sandbox setup, architecture, monitoring, and debugging
Observability Audit sinks, OTLP, Splunk, Grafana, and webhook notifications
Splunk App Local Splunk app dashboards and investigation flow
TUI Terminal dashboard panels and navigation
Config Files Config locations, environment variables, and policy files
Plugin Development Custom scanner plugin workflow and example
Testing Python, Go, TypeScript, Rego, docs, and CI checks
Developer Spec Historical product/developer spec
Gateway Spec Internal gateway package specification

Project Markdown documentation is centralized under docs/. Package-local READMEs stay beside bundles or examples that need local context.

Installation

Prerequisites

Requirement Version
Python 3.10+
Go 1.26.2+
Node.js 18+ for the OpenClaw plugin
uv Recommended for Python installs
Docker Optional, for local observability and Splunk bundles

Install from source

git clone https://github.com/cisco-ai-defense/defenseclaw.git
cd defenseclaw
make all

Install with the release script

curl -LsSf https://raw.githubusercontent.com/cisco-ai-defense/defenseclaw/main/scripts/install.sh | bash
defenseclaw init --enable-guardrail

For platform-specific steps, see docs/INSTALL.md.

Quick Start

# Check the local install and dependencies
defenseclaw doctor

# Initialize config, scanner defaults, and guardrail plumbing
defenseclaw init --enable-guardrail

# Scan installed agent capabilities
defenseclaw skill scan all
defenseclaw mcp list
defenseclaw plugin scan extensions/defenseclaw

# Start the Go gateway sidecar
defenseclaw-gateway start

# Open the operator dashboard
defenseclaw tui

Run the guardrail in observe mode while tuning:

defenseclaw setup guardrail --mode observe --restart

Switch to action mode when the policy is ready to block:

defenseclaw setup guardrail --mode action --restart

See docs/QUICKSTART.md for the full walkthrough.

Architecture

Component Runtime Role
Python CLI Python Operator commands, scanner orchestration, config setup, local bundles
Gateway sidecar Go REST API, WebSocket bridge, policy engine, guardrail proxy, audit store, telemetry
OpenClaw plugin TypeScript Fetch interception, tool-call inspection hooks, slash commands, sidecar integration
Policies YAML/Rego Admission decisions, guardrail actions, sandbox/firewall behavior, scanner profiles
Documentation Markdown/JSON Centralized docs, package-local READMEs, and DeepWiki configuration

The gateway exposes local REST APIs for the CLI and plugin, connects to OpenClaw over WebSocket, inspects LLM traffic through a local proxy, and records decisions in a durable audit store.

Agent runtime -> OpenClaw plugin -> DefenseClaw gateway -> policy + scanners + audit
                                    |
                                    +-> guardrail proxy -> LLM provider
                                    +-> OTLP / Splunk / webhooks / JSONL

For diagrams and detailed flows, read docs/ARCHITECTURE.md.

Scanning and Guardrails

DefenseClaw wraps Cisco AI Defense scanners and local policy into a single admission flow:

Surface Scanner or control
Skills cisco-ai-skill-scanner, CodeGuard, policy actions
MCP servers cisco-ai-mcp-scanner, block/allow policy
Plugins DefenseClaw plugin scanner, install-source checks, optional LLM analysis
Source code CodeGuard via CLI, sidecar API, and plugin write/edit hooks
Prompts and completions Guardrail proxy with rule packs, suppressions, optional LLM judge, Cisco inspection
Tool calls Tool argument inspection, sensitive path checks, command risk checks, policy verdicts

Scanner policies live in policies/scanners/. Guardrail rule packs live in policies/guardrail/.

Observability

DefenseClaw records enforcement and runtime evidence across several channels:

Channel Use
SQLite audit store Local durable event history
Gateway JSONL Correlated structured runtime events
OTLP Metrics, logs, and traces to compatible collectors
Splunk HEC SIEM forwarding and local Splunk app workflows
Webhooks Slack, PagerDuty, Webex, and generic event notifications
TUI Operator-facing alerts, health, scans, tools, policy, and setup

Start local observability with:

defenseclaw setup local-observability up
defenseclaw gateway
defenseclaw setup local-observability status

See docs/OBSERVABILITY.md and docs/SPLUNK_APP.md.

Development

# Build all components
make build

# Run primary test suites
make test

# Run lint checks
make lint

Focused test and development guidance lives in docs/TESTING.md and docs/CONTRIBUTING.md.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, docs/CONTRIBUTING.md, and the focused docs for the area you are changing.

Security

Please report vulnerabilities through the process in SECURITY.md.

License

Apache 2.0 - see LICENSE.

Copyright 2026 Cisco Systems, Inc. and its affiliates.