Skip to content

Quais Chaves Estão ao Alcance do Seu Agente?

Published:
4 min de leitura Suggest Changes

Criei o heldkeys, uma CLI open source que mostra quais credenciais um agente de IA consegue usar a partir de onde ele roda: seu laptop, um sandbox ou um job de CI. Um agente de código no seu terminal roda como você, então ele alcança seus logins de nuvem, seus tokens de git e de pacotes, os arquivos .env de todo repositório que você clonou e as chaves de API esquecidas nas suas configs MCP. Isso não é problema até que um prompt injection numa issue, numa página web ou num README convença o agente a rodar um comando. Scanners de segredos dizem o que foi commitado num repositório. O heldkeys diz o que um processo rodando como você conseguiria usar agora.

Para começar

brew install hugomn/tap/heldkeys
heldkeys

Rode no mesmo terminal que o seu agente usa. Ele só lê, não faz chamadas de rede e termina em bem menos de um segundo. Este é o resultado numa máquina de teste montada com as credenciais falsas do repositório:

heldkeys listando as credenciais que um agente alcançaria numa máquina de teste, com o que resolver primeiro
heldkeys numa máquina de teste

O relatório cabe em uma tela. Primeiro vêm as credenciais para resolver logo, ordenadas pelo tempo que cada uma continua valendo e por conseguir ou não alterar coisas, já que um token de longa duração com permissão de escrita é um risco bem maior que uma sessão curta só de leitura. Depois vêm onde estão as demais, os segredos que aparecem em vários lugares e próximos passos concretos. O heldkeys --details lista tudo, e --format json, markdown ou sarif alimentam outras ferramentas.

Ele procura onde as credenciais realmente ficam: variáveis de ambiente, logins de AWS, gcloud, Azure e kubeconfig, arquivos e helpers de credenciais do git, a CLI do GitHub, tokens de registry do npm, PyPI, cargo e Docker, chaves SSH sem passphrase, logins de ferramentas de IA como Codex e Claude Code, arquivos .env do projeto (inclusive cópias antigas no histórico do editor) e tokens nas configs MCP do Claude, Cursor, VS Code e outros.

Como trava de segurança num sandbox

Se os seus agentes rodam num container, o mesmo binário verifica o que o sandbox expõe por dentro, como um socket do Docker montado, um token de service account do Kubernetes ou um endpoint de metadata de nuvem acessível. O heldkeys preflight transforma isso num teste de passa ou falha, que você coloca na frente do agente no entrypoint:

COPY --chmod=0755 heldkeys /usr/local/bin/heldkeys
ENTRYPOINT ["/bin/sh", "-c", "heldkeys preflight --fail-on long-lived-write && exec \"$@\"", "heldkeys-gate"]
CMD ["your-agent", "--its-flags"]

Quando o sandbox guarda uma credencial que não deveria, o container se recusa a subir e explica o motivo:

heldkeys preflight falhando porque o sandbox guarda credenciais de escrita de longa duração
heldkeys preflight num sandbox

Os binários para Linux são estáticos, então isso funciona em qualquer imagem, inclusive distroless. Também dá para verificar um container que já está rodando com heldkeys scan --docker <container> ou --kube <pod>.

No CI

Acho que o risco mais novo está no GitHub Actions. Times estão colocando agentes em workflows que reagem a comentários de issues e pull requests, e alguns entregam ao agente um token de escrita ou os segredos do repositório enquanto ele lê texto que qualquer pessoa na internet pode escrever. O heldkeys ci lê os seus arquivos de workflow e aponta essa combinação: passos de agentes em gatilhos não confiáveis com segredos ou permissões de escrita, agentes trabalhando dentro de um checkout de pull request externo, actions de agentes sem pin de versão e acesso irrestrito ao shell. Rodando dentro de um job, ele também lista o que esse job alcança.

O jeito mais fácil de rodar é a GitHub Action:

jobs:
  heldkeys:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: hugomn/heldkeys@v0

Num workflow que roda o Claude Code em comentários de issues, com token de escrita, chaves de nuvem e checkout do pull request, o resultado é este:

heldkeys ci apontando um passo de agente de IA num workflow do GitHub
heldkeys ci num workflow de agente arriscado

Para segurança de workflows em geral, o zizmor já faz um ótimo trabalho, então o heldkeys só tem regras para passos de agentes.

O que ele encontrou na minha máquina

Rodei primeiro no meu próprio laptop, e ele achou o que vai se acumulando com os anos: um arquivo antigo de credenciais do git em texto puro, um token exportado no meu perfil do shell e chaves SSH sem passphrase. Eu não teria lembrado de nenhum desses itens, e qualquer agente que eu iniciasse poderia usá-los. A limpeza levou uns vinte minutos. O git agora usa o keychain do sistema, o token de pacotes só é carregado nos projetos que precisam dele e as chaves ganharam passphrase.

Por que confiar nele com os seus segredos

Uma ferramenta que lê todas as credenciais da sua máquina precisa conquistar essa confiança. Os valores só aparecem como fingerprints curtos, tipo ghp_…021, e um teste passa todas as fixtures por todos os formatos de saída e falha se qualquer pedaço de um segredo falso vazar. Não há telemetria nem checagem de atualização, ele nunca chama os provedores por trás das suas credenciais e não escreve nada na sua máquina. O threat model explica do que ele protege e o que fica fora do alcance dele, como sessões do navegador, segredos que só existem dentro do keychain do sistema e o histórico do git, onde gitleaks e TruffleHog são as ferramentas certas.

Se você rodar, adoraria saber o que ele encontrou e quais lugares de credenciais ele deveria aprender a verificar. Issues e pull requests são bem-vindos no GitHub.