Verificações de integridade do gateway de ações de um agente local

Um gateway de ações local só está saudável quando consegue recusar a ação errada, executar a ação controlada certa e deixar evidências que resistam a uma revisão. Um monitor de processos verde prova quase nada disso. Ele informa que algo tem um PID. Não informa se o cofre está bloqueado, se um agente consegue alcançar o gateway, se as credenciais injetadas ainda funcionam ou se o registro de auditoria gravou a chamada.

Essa diferença importa com o Sallyport porque o app, o cofre, a decisão de autorização, a ação externa e o registro de auditoria criptografado são pontos de falha separados. Tratá-los como um único sinal genérico de «integridade» cria o pior tipo de monitor: aquele que continua verde enquanto o controle em que você confia deixou de funcionar.

Monte isso como uma pequena suíte de aceitação, não como um amontoado de verificações de porta. A suíte deve usar destinos de canário inofensivos, retornar evidências não secretas e classificar corretamente um cofre bloqueado. Se uma pessoa precisar desbloquear o cofre com Touch ID, o monitor deve informar esse estado claramente, em vez de tentar contorná-lo.

Um app em execução é apenas a primeira condição

Uma sonda de disponibilidade deve responder a uma pergunta específica: o Mac local consegue iniciar e manter o app do gateway em execução? Ela não deve fingir que um processo em execução prova que as ações externas funcionam.

Para um app de barra de menus, comece com uma verificação local que um supervisor possa executar sem credenciais. O nome exato do processo e o local de instalação podem variar conforme a versão, portanto mantenha esses valores em um único arquivo de configuração local, em vez de espalhá-los pelos scripts. Uma sonda básica de shell pode ser assim:

#!/bin/sh
set -eu

APP_NAME="Sallyport"

if ! pgrep -x "$APP_NAME" >/dev/null 2>&1; then
  open -a "$APP_NAME"
  sleep 2
fi

if pgrep -x "$APP_NAME" >/dev/null 2>&1; then
  printf 'app=ready\n'
  exit 0
fi

printf 'app=unavailable\n' >&2
exit 2

Essa sonda faz uma afirmação deliberadamente modesta. open -a pede ao macOS que inicie um aplicativo, e pgrep observa um processo depois desse pedido. Isso não prova que o app terminou de inicializar, que o cofre consegue responder a uma solicitação ou que o shim MCP aceita um cliente. A Apple documenta o Launch Services como a interface do sistema usada para iniciar e ativar aplicativos. Por isso, iniciar o app pelo sistema operacional é melhor do que fixar o caminho do pacote do aplicativo no script.

Mantenha a saída estruturada e sem detalhes desnecessários. app=ready basta para um agendador. Não despeje a saída de ps em um log central, onde argumentos de comandos, nomes de usuários ou detalhes de processos sem relação possam virar sujeira permanente.

Um processo pode existir enquanto está travado. Também pode estar ausente porque o Mac está em repouso, sem sessão iniciada ou reiniciando depois de uma atualização. Sua regra de alertas precisa de um período de tolerância para essas condições esperadas. Uma verificação que aciona alguém toda vez que um laptop fecha a tampa será desativada e não ajudará durante uma falha real.

O sinal útil de disponibilidade é local e limitado: o app iniciou, continuou presente durante um curto intervalo de estabilização e um cliente MCP consegue começar uma sessão. A última parte pertence a uma sonda separada, pois testa outro limite.

O estado do cofre precisa ser um resultado explícito

Um cofre bloqueado está saudável quando recusa ações. Chamar esse estado de indisponibilidade confunde um comportamento de segurança com uma falha de serviço.

O portão do cofre do Sallyport é absoluto: enquanto está bloqueado, toda ação é recusada. Em hardware compatível com o macOS, o portão usa Secure Enclave e Touch ID. Uma verificação precisa preservar essa regra. Não escreva um script que insira senhas em uma interface, armazene um token para contornar a biometria ou trate uma sessão de desktop desbloqueada como prova de que o cofre deve ser desbloqueado.

