Módulo 9: Agentes de IA com Chave SSH Própria, Match exec e Deploy por Repositório | Curso de Segurança para Sites

Módulo 9 · Curso de Segurança para Sites e Servidores

Agentes de IA com chave própria

Agentes de código como o Claude Code e o Codex rodam comandos no seu terminal, com o seu usuário e, se nada for feito, com a sua chave SSH. Este módulo dá a cada ferramenta uma identidade própria no servidor, faz o alerta de login dizer qual IA entrou e fecha a sua chave pessoal de um jeito que nenhuma instrução esquecida consegue abrir.

uma chave por agente Match exec FIDO2 deploy por repositório

Aula 32

Por que cada agente precisa da própria chave

Um agente de código não é um site que você visita: é um programa que lê arquivos, escreve arquivos e executa comandos no seu computador, como se fosse você. Quando ele roda ssh servidor, o SSH procura chaves no seu ~/.ssh e no seu ssh-agent, encontra a sua chave pessoal e entra. No servidor, o alerta do módulo 5 diz "root entrou com a chave do notebook pessoal". Foi você ou foi a IA? Não há como saber.

Esse problema tem três faces, e as três apareceram na auditoria que deu origem ao curso:

  • Identidade. Com uma chave só, todo acesso parece seu. O registro perde o valor justamente no dia em que você precisa dele.
  • Revogação. Se uma ferramenta se comportar mal, ou for descontinuada, você não consegue cortar só ela: teria de trocar a sua própria chave em todos os servidores.
  • Menor privilégio. O agente herda tudo o que a sua chave alcança. O OWASP chama isso de agência excessiva (LLM06): dar ao modelo mais poder do que a tarefa pede. Somado à injeção de prompt, em que um texto lido pelo agente (uma página, um issue, um comentário de código) o convence a fazer outra coisa, o resultado é um comando que você não pediu, rodando com o seu acesso.

A resposta é a mesma que o curso deu para pessoas e automações: uma identidade por quem acessa. Cada ferramenta de IA ganha um par de chaves só dela, com um comentário que diz de quem é, cadastrado nos servidores que ela pode tocar. O inventário fica assim:

Comentário da chaveOnde fica a parte secretaProteçãoQuem usa
notebook-pessoal-hellochip do computador (Windows Hello)FIDO2 com PIN ou digitalvocê, no terminal normal
agente-claudearquivo ~/.ssh/agente-claudenome próprio no alerta, revogável sozinhaClaude Code
agente-codexarquivo ~/.ssh/agente-codexnome próprio no alerta, revogável sozinhaCodex
agente-deepseekarquivo ~/.ssh/agente-deepseeknome próprio no alerta, só pela rede privadaferramenta que usa o DeepSeek
deploy-repo-exemplo-lojasegredo do repositório no GitHubcomando travado, aprovação no ambienteGitHub Actions daquele repositório

Repare que as chaves dos agentes não têm senha. Elas não precisam: o agente não teria como digitá-la, e a proteção delas é outra, a de serem só dele, aparecerem com nome no alerta e poderem ser apagadas do servidor com uma linha. Quem precisa de senha, ou de um dedo, é a chave da primeira linha. É o tema da aula 34.

Fontes desta aula: OWASP: LLM06 Excessive Agency · OWASP Top 10 para LLMs · Simon Willison: The lethal trifecta

Aula 33

Variável de ambiente e Match exec: a chave certa em cada terminal

O desafio é fazer o mesmo comando ssh servidor usar chaves diferentes conforme quem o roda, sem depender da memória de ninguém. A solução tem três peças: uma variável de ambiente fixa em cada ferramenta, um bloco Match exec no ~/.ssh/config que lê essa variável, e o cadastro das chaves no servidor.

Quem chama o ssh decide qual chave sai

Terminal normal AGENTE_IA vazia Claude Code AGENTE_IA=claude Codex AGENTE_IA=codex Ferramenta c/ DeepSeek AGENTE_IA=deepseek ~/.ssh/config Match exec lê AGENTE_IA e entrega uma única chave notebook-pessoal FIDO2: pede PIN ou dedo agente-claude agente-codex agente-deepseek Servidor authorized_keys com uma linha por chave, cada uma com seu nome Alerta (módulo 5) "root entrou com a chave agente-codex"
Ilustração do curso. Nomes de chaves e de ferramentas são exemplos.

Passo 1. Uma chave por ferramenta

# O comentário (-C) é o nome que vai aparecer no alerta de login
ssh-keygen -t ed25519 -f ~/.ssh/agente-claude   -C "agente-claude"   -N ""
ssh-keygen -t ed25519 -f ~/.ssh/agente-codex    -C "agente-codex"    -N ""
ssh-keygen -t ed25519 -f ~/.ssh/agente-deepseek -C "agente-deepseek" -N ""

