Ir para o conteúdo principal
DocsSecureStamp Protocol
Execution Governance · MCP · agentes · harnesses

Deixe o agente trabalhar. Mantenha o controle do efeito final.

Proteger um servidor MCP não basta: um agente também alcança o shell, os arquivos, as APIs e as automações que seu harness permite alcançar. Este guia reúne o caminho completo para desenvolvedores e instituições: diagnosticar a configuração que você já tem, testar o limite, autorizar apenas o candidato exato, controlar a execução e reconstruir com evidências o que realmente aconteceu.

Disponível · Break the Mandate

Para quem é

Desenvolvedores e mantenedores

Equipes que já delegam tarefas a agentes de código e querem deixá-los trabalhar por mais tempo sem aprovar cada comando. Doctor nos próprios arquivos, um laboratório local sem conta e um recibo que anexam ao PR.

Equipes de plataforma e segurança

Quem decide o que um agente pode montar, alcançar e exportar. Uma configuração portátil versionada no Git, a mesma validação na CLI e no painel, e controles de hold e stop confirmados pelo runtime.

Instituições e organizações

Quem responde pelo que o software autônomo faz a clientes, auditores ou reguladores. A autoridade fica fora do agente, cada efeito deixa evidência que se verifica offline, e os limites dessa evidência estão escritos.

Três superfícies, um princípio

Os agentes podem propor. A autoridade fica fora do agente. A cobertura se limita às rotas declaradas e testadas: o SecureStamp não controla operações que contornam essa fronteira e as nomeia em vez de escondê-las.

Break the Mandate — o passo a passo

A pergunta de entrada é simples: seu agente consegue fazer algo fora da tarefa que você aprovou? O cenário de referência responde em cinco passos, com fixtures sintéticas, sem conta e sem chave de API de modelo.

  1. 01

    Uma tarefa útil

    O agente prepara uma mudança real dentro de uma fixture contida.

  2. 02

    A brecha, na linha de base

    A mesma tentativa fora do escopo produz seu efeito em uma linha de base deliberadamente permissiva, observada a partir de outro processo. É um controle experimental conhecido, não uma vulnerabilidade descoberta na sua máquina.

  3. 03

    A brecha, contida

    Com o controle ativo, essa rota fica contida e a tarefa útil continua sendo concluída. Uma negação que inutiliza a tarefa não conta como valor.

  4. 04

    A evidência expira quando o ambiente muda

    Uma dependência material do perfil muda: a evidência anterior deixa de habilitar essa rota até ser revalidada.

  5. 05

    Só o candidato exato sai

    O candidato congelado é revisado. Alterar seus bytes ou seu destino invalida a exportação; restaurar o que foi aprovado permite o efeito.

Início rápido

O Doctor não precisa de Docker nem de um modelo e não executa nada do que lê. O cenário de referência é sintético: nunca executa código do projeto e seu relatório é rotulado como evidência simulada.

shell
# Node 22.22.3 ou posterior
npm install --save-dev @securestamp/mcp-guard @securestamp/execution-governance

# 1. Doctor: diagnóstico estático dos arquivos que você escolher
npx securestamp-mcp-doctor scan .mcp.json --propose
npx securestamp-mcp-doctor scan-native <settings.json|config.toml> --format=<shape>
npx securestamp-mcp-doctor scan-workflow .github/workflows/agent.yml

# 2. Cenário portátil: validar e executar a referência, com um hold
npx securestamp-execution-governance validate scenario.json
npx securestamp-execution-governance run scenario.json --hold-before=step-1

# 3. SAES (explain-derived, export-bundle, verify-bundle, supervision-history): chega na 0.1.2-beta.2, ainda não publicada no npm

Cada comando imprime seu uso e os formatos compatíveis quando recebe argumentos inválidos. Para um HarnessProfileV1 completo, use securestamp-mcp-doctor scan-harness. Com --hold-before, a execução mostra um efeito retido que nunca é admitido. Sem telemetria por padrão.

Doctor: primeiro, seus arquivos nativos