Use quatro estados de resultado em vez de um booleano:

• ready: o app está disponível, o cofre está desbloqueado e as verificações controladas podem ser executadas.
• locked: o app está disponível, mas o cofre recusa ações corretamente.
• denied-unexpectedly: o cofre está desbloqueado, mas a ação de canário pretendida foi recusada.
• unavailable: o app ou o caminho MCP local não consegue responder.

Esse vocabulário evita um erro operacional comum. Muitas equipes agendam uma sonda com credenciais à noite, veem falhas depois que a tela é bloqueada e enfraquecem o sistema até que ele consiga se desbloquear sozinho. Elas não corrigiram o monitoramento. Removeram a decisão humana que o cofre foi criado para exigir.

O padrão prático tem duas partes. Um trabalho sem supervisão registra a disponibilidade do app e a recusa do cofre bloqueado. Uma pessoa, ou uma sessão de estação de trabalho controlada que já tenha aprovação humana, inicia as verificações com credenciais depois de desbloquear o cofre. Registre o motivo na saída da execução:

{
  "run_id": "hc-2026-07-22T141501Z-8f29",
  "app": "ready",
  "vault": "locked",
  "http": "skipped",
  "ssh": "skipped",
  "audit": "verified",
  "reason": "credentialed checks require an unlocked vault"
}

O ID da execução não é um segredo. Ele dá aos operadores algo estável para comparar mais tarde com o registro de atividade. Não use como ID de execução um nome de usuário, número de série da máquina, URL de endpoint ou rótulo de credencial.

A autorização por sessão e a aprovação por chamada também precisam de um tratamento próprio. Um novo processo de agente pode exigir aprovação da sessão, e uma credencial pode exigir aprovação a cada uso. Esse é um comportamento esperado, não um teste instável. Seu executor deve informar se foi projetado para uma sessão aprovada ou se uma pessoa aprovará cada chamada. Um timeout silencioso não deixa nenhuma informação útil para a próxima investigação.

Use destinos de canário que comprovem a injeção de credenciais

Uma verificação HTTP deve chamar um endpoint criado para validar uma credencial de canário específica e retornar um resultado fixo e não secreto. Testar uma URL pública prova apenas que a rede funciona. Não informa se o gateway selecionou a credencial pretendida, inseriu-a no cabeçalho correto ou a manteve longe do agente.

Configure um serviço pequeno que aceite um caminho, um método e um formato de credencial. Armazene o segredo de canário esperado no lado do serviço. Armazene o mesmo segredo no cofre do gateway. O cliente que aciona a ação nunca deve receber o segredo, e o serviço nunca deve devolvê-lo na resposta.

O contrato de resposta pode ser pequeno:

{
  "check": "agent-gateway-http",
  "result": "ok",
  "request_id": "7d7a0f3c"
}

O serviço deve retornar 401 quando a credencial estiver ausente ou incorreta, 405 para o método errado e 200 somente quando a credencial esperada tiver chegado. Gere request_id no serviço e mantenha-o opaco. Não o derive do cabeçalho de autorização nem de qualquer parte da requisição recebida.

Use uma rota dedicada, como /agent-gateway-canary. Não acrescente a verificação a um endpoint de produção existente. Endpoints de produção acumulam comportamentos ao longo do tempo: limites de taxa, redirecionamentos, negociação de conteúdo, regras de cache, efeitos de cobrança e mudanças de permissão. Uma rota de canário pode continuar deliberadamente simples.

A RFC 9110 define a semântica dos métodos de requisição e classifica GET, HEAD, OPTIONS e TRACE como métodos seguros. Em HTTP, porém, «seguro» significa que a ação solicitada não deve alterar o estado pretendido do recurso. Isso não significa que a chamada seja inofensiva para sua conta, seus logs, suas cotas ou comportamentos posteriores. Uma API pode registrar um GET, cobrar uma requisição ou acionar um efeito colateral de uma implementação ruim. Crie uma rota cujo comportamento no servidor possa ser inspecionado, em vez de confiar em um verbo conhecido.