Passo 2. Uma variável fixa na configuração global de cada ferramenta

A variável precisa estar na configuração global da ferramenta, e não na de um projeto, para valer em todas as pastas. O nome é livre; aqui usamos AGENTE_IA.

# Claude Code: ~/.claude/settings.json
{
  "env": { "AGENTE_IA": "claude" }
}

# Codex: ~/.codex/config.toml
[shell_environment_policy]
set = { AGENTE_IA = "codex" }

# Ferramenta sem essa opção (ex.: a que você usa com o DeepSeek):
# um script de entrada em ~/bin/agente-deepseek, usado no lugar do comando original
#!/bin/sh
export AGENTE_IA=deepseek
exec ferramenta-do-agente "$@"

Passo 3. O ~/.ssh/config escolhe a chave

# ~/.ssh/config: estes blocos ficam no TOPO do arquivo
Match exec "test \"$AGENTE_IA\" = claude"
    IdentityFile ~/.ssh/agente-claude
    IdentitiesOnly yes      # oferece só esta chave
    IdentityAgent none      # não consulta o ssh-agent, onde mora a chave pessoal

Match exec "test \"$AGENTE_IA\" = codex"
    IdentityFile ~/.ssh/agente-codex
    IdentitiesOnly yes
    IdentityAgent none

Match exec "test \"$AGENTE_IA\" = deepseek"
    IdentityFile ~/.ssh/agente-deepseek
    IdentitiesOnly yes
    IdentityAgent none

# Terminal normal: só quando a variável NÃO existe
Match exec "test -z \"$AGENTE_IA\""
    IdentityFile ~/.ssh/notebook-pessoal-hello
    IdentitiesOnly yes

# Daqui para baixo, os servidores de sempre
Host servidor-exemplo
    HostName servidor.example.com
    User root

Três detalhes fazem a diferença. Primeiro, no ssh_config vale o primeiro valor encontrado, por isso os blocos vão no topo. Segundo, o IdentityFile é a exceção a essa regra: ele se acumula, e todas as chaves listadas são tentadas em sequência. Se a chave pessoal estivesse num Host * comum, ela seria oferecida também nas sessões dos agentes. Por isso ela fica num bloco próprio, que só vale com a variável vazia. Terceiro, sem IdentitiesOnly e IdentityAgent none, o SSH ofereceria as chaves carregadas no ssh-agent, incluindo a sua.

Para conferir sem conectar, peça ao SSH a configuração final de cada cenário: AGENTE_IA=codex ssh -G servidor-exemplo | grep -i identityfile deve mostrar só a chave do Codex, e o mesmo comando sem a variável, só a pessoal. No Windows nativo, o Match exec roda no shell do sistema e a sintaxe do teste muda; no WSL, no Linux e no macOS o exemplo funciona como está.

Passo 4. O servidor reconhece cada chave pelo nome

# /root/.ssh/authorized_keys
[email protected] AAAA... notebook-pessoal-hello
ssh-ed25519 AAAA... agente-claude
ssh-ed25519 AAAA... agente-codex
from="100.64.0.0/10" ssh-ed25519 AAAA... agente-deepseek   # opcional: só pela rede privada

O script de alerta do módulo 5 já traduz a impressão digital da chave para o comentário dessa linha. Sem mudar nada nele, a mensagem passa de "root entrou com a chave do notebook pessoal" para "root entrou com a chave agente-codex, de 198.51.100.23". Se a IA que você não abriu hoje aparecer no alerta, você sabe na hora o que investigar e qual linha apagar.

Fontes desta aula: ssh_config(5): Match, IdentityFile, IdentitiesOnly · Claude Code: settings · Codex: shell_environment_policy · sshd(8): formato do authorized_keys

Aula 34

Instrução não é trava: fechando a chave pessoal

É tentador resolver tudo com uma frase no CLAUDE.md ou no AGENTS.md: "use sempre a chave agente-claude". Funciona na maior parte do tempo, e é justamente esse o problema. O modelo pode esquecer a regra numa conversa longa, entender a regra de outro jeito ou ser convencido a ignorá-la por um texto malicioso. Um controle de segurança que funciona "na maior parte do tempo" não é controle.

Mesmo a configuração da aula 33 tem um limite honesto: o agente roda com o seu usuário do sistema. Ele consegue ler ~/.ssh, apagar a variável ou chamar ssh -i ~/.ssh/chave-pessoal. A configuração separa e identifica, mas quem fecha a porta é um segredo que o agente não tem.

Três camadas, três forças diferentes

