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

O DefenseClaw combina um CLI operador Python, um sidecar gateway Go e um plugin TypeScript OpenClaw. Juntos, eles impõem uma regra operacional simples: capacidades de agente não confiáveis são escaneadas, governadas, registradas e bloqueadas quando a política as considera inseguras.

Destaques

• Controle de admissão - escaneie skills, servidores MCP, plugins e código antes de executarem.
• Barreiras de proteção em tempo de execução - inspecione prompts, complementos e chamadas de ferramenta com regras regex, política, juiz LLM opcional e inspeção do Cisco AI Defense.
• CodeGuard - verificações estáticas internas para segredos, execução perigosa, desserialização insegura, criptografia fraca, padrões de injeção e acesso a arquivos arriscado.
• Suporte a sandbox OpenShell - configuração de sandbox Linux com rede, sistema de arquivos, chamadas de sistema e controles de política.
• Registros - ingestão de catálogos externos de skills / MCP (YAML HTTPS corporativo, smithery.ai, skills.sh, git, ClawHub) com proteções SSRF, vereditos baseados em scanner e promoção automática para política de ativos. Veja docs/REGISTRIES.md.
• Auditoria e observabilidade - um gráfico v8 de configuração para coleta de buckets, histórico SQLite obrigatório, redação centralizada e destinos independentes JSONL, OTLP, Prometheus, Splunk HEC, Galileo, HTTP, console e Grafana/Splunk local.
• UX do operador - um CLI e TUI para configuração, verificações de saúde, alertas, listas de bloqueio/permissão, resultados de scanner e fluxos de política.

Escopo e Limitações

O DefenseClaw é uma camada de aplicação e evidência para implantações de IA agêntica. Ele melhora a segurança combinando resultados de scanner, inspeção em tempo de execução, decisões de política, controles de sandbox e trilhas de auditoria, mas não prova que um agente, skill, plugin ou interação com modelo está livre de riscos.

Implantações de alto risco devem emparelhar o DefenseClaw com revisão humana, credenciais de privilégio mínimo, sandbox, barreiras de CI e monitoramento de produção. No modo de observação, os achados são registrados sem bloqueio. No modo de ação, os achados configurados como ALTO e CRÍTICO podem bloquear prompts, chamadas de ferramenta ou admissão de componentes.

Documentação

A documentação em Markdown do projeto está centralizada em docs/. READMEs locais de pacotes permanecem junto aos bundles ou exemplos que precisam de contexto local.

Instalação

Pré-requisitos

Compilar a partir da fonte (apenas desenvolvedores)

Escolha o comando por objetivo:

Os alvos de origem e `scripts/install-dev.sh` são ferramentas de desenvolvimento, não um
caminho de atualização. Alvos de instalação direta recusam-se a sobrescrever uma instalação
gerenciada por release ou uma pertencente a outro checkout. `make all` é o fluxo de trabalho
explícito de reinstalação em máquina de desenvolvimento: quando a CLI instalada já aponta
exatamente para o checkout atual, ela pode recuperar o estado de origem sem marcador ou de
release anterior e grava um marcador de propriedade estrito após a reconstrução. Isso pode
executar as migrações atuais do checkout contra o estado de desenvolvedor e não deve ser
usado como uma atualização de release. Instalações gerenciadas por release devem usar o
resolvedor `scripts/upgrade.sh` ou `scripts/upgrade.ps1` de propriedade da release.
`make install`, `make dev-install` e `scripts/install-dev.sh` são encanamentos estritos de
nível inferior para um ambiente de desenvolvimento novo ou isolado; eles não são o comando
normal de desenvolvimento repetido.

### Instalar com o script de release```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 etapas específicas da plataforma, consulte docs/INSTALL.md.

No Windows nativo x64, use o EXE de instalação nativa e o caminho do conector hook-only no Guia do Windows nativo. WSL não é suportado. Codex CLI e Claude Code são os únicos conectores Windows certificados.

Início 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

Execute o guardrail em modo de observação durante o ajuste:```bash
defenseclaw setup guardrail --mode observe --restart

Mude para o modo de ação quando a política estiver pronta 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 o passo a passo completo.

---

## Arquitetura

| Componente | Ambiente de Execução | Função |
|-----------|---------|------|
| CLI Python | Python | Comandos do operador, orquestração de scanner, configuração, bundles locais |
| Sidecar do Gateway | Go | API REST, ponte WebSocket, motor de políticas, proxy de proteção, armazenamento de auditoria, telemetria |
| Plugin OpenClaw | TypeScript | Intercepção de fetch, hooks de inspeção de chamadas de ferramentas, comandos de barra, integração com sidecar |
| Políticas | YAML/Rego | Decisões de admissão, ações de proteção, comportamento de sandbox/firewall, perfis de scanner |
| Documentação | Markdown/JSON | Documentação centralizada, READMEs locais de pacotes e configuração do DeepWiki |

O gateway expõe APIs REST locais para a CLI e o plugin, conecta-se ao OpenClaw via WebSocket, inspeciona o tráfego de LLM através de um proxy local e registra decisões em um armazenamento de auditoria durável.```text
Agent runtime -> OpenClaw plugin -> DefenseClaw gateway -> policy + scanners + audit
                                    |
                                    +-> guardrail proxy -> LLM provider
                                    +-> OTLP / Splunk / webhooks / JSONL