Uma recomendação ruim e frequente é usar curl com um token de API de produção como verificação de integridade. Ela é popular porque cabe em uma linha. Está errada porque o histórico do shell, a inspeção de processos, os logs de CI e as mensagens de erro criam lugares demais para um token bearer aparecer. Também ignora o comportamento que você precisa testar se o gateway normalmente injeta as credenciais por conta própria.

Seu executor deve chamar o gateway pelo mesmo caminho MCP usado por um agente. Não invente um cliente HTTP alternativo para a verificação. Mantenha a chamada específica do transporte atrás de um adaptador local, pois os nomes das ferramentas e os formatos das requisições podem mudar. O adaptador recebe uma ação lógica, pede ao gateway conectado por MCP que a execute e emite apenas o resultado normalizado.

{
  "action": "http_canary",
  "target": "canary-api",
  "method": "POST",
  "path": "/agent-gateway-canary",
  "expected_status": 200,
  "expected_check": "agent-gateway-http"
}

O adaptador deve ocultar dados em caso de falha. Ele pode informar http_status=401, transport_error=timeout ou response_schema=invalid. Não deve imprimir cabeçalhos enviados, corpo da requisição, URL completa com parâmetros de consulta nem a resposta bruta, a menos que esses dados tenham sido revisados como seguros.

Um sucesso HTTP precisa provar a ação pretendida

Um 200 isolado é uma evidência fraca. A verificação precisa validar a resposta do serviço, o método e a identidade do destino, para que uma página de redirecionamento, um proxy ou um recurso de teste antigo não gere uma aprovação falsa.

Faça a resposta do canário identificar o teste sem identificar uma credencial. Compare alguns campos exatos:

status=200
check=agent-gateway-http
result=ok
request_id=7d7a0f3c

O verificador deve aceitar qualquer request_id sintaticamente válido e salvá-lo junto do ID da execução. Deve rejeitar um campo ausente, um corpo que declare sucesso com status diferente de 2xx e um tipo de conteúdo inesperado. Um portal cativo, uma página de erro de proxy corporativo ou um registro DNS apontando para o lugar errado frequentemente retornam uma resposta HTTP válida. Isso é sucesso do transporte, não sucesso da ação.

A documentação do curl apresenta um ponto relacionado: sem --fail ou --fail-with-body, o curl não trata um status HTTP como 404 ou 401 como falha do comando. Esse comportamento é correto para um cliente geral de transferência, mas surpreende quem cria monitores que observam apenas o status de saída do curl. Se o adaptador usar curl internamente, capture tanto o resultado do processo quanto o status HTTP e decida o sucesso com base no contrato explícito.

Não permita que uma verificação siga redirecionamentos automaticamente, a menos que eles façam parte do desenho pretendido do endpoint. Um redirecionamento pode enviar a chamada de canário para uma página de login que retorna 200, ou para outro host que você não pretendia contatar. Fixe a origem HTTPS na configuração, valide o certificado pela pilha normal do cliente e registre a identidade final do peer somente se esse registro não puder revelar detalhes sensíveis da rede.

Os timeouts precisam de rótulos separados. Uma falha de DNS, uma recusa TCP, uma falha de validação TLS, uma recusa do gateway, um 401 do serviço remoto, um 500 remoto e uma resposta incompatível têm responsáveis diferentes. Se o executor chamar todos de http=failed, você perderá os primeiros dez minutos de cada incidente descobrindo onde a requisição parou.

Um registro de falha útil é assim:

{
  "run_id": "hc-2026-07-22T141501Z-8f29",
  "check": "http_canary",
  "outcome": "failed",
  "stage": "upstream_response",
  "http_status": 401,
  "request_id": null,
  "secret_material": "redacted"
}

