Fixação de versão para clientes de agentes antes do acesso sensível

Um cliente de agente local não deve receber acesso a serviços sensíveis apenas porque seu nome aparece em uma lista de ferramentas aprovadas. O executável, o runtime, as extensões e a forma como ele é iniciado determinam o que fará a solicitação. Se qualquer um desses elementos mudar, você terá um assunto de segurança diferente, mesmo que o título da janela e o nome do comando pareçam familiares.

A fixação de versão para clientes de agentes é uma prática de controle de lançamentos, não uma cura para prompts ruins ou permissões excessivas. Ela oferece uma propriedade útil: você pode testar um artefato conhecido, registrar o que testou e recusar acesso sensível a uma substituição não revisada. Parece algo básico. Ainda assim, evita um número surpreendente de falhas que poderiam ser prevenidas.

Já vi equipes investirem muito em cofres e diálogos de aprovação e, depois, permitirem que um atualizador de desktop substituísse durante a noite o programa que fazia essas solicitações. Ainda havia uma pessoa no circuito, mas ela estava aprovando o comportamento de um código que ninguém havia avaliado. Isso não é uma fronteira de segurança significativa.

Fixe a identidade do executável, não um rótulo amigável de versão

Um número de versão exato é necessário, mas sozinho não identifica bem um cliente local. Um rótulo de lançamento como 2.4.1 informa o que o fornecedor pretendia distribuir. Ele não prova quais bytes foram instalados, quem os assinou, qual runtime os iniciou ou se uma extensão alterou seu comportamento depois da inicialização.

Um registro de aprovação útil identifica o artefato em várias camadas:

• O nome do cliente e a string exata da versão.
• O digest SHA-256 do instalador ou executável baixado.
• A autoridade de assinatura de código e o identificador do pacote, quando o sistema operacional os disponibilizar.
• O caminho de instalação, a versão do runtime e o inventário de extensões.
• A data, o revisor e os serviços ou escopos de credenciais aprovados para esse registro.

A diferença entre uma fixação de versão e uma fixação de artefato importa. A primeira informa ao instalador qual versão ele deve procurar. A segunda permite rejeitar um arquivo diferente daquele que você testou. As equipes costumam misturar os termos porque os gerenciadores de pacotes usam a palavra «fixação» para os dois casos. O resultado é ruim: aprovam 1.4.3, recebem uma versão recompilada 1.4.3 de um espelho comprometido ou de um cache alterado e não têm nenhum teste local que perceba a diferença.

Uma identidade de assinatura acrescenta outra verificação, mas não substitui um digest. Um fornecedor legítimo pode assinar uma versão ruim, e um digest sozinho não informa se o arquivo veio do fornecedor esperado. Registre os dois quando o cliente tiver acesso a sistemas de produção.

Não transforme isso em burocracia por si só. O registro precisa responder a uma pergunta durante um incidente: «Qual código tinha permissão para enviar essa solicitação?» Se ele disser apenas «o agente de programação», não poderá responder.

Uma árvore de dependências bloqueada é diferente de um cliente revisado

Lockfiles ajudam, mas resolvem um problema mais limitado do que muitas equipes imaginam. Um lockfile de pacote seleciona versões de dependências para uma instalação específica. Ele não inspeciona módulos nativos, não verifica todas as ações pós-instalação, não impede que um runtime carregue código de um diretório do usuário e não estabelece que o executável iniciado é o artefato examinado pelo revisor.

Isso é especialmente importante para clientes distribuídos por ecossistemas de linguagens. Um comando que parece ser um único programa pode, na verdade, ser um pequeno iniciador, um runtime, uma árvore de pacotes e um ou mais plugins baixados. Fixar apenas o pacote de nível superior pode deixar a maior parte da decisão de confiança sem controle.

A especificação OpenSSF SLSA traça uma distinção útil entre procedência e integridade. A procedência descreve onde e como um artefato foi compilado. As verificações de integridade estabelecem que um artefato não foi alterado. Nenhuma dessas afirmações significa que o programa é seguro para receber credenciais. As duas continuam importantes porque uma equipe não pode revisar nem reproduzir um alvo que muda.

Comece mapeando o que é executado quando um desenvolvedor inicia o agente. No macOS, consulte o shell em vez de confiar em um ícone do Dock:

command -v agent-client
file "$(command -v agent-client)"
head -n 1 "$(command -v agent-client)"

