🦞 ClawGuard v3

Kit de Segurança para Agentes de IA Empresariais - Defesa Ativa Orientada por SKILL.md

Conceito Central

A defesa central do ClawGuard v3 não está no código, mas no SKILL.md!

O SKILL.md de cada módulo é, por si só, um guia de defesa completo:

• Diz ao Agente quando acionar
• Orienta o Agente como detectar
• Fornece padrões e regras de detecção específicos
• Define formato de saída e critérios de decisão

Os scripts de código são apenas ferramentas auxiliares; a inteligência real está no SKILL.md.

---

🎯 Cinco Módulos de Segurança

Módulo	Posição	Linhas do SKILL.md	Recursos Principais
Auditor	Auditoria Pré-voo	679 linhas	Detecção de Desvio de Intenção, Varredura de Código SKILL.md
Checker	Verificação Estática	476 linhas	Endurecimento de Configuração, Correção com Um Clique
Detect	Monitor de Execução	615 linhas	Detecção de Ameaças, Integração com Guardian
Guardian	Controle de Execução	451 linhas	Monitoramento de Comportamento, Congelamento/Reprodução de Sessão
Shield	Defesa Ativa	493 linhas	Injeção de Prompt, Detecção de Largura Zero

Documentação Total: 2.714 linhas (v2 tem 2.226 linhas com apenas 3 módulos)

---

📂 Estrutura do Módulo

Cada módulo contém:

auditor-skill/
├── SKILL.md      ← Guia de defesa central (mais importante!)
├── _meta.json    ← Metadados
├── cli.js        ← Ferramenta CLI auxiliar
└── src/          ← Módulos de código auxiliares

Conteúdo Central do SKILL.md

Cada SKILL.md inclui:

1. Quando Acionar - Quando o Agente deve usar este módulo
2. Como Executar - Etapas de detecção e fluxos de trabalho detalhados
3. Biblioteca de Padrões de Detecção - Regras específicas de regex e correspondência de padrões
4. Critérios de Decisão - Como gerar resultados e níveis de risco
5. Exemplos - Casos de uso reais

---

🚀 Início Rápido

Uso via Agente (Recomendado)

Diga ao Agente o que fazer, e ele lerá o SKILL.md e executará:

Usuário: Ajude-me a auditar esta skill: /workspace/skills/weather-tool
        ↓
O Agente lê auditor-skill/SKILL.md
        ↓
O Agente executa a auditoria de acordo com as diretrizes do SKILL.md
        ↓
Gera os resultados da auditoria

Uso via CLI

# Auditar Skill
cd auditor-skill && node cli.js /path/to/skill

# Verificar Configuração
cd checker-skill && node cli.js ~/.openclaw/openclaw.json

# Detectar Ameaças
cd detect-skill && node cli.js --monitor

# Guardian de Execução
cd guardian-skill && node cli.js start

# Detectar Injeção
cd shield-skill && node cli.js defend "test text"

---

📋 Detalhes dos Módulos

Auditor - Auditoria Pré-voo (679 linhas)

Cenários de Acionamento: Antes de instalar uma nova Skill

Recursos Principais do SKILL.md:

• Detecção de risco de execução de comandos (100+ padrões)
• Detecção de risco de acesso a arquivos
• Detecção de risco de requisições de rede
• Detecção de Desvio de Intenção (novo na v3)
• Varredura de Blocos de Código SKILL.md (novo na v3)
• Análise de segurança da cadeia de suprimentos
• Mapeamento MITRE ATT&CK

Saída de Decisão:

🟢 Seguro → Pode instalar
🟡 Requer Revisão → Pode instalar após confirmação
🔴 Alto Risco → Não recomendado instalar

Checker - Verificação de Configuração (476 linhas)

Cenários de Acionamento: Verificar a segurança da configuração

Recursos Principais do SKILL.md:

• Verificação de configuração do gateway
• Verificação de configuração de execução de ferramentas
• Verificação de configuração do sandbox
• Verificação de segurança de rede
• Recomendações de Endurecimento (novo na v3)
• Correção com Um Clique (novo na v3)

Saída de Decisão:

⚠️ Problemas encontrados + Recomendações de correção específicas + Endurecimento com um clique