A linha secret_material é um lembrete para as pessoas que leem o registro, não uma prova de que a ocultação funcionou. Prove a ocultação com testes: faça deliberadamente o canário rejeitar a credencial, capture a saída padrão e a saída de erro do executor e procure o segredo de teste nesses arquivos. O segredo não pode aparecer. Repita com JSON inválido, timeout, falha TLS e erro de ferramenta no lado do agente. É nos caminhos de erro que os segredos costumam escapar.

O SSH precisa de um destino isolado, não de um shell de login

Uma verificação SSH deve provar a autenticação e a execução de comandos contra uma conta dedicada cujo servidor se recuse a executar comandos arbitrários. Uma conexão bem-sucedida a um host administrativo geral prova demais na direção errada: dá ao credencial de integridade um shell útil.

Crie uma conta separada, como gateway-health, em um host de teste controlado. Dê a ela um comando forçado em authorized_keys ou uma restrição equivalente no servidor. O comando forçado deve ignorar o comando original, gravar um timestamp e um ID de execução opaco em um arquivo de auditoria local e retornar uma resposta constante.

Uma entrada conceitual em authorized_keys é assim:

command="/usr/local/libexec/gateway-health",no-port-forwarding,no-agent-forwarding,no-X11-forwarding,no-pty ssh-ed25519 AAAA... gateway-health

A chave pública pertence à identidade de canário do gateway. A chave privada fica no cofre. O texto AAAA... está incompleto de propósito, porque você deve gerar seu próprio material de chave, não copiar um exemplo para um arquivo de produção.

O comando no servidor deve evitar repetir $SSH_ORIGINAL_COMMAND, variáveis de ambiente ou detalhes de autenticação. Ele pode retornar um formato fixo:

{"check":"agent-gateway-ssh","result":"ok","receipt":"c2b91a"}

Se precisar de um ID de execução para correlação, passe um token opaco no comando enviado e faça o comando forçado validar um formato restrito, como caracteres hexadecimais de tamanho fixo. Nunca aceite uma string arbitrária e a escreva em um comando de shell, nome de arquivo ou linha de log. Melhor ainda, deixe o servidor gerar o recibo e relacione os registros por intervalo de tempo durante a investigação.

A verificação deve falhar se o servidor permitir um shell interativo, encaminhar uma porta, alocar um TTY ou executar um comando diferente do comando forçado. Essas são regressões de configuração. Elas merecem uma gravidade diferente da de um timeout de rede comum, pois alteram a exposição da credencial de canário.

Não reutilize a identidade SSH usada em implantações. A reutilização facilita a configuração da verificação, mas transforma uma falha de monitoramento em um problema amplo de acesso. Uma credencial de integridade deve ter uma única função, uma única conta de destino e nenhuma permissão além de produzir o recibo.

O Sallyport envia SSH pelo auxiliar stateless sp-ssh integrado. Portanto, seu teste deve passar pelo caminho normal de ação do gateway, em vez de chamar uma chave privada local com OpenSSH. Caso contrário, você terá verificado apenas o host e a conta. Terá ignorado o limite de credenciais que precisa ser comprovado.

A verificação da auditoria é uma afirmação separada

Uma ação de canário bem-sucedida e um registro de auditoria válido são afirmações diferentes. Verifique ambas.

O registro de atividade informa que o gateway registrou uma ação individual. O registro de sessão informa detalhes da execução do agente e oferece uma forma de revogá-la. Nenhum dos dois deve substituir a verificação do efeito remoto, pois uma requisição pode ser registrada antes de uma falha no serviço remoto. Da mesma forma, um sistema remoto pode receber uma requisição enquanto um caminho de registro local falha em um momento ruim. Você precisa de correlação, não de esperança.

Para cada ação HTTP ou SSH bem-sucedida, colete três evidências não secretas:

• o ID da execução de integridade gerado pelo executor;
• o recibo opaco ou ID de requisição gerado pelo serviço de canário;
• o timestamp local da ação, registrado em UTC.

