# Boas Práticas de Segurança para Armazenamento de Chaves de API em Repositórios de Código > Conheça as boas práticas para armazenar chaves de API de forma segura em repositórios de código, evitando vazamentos e acessos não autorizados. **Publicado:** 03/07/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/boas-praticas-seguranca-armazenamento-chaves-api-repositorios --- 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](https://github.com) 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: | Vetor | Descrição | Frequência | |-------|-----------|------------| | Hardcoding intencional | Desenvolvedor coloca a chave diretamente no código "para testar" | Muito alta | | Arquivo .env commitado | Arquivo de configuração adicionado ao Git sem .gitignore | Alta | | Logs de debug | Chave impressa em console.log ou print durante desenvolvimento | Média | | Documentação interna | README ou wiki com exemplos contendo chaves reais | Média | | Jupyter notebooks | Células de notebook com API keys em texto aberto | Frequente | | Histórico do Git | Chave removida do código mas presente em commits anteriores | Permanente | | Fork de repositório | Chave commitada em repo privado que depois se torna público | Ocasional | --- ## Configuração do .gitignore A primeira linha de defesa é impedir que arquivos com credenciais sejam rastreados pelo Git: ```bash # .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: ```python 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 ```javascript // 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](https://owasp.org) mantém guias atualizados sobre prevenção de exposição de segredos em pipelines de desenvolvimento: | Ferramenta | Tipo | Integração | |-----------|------|-----------| | git-secrets (AWS) | Pre-commit hook | Local + CI | | GitLeaks | Scanner de repositório | CI/CD + pre-commit | | TruffleHog | Scanner de entropia | CI/CD | | GitHub Secret Scanning | Scanner nativo | GitHub (automático) | | detect-secrets (Yelp) | Pre-commit hook | Local + CI | Configure hooks de pre-commit que impeçam o commit de código contendo padrões de credenciais: ```bash # 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. ### Leia também - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) --- ## 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](https://www.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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e implemente a integração segura hoje mesmo.