⚠️ O risco real de vazar chaves de API
O que é
O risco não é teórico — acontece rotineiramente. Uma chave exposta pode resultar em centenas de dólares de uso não autorizado em horas antes de você perceber.
Por que aprender
🚨 Como chaves de API são comprometidas
- •Repositório GitHub público: bots escaneiam novos commits em tempo real. Uma chave commitada acidentalmente pode ser usada em minutos.
- •Arquivo de configuração commitado: .env, config.json ou qualquer arquivo com chaves no repositório.
- •Logs de aplicação expostos: alguns frameworks loggam variáveis de ambiente — se o log for público, a chave é pública.
- •Compartilhamento por email ou chat: chaves enviadas em texto claro ficam no histórico para sempre.
🛡️ GitHub Secret Scanning
O GitHub detecta automaticamente padrões de chaves conhecidas (sk-ant-, sk-or-, sk-...) e notifica. Mas a notificação chega depois da exposição — bots já podem ter lido a chave antes da notificação.
Conceitos-chave
Bots monitoram novos commits e arquivos públicos — velocidade de minutos, não horas
Proteção nativa, mas reativa — notifica depois da exposição, não antes
Centenas de dólares em horas é comum — a maioria dos usos maliciosos são imediatos e intensos
Detecção sempre chega tarde. A única estratégia eficaz é nunca expor
🚫 Nunca colocar chaves no soul.md — alternativas seguras
O que é
O soul.md é um arquivo de texto simples que pode ser lido por qualquer processo com acesso ao sistema. Estabelecer a regra "nunca chaves no soul.md" antes de começar a preencher evita o hábito errado.
Por que aprender
✗ Nunca colocar no soul.md
- ✗Chaves de API de qualquer provedor
- ✗Senhas de contas (email, banco, serviços)
- ✗Tokens de autenticação ou refresh tokens
- ✗Qualquer credencial que dê acesso a sistemas externos
Opção 1: hermes secrets
hermes secrets set ANTHROPIC_KEY sk-ant-...
Armazenamento seguro nativo do Hermes — criptografado no keychain do sistema operacional.
Opção 2: Arquivo .env
ANTHROPIC_API_KEY=sk-ant-...
Arquivo na raiz do projeto, NUNCA commitado. Sempre adicionar ao .gitignore antes de criar o arquivo.
Opção 3: Gerenciador
1Password, Bitwarden ou keychain do sistema operacional. Credenciais ficam separadas de qualquer código ou arquivo de texto.
Conceitos-chave
Acessível a qualquer processo com permissão de leitura no sistema — não é cofre
Armazenamento seguro nativo — usa keychain do SO, não arquivo de texto
Adicionar ao .gitignore ANTES de criar o arquivo .env — a ordem importa
1Password ou Bitwarden — a solução mais segura e mais conveniente a longo prazo
🔧 Variáveis de ambiente — como usar corretamente
O que é
Variáveis de ambiente são o padrão da indústria para credenciais. Ficam fora do sistema de arquivos de projeto, não aparecem em logs de debug e não são acidentalmente commitadas — quando configuradas corretamente.
Por que aprender
Adicionar .env ao .gitignore ANTES de criar o arquivo
echo ".env" >> .gitignore
A ordem importa: .gitignore antes do arquivo. Se você criar o arquivo primeiro e depois adicionar ao .gitignore, pode já ter sido commitado.
Criar o arquivo .env
ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
DEEPSEEK_API_KEY=sk-ds-...
Uma variável por linha. Sem espaços ao redor do =. Sem aspas nos valores (a menos que o valor tenha espaços).
Carregar as variáveis
source .env
Para persistência entre sessões, adicione ao ~/.bashrc ou ~/.zshrc.
Conceitos-chave
A dupla obrigatória — .gitignore sempre antes do arquivo .env
Carrega as variáveis na sessão atual do terminal
Para não precisar executar source .env a cada nova sessão de terminal
Variáveis de ambiente vivem no ambiente do SO, não no repositório de código
🔄 Rotação de chaves — quando e como trocar
O que é
Chaves antigas que nunca foram rotacionadas são um risco silencioso — você não sabe se foram expostas em algum momento. Rotação regular limita a janela de exposição potencial.
Por que aprender
📅 Quando rotacionar
Gerar nova chave no provedor
No dashboard do provedor (Anthropic, OpenRouter, DeepSeek), crie uma nova chave antes de revogar a antiga. As duas ficam ativas temporariamente.
Atualizar variáveis de ambiente e testar
Substituir a chave no .env ou no gerenciador de senhas. Testar uma chamada simples com a nova chave antes de revogar a antiga.
Revogar a chave antiga
Somente após confirmar que a nova chave funciona. Revogar antes de testar a nova pode derrubar o sistema por horas.
Conceitos-chave
Limite de janela de exposição — chave comprometida fica ativa por no máximo 90 dias
Rotacionar no dia do offboard — não depois, não antes
A sequência correta: gerar nova → testar nova → revogar antiga
O período em que uma chave comprometida pode ser usada — rotação limita isso
🛡️ Permissões mínimas — dando ao agente apenas o que precisa
O que é
Princípio de menor privilégio — dar ao agente apenas o que ele precisa para a função limita o dano potencial de comportamento inesperado ou de um prompt injection.
Por que aprender
📋 O que o Triad precisa vs não precisa
✓ Hermes precisa de
- ✓Acesso à internet (chamadas de API para OpenRouter, Anthropic)
- ✓Acesso ao terminal (para CLIs e comandos específicos)
- ✓Leitura de
~/.hermes/(configuração, logs, memória) - ✓Leitura/escrita no diretório de trabalho configurado
✗ Hermes NÃO precisa de
- ✗Acesso a arquivos fora dos diretórios configurados
- ✗Execução de scripts arbitrários sem aprovação
- ✗Acesso a configurações do sistema operacional
- ✗Permissões de root ou admin
💻 Configurando escopo de ferramentas
hermes config set tools.allowed "terminal,web,files"
Restringe o Hermes a usar apenas as ferramentas listadas. Qualquer tentativa de usar uma ferramenta não listada é bloqueada automaticamente.
Conceitos-chave
Princípio fundamental de segurança — só o mínimo necessário para a função
Lista explícita de ferramentas permitidas — bloqueio de tudo que não está na lista
Dados maliciosos que tentam fazer o agente executar ações não autorizadas
Mesmo que injetado, o agente só pode fazer o que sua configuração permite
👁️ O que o Hermes pode ver — e o que nunca mostrar
O que é
O contexto que você dá ao Hermes pode eventualmente chegar a um modelo externo via API. Minimizar dados sensíveis no contexto é uma prática de privacidade básica.
Por que aprender
✓ Seguro incluir no soul.md
- ✓Perfil profissional e objetivos de negócio
- ✓Tom de voz e preferências de comunicação
- ✓Contexto financeiro de alto nível (ex: "empresa pré-revenue")
- ✓Ferramentas e tecnologias que você usa
- ✓Projetos e iniciativas em andamento (sem dados confidenciais)
✗ Nunca incluir no soul.md
- ✗Senhas ou chaves de API de qualquer tipo
- ✗Dados pessoais de clientes ou colaboradores
- ✗Informações financeiras detalhadas (saldos, credenciais bancárias)
- ✗Conteúdo de acordos de sigilo (NDAs)
- ✗Propriedade intelectual confidencial de terceiros
Conceitos-chave
Tudo no soul.md chega aos modelos externos via API — trate como dado potencialmente público
Clientes e colaboradores não consentiram em ter seus dados transmitidos a modelos de IA
Fornecer apenas o contexto mínimo necessário para o Hermes ser útil
"Empresa pré-revenue" é contexto. Saldos bancários são dados — a diferença importa
✅ Checklist de segurança antes de deixar o agente em produção
O que é
Um checklist sistemático substitui a dependência de memória. Segurança que depende de lembrar é segurança que vai falhar eventualmente.
Por que aprender
✅ Checklist de produção — verificar a cada novo projeto
Confirmar que nenhuma chave está em arquivo de texto (.env, soul.md, config.json, README)
Verificar que .gitignore existe e contém .env antes de qualquer commit
Reler o soul.md e confirmar que não há nenhuma chave, senha ou token
Escopo de ferramentas definido com o mínimo necessário para a tarefa
Spend Alert configurado para o projeto específico
Hard limit no OpenRouter que bloqueia quando atingido
Verificar a data da última rotação — se acima de 90 dias, rotacionar antes de começar
Conceitos-chave
Verificação sistemática que não depende de lembrar cada ponto individualmente
Cada projeto novo = nova verificação. Não assume que o projeto anterior estava correto
O checklist existe exatamente porque memória falha — especialmente sob pressão
O momento certo é antes de colocar em produção — não depois do primeiro incidente
✅ Resumo do Módulo
Próximo Módulo:
3.5 — Resiliência — Fallbacks e recuperação de erros