Para diagramas e fluxos detalhados, leia docs/ARCHITECTURE.md.

Varredura e Guardrails

O DefenseClaw envolve os scanners do Cisco AI Defense e a política local em um único fluxo de admissão:

As políticas de scanner estão em policies/scanners/. Os pacotes de regras de guardrail estão em policies/guardrail/.

Observabilidade

O DefenseClaw registra evidências de aplicação e tempo de execução em vários canais:

O Config v8 mantém a fonte concisa enquanto compila omissões em um plano efetivo completo:```yaml config_version: 8 observability: {}

Essa configuração padrão coleta todos os logs, traces e métricas registados e retém cada
log coletado não redigido no SQLite local obrigatório. Nenhuma exportação remota ocorre até
que um destino seja adicionado. Um destino ativado sem `send` ou `routes` recebe
cada bucket e cada sinal que seu tipo suporta, não redigido: OTLP geral recebe
logs/traces/métricas, Splunk HEC recebe logs, Prometheus recebe métricas, e o preset
Galileo recebe traces. Vários destinos recebem cópias independentes.

Revise a política expandida e as partes não redigidas com:```bash
defenseclaw config show --effective --section observability
defenseclaw observability plan

Use perfis centralizados de none, sensitive, content, strict ou perfis personalizados com reconhecimento de campos por bucket ou destino. Os padrões de fidelidade total podem incluir prompts, saídas, argumentos/resultados de ferramentas, evidências, caminhos e identificadores. Portanto, configure um perfil de redação antes de exportar através de um limite de confiança que não deve receber esse conteúdo.

Edite a política de bucket e redação no arquivo de origem, valide-a antes que o gateway a veja, e inspecione o resultado compilado em vez de copiar a referência gerada na íntegra:```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

Não reinicie após uma falha de validação. Restaure o backup privado, corrija a fonte e valide novamente. Um perfil de redação global ou de bucket também se aplica à projeção local SQLite gerada. Para manter o histórico local com total fidelidade enquanto redige apenas um limite de confiança remoto, deixe o perfil global/de bucket como `none` e defina `send.redaction_profile` ou um perfil de rota nesse destino remoto.

Inicie a observabilidade local com:```bash
defenseclaw setup local-observability up
defenseclaw-gateway start
defenseclaw setup local-observability status

A ausência de dados no dashboard não é um estado único: 0 significa que o sinal instrumentado teve zero eventos correspondentes, Sem dados significa que não existe série/log/traço correspondente para o intervalo e filtros selecionados, e Não relatado significa que o conector/provedor não forneceu um valor opcional como tokens ou custo. Painéis condicionais como HITL, visualizações apenas de falhas e uma cascata de traço antes de um ID de Traço ser selecionado devem mostrar Sem dados. Um teste de destino verifica apenas a conectividade e não cria tráfego comum de dashboard; gere uma nova rodada de agente real, chamada de ferramenta, varredura ou aprovação para validar os painéis correspondentes.

O gráfico de nós do Agent360 é um DAG de ciclo de vida apoiado pelo Loki: a criação de sessão é uma âncora separada, um nó Entradas de Prompt por raiz conta fatos distintos model.request de profundidade zero no intervalo, e a delegação pai-para-filho alimenta resumos por agente de modelo, ferramenta, aprovação, atualização, resultado de turno e terminal. As entradas de prompt deduplicam por turno, solicitação-modelo, solicitação, operação e depois ID de ocorrência; as visões ordenadas/brutas mantêm os registros iniciais e de acompanhamento individuais. Âncoras de sessão e spawn podem ser recuperadas das últimas 24 horas para que as janelas de limite permaneçam renderizáveis; um spawn recuperado é mantido apenas quando aquele filho tem atividade elegível para gráfico no intervalo selecionado. Chamadas de modelo repetidas são agrupadas por agente proprietário, provedor e modelo. Chamadas de ferramenta repetidas são agrupadas por agente proprietário em Controle de Bash, MCP, Habilidades, Colaboração, Edições de Arquivo, Web/navegador, Visual ou Tarefa; uma ferramenta não reconhecida mantém seu nome relatado. Solicitações exatas collaboration.send_message são excluídas da família genérica de Colaboração para que apareçam apenas como grupos de mensagem; outras ferramentas de colaboração permanecem nessa família. Os registros de solicitação são incluídos mesmo quando nenhuma contraparte terminal chegou. Seu total agrupado é uma contagem de solicitações, não uma afirmação de que cada solicitação ainda está pendente; o status terminal permanece disponível nos registros brutos vinculados. Profundidade 0 é a raiz e filhos recursivos podem ser relatados até profundidade 64; o detalhe do clique identifica se cada aresta de linhagem foi relatada pelo conector ou inferida pela DefenseClaw. Os cliques nos nós expõem contagens exatas e identidade estável de agente/raiz/pai, com links filtrados para os eventos OTEL brutos por trás de cada grupo. Campos opcionais de sessão atual/raiz/pai permanecem nas superfícies de ciclo de vida, sessão, ordenada e bruta; não são chaves de agrupamento de nó de agente, então metadados de sessão ausentes ou atrasados não podem dividir o total de um agente.

