Guia Completo de Segurança do Claude Code: Chaves API, Permissões e Proteção da Produção

O Claude Code tem poderosas capacidades de manipulação de arquivos e execução de comandos — mas uma configuração incorreta pode levar a acidentes irreversíveis. Commitar um arquivo .env, excluir acidentalmente um banco de dados de produção, imprimir uma chave API nos logs — esses são incidentes reais causados pelo uso do Claude Code sem as proteções adequadas.

Este artigo fornece uma explicação em nível de implementação das melhores práticas de segurança para o Claude Code. O foco não é na teoria, mas em configurações prontas para uso e código preventivo que você pode copiar e aplicar imediatamente.

Por que o Claude Code Precisa de Medidas de Segurança

Ao contrário de um editor de texto comum, o Claude Code tem as seguintes capacidades:

• Ler, escrever e excluir qualquer arquivo (Read / Write / Edit / Bash(rm))
• Executar comandos shell (Bash)
• Acesso à rede (WebFetch / chamadas de API)
• Postar em serviços externos (GitHub, Slack, etc.)

Tudo isso pode ser executado com a aprovação do usuário. O problema é que aprovar mecanicamente cada prompt permite que operações indesejadas passem despercebidas. Medidas de segurança significam eliminar estruturalmente o espaço para erros.

Medida 1: Gerenciamento de Chaves API — .env + .gitignore como Base

O que NÃO Fazer

// ❌ Escrito diretamente no código fonte
const client = new Anthropic({ apiKey: "PASTE_REAL_API_KEY_HERE" });

// ❌ Escrito no CLAUDE.md ou arquivos de configuração
// ANTHROPIC_API_KEY=PASTE_REAL_API_KEY_HERE

// ❌ Incluído no prompt do claude -p
// Use QIITA_TOKEN=PASTE_REAL_TOKEN_HERE para publicar

A Abordagem Correta

# .env (excluído do git, armazenado apenas na máquina local)
ANTHROPIC_API_KEY=<anthropic-api-key>
QIITA_TOKEN=<qiita-token>
SLACK_BOT_TOKEN=<slack-bot-token>
DATABASE_URL=postgresql://...

# Sempre adicionar ao .gitignore
.env
.env.*
.env.local
!.env.example   # ← Arquivo de exemplo pode ser commitado
*.pem
*.key
credentials.json
*-service-account.json

# .env.example (seguro para commitar, valores vazios)
ANTHROPIC_API_KEY=
QIITA_TOKEN=
SLACK_BOT_TOKEN=
DATABASE_URL=

Lendo Variáveis no Código

// ✅ Leia a partir de variáveis de ambiente
import { config } from "dotenv";
config();

const token = process.env.QIITA_TOKEN;
if (!token) throw new Error("QIITA_TOKEN não está definido. Por favor, verifique seu arquivo .env.");

Documente Proibições no CLAUDE.md

## Proibições de Segurança
- Nunca incluir chaves API ou tokens em prompts
- Nunca ler e exibir o conteúdo de arquivos .env
- Nunca escrever valores de variáveis de ambiente em logs ou comentários
- Nunca fazer console.log do conteúdo de process.env

Medida 2: Varredura de Secrets Antes do Commit

Mesmo com .env no .gitignore, entradas acidentais em outros arquivos ou erros de copiar e colar ainda podem acontecer. Adicione uma varredura automática de pré-commit.

Verificação Pré-Commit com Hooks

.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/secret-scan.mjs"
          }
        ]
      }
    ]
  }
}

scripts/secret-scan.mjs:

import { execSync } from "child_process";

// Obter alterações em staging
const diff = execSync("git diff --cached").toString();

