____         ____                       ____  _
    / __ \  ___  / __/___   ___   ___  ___  / ___|| | __ _ __      __
   / / / / / _ \/ /_// _ \ / _ \ / __|/ _ \| |    | |/ _` |\ \ /\ / /
  / /_/ / /  __/ __//  __/| | | |\__ \  __/| |___ | | (_| | \ V  V /
 /_____/  \___/_/   \___/ |_| |_||___/\___| \____||_|\__,_|  \_/\_/

DefenseClaw combina una CLI de operador Python, un sidecar gateway Go y un plugin OpenClaw TypeScript. Juntos imponen una regla operativa simple: las capacidades de agente no confiables se escanean, gobiernan, registran y bloquean cuando la política dice que no son seguras.

Aspectos destacados

• Control de admisión: escanea skills, servidores MCP, plugins y código antes de ejecutarse.
• Barandillas de tiempo de ejecución: inspecciona prompts, completaciones y llamadas a herramientas con reglas regex, política, un juez LLM opcional e inspección de Cisco AI Defense.
• CodeGuard: verificaciones estáticas integradas para secretos, ejecución peligrosa, deserialización insegura, criptografía débil, patrones de inyección y acceso riesgoso a archivos.
• Soporte de sandbox OpenShell: configuración de sandbox Linux con controles de red, sistema de archivos, llamadas al sistema y política.
• Registros: ingesta de catálogos externos de skills / MCP (HTTPS YAML corporativo, smithery.ai, skills.sh, git, ClawHub) con protecciones SSRF, veredictos del escáner y promoción automática a política de activos. Ver docs/REGISTRIES.md.
• Auditoría y observabilidad: un gráfico config-v8 para recolección en buckets, historial SQLite obligatorio, redacción centralizada y destinos independientes JSONL, OTLP, Prometheus, Splunk HEC, Galileo, HTTP, consola y Grafana/Splunk locales.
• UX del operador: una CLI y TUI para configuración, comprobaciones de estado, alertas, listas de bloqueo/permiso, resultados del escáner y flujos de trabajo de política.

Alcance y limitaciones

DefenseClaw es una capa de aplicación y evidencia para despliegues de IA agentiva. Mejora la seguridad combinando resultados del escáner, inspección en tiempo de ejecución, decisiones de política, controles de sandbox y rastros de auditoría, pero no demuestra que un agente, skill, plugin o interacción con el modelo esté libre de riesgos.

Los despliegues de alto riesgo deben emparejar DefenseClaw con revisión humana, credenciales de mínimo privilegio, sandboxing, puertas de CI y monitoreo de producción. En modo observación, los hallazgos se registran sin bloquear. En modo acción, los hallazgos configurados como HIGH y CRITICAL pueden bloquear prompts, llamadas a herramientas o admisión de componentes.

Documentación

La documentación del proyecto en Markdown se centraliza en docs/. Los README locales de paquetes permanecen junto a bundles o ejemplos que necesitan contexto local.

Instalación

Prerrequisitos

Compilar desde la fuente (solo desarrolladores)

Elige el comando según la intención:

Los objetivos fuente y `scripts/install-dev.sh` son herramientas de desarrollo, no una ruta de actualización. Los objetivos de instalación directa se niegan a sobrescribir una instalación gestionada por una versión o una propiedad de otro checkout. `make all` es el flujo de trabajo explícito de reinstalación en la máquina de desarrollo: cuando el CLI instalado ya apunta exactamente al checkout actual, puede recuperar el estado fuente sin marcador o de versión anterior y registra un marcador de propiedad estricto después de la reconstrucción. Esto puede ejecutar las migraciones actuales del checkout contra el estado de desarrollo y no debe usarse como una actualización de versión. Las instalaciones gestionadas por versiones deben usar el resolutor `scripts/upgrade.sh` o `scripts/upgrade.ps1` propiedad de la versión. `make install`, `make dev-install` y `scripts/install-dev.sh` son tuberías estrictas de bajo nivel para un hogar de desarrollo nuevo o aislado; no son el comando normal de desarrollo repetido.

