Boas Práticas de Segurança para Armazenamento de Chaves de API em Repositórios de Código

Nunca commite chaves de API diretamente no código: use variáveis de ambiente para desenvolvimento local, gerenciadores de segredos para produção e hooks de pre-commit para detectar credenciais antes que cheguem ao repositório. Uma chave exposta no GitHub pode ser capturada por bots em minutos e usada para consultas não autorizadas em massa.

Introdução

Chaves de API commitadas em repositórios de código são uma das causas mais frequentes de vazamentos de dados. Bots automatizados escaneiam repositórios públicos no GitHub em busca de credenciais expostas, e em minutos uma chave de API de CPF pode ser usada para consultas em massa não autorizadas. Mesmo em repositórios privados, a presença de chaves no histórico do Git representa um risco permanente: uma vez commitada, a credencial permanece acessível no histórico mesmo após ser removida do código atual.

Por que chaves de API vazam em repositórios

Entender os vetores de exposição é o primeiro passo para preveni-los:

Configuração do .gitignore

A primeira linha de defesa é impedir que arquivos com credenciais sejam rastreados pelo Git:

# .gitignore para projetos que consomem APIs de CPF

# Variáveis de ambiente
.env
.env.local
.env.production
.env.staging
.env.*.local

# Diretórios de segredos
secrets/
.secrets/
credentials/

# Arquivos de configuração com credenciais
config.local.js
config.local.py
settings.local.py

# Notebooks com possíveis credenciais
*.ipynb_checkpoints/

# Arquivos de IDE que podem conter variáveis
.idea/
.vscode/settings.json

# Logs que podem conter chaves
*.log
logs/

# Certificados e chaves privadas
*.pem
*.key
*.p12
*.pfx

Configure o .gitignore antes do primeiro commit do projeto para evitar que arquivos sensíveis entrem no histórico.

Uso correto de variáveis de ambiente

Variáveis de ambiente são o método mais básico para separar credenciais do código:

import os
import requests

# CORRETO: chave vem de variável de ambiente
CPFHUB_API_KEY = os.environ.get("CPFHUB_API_KEY")

if not CPFHUB_API_KEY:
    raise EnvironmentError(
    "Variável CPFHUB_API_KEY não definida. "
    "Configure-a no ambiente antes de executar."
    )

def consultar_cpf(cpf: str) -> dict:
    """Consulta CPF usando chave de variável de ambiente."""
    response = requests.get(
    f"https://api.cpfhub.io/cpf/{cpf}",
    headers={"x-api-key": CPFHUB_API_KEY},
    timeout=10
    )
    return response.json()

# Para desenvolvimento local, use arquivo .env com python-dotenv
# IMPORTANTE: o arquivo .env NUNCA deve ser commitado
#
# .env (NÃO commitado):
# CPFHUB_API_KEY=sua_chave_aqui
#
# No código:
# from dotenv import load_dotenv
# load_dotenv()

Gerenciadores de segredos

Para ambientes de produção, variáveis de ambiente simples não são suficientes. Utilize gerenciadores dedicados:

• AWS Secrets Manager -- armazena e rotaciona segredos automaticamente, com integração nativa a serviços AWS
• HashiCorp Vault -- solução open-source com políticas de acesso granulares, auditoria e rotação automática
• Azure Key Vault -- gerenciador de segredos da Microsoft com integração ao ecossistema Azure
• Google Secret Manager -- serviço gerenciado do GCP com versionamento e controle de acesso IAM
• Doppler -- plataforma SaaS que sincroniza segredos entre ambientes e equipes

// Exemplo com AWS Secrets Manager
const {
    SecretsManagerClient,
    GetSecretValueCommand
} = require("@aws-sdk/client-secrets-manager");

async function obterChaveAPI() {
    const client = new SecretsManagerClient({
    region: "sa-east-1"
    });
    const command = new GetSecretValueCommand({
    SecretId: "producao/cpfhub/api-key"
    });
    const response = await client.send(command);
    const secrets = JSON.parse(response.SecretString);
    return secrets.CPFHUB_API_KEY;
}

