Hooks do Claude Code para Validação e Segurança

Uma IA com acesso ao seu terminal pode executar qualquer comando que você executaria. Pense nisso por um segundo. O Claude Code consegue rodar rm -rf, sobrescrever variáveis de ambiente, alterar configurações de banco de dados e até fazer push direto para a branch principal do seu repositório. Sem uma camada de proteção, a distância entre um prompt mal formulado e um desastre no ambiente de produção é assustadoramente curta.

Os hooks do Claude Code permitem criar exatamente essa camada. Em vez de depender apenas do bom senso ao escrever prompts, você configura gatilhos automáticos que interceptam ações antes que elas aconteçam — validando comandos, bloqueando operações em arquivos sensíveis e exigindo confirmação para ações destrutivas. Este artigo mostra como implementar cada uma dessas proteções de forma prática.

Riscos de segurança ao usar IA para codificar

Antes de configurar qualquer hook, vale entender quais riscos concretos existem quando uma IA opera com acesso ao sistema de arquivos e ao terminal.

Execução de comandos destrutivos

O Claude Code interpreta suas instruções e traduz em ações. Se você pedir para “limpar os arquivos temporários do projeto”, ele pode interpretar de forma mais ampla do que o esperado. Um rm no diretório errado, um drop table em um banco conectado, ou um git push --force na branch errada — tudo isso está ao alcance da ferramenta.

Exposição de credenciais e segredos

Arquivos como .env, chaves SSH, tokens de API e certificados ficam no mesmo sistema de arquivos que o Claude Code acessa. Sem restrições, a IA pode ler, exibir no terminal ou até incluir essas informações em commits.

Alteração de configurações críticas

Arquivos de configuração de infraestrutura (Dockerfiles, arquivos de CI/CD, configs do Nginx) podem ser modificados pela IA durante uma sessão de desenvolvimento. Uma alteração aparentemente inofensiva pode abrir portas no firewall ou desabilitar autenticação.

Criando hooks de validação antes de executar comandos

O hook PreToolUse é o principal mecanismo de defesa. Ele intercepta a ação do Claude Code antes da execução, permitindo que um script decida se o comando deve prosseguir ou ser bloqueado.

Estrutura básica de um hook de validação

No arquivo .claude/hooks.json do seu projeto, a configuração segue este formato:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 .claude/scripts/validate_command.py"
      }
    ]
  }
}

O script recebe via stdin um JSON com os detalhes da ação que o Claude Code pretende executar. Para comandos Bash, o campo command contém exatamente o que será rodado no terminal.

Script de validação com lista de bloqueio

Crie o arquivo .claude/scripts/validate_command.py:

import json
import sys

BLOCKED_PATTERNS = [
    "rm -rf /",
    "rm -rf ~",
    "DROP TABLE",
    "DROP DATABASE",
    "git push --force",
    "git push origin main",
    "chmod 777",
    "curl | bash",
    "wget | sh",
    "> /dev/sda",
]

def main():
    input_data = json.load(sys.stdin)
    command = input_data.get("command", "")

    for pattern in BLOCKED_PATTERNS:
        if pattern.lower() in command.lower():
            result = {
                "status": "blocked",
                "message": f"Comando bloqueado por política de segurança: contém '{pattern}'"
            }
            print(json.dumps(result))
            sys.exit(0)

    result = {"status": "approved"}
    print(json.dumps(result))
    sys.exit(0)

if __name__ == "__main__":
    main()

Quando o script retorna "status": "blocked", o Claude Code não executa o comando e exibe a mensagem ao usuário.

Adicionando validação por regex

Para cobrir variações de comandos destrutivos, expanda a validação:

import re

BLOCKED_REGEX = [
    r"rm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+)?/(?!tmp)",  # rm com force fora de /tmp
    r"git\s+push.*--force",
    r"chmod\s+777",
    r"DROP\s+(TABLE|DATABASE)",
    r"curl.*\|.*(?:bash|sh)",
]

def is_dangerous(command):
    for pattern in BLOCKED_REGEX:
        if re.search(pattern, command, re.IGNORECASE):
            return True, pattern
    return False, None

Protegendo arquivos sensíveis com hooks de bloqueio