### Instalar con el script de lanzamiento```bash
VERSION=0.8.6
INSTALL_URL="https://raw.githubusercontent.com/cisco-ai-defense/defenseclaw/${VERSION}/scripts/install.sh"
curl -LsSf "$INSTALL_URL" | VERSION="$VERSION" bash
defenseclaw init --enable-guardrail

Para pasos específicos de la plataforma, consulta docs/INSTALL.md.

En Windows nativo x64, usa el Setup EXE nativo y la ruta del hook-only connector en la guía de Windows nativo. WSL no es compatible. Codex CLI y Claude Code son los únicos conectores Windows certificados.

Inicio Rápido```bash

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

Ejecute el guardrail en modo de observación mientras ajusta:```bash
defenseclaw setup guardrail --mode observe --restart

Cambiar al modo de acción cuando la política esté lista para bloquear:```bash defenseclaw setup guardrail --mode action --restart

Consulte [docs/QUICKSTART.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/QUICKSTART.md) para ver el tutorial completo.

---

## Arquitectura

| Componente | Runtime | Rol |
|-----------|---------|------|
| Python CLI | Python | Comandos del operador, orquestación del escáner, configuración, bundles locales |
| Gateway sidecar | Go | API REST, puente WebSocket, motor de políticas, proxy de protección, almacén de auditoría, telemetría |
| OpenClaw plugin | TypeScript | Intercepción de fetch, hooks de inspección de llamadas a herramientas, comandos de barra, integración con sidecar |
| Policies | YAML/Rego | Decisiones de admisión, acciones de protección, comportamiento de sandbox/firewall, perfiles de escáner |
| Documentation | Markdown/JSON | Documentación centralizada, READMEs locales de paquetes y configuración de DeepWiki |

El gateway expone APIs REST locales para la CLI y el plugin, se conecta a OpenClaw a través de WebSocket, inspecciona el tráfico de LLM a través de un proxy local y registra las decisiones en un almacén de auditoría duradero.```text
Agent runtime -> OpenClaw plugin -> DefenseClaw gateway -> policy + scanners + audit
                                    |
                                    +-> guardrail proxy -> LLM provider
                                    +-> OTLP / Splunk / webhooks / JSONL

Para diagramas y flujos detallados, lea docs/ARCHITECTURE.md.

Escaneo y Guardrails

DefenseClaw envuelve los escáneres de Cisco AI Defense y la política local en un único flujo de admisión:

Las políticas de escáner residen en policies/scanners/. Los paquetes de reglas de Guardrail residen en policies/guardrail/.

Observabilidad

DefenseClaw registra la aplicación y las evidencias de tiempo de ejecución a través de varios canales:

Config v8 mantiene la fuente concisa mientras compila omisiones en un plan efectivo completo:```yaml config_version: 8 observability: {}

Ese valor predeterminado recopila cada registro, traza y métrica registrados y conserva cada registro recopilado sin redactar en la SQLite local obligatoria. No se produce ninguna exportación remota hasta que se agrega un destino. Un destino habilitado sin `send` ni `routes` recibe cada bucket y cada señal que su tipo soporta, sin redactar: OTLP general obtiene logs/traces/métricas, Splunk HEC obtiene logs, Prometheus obtiene métricas, y el preset Galileo obtiene traces. Múltiples destinos reciben copias independientes.

Revise la política ampliada y los segmentos sin redactar con:```bash
defenseclaw config show --effective --section observability
defenseclaw observability plan

Utilice perfiles de redacción centralizados none, sensitive, content, strict o personalizados por campo, por bucket o destino. Los valores predeterminados de fidelidad completa pueden incluir prompts, salidas, argumentos/resultados de herramientas, evidencia, rutas e identificadores, por lo tanto, configure un perfil de redacción antes de exportar a través de un límite de confianza que no deba recibir ese contenido.

Edite la política de bucket y redacción en el archivo fuente, valídelo antes de que la puerta de enlace lo vea, e inspeccione el resultado compilado en lugar de copiar la referencia generada directamente:

``````bash
umask 077
cp "$HOME/.defenseclaw/config.yaml" \
  "$HOME/.defenseclaw/config.yaml.before-observability-edit"
${EDITOR:-vi} "$HOME/.defenseclaw/config.yaml"

defenseclaw config validate && \
defenseclaw config show --effective --section observability && \
defenseclaw observability plan && \
defenseclaw-gateway restart && \
defenseclaw doctor

No reiniciar después de un fallo de validación. Restaurar la copia de seguridad privada, corregir la fuente y validar de nuevo. Un perfil de redacción global o de bucket también se aplica a la proyección local de SQLite generada. Para mantener un historial local de fidelidad completa mientras se redacta solo un límite de confianza remoto, deje el perfil global/bucket en none y configure send.redaction_profile o un perfil de ruta en ese destino remoto.

Iniciar observabilidad local con:

``````bash
defenseclaw setup local-observability up
defenseclaw-gateway start
defenseclaw setup local-observability status

El vacío del tablero no es un solo estado: 0 significa que la señal instrumentada tuvo cero eventos coincidentes, No data significa que no existe ninguna serie/registro/traza coincidente para el rango y filtros seleccionados, y Not reported significa que el conector/proveedor no proporcionó un valor opcional como tokens o costos. Se espera que los paneles condicionales como HITL, vistas solo de fallos y una cascada de trazas antes de que se seleccione un ID de traza muestren No data. Una prueba de destino verifica solo la conectividad y no crea tráfico de tablero ordinario; genere un turno real de agente fresco, llamada de herramienta, escaneo o aprobación para validar los paneles correspondientes.

El gráfico de nodos de Agent360 es un DAG respaldado por Loki: la creación de sesión es un anclaje separado, un nodo Prompt inputs por raíz cuenta hechos distintos de model.request de profundidad cero en el rango, y la delegación de padre a hijo alimenta resúmenes por agente de modelo, herramienta, aprobación, actualización, resultado de turno y terminal. Prompt inputs desduplica por turno, model-request, request, operación, luego ID de ocurrencia; las vistas ordenadas/crudas retienen los registros iniciales y de seguimiento individuales. Los anclajes de sesión y spawn pueden recuperarse de las 24 horas anteriores para que las ventanas de límite sigan siendo renderizables; un spawn recuperado se mantiene solo cuando ese hijo tiene actividad elegible para el gráfico en el rango seleccionado. Las llamadas repetidas al modelo se agrupan por agente propietario, proveedor y modelo. Las llamadas repetidas a herramientas se agrupan por agente propietario en Bash, MCP, Skills, Collaboration, File edits, Web/browser, Visual o Task control; una herramienta no reconocida conserva su nombre reportado. Las solicitudes exactas collaboration.send_message se excluyen de la familia genérica Collaboration para que aparezcan solo como grupos de mensajes; otras herramientas de colaboración permanecen en esa familia. Los registros de solicitud se incluyen incluso cuando no llegó una contraparte terminal. Su total agrupado es un conteo de solicitudes, no una afirmación de que cada solicitud sigue pendiente; el estado terminal permanece disponible en los registros crudos enlazados. La profundidad 0 es la raíz y los hijos recursivos pueden reportarse hasta la profundidad 64; el detalle al hacer clic identifica si cada borde de linaje fue reportado por el conector o inferido por DefenseClaw. Los clics en nodos exponen conteos exactos e identidad estable de agente/raíz/padre, con enlaces filtrados a los eventos OTEL crudos detrás de cada grupo. Los campos opcionales de sesión actual/raíz/padre permanecen en las superficies de ciclo de vida, sesión, ordenadas y crudas; no son claves de agrupación de nodos de agente, por lo que los metadatos de sesión faltantes o tardíos no pueden dividir el total de un agente.