// Uso na aplicação
async function consultarCPF(cpf) {
    const apiKey = await obterChaveAPI();
    const response = await fetch(
    `https://api.cpfhub.io/cpf/${cpf}`,
    { headers: { "x-api-key": apiKey } }
    );
    return response.json();
}

Detecção automatizada de vazamentos

Implemente ferramentas que detectem credenciais antes que cheguem ao repositório. O OWASP mantém guias atualizados sobre prevenção de exposição de segredos em pipelines de desenvolvimento:

Configure hooks de pre-commit que impeçam o commit de código contendo padrões de credenciais:

# Instalação e configuração do git-secrets
brew install git-secrets

# Configurar no repositório
cd /caminho/do/projeto
git secrets --install

# Adicionar padrões para detectar chaves de API
git secrets --add 'cpfhub_[a-zA-Z0-9]{20,}'
git secrets --add 'x-api-key:\s*[a-zA-Z0-9]{20,}'
git secrets --add 'CPFHUB_API_KEY=[a-zA-Z0-9]{20,}'

# Verificar histórico existente
git secrets --scan-history

O que fazer quando uma chave vaza

Se uma chave de API for descoberta em um repositório, aja imediatamente:

• Revogar imediatamente -- gere uma nova chave e revogue a comprometida no painel do provedor da API, sem esperar pela conclusão da investigação
• Rotacionar em todos os ambientes -- atualize a nova chave em todos os serviços que utilizavam a credencial comprometida
• Limpar o histórico do Git -- use git filter-branch ou BFG Repo-Cleaner para remover a chave do histórico, lembrando que clones anteriores ainda podem conter a credencial
• Investigar uso indevido -- verifique nos logs se a chave comprometida foi utilizada por terceiros não autorizados
• Comunicar -- informe o DPO e a equipe de segurança sobre o incidente para avaliação de impacto
• Implementar prevenção -- configure hooks de pre-commit e scanners de CI para evitar recorrência

Perguntas frequentes

O que acontece se minha chave de API do CPFHub.io for exposta em um repositório?

Acesse imediatamente o painel em app.cpfhub.io, revogue a chave comprometida e gere uma nova. Em paralelo, verifique os logs de uso para identificar consultas não autorizadas. Após revogar, use BFG Repo-Cleaner para remover a credencial do histórico do Git, pois deletar o arquivo do código atual não apaga commits anteriores.

Variáveis de ambiente são suficientes para proteger chaves em produção?

Para desenvolvimento local, sim. Em produção, variáveis de ambiente no servidor podem ser lidas por qualquer processo com acesso ao sistema. O ideal é usar gerenciadores dedicados — AWS Secrets Manager, HashiCorp Vault ou Google Secret Manager — que oferecem controle de acesso granular, auditoria e rotação automática de segredos.

Como detectar se uma chave já foi exposta em um repositório?

Execute git secrets --scan-history após instalar o git-secrets, ou use o TruffleHog com trufflehog git file://./seu-repo para varrer todo o histórico de commits em busca de padrões de credenciais. O GitHub Secret Scanning faz isso automaticamente em repositórios públicos e privados (planos pagos).

Notebooks Jupyter são um vetor de risco para chaves de API?

Sim, são um dos vetores mais comuns e menos percebidos. Células executadas com a chave em texto plano ficam registradas no output do notebook, que é salvo no arquivo .ipynb — um JSON que vai para o Git como qualquer outro arquivo. Use nbstripout para limpar outputs antes de commitar e nunca coloque a chave diretamente em células de código.

Conclusão

Proteger chaves de API de CPF em repositórios de código é uma responsabilidade fundamental de toda equipe de desenvolvimento. A combinação de .gitignore adequado, variáveis de ambiente, gerenciadores de segredos e scanners automatizados cria múltiplas camadas de proteção que reduzem drasticamente o risco de vazamento. Ao integrar com a API do cpfhub.io, aplicar essas práticas desde o início garante que suas consultas de CPF permaneçam seguras e auditáveis em qualquer ambiente.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e implemente a integração segura hoje mesmo.