Depois, inspecione o diário de atividade em busca dos metadados da ação que podem ser mantidos com segurança, como canal, resultado da ação, alias do destino e horário. Não espere encontrar credenciais em texto simples no diário. Elas não devem estar lá. Também não exija que ele reproduza o corpo da resposta remota. O recibo pertence ao sistema remoto de canário, não ao cofre de segredos do gateway.

O Sallyport projeta seus diários Sessions e Activity a partir de um registro de auditoria criptografado, encadeado por hash e que não pode ser alterado. Execute sua verificação de integridade offline como uma parte independente da suíte:

sp audit verify

Um comando aprovado deve ser registrado como audit=verified; um resultado diferente de zero é um incidente de integridade até que se prove o contrário. Essa verificação não precisa da chave do cofre, o que a torna adequada para uma verificação local sem supervisão mesmo quando o cofre está bloqueado.

Não reduza a verificação da auditoria a «um arquivo de log existe». A existência do arquivo quase não detecta nada. Um arquivo truncado, registros substituídos, uma cadeia quebrada ou um gravador que parou depois da inicialização podem coexistir com um caminho que parece normal no Finder.

Há outro erro fácil: verificar apenas se a cadeia de auditoria é válida. Uma cadeia pode ser válida e ainda não conter o evento esperado se o gateway nunca tentou executar a ação. Combine a verificação da cadeia com uma afirmação de presença do evento após cada ação de canário. Defina uma janela razoável para a chegada da projeção local e informe um atraso separadamente de um evento ausente. Uma atualização atrasada do diário pode exigir investigação, mas não é idêntica a uma gravação que falhou.

Mantenha o executor fora do limite de confiança que ele verifica

O executor de integridade deve coordenar ações e avaliar evidências. Não deve armazenar credenciais, analisar arquivos do cofre ou ler o estado do aplicativo que contenha segredos.

Uma estrutura prática tem quatro componentes:

1. Um agendador local inicia um executor pequeno em uma conta dedicada do macOS.
2. O executor verifica a presença do app e chama um adaptador MCP local.
3. O adaptador solicita ações de canário nomeadas pelo gateway e retorna resultados estruturados e sem segredos.
4. O executor verifica a integridade da auditoria e grava um relatório curto em um diretório local protegido.

A conta dedicada não deve ter acesso aos arquivos de dados do cofre. A Apple coloca dados de suporte de aplicativos macOS sem sandbox no diretório ~/Library/Application Support do usuário atual, mas um monitor não deve presumir que pode ou deve inspecionar esses arquivos. A verificação precisa do comportamento, não de uma cópia do conteúdo do cofre.

Mantenha a configuração declarativa e sem segredos. Este exemplo dá ao executor informações suficientes para validar os resultados sem revelar credenciais:

checks:
  http_canary:
    target_alias: canary-api
    expected_status: 200
    expected_check: agent-gateway-http
    timeout_seconds: 10
  ssh_canary:
    target_alias: canary-ssh
    expected_check: agent-gateway-ssh
    timeout_seconds: 10
  audit:
    command: sp audit verify
    timeout_seconds: 15

Os aliases dos destinos importam. Um alias é menos sensível que uma URL ou nome de host completo e obriga você a tornar explícita a seleção do destino na configuração do gateway. Se um operador alterar um alias, a verificação da ação deve mostrar que uma revisão de configuração é necessária antes de começar silenciosamente a testar outro lugar.

Não dê ao executor permissão para aprovar um novo processo de agente. A autorização por sessão existe por um motivo. A primeira chamada de um novo processo de agente identifica sua autoridade de assinatura de código no cartão de aprovação, e a aprovação dura apenas durante aquela execução. Se precisar de verificações agendadas depois da aprovação de uma pessoa, organize um processo de cliente de integridade duradouro e revisado. Se o processo for encerrado, espere que a próxima execução peça aprovação novamente.

Essa escolha é um pouco menos conveniente que uma conta de automação oculta e sempre aprovada. Ela também impede que um novo executável obtenha permissão apenas por copiar a linha de comando da verificação de integridade.