Los paneles no redactan, enmascaran ni ocultan campos nuevamente. DefenseClaw aplica redacción centralizada v8 antes de la exportación canónica de OTEL; Grafana muestra o enlaza cada campo realmente presente en esa proyección, incluido el contenido cuando el productor lo exportó. Un campo eliminado o transformado antes de la exportación no puede ser recuperado por la pila local. Los bordes de actualización provienen solo de registros reales de la herramienta collaboration.send_message. Para cada remitente, los objetivos /root y /root/* se colapsan en un nodo Messages to root cuyo ID de agente destino se resuelve a la raíz exportada. Las rutas y llamadas de tarea raíz exactas permanecen en los desgloses ordenados/crudos. Los objetivos no raíz se mantienen explícitamente agrupados por ruta de tarea exacta y no se inventan como uniones opacas de ID de agente cuando el conector no reportó ese mapeo. Los eventos de compatibilidad genérica nunca se etiquetan como actualizaciones.

Los destinos opcionales tienen colas acotadas independientes. Los valores predeterminados son 2,048 registros y 64 MiB por cola; los lotes de push predeterminados son 512 registros, 8 MiB y 5 segundos (1 segundo para el retraso preestablecido omitido de Galileo). El desbordamiento de la cola elimina el intento de encolado más nuevo sin desalojar trabajo FIFO más antiguo ni afectar a los destinos obligatorios SQLite y hermanos. Los campos, límites y diferencias de adaptador exactos están en docs/OBSERVABILITY.md.

Agregue Galileo Cloud o Galileo auto-alojado sin reemplazar la ruta local:```bash export GALILEO_API_KEY='...' defenseclaw setup galileo --project defenseclaw --logstream production defenseclaw setup galileo test

Consulte [docs/OBSERVABILITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/OBSERVABILITY.md), la
[guía de Galileo](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs-site/content/docs/observability/galileo.mdx) y el
[mapa de propiedad de esquemas](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/schemas/README.md). La configuración específica de Splunk está en
[docs/SPLUNK_APP.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/SPLUNK_APP.md).

Toda instalación POSIX existente compatible, incluyendo una que ya esté en `0.8.4`,
cruza el corte duro `0.8.5` con el activo de versión objetivo autenticado
`defenseclaw-upgrade.sh` en modo latest, sin una anulación de versión. El
analizador incorporado inmutable `0.8.4` no puede aceptar el manifiesto objetivo veraz
cuya matriz de puente de Windows está vacía. No ejecute ninguna sugerencia de red
sin formato obsoleta impresa por una CLI incorporada congelada. El solucionador
propiedad de la versión realiza `source → 0.8.4 bridge → fresh 0.8.4 controller → 0.8.5 hard cut` como una
transacción. La migración
hace una copia de seguridad y convierte atómicamente la configuración, conserva el
comportamiento de enrutamiento/redacción más estricto y la compatibilidad con root/subagente Agent360,
actualiza los paneles locales propietarios sin restablecer volúmenes, y nunca requiere
un comando apply separado. Consulte [CLI Reference — upgrade](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CLI.md#upgrade) para el
bootstrap del solucionador autenticado.

Para Splunk Observability Cloud, use el paquete de paneles en
[bundles/splunk_o11y_dashboards/README.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/bundles/splunk_o11y_dashboards/README.md):```bash
defenseclaw setup splunk dashboards apply \
  --api-url <api-endpoint> \
  --o11y-api-token <api-access-token> \
  --with-detectors \
  --enable-detectors \
  --yes

Desarrollo```bash

Build all components

make build

Run primary test suites

make test

Run lint checks

make lint

La guía de pruebas y desarrollo se encuentra en [docs/TESTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/TESTING.md) y [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md).

---

## Cómo contribuir

Las contribuciones son bienvenidas. Comience con [CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/CONTRIBUTING.md), [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md) y la documentación específica del área que desee modificar.

## Seguridad

Informe las vulnerabilidades a través del proceso descrito en [SECURITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/SECURITY.md).

## Licencia

Apache 2.0 - consulte [LICENSE](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/LICENSE).

Copyright 2026 Cisco Systems, Inc. y sus afiliados.