ClawShield

Proxy de segurança para agentes de IA. Fica na frente do OpenClaw e examina cada mensagem em busca de injeção de prompt, vazamento de PII e segredos — antes que cheguem ao modelo ou saiam da rede.

Acompanha 5 agentes de IA especializados, um painel integrado e um mecanismo de políticas YAML. Um comando para começar.

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│   Browser    │────▶│  ClawShield      │────▶│   OpenClaw   │
│   (you)      │◀────│  Security Proxy  │◀────│   Gateway    │
└──────────────┘     └──────────────────┘     └──────────────┘
                      ▪ Prompt injection       ▪ Claude, GPT,
                        detection                LM Studio
                      ▪ PII/secrets redaction  ▪ Multi-agent
                      ▪ Policy enforcement       routing
                      ▪ Audit logging          ▪ RAG knowledge

Início Rápido (Docker)

Pré-requisitos: Docker e uma chave de API Anthropic.

# 1. Clone o repositório
git clone https://github.com/SleuthCo/clawshield-public.git
cd clawshield-public

# 2. Defina sua chave de API
cp standalone/.env.template standalone/.env
# Edite standalone/.env e cole sua chave de API Anthropic

# 3. Inicie
cd standalone
docker compose up -d

Abra http://localhost:18801 no seu navegador. Você verá o painel do ClawShield com 5 agentes de IA prontos para conversar.

É isso. O ClawShield está examinando todo o tráfego entre você e os agentes.

Obtendo uma Chave de API Anthropic

O ClawShield usa Claude (via API da Anthropic) como modelo de linguagem padrão. Veja como obter sua chave:

1. Acesse console.anthropic.com e cadastre-se (ou faça login)
2. Clique em API Keys na barra lateral esquerda
3. Clique em Create Key
4. Dê um nome (por exemplo, "clawshield") e clique em Create
5. Copie a chave — ela começa com sk-ant-
6. Cole-a no arquivo standalone/.env:
   root@kitploit:~

   ANTHROPIC_API_KEY=sk-ant-your-key-here
   

Custo: a Anthropic cobra por token. Uma sessão de chat típica custa alguns centavos. Contas novas recebem US$ 5 em créditos gratuitos. Consulte anthropic.com/pricing para detalhes.

Usando um modelo diferente? O ClawShield funciona com qualquer API compatível com OpenAI (GPT, LM Studio, Ollama, etc.). Edite standalone/config/openclaw.json para apontar para o provedor de sua preferência.

Opções de Instalação

Opção 1: Docker (recomendado)

Tudo roda em um único contêiner — proxy ClawShield + gateway OpenClaw + 5 agentes.

Consulte Início Rápido acima.

Opção 2: Binários Pré-compilados

Baixe a versão mais recente em GitHub Releases:

Em seguida, execute o assistente de configuração interativo:

# Baixe o assistente de configuração também
chmod +x clawshield-setup-*

# Execute o assistente — ele guia você por todo o processo
./clawshield-setup-linux-amd64

O assistente irá:

• Pedir sua chave de API Anthropic
• Configurar seus agentes
• Gerar a configuração do OpenClaw
• Criar scripts de início/parada

Opção 3: Compilar a partir do Código-fonte

Requer Go 1.24+.

git clone https://github.com/SleuthCo/clawshield-public.git
cd clawshield-public

# Compile o proxy
cd proxy/cmd/clawshield-proxy
go build -o clawshield-proxy

# Compile o assistente de configuração
cd ../../clawshield-setup
go build -o clawshield-setup

# Execute a configuração
./clawshield-setup

O Que Está Incluído

Observabilidade

O ClawShield expõe um endpoint /metrics compatível com Prometheus para monitoramento em tempo real:

curl http://localhost:18789/metrics

Métricas principais:

• clawshield_requests_total — Total de solicitações avaliadas
• clawshield_decisions_allowed_total / _denied_total / _redacted_total — Resultados das decisões
• clawshield_scanner_detections_total{scanner,action} — Detecções por tipo de scanner
• clawshield_evaluation_duration_seconds — Histograma de latência de avaliação
• clawshield_active_connections — Conexões WebSocket atuais
• clawshield_crosslayer_events_* — Atividade do barramento de eventos entre camadas