1. Instrução em texto CLAUDE.md, AGENTS.md o modelo pode esquecer 2. Configuração variável + Match exec separa e identifica cada IA mas o agente roda como você e pode contornar 3. Segredo que o agente não tem chave pessoal com senha ou FIDO2 (toque, PIN, digital) sem você presente, a chave pessoal não abre só esta camada é uma trava
Ilustração do curso. As camadas se somam: a instrução ajuda o agente a acertar, a configuração identifica e o segredo impede.

Na prática, há duas formas de criar esse segredo, e a segunda é a melhor:

# Opção A: pôr senha numa chave pessoal em arquivo que já existe
ssh-keygen -p -f ~/.ssh/chave-pessoal
# Se usar ssh-agent, carregue com confirmação a cada uso:
ssh-add -c ~/.ssh/chave-pessoal

# Opção B (recomendada): chave pessoal FIDO2, como no módulo 4
ssh-keygen -t ed25519-sk -O verify-required -C "yubikey-pessoal"
ssh-keygen -t ecdsa-sk -C "notebook-pessoal-hello"     # Windows Hello

A senha sozinha tem uma armadilha: se a chave ficar carregada no ssh-agent sem confirmação, qualquer programa da sua sessão usa a chave sem pedir nada, inclusive o agente de IA. Por isso o -c no ssh-add, que pede um "sim" na tela a cada uso. Com FIDO2 e verify-required, cada login exige PIN, digital ou um toque físico, e nenhum processo consegue fazer isso por você. No Codex, ainda é possível tirar o acesso ao ssh-agent da sessão excluindo a variável SSH_AUTH_SOCK nos filtros da shell_environment_policy.

Comparando as três abordagens

Escala de 1 (fraco) a 5 (forte) em cada critério.

Avaliação qualitativa do curso, a partir da documentação do OpenSSH e do guia de agência excessiva do OWASP.

O gráfico mostra por que as duas peças andam juntas. Só a chave por agente resolve identidade e revogação, mas não segura um agente que decide usar a sua chave. Só a FIDO2 segura a sua chave, mas deixa os acessos da IA sem nome. Juntas, cada IA entra com o próprio nome e nenhuma entra com o seu.

Fontes desta aula: ssh-add(1): opção -c · ssh-keygen(1) · Codex: filtros de ambiente

Aula 35

Deploy: uma chave por repositório

O mesmo raciocínio vale para a automação. No módulo 6, o deploy entra por uma chave que só consegue chamar um script fixo. Se vários sites moram no mesmo servidor e todos usam a mesma chave de deploy, o alerta diz apenas "deploy rodou", a chave vazada de um projeto publica qualquer outro, e trocar a chave obriga a mexer em todos os repositórios de uma vez.

A correção é dar a cada repositório a sua chave, guardada como segredo só daquele repositório no GitHub, e amarrar no servidor o nome do projeto à chave, e não ao que o cliente pede:

# /home/deploy/.ssh/authorized_keys
command="/usr/local/bin/deploy-site exemplo-loja",restrict ssh-ed25519 AAAA... deploy-repo-exemplo-loja
command="/usr/local/bin/deploy-site exemplo-blog",restrict ssh-ed25519 AAAA... deploy-repo-exemplo-blog
#!/bin/sh
# /usr/local/bin/deploy-site: o projeto vem da chave ($1), nunca do cliente
set -eu
PROJETO="$1"
PEDIDO="${SSH_ORIGINAL_COMMAND:-}"
echo "$PEDIDO" | grep -Eq '^(producao|teste) [0-9a-f]{40}$' || { echo "pedido inválido" >&2; exit 1; }
set -- $PEDIDO
/usr/local/bin/avisar "deploy de $PROJETO ($1) no commit $2"   # alerta com o nome do repositório
exec flock -n "/run/deploy-$PROJETO.lock" /opt/deploy/"$PROJETO".sh "$1" "$2"

Agora o servidor sabe qual repositório pediu o deploy porque a chave diz, e o alerta mostra "deploy de exemplo-loja (producao) no commit 3f9c...". A chave do blog só publica o blog, mesmo que alguém tente pedir outra coisa, e revogar uma é apagar uma linha. Combinado com a aprovação de ambiente do GitHub (módulo 6), nenhum deploy acontece sem alguém clicar em aprovar, e nenhum acontece sem nome.

Fontes desta aula: sshd(8): command= e restrict · GitHub: managing deploy keys