Os dashboards não redigem, mascaram ou ocultam campos novamente. DefenseClaw aplica redação v8 centralizada antes da exportação canônica OTEL; Grafana mostra ou vincula cada campo realmente presente nessa projeção, incluindo conteúdo quando o produtor o exportou. Um campo removido ou transformado antes da exportação não pode ser recuperado pela pilha local. As arestas de atualização vêm apenas de registros reais da ferramenta collaboration.send_message. Para cada remetente, os destinos /root e /root/* colapsam em um nó Mensagens para a raiz cujo ID de agente de destino resolve para a raiz exportada. Caminhos e chamadas de tarefa raiz exatos permanecem nos detalhamentos ordenados/brutos. Destinos não-raiz permanecem explicitamente agrupados por caminho de tarefa exato e não são inventados como junções de ID de agente opaco quando o conector não relatou esse mapeamento. Eventos de compatibilidade genérica nunca são rotulados como atualizações.

Destinos opcionais possuem filas limitadas independentes. Os padrões são 2.048 registros e 64 MiB por fila; lotes de envio padrão são 512 registros, 8 MiB e 5 segundos (1 segundo para o atraso predefinido do Galileo omitido). Estouro de fila descarta a tentativa de enfileiramento mais recente sem remover trabalho FIFO mais antigo ou afetar destinos obrigatórios SQLite e irmãos. Campos exatos, limites e diferenças de adaptador estão em docs/OBSERVABILITY.md.

Adicione Galileo Cloud ou Galileo auto-hospedado sem substituir a rota local:```bash export GALILEO_API_KEY='...' defenseclaw setup galileo --project defenseclaw --logstream production defenseclaw setup galileo test

Veja [docs/OBSERVABILITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/OBSERVABILITY.md), o [guia Galileo](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs-site/content/docs/observability/galileo.mdx) e o [mapa de propriedade do esquema](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/schemas/README.md). A configuração específica do Splunk está em [docs/SPLUNK_APP.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/SPLUNK_APP.md).

Toda instalação POSIX existente suportada, incluindo uma já na `0.8.4`, atravessa o corte duro `0.8.5` com o ativo autenticado `defenseclaw-upgrade.sh` da versão-alvo no modo mais recente, sem uma sobreposição de versão. O analisador embutido imutável `0.8.4` não pode aceitar o manifesto alvo verdadeiro cuja matriz de ponte do Windows está vazia. Não execute nenhuma dica obsoleta de rede bruta impressa por uma CLI embutida congelada. O resolvedor de propriedade da versão executa `source → 0.8.4 bridge → fresh 0.8.4 controller → 0.8.5 hard cut` como uma única transação. A migração faz backup e converte atomicamente a configuração, preserva o comportamento estreito de roteamento/ocultação e a compatibilidade root/subagent Agent360, atualiza os painéis locais próprios sem redefinir volumes e nunca requer um comando apply separado. Veja [Referência da CLI — upgrade](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CLI.md#upgrade) para a inicialização do resolvedor autenticado.

Para Splunk Observability Cloud, use o pacote de painéis em [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

Desenvolvimento```bash

Build all components

make build

Run primary test suites

make test

Run lint checks

make lint

Orientações focadas para teste e desenvolvimento estão em [docs/TESTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/TESTING.md) e [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md).

---

## Contribuindo

Contribuições são bem-vindas. Comece com [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), e as documentações focadas para a área que você está alterando.

## Segurança

Por favor, reporte vulnerabilidades através do processo em [SECURITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/SECURITY.md).

## Licença

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

Copyright 2026 Cisco Systems, Inc. e suas afiliadas.