const PATTERNS = [
  { name: "Atribuição de chave API Anthropic", re: /\b(?:ANTHROPIC_API_KEY|CLAUDE_API_KEY)\s*[:=]\s*["']?[^"'\s]{20,}/i },
  { name: "Atribuição de chave API OpenAI", re: /\bOPENAI_API_KEY\s*[:=]\s*["']?[^"'\s]{20,}/i },
  { name: "Chave de Acesso AWS", re: /\bAKIA[0-9A-Z]{16}\b/ },
  { name: "Token Slack", re: /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/ },
  { name: "Secret Genérico", re: /\b(?:secret|token|api[_-]?key|password)\s*[:=]\s*["'][^"']{10,}["']/i },
];

const found = PATTERNS.filter(({ re }) => re.test(diff));

if (found.length > 0) {
  console.error("🚨 Secret detectado! Abortando o commit:");
  found.forEach(({ name }) => console.error(`  - ${name}`));
  console.error("\nSolução: execute `git reset HEAD <arquivo>` para fazer unstage do arquivo");
  process.exit(1);  // Código de saída 1 → Hook bloqueia o comando
}

console.log("✓ Varredura de secrets: nenhum problema encontrado");
process.exit(0);

Isso significa que no momento em que o Claude Code tenta executar git commit, uma varredura automática é iniciada e qualquer vazamento detectado é bloqueado.

Medida 3: Configuração dos Modos de Permissão

As configurações de permitir/negar do Claude Code podem ser controladas de forma granular no nível do arquivo.

Configurações de Permissão no .claude/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "disableBypassPermissionsMode": "disable",
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(DROP TABLE*)",
      "Bash(truncate*)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(npm publish*)",
      "Bash(wrangler pages deploy*)"
    ]
  },
  "disableAutoMode": "disable"
}

Configuração	Significado
allow	Executar sem confirmação
deny	Nunca executar (completamente bloqueado)
ask	Requer aprovação a cada vez

Princípio-chave: Comandos destrutivos vão em deny, operações de escrita em ask, operações de leitura em allow.

Separe produção e política da organização com local ou managed settings

O modelo oficial de configuração aplica os escopos nesta ordem: managed, argumentos de linha de comando, local, project e user. Em vez de depender de uma troca por arquivo personalizado não oficial, use .claude/settings.local.json para um terminal pessoal de produção mais rígido e managed settings para regras da organização.

Use .claude/settings.local.json para overrides locais e não faça commit dele.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "plan",
    "disableBypassPermissionsMode": "disable",
    "allow": ["Read(**)", "Glob(**)", "Grep(**)", "Bash(git log*)", "Bash(git diff*)"],
    "deny": ["Write(**)", "Edit(**)", "Bash(git push*)", "Bash(rm*)", "Bash(*deploy*)"],
    "ask": []
  },
  "disableAutoMode": "disable"
}

Para uma política de equipe ou empresa, coloque o limite em managed settings. Com allowManagedPermissionRulesOnly, usuários e repositórios de projeto não podem redefinir regras allow, ask ou deny para contornar a política da organização.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "disableAutoMode": "disable",
  "allowManagedPermissionRulesOnly": true
}

Medida 4: Proteção do Ambiente de Produção

Separar Explicitamente os Destinos de Conexão

## CLAUDE.md — Regras do Ambiente de Produção

## Detecção de Ambiente
- Se DATABASE_URL contiver 'prod' ou 'production', é um **ambiente de produção**
- Em produção, nunca execute:
  - DROP / TRUNCATE / DELETE (sem cláusula WHERE)
  - Migrações (requerem confirmação prévia)
  - Exclusões em massa de arquivos

## Fluxo de Confirmação
Todas as mudanças em produção devem:
1. Ser testadas primeiro em um ambiente de staging
2. Receber confirmação do usuário
3. Reportar resultados após a execução

Controlar Conexões com Variáveis de Ambiente

// scripts/db-query.mjs
const env = process.env.NODE_ENV ?? "development";
const dbUrl = process.env.DATABASE_URL;

if (env === "production" && process.argv.includes("--write")) {
  console.error("❌ Escrever em produção requer a flag --force-production");
  process.exit(1);
}

Medida 5: Proteções para Operações de Arquivos

Automatizar Backups Antes da Exclusão

// Hooks no .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(rm *)",
        "hooks": [
          {
            "type": "command",
            "command": "echo '⚠️  Um comando de exclusão está prestes a ser executado. Pressione Ctrl+C para cancelar.' && sleep 3"
          }
        ]
      }
    ]
  }
}