Detect - Detecção de Ameaças (615 linhas)

Cenários de Acionamento: Monitoramento em tempo real e varredura de ameaças

Recursos Principais do SKILL.md:

• Detecção de ameaças de execução de comandos
• Detecção de ameaças de operações com arquivos
• Detecção de ameaças de rede
• Detecção de injeção de prompt
• Análise de correlação de cadeia de ataques
• Integração com Guardian (novo na v3)

Saída de Decisão:

🔴 CRÍTICO → Ação imediata necessária
🟠 ALTO → Solicitar confirmação
🟡 MÉDIO → Registrar e alertar

Guardian - Guardião de Execução (451 linhas)

Cenários de Acionamento: Quando o monitoramento de comportamento é necessário

Recursos Principais do SKILL.md:

• Monitoramento de comportamento em tempo real
• Interceptação de operações de risco
• Reprodução de auditoria de sessão
• Congelamento de Emergência (novo na v3)
• Preservação de Evidências (novo na v3)
• Mecanismo de Regras (novo na v3)

Regras Principais:

Negar: /etc/*, /root/*, /.ssh/*
Confirmar: rm -rf, chmod 777, killall
Registrar: Todas as operações

Shield - Escudo Ativo (493 linhas)

Cenários de Acionamento: Verificar a segurança da entrada do usuário

Recursos Principais do SKILL.md:

• Detecção de Injeção Codificada em Base64 (novo na v3)
• Detecção de Codificação Hex/Unicode (novo na v3)
• Detecção de Caracteres de Largura Zero (novo na v3)
• Detecção de sequestro de função
• Detecção de ataques de jailbreak
• Detecção de Sequestro de Cadeia de Instruções (novo na v3)
• Validação de Intenção (novo na v3)

Fluxo de Trabalho de Detecção:

Codificação → Sequestro → Jailbreak → Sequestro de Cadeia → Desvio de Intenção

---

🔍 Detecção de Desvio de Intenção (Recurso Central da v3)

O que é Desvio de Intenção?

A funcionalidade declarada da Skill vs. o comportamento real não correspondem:

Declarado	Real	Decisão
"Ferramenta de Clima"	Lê chaves SSH	🔴 Desvio grave
"Organizador de Arquivos"	Inicia processo de backdoor	🔴 Desvio grave
"Assistente de Tradução"	Exfiltra documentos do usuário	🔴 Desvio grave

Método de Detecção

1. Extrair a funcionalidade declarada do SKILL.md
2. Analisar o comportamento real no código
3. Comparar para verificar correspondência
4. Sinalizar como alto risco se houver incompatibilidade

---

📁 Estrutura do Projeto

ClawGuardv3/
├── auditor-skill/           # Auditoria pré-voo (679 linhas SKILL.md)
│   ├── SKILL.md          # ⭐ Guia de defesa central
│   ├── _meta.json
│   ├── cli.js
│   └── src/
│       ├── auditor.js
│       ├── sast-analyzer.js
│       ├── intent-drift-detector.js
│       └── supply-chain-analyzer.js
├── checker-skill/           # Verificação de configuração (476 linhas SKILL.md)
│   ├── SKILL.md          # ⭐ Guia de defesa central
│   ├── _meta.json
│   ├── cli.js
│   └── src/
│       └── checker.js
├── detect-skill/            # Detecção de ameaças (615 linhas SKILL.md)
│   ├── SKILL.md          # ⭐ Guia de defesa central
│   ├── _meta.json
│   ├── cli.js
│   └── src/
│       └── detector.js
├── guardian-skill/           # Guardião de execução (451 linhas SKILL.md)
│   ├── SKILL.md          # ⭐ Guia de defesa central
│   ├── _meta.json
│   ├── cli.js
│   └── src/
│       └── guardian.js
├── shield-skill/            # Escudo ativo (493 linhas SKILL.md)
│   ├── SKILL.md          # ⭐ Guia de defesa central
│   ├── _meta.json
│   ├── cli.js
│   └── src/
│       └── shield.js
└── shared/
    └── rules/
        └── interceptor-rules.js

---

🆚 Comparação v2 vs v3