Uma verificação com falha precisa de um diagnóstico útil

A maioria das falhas de integridade do gateway é um desvio comum de configuração. A parte perigosa é a rapidez com que as pessoas respondem enfraquecendo os controles, em vez de localizar o limite que quebrou.

Considere uma sequência realista. O app está em execução. O cofre está desbloqueado. O canário HTTP retorna 401. O primeiro impulso é colar o token de canário em um shell e chamar o endpoint diretamente. Não faça isso. Você prova que o token funciona, mas contorna o cofre e cria um novo caminho para vazamento de segredo.

Analise as evidências na ordem:

1. Confirme que o adaptador MCP local alcançou o gateway e recebeu um resultado de ação, em vez de atingir o timeout antes do envio.
2. Confirme que o alias do destino ainda seleciona a credencial armazenada e a configuração de endpoint pretendidas.
3. Verifique os logs do serviço de canário em busca do ID de requisição opaco, método, rota e motivo da recusa. Não registre o valor de autorização recebido.
4. Inspecione o diário de atividade em busca da tentativa de ação correspondente e verifique a cadeia de auditoria com sp audit verify.
5. Faça a rotação da credencial de canário se a revisão de configuração mostrar que seu valor esperado mudou ou pode ter sido exposto.

Essa sequência separa quatro falhas que, de outra forma, parecem idênticas: um mapeamento de destino incorreto, um segredo revogado ou rotacionado, uma falha de injeção do gateway e uma mudança na configuração do serviço remoto. Ela também evita o incidente autoinfligido conhecido: o operador «testa» um segredo no terminal e depois o encontra no histórico do shell, no buffer de rolagem ou em um pacote de suporte.

Classifique a gravidade pelo controle que falhou. Um app indisponível é um problema de disponibilidade. Um cofre bloqueado que recusa uma ação é informativo, a menos que uma verificação aprovada agendada fosse esperada. Uma ação de canário que tenha sucesso enquanto o cofre informa estar bloqueado é um incidente de segurança. Uma cadeia de auditoria quebrada também é um incidente de segurança, mesmo que os dois destinos de canário continuem retornando sucesso.

Não esconda essas categorias atrás de um único selo vermelho ou verde. O operador que vê vault=locked, audit=verified e http=skipped sabe exatamente o que fazer. O operador que vê health=warning começa a adivinhar.

A menor agenda útil tem duas linhas de execução

Execute verificações sem segredos com frequência e depois execute ações de canário com credenciais de forma moderada e deliberada. As duas linhas geram menos ruído e oferecem evidências melhores.

A linha sem supervisão pode ser executada sempre que se espera que o Mac esteja ativo. Ela verifica se o app está presente, se um cofre bloqueado recusa ações, se o caminho MCP consegue retornar uma resposta classificada e se sp audit verify passa. Nenhuma dessas verificações deve exigir a extração de uma credencial ou o desbloqueio do cofre.

A linha com credenciais é executada depois que uma pessoa desbloqueia o cofre e aprova a sessão do cliente de integridade, se necessário. Ela executa uma ação de canário HTTP, uma ação de canário SSH, confirma os recibos remotos, verifica os registros de atividade locais correspondentes e verifica novamente a cadeia de auditoria. Use uma cadência moderada. Cada ação com credenciais vira um evento de auditoria e um evento no serviço remoto, portanto uma verificação a cada minuto cria ruído sem oferecer muito mais confiança.

Execute a linha com credenciais depois de mudanças na configuração de credenciais, aliases de destino, ferramentas do agente, permissões do macOS, controles de rede ou app do gateway. Esse momento detecta as mudanças com maior probabilidade de interromper a execução das ações. Também oferece ao revisor um registro claro de antes e depois.

O padrão é simples: uma suíte de integridade precisa provar os controles em que você pretende confiar. Se ela só consegue provar que o ícone do app continua na barra de menus, chame-a de sonda de disponibilidade e pare por aí. Não a chame de prova de que agentes autônomos podem agir com segurança.