Erros comuns

  • Confiar só na instrução em texto. O CLAUDE.md ajuda o agente a acertar, mas não impede que ele erre. A trava é a configuração mais o segredo da chave pessoal.
  • Pôr os blocos Match no fim do ~/.ssh/config. Um Host * acima deles vence. Eles vão no topo.
  • Deixar a chave pessoal num Host * comum. Como o IdentityFile se acumula, ela seria oferecida também nas sessões dos agentes.
  • Esquecer o ssh-agent. Sem IdentitiesOnly e IdentityAgent none, o SSH oferece as chaves carregadas no agente, inclusive a sua.
  • Variável só na configuração de um projeto. Em outra pasta, a variável some e a ferramenta volta a usar a chave pessoal. Use a configuração global.
  • Uma chave de deploy para todos os sites. Uma chave vazada publica qualquer um, e o alerta não diz qual.

Aplicação prática

  1. Liste as ferramentas de IA que você usa e que rodam comandos no terminal. Para cada uma, gere uma chave com o comentário agente-nome.
  2. Fixe a variável AGENTE_IA na configuração global de cada ferramenta e monte os blocos Match exec no topo do ~/.ssh/config.
  3. Teste com ssh -G, com e sem a variável, e confira que cada cenário mostra uma única chave.
  4. Cadastre as chaves no servidor, abra uma sessão por cada ferramenta e confira se o alerta mostra o nome certo.
  5. Feche a chave pessoal com FIDO2 (ou, no mínimo, senha e ssh-add -c). Peça a um agente para rodar ssh -i com a sua chave e veja o pedido de PIN ou de toque aparecer.
  6. Exercício de revisão: no seu servidor, conte quantas chaves de deploy existem e quantos repositórios publicam nele. Se os números forem diferentes, você já sabe o que fazer.

Siglas usadas neste módulo

IA:
Inteligência Artificial, aqui, os agentes de código que rodam comandos no seu computador.
LLM:
Large Language Model, modelo de linguagem de grande porte, o motor dos agentes de IA.
CLI:
Command-Line Interface, programa usado pelo terminal, como o Claude Code e o Codex.
SSH:
Secure Shell, protocolo de acesso remoto seguro a servidores.
FIDO2:
Fast IDentity Online 2, padrão de autenticação com chaves guardadas em dispositivos.
PIN:
Personal Identification Number, código numérico pessoal.
OWASP:
Open Worldwide Application Security Project, fundação que publica guias abertos de segurança, como o Top 10 para LLMs.

Perguntas frequentes

Por que não basta escrever no CLAUDE.md ou no AGENTS.md que o agente deve usar a chave dele?
Porque instrução em texto é um pedido, não uma trava. O modelo lê o arquivo no começo da sessão, mas pode esquecer a regra numa conversa longa, interpretá-la de outro jeito ou ser convencido a ignorá-la por um texto malicioso que leu no caminho, como uma página, um issue ou um comentário de código. A separação precisa estar na configuração (variável de ambiente e ~/.ssh/config) e, para fechar de verdade, num segredo que o agente não tem: a senha ou o toque da sua chave pessoal.
A chave de cada agente precisa ter senha?
Normalmente não, porque o agente não tem como digitá-la, e uma senha guardada em arquivo para ele ler não protege nada. A chave do agente é protegida de outro jeito: ela é só dele, aparece com nome próprio no alerta de login, pode ser revogada sozinha e, se você quiser, só funciona pela rede privada (opção from= no authorized_keys). Quem precisa de senha ou FIDO2 é a sua chave pessoal, para que o agente não consiga usá-la.
O que o Match exec faz, e por que ele vai no topo do ~/.ssh/config?
O Match exec roda um comando curto antes de cada conexão e aplica o bloco se o comando terminar com sucesso. Aqui o comando só testa se a variável AGENTE_IA tem um valor. Ele vai no topo porque, no ssh_config, vale o primeiro valor encontrado para quase todas as opções: um bloco Host * mais acima venceria. A exceção é o IdentityFile, que se acumula; por isso a chave pessoal fica num bloco próprio, que só vale quando a variável não existe.
Funciona com qualquer ferramenta de IA, como Codex ou as que usam o DeepSeek?
Funciona com qualquer ferramenta que rode comandos no seu terminal, porque a separação acontece no SSH, e não na ferramenta. O que muda é como fixar a variável: o Claude Code aceita um bloco env no settings.json, o Codex aceita set na seção shell_environment_policy do config.toml, e uma ferramenta sem essa opção pode ser aberta por um pequeno script que exporta a variável e chama o programa. Confira a documentação da ferramenta que você usa, porque os nomes das opções mudam entre versões.
Se eu já uso uma chave por agente, ainda preciso de uma chave por repositório no deploy?
Sim, porque são acessos diferentes. A chave do agente é usada quando a IA abre uma sessão no servidor durante o seu trabalho. A chave de deploy é usada pela automação do GitHub, sem ninguém presente, e só consegue chamar o script de deploy. Com uma chave por repositório, o alerta diz qual projeto publicou, a chave vazada de um projeto não publica outro e você revoga um sem parar os demais.