Doctor produz fatos declarados, cada um com seu arquivo e campo de origem, e um diagnóstico parcial que diz quais camadas leu e quais continuam desconhecidas. A compatibilidade é descrita como forma + transporte + cliente testado; um formato que ele não reconhece é reportado como não suportado, nunca ignorado em silêncio.

  • .mcp.json · JSON com mcpServers (stdio)

    Comandos declarados, referências a credenciais, segredos escritos no arquivo, inicializações via shell e pacotes mutáveis ou @latest. Uma versão fixada não estabelece integridade: conferir o artefato efetivo com o aprovado é tarefa do executor.

  • settings.json · config.toml ([mcp_servers])

    Permissões, ferramentas e camadas de configuração reconhecidas, com conflitos e dados ausentes. Um único arquivo não revela políticas gerenciadas, sobrescritas da CLI nem configuração herdada: a saída informa isso.

  • .github/workflows/*.yml

    Agent Workflow Doctor: entrada não confiável de issue, PR ou comentário que chega ao agente, permissões declaradas, referências a segredos, ferramentas amplas e checkout de conteúdo externo. Não baixa actions, não resolve segredos nem executa YAML.

  • HarnessProfileV1

    O perfil completo, para usuários avançados. Doctor nunca o inventa a partir de um único arquivo: montagens, observador, credenciais efetivas e backend são escolhidos e validados pelo operador.

  • Lê apenas os arquivos indicados; não vasculha o diretório home.
  • Não executa comandos, hooks nem expressões do arquivo.
  • Não resolve segredos nem valida tokens.
  • Propõe um patch revisável em uma cópia; nunca sobrescreve o original.
  • Mostra um resultado limpo com o mesmo peso de um achado.
  • Um diagnóstico estático não estabelece isolamento nem proteção.

Exact Export: o agente prepara, você autoriza a mudança exata

O agente prepara a mudança em uma cópia contida do seu projeto. A credencial de exportação fica fora do ambiente dele, e só o candidato revisado sai, por meio do Execution Guardian.

  1. 01

    Preparar

    Em quarentena, sobre um snapshot do projeto escolhido; seu .git nunca é reutilizado como base confiável.

  2. 02

    Congelar

    O candidato é fixado antes da revisão: base, bytes e digests, ref, destino e estado anterior.

  3. 03

    Autorizar

    A aprovação fica vinculada a esse candidato. Uma mudança posterior a invalida; um --yes não substitui MFA nem quórum.

  4. 04

    Executar

    Mantido em custódia pelo Guardian, com verificação do estado do destino: desvios e corridas nunca são sobrescritos.

  5. 05

    Verificar

    Verificação independente da pós-condição e um recibo que você anexa ao PR ou à issue.

O destino inicial é um repositório Git local. Com um perfil e um destino autorizados, o adaptador do GitHub cria uma ref nova: não atualiza nenhuma branch, não faz force-push, não faz merge nem deploy, e abrir um PR é um efeito separado, com autorização própria. A custódia da credencial só é afirmada para o perfil que a demonstra com identidade efetiva, montagens, sockets e rede, mais canaries a partir do contexto do agente.

Uma configuração portátil, três interfaces

A configuração é um arquivo JSON versionado no seu repositório. A biblioteca gera os contratos completos e seus digests; ninguém escreve assinaturas à mão. A CLI e o painel importam e exportam a mesma representação e passam pela mesma validação: não existe política na web diferente da política no Git. Cada edição cria uma nova revisão e as execuções ativas mantêm seu snapshot.

Cenário

Um SSPI-execution-scenario versionado: parâmetros, o código-fonte do projeto com digests do candidato e da base, e os passos com sua operação e efeito esperado. Não aceita scripts arbitrários nem um resultado esperado editado para transformar uma brecha em sucesso.

Perfil

O runner e seu perfil: backend, lease do observador e lease do canal de controle. O sistema verifica sua disponibilidade e a aplicabilidade da evidência.

Mandato

Limites de efeito e de tempo, digests de cada efeito e recurso, e as aprovações exigidas: um Task Contract fora do alcance do agente.

  • npm · @securestamp/execution-governance

    Contratos de cenário portáteis, um plano de controle com hold, resume e stop, e relatórios redigidos: validar e serializar cenários, iniciar execuções, emitir ordens idempotentes, e construir, verificar e comparar relatórios. Não concede autoridade, não contém o host e não substitui o Guardian do cliente.

    npm · @securestamp/execution-governance
  • CLI · securestamp-mcp-doctor · securestamp-execution-governance

    scan, scan-native, scan-workflow e scan-harness para diagnóstico; validate e run para cenários; explain-derived para ver o que é executado depois de uma mudança (com --git=<base>, sem montar nada à mão); export-bundle e verify-bundle para evidência que se verifica offline; supervision-history para saber que modalidade de supervisão um histórico sustenta. Sem conta. Cada execução produz seu próprio relatório sem sobrescrever outro.

  • Dashboard · securestamp.online/dashboard/agents

    Cenários, preparação, execuções, detalhe ao vivo e análise pós-execução, em runners registrados operados pelo cliente. O navegador não executa o teste nem recebe credenciais do provedor; conectar um runner é opcional.

Hold, resume, stop

Os controles atuam sobre as rotas mediadas pelo Guardian. O agente pode continuar raciocinando enquanto seus efeitos estão retidos; a interface mostra isso como “efeitos retidos / processo em execução”, nunca como um agente congelado.

Hold

O Guardian fecha a admissão de novos efeitos e preserva orçamento, concessões consumidas e histórico. Não congela chamadas já enviadas nem monta uma fila de efeitos obsoletos.

Resume

Antes de reabrir, mandato, validade, política, perfil, observador e orçamentos são revalidados. Cada nova solicitação é avaliada de novo.

Stop

Terminal para a execução: fecha a admissão de forma durável, cancela o trabalho pendente e encerra os processos supervisionados e seus filhos. Prevalece sobre resume e sobre uma reconexão.

Uma resposta HTTP bem-sucedida apenas confirma que a ordem foi recebida. O painel mostra, separadamente, o que foi solicitado, o que o supervisor aplicou e o que foi observado. Se o canal remoto cair enquanto o observador está saudável, as admissões permanecem retidas localmente; se o observador falhar, o perfil corta o egress e encerra o contêiner. O stop local nunca depende do painel.

Relatórios: estados que não se reduzem a um semáforo

O relatório de execução traz apenas um checksum informativo, declara seu nível de evidência e permite comparar execuções; um checksum não autentica o emissor. Quando um bundle Action Proof completo está anexado, o verificador independente o confere offline com âncoras fornecidas fora do relatório e vincula candidato, destino, autoridade e resultado observado do recibo. FAIL, SKIP, evidência ausente e rota não avaliada continuam visíveis; uma falha de instrumentação deixa a execução INCOMPLETE, nunca PASS.

Estado da execuçãoqueued · running · held · stopping · stopped · completed · failed · incomplete
Resultado da rotaPASS · FAIL · SKIP
Coberturaprotected · contradicted · partial · not_evaluated
Integraçãosimulated · integration_real · no_evaluated
Completudecomplete · incomplete
Resultado do relatórioPASS · FAIL · INCOMPLETE
Resultado do efeitosucceeded · failed_no_effect · indeterminate

Checksum é informativo

O digest verifica os bytes apresentados, mas quem puder reescrever o relatório poderá recalculá-lo. Não autentica o emissor.

Evidência assinada com âncoras externas

Um bundle Action Proof completo só é verificado offline com âncoras de grant e de transparência instaladas fora do artefato. O bundle vincula candidato, destino, autoridade e resultado do recibo.

Reproduzido por terceiros

Outra pessoa executou o mesmo pack e obteve o mesmo resultado. É uma afirmação diferente e é reportada separadamente.

Relatórios de atividade de agentes e MCP

Atividade observada. Evidências para revisar.

O dashboard de Agentes reúne eventos MCP observados pelo SecureStamp, observações de tarefas delegadas e execuções para uma organização e um período selecionado. Agrupa a atividade por chave de API ou sessão delegada e, quando informado, por uma referência de agente declarada pelo cliente e protegida por hash.

  • S1–S9: Nove famílias determinísticas identificam chamadas fora do escopo, persistência após uma negativa, sequências entre vários atores, perda de observação ou controle, credenciais usadas fora do contexto esperado, efeitos sem evidência, limites de recursos, tempo ou cota, ausência de escalonamento e lacunas na evidência dos eventos.
  • Cada achado inclui severidade, contagem, sujeitos afetados, primeira e última ocorrência e referências a eventos. Exportações assinadas com ES256 podem ser verificadas pelo JWKS público ou endpoint de verificação do SecureStamp; o verificador confere o arquivo recebido e não o armazena. Alertas por limite aparecem em Agentes e MCP Guard e nunca alteram uma autorização.
  • GET /api/agents/reports exige execution:observe; GET /api/agents/reports/export exige execution:export e gera auditoria; POST /api/agents/reports/verify é público. Ler a política de alertas exige execution:observe; alterá-la exige execution:control e gera auditoria. O dashboard também requer um plano MCP Guard elegível.
  • Os relatórios cobrem somente atividades mediadas ou observadas pelo SecureStamp. Não leem o raciocínio dos agentes nem mensagens privadas entre eles. X-SecureStamp-Agent-Id é opcional e declarado pelo cliente; seu hash ajuda a separar sujeitos, mas não autentica quem agiu. O relatório informa limites da consulta, da linha do tempo de 200 eventos e períodos além da retenção de 180 dias.
Abrir relatórios de agentes no SecureStamp.online

Verificação informativa de pull request

Compara base e head dos arquivos nativos com os mesmos importadores e regras, mostra as mudanças declaradas, os desconhecidos e os candidatos a revalidação, e valida um recibo anexado contra suas âncoras. Executa a partir de uma revisão confiável fixada, com permissões de leitura, sem segredos e sem executar código do PR. Informa a revisão: não é a verificação que autoriza uma exportação, nem substitui o Guardian ou um ruleset.

O que isto não faz

  • Não torna o modelo seguro nem prova alinhamento geral: testa limites de execução em um perfil declarado.
  • Não controla rotas que contornam o Guardian; uma rota sem sonda continua not_evaluated, nunca protegida por herança.
  • Não desfaz um efeito que já aconteceu: hold e stop não são rollback.
  • Um recibo mostra integridade e escopo sob suas âncoras; não mostra que o código aprovado seja benigno nem que alguém independente o tenha auditado.
  • Não é um kill switch para toda a empresa: a v1 controla a execução escolhida e seus runners declarados.
  • A compatibilidade é publicada por perfil, versão e ambiente. Um PASS em um harness não se transfere para outro sistema operacional, rota ou cliente.

Continue lendo

Status

Disponível: Doctor em arquivos nativos, o cenário de referência parametrizado por npm, CLI e painel, Exact Export para Git local e a verificação informativa de PR. Os relatórios distinguem o histórico apenas com checksum de um bundle Action Proof anexado; um recibo compartilhável só é afirmado quando o bundle existe e verifica com âncoras externas. Cada capacidade publica seu nível de evidência — simulada, integração real ou não avaliada — por perfil e ambiente. explain-derived, export-bundle, verify-bundle e supervision-history, a parte do SAES que roda neste pacote, chegam na versão 0.1.2-beta.2 de @securestamp/execution-governance, que ainda não está publicada no npm: a versão publicada é a 0.1.1.

Aberto e reproduzível

Cenários, fixtures, receitas e vetores são publicados para que um terceiro possa reproduzir ou refutar cada propriedade. Contraexemplos são enviados como issues com seed, perfil e resultado observado; achados sensíveis seguem o SECURITY.md. Não há ranking de “agentes seguros” nem selos genéricos.

Execution Governance — segurança para MCP, agentes e harnesses | SecureStamp Foundation