O comando head importa quando o primeiro resultado é um script. Uma primeira linha como #!/usr/bin/env node informa que o runtime Node e a árvore de pacotes fazem parte do caminho de execução. Uma primeira linha que delega a outro iniciador significa que você precisa continuar rastreando. Não aprove um alias de shell, um link simbólico ou um script de inicialização como se fosse o cliente.

Para um pacote de aplicativo, inspecione o executável real e os metadados de assinatura:

APP="/Applications/Agent Client.app"
BIN="$APP/Contents/MacOS/Agent Client"
shasum -a 256 "$BIN"
codesign -dv --verbose=4 "$APP" 2>&1 | grep -E 'Identifier=|TeamIdentifier=|Authority='
spctl --assess --type execute --verbose=4 "$APP"

A saída do hash tem o formato digest path. A saída de codesign normalmente inclui um identificador, um identificador de equipe e uma ou mais linhas de autoridade. Salve essa saída com o registro de aprovação. O spctl pede ao macOS que avalie o aplicativo de acordo com a política de segurança atual. É uma evidência útil, mas não significa que o aplicativo merece acesso a uma credencial de implantação.

Uma revisão que diz «o lockfile está versionado» deixa perguntas demais sem resposta. Mantenha o lockfile. Depois identifique o artefato que realmente inicia as ações sensíveis.

A compatibilidade de protocolo não estabelece a confiança no cliente

Um cliente pode falar corretamente um protocolo de agentes e ainda assim ser inadequado para acesso sensível. A compatibilidade de protocolo responde se dois programas conseguem trocar mensagens. A confiança no cliente responde se aquele programa específico, iniciado naquele estado específico, pode solicitar uma ação respaldada por credencial.

A documentação do Model Context Protocol descreve um cliente e um servidor trocando capacidades declaradas durante a inicialização. Essa negociação é útil para a interoperabilidade. Ela não atesta o binário do cliente, não informa quais extensões foram carregadas nem promete que o cliente preservará a intenção do usuário. Não trate um handshake bem-sucedido como uma verificação de identidade.

Essa confusão aparece quando as equipes permitem que qualquer cliente local compatível com MCP invoque uma ferramenta sensível porque a ferramenta tem um nome de servidor conhecido. O servidor MCP vê uma solicitação por um canal de protocolo. Ele pode saber pouco sobre o programa que construiu a solicitação. Um cliente malicioso ou simplesmente desconhecido pode usar os mesmos nomes de métodos que um cliente testado.

Mantenha três registros separados:

1. A versão do protocolo e as capacidades que você testou.
2. O artefato do cliente, a identidade de assinatura, o runtime e as extensões que você aprovou.
3. As permissões de serviço que o cliente pode solicitar.

Uma mudança em qualquer um desses registros merece revisão. Uma atualização de protocolo pode alterar padrões ou o tratamento de mensagens. Uma atualização do cliente pode alterar quais ferramentas ele chama ou quando repete uma solicitação. Uma mudança de permissão do serviço pode tornar destrutiva uma repetição antes inofensiva.

Há outra distinção que costuma ser esquecida: fixar um cliente não fixa as instruções de um agente. O prompt do usuário, os arquivos do repositório, as descrições das ferramentas, o conteúdo remoto e a saída do modelo podem influenciar um cliente fixado. A fixação limita as surpresas causadas pela substituição do software. Ela não torna seguro o uso arbitrário de ferramentas. Coloque um ponto de aprovação humana diante de ações cujas consequências não possam ser facilmente desfeitas.

Teste o caminho das permissões, não apenas a janela de conversa

Um cliente candidato só passa pela revisão depois de se comportar corretamente em todo o caminho de acesso que você pretende permitir. Pedir que ele resuma um repositório ou crie um arquivo temporário prova que a interface funciona. Não testa a injeção de credenciais, o comportamento de aprovação, as repetições, os redirecionamentos, as verificações de hosts SSH nem o que o cliente faz depois que uma ferramenta retorna um erro.

Use um serviço de homologação ou uma credencial de teste criada para esse fim, com escopo limitado. A credencial deve demonstrar a ação, mas não poder alterar dados de produção, rotacionar segredos compartilhados ou acessar contas não relacionadas. Se você não consegue criar uma credencial assim, o serviço é amplo demais para um cliente autônomo e merece uma discussão própria sobre desenho de acesso.

Teste estes casos deliberadamente:

• Uma solicitação permitida comum, com a resposta esperada.
• Uma solicitação que excede o escopo da credencial e recebe uma recusa.
• Um atraso de resposta ou falha de conexão que acione uma nova tentativa.
• Um redirecionamento ou endpoint alterado, se o cliente usar HTTP.
• Uma conexão SSH com uma chave de host alterada, se o cliente usar SSH.

Os dois últimos casos revelam comportamentos que frequentemente surpreendem as pessoas. Clientes HTTP podem seguir redirecionamentos, e um redirecionamento pode enviar uma solicitação para outro host. O envio das credenciais depende do cliente e da implementação da autenticação. Você precisa observar o comportamento, não deduzi-lo a partir de uma nota de lançamento. Clientes SSH devem tratar uma divergência na chave do host como uma condição de parada até que uma pessoa resolva a alteração. Um agente não deve decidir que uma chave de host desconhecida é aceitável apenas porque a tarefa pede que ele continue.

Capture metadados das solicitações sem registrar segredos. Para HTTP, um endpoint de teste pode registrar método, host, caminho, status e alguns cabeçalhos não secretos. Confirme qual cabeçalho de autorização o gateway adiciona e depois confirme que o cliente nunca recebe esse valor de volta em um resultado de ferramenta, mensagem de erro ou transcrição local.

Para um endpoint destrutivo, faça com que a operação de homologação deixe uma marca reconhecível. Um teste que apenas retorna HTTP 200 prova pouco. Você precisa de evidências de que exatamente uma ação intencional ocorreu, de que a ação errada não aconteceu depois de uma nova tentativa e de que o registro de auditoria identifica a sessão correta.

Mantenha o candidato isolado do cliente aprovado

Uma versão candidata precisa de instalação, configuração, caches e diretórios de extensões próprios. Compartilhar esses diretórios dá à compilação de teste acesso a um estado que pode ser diferente de uma instalação limpa e torna o rollback menos confiável. As falhas mais irritantes que já investiguei vieram de um cliente «novo» carregando silenciosamente um plugin antigo ou reutilizando uma sessão autenticada do navegador.

No macOS, contas de usuário separadas oferecem a fronteira mais limpa para um teste sério. Uma conta separada muda o diretório pessoal, os diretórios de suporte de aplicativos, os caches, os itens de login e muitos armazenamentos de credenciais. Para um teste rápido de desenvolvimento, diretórios separados podem funcionar se o cliente documentar como selecionar cada caminho e você verificar que ele os respeita.

Não aponte as duas versões para um único arquivo de configuração com permissão de escrita. Os clientes frequentemente atualizam os formatos de configuração na inicialização. A compilação mais nova pode gravar campos que a antiga ignora ou trata mal. Isso transforma o rollback em uma migração parcial, justamente quando você precisa que ele seja previsível.

Trate as extensões com a mesma desconfiança que o cliente. Registre suas versões exatas, locais de origem, hashes quando possível e se o cliente pode buscar atualizações automaticamente. Se o cliente descobrir extensões em um diretório amplo, como uma pasta de plugins no nível do usuário, o teste candidato deve começar com esse diretório vazio. Adicione apenas as extensões necessárias para o teste.

Um teste limpo também expõe um problema menos glamoroso: dependências não documentadas. Se o candidato só funciona depois de herdar variáveis de ambiente, cookies do navegador, funções do shell ou um cache global de pacotes da configuração aprovada, documente essas entradas. Cada dependência oculta torna mais difícil reproduzir o comportamento depois.

Transforme a promoção em uma pequena mudança de lançamento repetível

A promoção deve substituir um registro revisado por outro, não depender de alguém lembrar em qual botão de download clicou. Escreva a mesma sequência todas as vezes. Ela dá aos revisores um vocabulário comum e ao engenheiro de plantão um caminho sensato de rollback.

1. Baixe o candidato pelo canal normal de lançamentos do fornecedor e registre a origem, a versão exata, o hash e o signatário.
2. Instale-o no local de teste isolado e registre o runtime e as extensões carregadas.
3. Execute os testes do caminho de permissões com credenciais de homologação, incluindo casos recusados e de falha.
4. Compare as solicitações, os prompts e os logs observados com o comportamento aprovado. Investigue toda nova solicitação de privilégio.
5. Instale o candidato aprovado no local privilegiado, preserve o artefato anterior e só altere o acesso depois que as verificações da instalação corresponderem ao registro.

A ordem final importa. Não conceda acesso primeiro para planejar a inspeção do arquivo instalado depois. Se a verificação da instalação falhar, mantenha o candidato sem capacidade de chamar serviços sensíveis. Rejeitar uma versão é um resultado rotineiro, não uma falha do processo.

