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: "sk-ant-api03-..." });

// ❌ Escrito no CLAUDE.md ou arquivos de configuração
// ANTHROPIC_API_KEY=sk-ant-api03-...

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

A Abordagem Correta

# .env (excluído do git, armazenado apenas na máquina local)
ANTHROPIC_API_KEY=sk-ant-api03-...
QIITA_TOKEN=06b4441b...
SLACK_BOT_TOKEN=xoxb-...
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: "Chave API Anthropic", re: /sk-ant-api\d+-[A-Za-z0-9_-]{80,}/ },
  { name: "Chave API OpenAI", re: /sk-[A-Za-z0-9]{48}/ },
  { name: "Chave de Acesso AWS", re: /AKIA[0-9A-Z]{16}/ },
  { name: "Token Slack", re: /xox[baprs]-[0-9A-Za-z-]{10,}/ },
  { name: "Secret Genérico", re: /[Ss]ecret[_-]?[Kk]ey\s*[:=]\s*['"][^'"]{10,}['"]/ },
];

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

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)"
    ],
    "deny": [
      "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*)"
    ]
  }
}

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.

Arquivo de Configuração Específico para Produção

Para ambientes de produção, restringir à leitura apenas é a abordagem mais segura.

// .claude/settings.production.json
{
  "permissions": {
    "allow": ["Read(**)", "Glob(**)", "Grep(**)", "Bash(git log*)", "Bash(git diff*)"],
    "deny": ["Write(**)", "Edit(**)", "Bash(git push*)", "Bash(rm*)", "Bash(*deploy*)"],
    "ask": []
  }
}

# Especificar explicitamente ao trabalhar em produção
CLAUDE_SETTINGS=.claude/settings.production.json claude

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.

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)
- [ ] settings.production.json dedicado usado para produção
- [ ] 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	Configurações específicas de produção + 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 Permissões do Claude Code
• Removendo Secrets do Histórico com git-filter-branch
• BFG Repo Cleaner