Proteger Arquivos Críticos de Edições Acidentais

## CLAUDE.md — Arquivos que Não Devem Ser Modificados

Os seguintes arquivos **nunca devem ser editados**:
- .env (contém variáveis de ambiente e chaves secretas)
- wrangler.toml (configuração de produção do Cloudflare)
- scripts/deploy.sh (script de implantação)
- .github/workflows/*.yml (configuração de CI/CD)

Se forem necessárias alterações, confirme primeiro com o usuário.

5 Armadilhas Comuns

1. Adicionar .gitignore depois do fato é tarde demais Um arquivo .env já commitado permanece no histórico do git mesmo após ser adicionado ao .gitignore.

# Remoção completa do histórico (atenção: requer force push)
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch .env" \
  --prune-empty --tag-name-filter cat -- --all

# Ou use o BFG Repo Cleaner

Se o arquivo já foi enviado para o GitHub, sempre rotacione suas chaves API primeiro antes de tratar o histórico.

2. Armazenar arquivos JSON de conta de serviço no repositório Chaves de conta de serviço para Google Cloud ou AWS são frequentemente distribuídas como arquivos .json, mas armazená-las em um repositório é perigoso. Converta-as em variáveis de ambiente ou migre para um Secret Manager (AWS Secrets Manager / GCP Secret Manager).

3. Executar comandos interativos com a ferramenta Bash Durante a execução sem interface com claude -p, comandos que requerem entrada interativa como sudo ou vim farão o processo travar. Use apenas comandos não interativos.

4. Incluir credenciais em mensagens de erro

// ❌ Perigoso: chave API aparece nos logs
throw new Error(`Autenticação falhou: token=${process.env.TOKEN}`);

// ✅ Seguro: não expor o valor
throw new Error(`Autenticação falhou: por favor verifique a variável de ambiente TOKEN`);

5. Reutilizar as mesmas configurações de permissão em todos os projetos Usar o mesmo settings.json para projetos pessoais e de trabalho significa que as configurações permissivas do projeto pessoal podem sobrescrever os requisitos mais rígidos do projeto de trabalho. Gerencie .claude/settings.json separadamente para cada projeto.

Regras operacionais práticas

Não expor secrets no trabalho normal

Quando você pede ao Claude Code “corrija este erro”, não cole o log completo nem o conteúdo de .env. Defina antes que chaves API, tokens OAuth, cookies, URLs de banco de dados, emails de clientes, IDs de cobrança e chaves privadas nunca entram em prompts, issues ou chats.

Se o Claude Code precisa de contexto, mascare os valores e mantenha só a estrutura. DATABASE_URL=***REDACTED*** basta para mostrar que existe uma URL de banco de dados. O valor real quase nunca é necessário para depurar código de aplicação.

Seguro de fornecer	Não fornecer
Tipo de erro, arquivos no stack trace, passos de reprodução	Chaves API, chaves privadas, cookies de sessão, valores reais de .env
.env.example, nomes de settings, regras de permissão, comando com falha	URLs de banco de produção, dados de clientes, credenciais internas
Logs mascarados, dados de teste, valores locais de exemplo	Tokens reais, JSON de service account, screenshots com secrets

Coloque esta tabela no CLAUDE.md para que toda sessão comece com o mesmo limite. Em equipes, “não expor secrets” precisa ser regra operacional, não conhecimento informal.

Duplicar a varredura de secrets antes do commit

O Hook PreToolUse acima bloqueia o commit quando o Claude Code executa git commit. Ele não cobre uma pessoa fazendo commit em outro terminal nem arquivos gerados no CI. Em times de produção, use três camadas: Hook do Claude Code, pre-commit local e secret scan no CI que bloqueia o merge.

A configuração mínima útil é bloquear localmente, revisar de novo no CI e falhar o pull request quando um padrão de secret aparecer. Ferramentas como gitleaks ou trufflehog são melhores para detecção em escala de CI; o script deste artigo continua útil como guarda local rápido.

Exemplos concretos de falha

Falha 1: ler .env durante investigação Um desenvolvedor pediu ao Claude Code para “verificar as variáveis de ambiente” e valores reais acabaram na conversa ou em logs de trabalho. A correção é negar leitura de .env e fornecer apenas .env.example.

Falha 2: colar token de publicação do Qiita no prompt Uma automação incluiu QIITA_TOKEN diretamente no prompt, criando chance de persistência em subagente ou log. O fluxo seguro é manter o token em .env e fazer comandos referenciarem só o nome da variável de ambiente.

Falha 3: URLs de produção e staging muito parecidas A instrução dizia apenas “limpe o banco” e pulava a verificação de conexão. Se a URL ativa fosse produção, um delete ou migration poderia virar incidente. Antes de escrever, mostre NODE_ENV, host e nome do banco, e exija confirmação explícita.

Primeiros passos após um incidente

Se você suspeita que um secret vazou, o primeiro passo não é limpar o histórico. É desativar a credencial.

1. Rotacione ou revogue imediatamente a chave API, token ou senha afetada
2. Verifique logs de GitHub Actions, Cloudflare, AWS, GCP e SaaS conectados
3. Registre quem expôs o quê, quando, em qual repositório e por qual canal
4. Remova o secret do histórico git e logs, comunicando o impacto de force push
5. Endureça regras deny, Hooks, scans de CI e proibições no CLAUDE.md

Na prática, parar a credencial primeiro e limpar o histórico depois reduz erros. Durante um incidente, as pessoas costumam colar mais logs tentando ajudar; prepare um modelo de log mascarado antes de precisar.

Caminho natural para material e consultoria

A segurança do Claude Code não se resolve com um único arquivo de settings. Também é preciso revisar estrutura do repositório, CI, permissões de deploy e fluxo de aprovação da equipe.

No ClaudeCodeLab, o caminho de aprendizado individual começa por higiene de .env e permission rules. Em consultorias para equipes, as primeiras perguntas são onde as managed settings devem ser aplicadas e onde o secret scan de CI deve bloquear merges. Se o Claude Code já é usado no trabalho, comece mapeando quem pode acessar quais secrets antes de ajustar permissões finas.

Lista de Verificação de Segurança

Uma lista de verificação para configurar um projeto Claude Code:

### Configuração Básica
- [ ] .env criado e adicionado ao .gitignore
- [ ] .env.example criado e compartilhado com a equipe
- [ ] Verificado via git log que commits existentes não contêm secrets

### Configurações de Permissão
- [ ] Lista de deny configurada no .claude/settings.json
- [ ] Comandos destrutivos (rm -rf, DROP TABLE, etc.) adicionados ao deny
- [ ] Comandos de deploy em produção configurados como ask

### Automação
- [ ] Hook de varredura de secrets pré-commit configurado
- [ ] Proibições de segurança documentadas no CLAUDE.md

### Operações
- [ ] Cronograma de rotação de chaves API estabelecido (recomendado: a cada 90 dias)
- [ ] Trabalho em produção restrito com .claude/settings.local.json ou managed settings
- [ ] Fluxo de resposta a incidentes documentado

Resumo

A segurança do Claude Code não é sobre “impor restrições” — é sobre construir uma estrutura onde acidentes estruturalmente não podem acontecer.

Ameaça	Contramedida
Vazamento de chave API	.env + .gitignore + Hook de varredura de secrets
Exclusão indesejada	Lista de deny + Hook pré-exclusão
Erros em produção	local/managed settings + proibições no CLAUDE.md
Contaminação de commits	Hook PreToolUse para varredura pré-commit

Uma vez configuradas, essas configurações são praticamente livres de manutenção. Gastar 30 minutos hoje pode prevenir um grande incidente no futuro.

Artigos Relacionados

• Guia de Permissões do Claude Code
• Casos de Falhas de Segurança do Claude Code
• Guia Completo de Integração Claude Code + SaaS
• Melhores Práticas do CLAUDE.md

Referências

• Documentação oficial de Claude Code settings
• Documentação oficial de Claude Code permissions
• Documentação oficial de server managed settings
• Removendo Secrets do Histórico com git-filter-branch
• BFG Repo Cleaner