Além de comandos, é fundamental controlar quais arquivos o Claude Code pode ler ou modificar. O hook PreToolUse também intercepta operações de escrita em arquivos.

Configurando proteção por caminho

Adicione um segundo hook no .claude/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 .claude/scripts/validate_command.py"
      },
      {
        "matcher": "WriteFile",
        "command": "python3 .claude/scripts/protect_files.py"
      }
    ]
  }
}

O script protect_files.py verifica o caminho do arquivo antes de permitir a escrita:

import json
import sys
import os

PROTECTED_PATHS = [
    ".env",
    ".env.local",
    ".env.production",
    "id_rsa",
    "id_ed25519",
    ".ssh/",
    "credentials.json",
    "serviceAccountKey.json",
    "docker-compose.prod.yml",
    ".github/workflows/",
]

def main():
    input_data = json.load(sys.stdin)
    file_path = input_data.get("path", "")

    normalized = os.path.normpath(file_path)

    for protected in PROTECTED_PATHS:
        if protected in normalized or normalized.endswith(protected):
            result = {
                "status": "blocked",
                "message": f"Arquivo protegido: '{file_path}'. Edite manualmente se necessário."
            }
            print(json.dumps(result))
            sys.exit(0)

    result = {"status": "approved"}
    print(json.dumps(result))
    sys.exit(0)

if __name__ == "__main__":
    main()

Tabela de arquivos que merecem proteção

Boas práticas de segurança com Claude Code

Hooks de validação são poderosos, mas funcionam melhor quando combinados com outras práticas.

1. Princípio do menor privilégio

Execute o Claude Code com um usuário que tenha apenas as permissões necessárias para o projeto atual. Evite rodar sessões como root ou com acesso administrativo ao sistema.

2. Versionamento dos scripts de hook

Mantenha os scripts de validação no repositório do projeto, dentro do diretório .claude/scripts/. Assim, toda a equipe compartilha as mesmas regras de segurança, e alterações passam por code review.

3. Logs de auditoria

Adicione logging aos seus scripts de validação para rastrear quais comandos foram bloqueados e quais foram aprovados:

import logging

logging.basicConfig(
    filename=".claude/logs/security.log",
    level=logging.INFO,
    format="%(asctime)s - %(message)s"
)

# Dentro da validação:
logging.info(f"BLOQUEADO: {command}")
# ou
logging.info(f"APROVADO: {command}")

4. Revisão periódica das regras

A cada sprint ou ciclo de desenvolvimento, revise a lista de comandos bloqueados e arquivos protegidos. Novos serviços, novas dependências e novas integrações podem exigir atualizações nas regras.

5. Ambientes isolados para experimentação

Quando estiver testando prompts novos ou explorando funcionalidades desconhecidas do Claude Code, use containers Docker ou máquinas virtuais descartáveis. Isso limita o raio de impacto de qualquer ação inesperada.

Montando sua estratégia de defesa em camadas

A segurança efetiva combina múltiplas barreiras. Veja como organizar suas camadas de proteção:

Nenhuma camada sozinha é suficiente. A combinação delas cria um ambiente onde o Claude Code opera com produtividade máxima e risco controlado.

A segurança no uso de ferramentas de IA para codificação não é paranoia — é engenharia responsável. Cada hook que você configura hoje é um incidente que você evita amanhã. Comece com as regras de bloqueio mais básicas, adicione proteção de arquivos sensíveis e evolua para logs de auditoria completos. Seu futuro eu vai agradecer.

Artigos relacionados

• Claude Code – Guia Completo para Criar Projetos com IA
• Hooks no Claude Code para Linting e Formatação
• Claude Code Hooks — Automatize Seu Fluxo de Trabalho

Bruno Bracaioli

Empreendedor e Desenvolvedor

Bruno Bracaioli é especialista em arquitetura de software, ciência de dados e cybersecurity. Além disso, investe em criptomoedas e em investimentos tradicionais como CDBs, Ações, Tesouro e outros. É influenciador digital no instagram (@brunobracaioli) e no Youtube (/brunobracaioli). Contato por: bruno@bracaiolitech.com ou pelo bruno@b2tech.com