Use um registro simples que possa ficar junto das suas anotações operacionais. YAML funciona porque as pessoas conseguem lê-lo durante um incidente:

client:
  name: agent-client
  version: "2.4.1"
  executable_sha256: "replace-with-verified-digest"
  signer_team_id: "record-the-observed-team-id"
  install_path: "/Applications/Agent Client.app"
  runtime: "native bundle"
review:
  tested_on: "2025-03-08"
  reviewer: "initials"
  extensions: []
access:
  environments: ["staging", "production-read"]
  forbidden_actions: ["secret-rotation", "deployment-write"]
rollback:
  previous_version: "2.4.0"

Os valores acima são exemplos, não um modelo que possa ser copiado como evidência. Preencha-os a partir da sua própria inspeção. Em especial, nunca cole um digest de um anúncio de lançamento sem calcular o hash do arquivo que você baixou.

Evite regras amplas como «todas as versões deste fornecedor estão permitidas». Elas são populares porque reduzem o trabalho de revisão. Também apagam o controle exato oferecido pela fixação. A identidade do fornecedor pode ser uma entrada da revisão, mas não é uma autorização permanente para que código desconhecido use suas credenciais de produção.

Atualizações automáticas e acesso sensível não devem compartilhar a mesma fronteira

Atualizações automáticas fazem sentido para muitos aplicativos de desktop. O risco muda quando o aplicativo pode causar ações externas por meio de credenciais armazenadas, chaves SSH ou contas de serviço privilegiadas. Nesse caso, um atualizador pode alterar o programa que solicita autorização entre um dia útil e o seguinte.

Há três padrões viáveis. O mais seguro é desativar a substituição automática da instalação privilegiada e promover as versões manualmente. Outra opção é permitir que desenvolvedores usem cópias atualizadas automaticamente, sem acesso sensível, enquanto uma cópia fixada cuida do trabalho privilegiado. A terceira é colocar a fronteira da ação fora do cliente, de modo que cada novo processo precise receber autorização nova antes de fazer qualquer coisa importante.

O terceiro padrão limita os danos de uma atualização inesperada, mas não exagere sua proteção. Um cartão de aprovação novo só é útil se identificar o processo de forma significativa. Ver um nome genérico de cliente e clicar nele toda manhã ensina as pessoas a aprovar qualquer coisa que apareça. Mostre a autoridade de assinatura, o caminho do processo ou outra evidência de identidade que o revisor possa comparar com o registro aprovado.

Não permita silenciosamente um cliente atualizado só porque ele veio de uma loja de aplicativos do sistema operacional ou porque o macOS o considera assinado. Esses mecanismos reduzem alguns riscos da cadeia de fornecimento. Eles não dizem se o novo comportamento corresponde às suas regras de acesso. Sua organização continua responsável pela decisão de conceder as credenciais.

A fixação de versão também precisa de uma rotina de expiração. Uma fixação permanente se torna uma fixação sem correções. Defina uma periodicidade de revisão com base no cliente, nos serviços que ele pode acessar e nos avisos de segurança do fornecedor. A revisão não precisa ser dramática quando o comportamento não mudou. Mas precisa ser uma decisão deliberada.

A autorização por ação captura o comportamento que a fixação não consegue

Um cliente fixado ainda pode receber instruções maliciosas por meio de um repositório, uma descrição de issue, uma página da web ou um resultado de ferramenta. Também pode tomar uma decisão ruim dentro das permissões concedidas para um trabalho legítimo. A autorização humana deve se concentrar em ações com efeitos relevantes, como gravar dados de produção, alterar a infraestrutura, transferir dados para um novo destino ou abrir uma sessão SSH em um host sensível.

Os prompts de aprovação falham quando pedem que as pessoas aprovem ruído técnico. Um prompt que aparece para toda leitura inofensiva ensina o usuário a clicar. Um prompt que aparece depois que a solicitação já ocultou seu destino também ajuda pouco. Mostre a ação, o destino, o método e a identidade da credencial antes que o gateway envie a solicitação. Mantenha o número de opções pequeno o suficiente para que uma pessoa consiga avaliá-las.

Uma divisão prática é permitir leituras de baixo risco por meio de uma aprovação de sessão e exigir aprovação explícita para ações que possam alterar o estado ou expor dados. A fronteira depende do serviço. Uma leitura em um repositório de código pode ser comum. Uma leitura em um banco de dados de clientes pode representar divulgação de dados. Não classifique ações apenas pelo verbo HTTP.