Proxy de Segurança

O núcleo do ClawShield. Um proxy reverso HTTP que intercepta todo o tráfego entre usuários e o gateway de IA.

Scanners (cada um produz registros de auditoria forense estruturados com IDs de regra e trechos de correspondência anonimizados):

• Detecção de injeção de prompt — bloqueia tentativas de jailbreak, sobrescrita de instruções e manipulação de papéis
• Anonimização de PII — detecta e anonimiza e-mails, números de telefone, SSNs e cartões de crédito
• Detecção de segredos — captura chaves de API, tokens e senhas antes que vazem
• Varredura de vulnerabilidades — sinaliza SQL injection, SSRF, path traversal, command injection e XSS
• Análise de malware — detecta executáveis, scripts, archive bombs e assinaturas conhecidas

Endurecimento de Produção (Camada 3):

• Monitor eBPF nativo em Go substituindo a dependência Python/BCC — um único binário compilado
• Degradação graciosa: fallback automático para polling de /proc quando o eBPF não está disponível (sem CAP_BPF, kernel antigo, contêineres)
• Sistema de health check: relatório de status por camada (saudável/degradado/fora do ar) para todas as 3 camadas de defesa
• Confiabilidade do pipeline de eventos: contagem de perdas, registro de backpressure e métricas de eventos publicados/descartados
• Re-resolução dinâmica de DNS para regras de firewall — evita regras obsoletas quando os IPs de CDN são rotacionados
• Detecção de capacidade na inicialização: versão do kernel, suporte a BTF e verificação de root/CAP_BPF

Hot-Reload de Políticas:

• Hot-reload baseado em file-watch — modifique policy.yaml e as alterações entram em vigor em até 5 segundos, sem reinicialização
• Versionamento por hash de conteúdo — cada versão da política recebe um ID de versão baseado em SHA256, registrado nos logs de auditoria
• Modo shadow/canary — teste novas políticas em modo somente-log antes de aplicá-las
• Diff de políticas — cada recarga registra exatamente o que mudou (adições à allowlist, alternâncias de scanners, etc.)
• Troca atômica — solicitações em andamento continuam com a política antiga; novas solicitações usam a nova política

Varredura de Respostas em Streaming:

• Varredura em tempo real, bloco por bloco, de streams SSE e NDJSON — sem atraso de buffer
• Janela deslizante de sobreposição (200 caracteres) captura padrões que atravessam limites de bloco
• Contexto transportado da solicitação para a resposta reduz falsos positivos (por exemplo, respostas de geração de código podem conter padrões de script)
• Anonimização por bloco de segredos e PII na saída em streaming

Mecanismo de políticas — baseado em YAML, negação por padrão:

default_action: deny

scanners:
  prompt_injection:
    enabled: true
    action: block
  pii:
    enabled: true
    action: redact
  secrets:
    enabled: true
    action: block

domain_allowlist:
  - "api.anthropic.com"
  - "api.openai.com"

Consulte policy/examples/ para mais exemplos.

5 Agentes de IA

Cada agente tem uma função especializada e sua própria base de conhecimento RAG:

Registro de Auditoria

Toda solicitação e resposta é registrada em um banco de dados SQLite local com:

• Carimbo de data/hora, IP de origem, método da solicitação
• Decisões dos scanners (permitir/bloquear/anonimizar) com motivos
• Explicabilidade de decisões — detalhe forense estruturado para cada decisão de negar/anonimizar, incluindo qual scanner disparou, qual regra correspondeu, um trecho da correspondência devidamente anonimizado e o nível de confiança
• Payloads completos de solicitação/resposta (configurável)
• Consulta por meio da CLI de auditoria integrada:

clawshield-audit --db /var/lib/clawshield/audit.db --last 50
clawshield-audit --db /var/lib/clawshield/audit.db --blocked-only
clawshield-audit --db /var/lib/clawshield/audit.db --scanner injection
clawshield-audit --db /var/lib/clawshield/audit.db --rule-id sqli

Consulte docs/audit-log-format.md para o esquema completo e Explicabilidade de Decisões para detalhes de consulta forense.

Integração com SIEM:

• Encaminhamento em tempo real de eventos de severidade Crítica e Alta para sistemas SIEM corporativos
• Formato Detection Finding OCSF v1.1 para compatibilidade universal com SIEM
• Transportes Syslog (RFC 5424 sobre TCP/TLS) e webhook (POST HTTPS)
• Limiar de severidade configurável — por padrão, encaminha apenas alertas Alta (4) e Crítica (5)
• Consulte docs/audit-log-format.md para configuração

Firewall de Rede (opcional)

Firewall de saída baseado em iptables que restringe quais domínios/IPs os agentes podem acessar:

cd firewall/cmd/clawshield-fw && go build -o clawshield-fw
sudo ./clawshield-fw apply --config firewall/examples/firewall.yaml

Monitor eBPF (opcional)

Monitoramento de chamadas de sistema em nível de kernel para detectar comportamento suspeito de agentes:

sudo python3 ebpf/cmd/clawshield-ebpf/main.py --config ebpf/config/default.yaml

Detecta: fork bombs, acesso a arquivos sensíveis, escalonamento de privilégios e conexões de rede anômalas.

Arquitetura

O ClawShield usa defesa em profundidade — três camadas de segurança conectadas por um barramento de eventos entre camadas:

Layer 1: Application (ClawShield Proxy)
  ▪ Scans message content
  ▪ Enforces YAML policies
  ▪ Logs all decisions

Layer 2: Network (ClawShield Firewall)
  ▪ iptables egress rules
  ▪ Domain/IP allowlist
  ▪ Blocks unapproved connections
  ▪ Dynamic temporary rules from cross-layer events

Layer 3: Kernel (ClawShield eBPF)
  ▪ Syscall monitoring
  ▪ Behavioral anomaly detection
  ▪ Real-time alerts

Cada camada funciona de forma independente. Se uma for contornada, as outras ainda protegem.

Barramento de Eventos entre Camadas

As três camadas se comunicam por meio de um barramento de eventos baseado em socket Unix, permitindo respostas de segurança adaptativas entre camadas:

┌──────────────┐                          ┌──────────────┐
│  eBPF        │──── Unix Socket ────────▶│  Proxy       │
│  (Layer 3)   │  /tmp/clawshield-       │  (Layer 1)   │
│  Produces:   │   events.sock           │  Produces:   │
│  • privesc   │                          │  • injection │
│  • port_scan │◀── Adaptive Controller ──│  • malware   │
│  • file_access│                         │  • vuln_scan │
└──────────────┘                          └──────────────┘
                         │
                         ▼
                ┌──────────────┐
                │  Firewall    │
                │  (Layer 2)   │
                │  Consumes:   │
                │  • temp block│
                │    rules     │
                └──────────────┘

Exemplos de reações adaptativas:

Habilite a integração entre camadas adicionando uma seção adaptive ao seu YAML de política. Consulte policy/examples/adaptive_crosslayer.yaml para um exemplo completo.

Implantação em Produção

Para implantar em um servidor real com TLS, consulte docs/install-guide.md.

O diretório deploy/ contém:

• cloud-init.yaml — Provisionamento de VM endurecida (bloqueio de SSH, fail2ban, nftables, auditd)
• docker-compose.yml — Stack de produção completo com terminação TLS via nginx
• nginx/conf.d/ — Configurações de nginx para produção com rate limiting, cabeçalhos de segurança e proxy WebSocket
• deploy.sh — Script de implantação automatizado
• smoke-test.sh — Verificação pós-implantação

Configuração

Variáveis de Ambiente

Arquivos

Testes

# Testes unitários
go test ./proxy/...
go test ./firewall/...

# Testes de integração
go test ./integration/...

Contribuindo

Issues e pull requests são bem-vindos em github.com/SleuthCo/clawshield-public.

Licença

Apache 2.0

Agradecimentos

Construído sobre OpenClaw. Inspirado por arquiteturas tradicionais de segurança de rede aplicadas a contextos de agentes de IA.