O Sallyport usa uma sequência fixa de decisões: o cofre recusa todas as ações enquanto está bloqueado, um novo processo de agente exige autorização de sessão por padrão e entradas selecionadas de credenciais podem exigir aprovação a cada uso. Esse modelo estreito é intencional. Uma linguagem geral de políticas ofereceria mais opções, mas também daria às equipes mais maneiras de escrever acidentalmente uma exceção que não compreendem.

Torne a revogação imediata. Quando um cliente candidato agir de modo inesperado, você deve conseguir interromper sua sessão de acesso atual antes de iniciar uma investigação longa. Revogar a credencial do serviço pode ser necessário mais tarde, mas é uma resposta ampla que pode interromper trabalhos não relacionados. A revogação da sessão contém primeiro o processo em execução.

Os registros de auditoria precisam relacionar a ação à execução aprovada

Um log de ação que diz «a chamada da API foi bem-sucedida» não basta para o trabalho com agentes. Você precisa relacionar a chamada ao processo local, à decisão de aprovação, à credencial usada e ao registro do cliente vigente naquele momento. Caso contrário, a investigação de um incidente acabará tentando combinar horários em terminais, histórico do navegador e logs do serviço.

Mantenha um registro de sessão para cada processo de agente. Ele deve incluir quando o processo começou, como o usuário o autorizou, sua identidade observada e quando terminou ou foi revogado. Mantenha um registro de atividade separado para cada ação. Esse registro deve identificar o destino, a operação, o resultado e a sessão associada, sem incluir material secreto.

A evidência contra adulteração importa porque um agente pode gerar muito trabalho em pouco tempo, e logs locais são fáceis de editar depois de um erro. Uma cadeia de hashes torna a exclusão ou alteração detectável quando alguém verifica a sequência. Ela não impede que uma máquina comprometida realize ações. Oferece aos investigadores uma base melhor para detectar um histórico reescrito.

O Sallyport projeta seus diários de Sessões e Atividades a partir de um único log de auditoria criptografado e encadeado por hashes, e sp audit verify pode verificar a cadeia offline sobre o texto cifrado, sem uma chave do cofre. Esse desenho é útil quando a pessoa que revisa o histórico não deve receber acesso aos segredos usados nas ações.

Teste o caminho de auditoria durante a promoção. Aprove uma sessão de homologação, faça uma solicitação permitida e uma recusada, revogue a sessão e verifique se os registros identificam os quatro eventos. Se os seus registros não conseguirem mostrar a solicitação recusada ou a revogação, falta informação que se torna importante justamente quando o comportamento dá errado.

A fixação falha quando o sistema ao redor continua mutável

Um cliente cuidadosamente submetido a hash ainda é executado em uma máquina que pode mudar por baixo dele. O sistema operacional, o runtime, o ambiente do shell, a configuração de DNS, as configurações de proxy, os armazenamentos de certificados, os binários auxiliares locais e as extensões instaladas pelo desenvolvedor afetam a forma como as solicitações deixam a máquina. A fixação é um controle em uma cadeia, não um rótulo que você cola em uma configuração arriscada.

Comece pelas partes que podem alterar ações privilegiadas sem mudar o digest do cliente. Inspecione as variáveis de ambiente usadas para selecionar endpoints, o comportamento do proxy ou os locais das credenciais. Verifique qual binário SSH ou auxiliar o cliente invoca. Registre o local pretendido para known-hosts e confirme que o teste rejeita uma identidade de servidor desconhecida. Analise se a configuração permite a execução de comandos locais arbitrários como ferramenta.

Não resolva toda incerteza construindo um mecanismo de políticas. A maioria das equipes precisa de menos peças móveis, não de um grande conjunto de regras que ninguém consegue explicar às duas da manhã. Uma lista curta de destinos permitidos, credenciais limitadas, aprovações explícitas para chamadas sensíveis e um artefato de cliente conhecido cobrem mais situações do que uma coleção elaborada de condições não testadas.

O hábito operacional é simples: quando um cliente muda, o acesso pausa até que o novo artefato o mereça. Mantenha a cópia antiga aprovada disponível, teste a substituição contra o caminho real de permissões e registre as evidências. Essa disciplina é menos empolgante do que demonstrações autônomas. Também é o que impede que uma atualização em segundo plano se transforme em uma alteração de produção não revisada.