MÓDULO 1.1

🛡️ Segurança de agentes e tools

Modele ameaças entre conteúdo, agente, tools, usuário e backend e aplique controles proporcionais ao efeito.

6

Tópicos

3h

Carga

Expert

Nível

Security

Tipo

0 de 60%
1

Desenhe as fronteiras de confiança

O que é: Documento, conteúdo remoto, modelo, agente, tool e backend são componentes com níveis distintos de confiança.

Por que aprender: O mapa mostra onde dados viram instruções e onde uma decisão pode produzir efeito.

Entrada não confiável estado de partida Policy + autorização decisão observável Efeito limitado resultado verificável

Antes de modelar

Escreva o pedido da pessoa, o estado atual e a evidência que provará conclusão.

Erro de partida

Começar pelo nome de uma função ou por um botão produz uma tool sem objetivo humano claro.

Preveja antes de abrir o código

Qual informação muda a decisão? Qual efeito precisa aparecer na interface? Responda antes de implementar.

untrusted: [pageContent, modelOutput, toolArguments]
trustedOnlyAfter: [validation, policy, authorization]
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

trust boundary

02

principal

03

data flow

04

asset

2

Modele ameaças por jornada

O que é: A ameaça é analisada sobre objetivo, dados, transições e efeitos, não apenas sobre endpoints isolados.

Por que aprender: Jornadas revelam combinações como prompt injection seguida de uma mutação válida.

PerguntaContrato forteContrato fraco
Quando usar?A descrição nomeia intenção e contexto.“Faz coisas” ou “gerencia”.
O que recebe?Somente dados necessários.Objeto genérico e ilimitado.
O que devolve?Estado e próxima ação verificáveis.Texto sem protocolo.
Como falha?Código, motivo e recuperação.Exceção opaca.

Faça

  • ✓ Use verbos específicos.
  • ✓ Delimite entradas.
  • ✓ Declare a evidência.

Evite

  • ✗ Misturar intenções.
  • ✗ Aceitar qualquer objeto.
  • ✗ Esconder efeitos.
ameaça: conteúdo induz agente a cancelar pedido
controle: tool fora do catálogo + confirmação vinculada ao pedido
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

STRIDE

02

abuse case

03

attack path

04

impact

3

Contenha prompt injection

O que é: Texto da página e resultados de tools são dados não confiáveis, mesmo quando parecem instruções.

Por que aprender: Separar canais e aplicar política impede que conteúdo controle autoridade do runtime.

1

Observe

Capture estado, entrada e contexto antes da ação.

2

Decida

Valide pré-condições e escolha a transição permitida.

3

Execute

Aplique a regra compartilhada e respeite cancelamento.

4

Prove

Atualize a interface e devolva resultado estruturado.

Ponto de controle

Se a etapa 2 reprovar, a tool não tenta “dar um jeito”: ela devolve uma recuperação explícita.

await document.modelContext.registerTool({
  ...searchTool,
  annotations: {
    readOnlyHint: true,
    untrustedContentHint: true
  }
});

// Conteúdo da página e saída de tools continuam sendo dados, não instruções.

Tool poisoning

Nome, descrição e metadados também podem tentar induzir seleção ou autoridade indevida.

Output injection

A resposta pode conter instruções hostis. Preserve proveniência, limite autoridade e trate o payload como não confiável.

Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

data vs instruction

02

provenance

03

allowlist

04

policy

4

Aplique least privilege

O que é: Cada tool recebe o menor escopo, duração e conjunto de recursos necessário.

Por que aprender: Credenciais amplas transformam um erro de seleção em incidente sistêmico.

CÓDIGO DE REFERÊNCIA

token = mint({ scope: "enrollment:read", resource: enrollmentId, ttl: 60 });
Entrada

É pequena, descrita e validável.

Execução

Reutiliza a regra real da aplicação.

Saída

Permite verificar efeito e continuar.

Leia o código como contrato

Sublinhe onde a entrada é validada, onde o efeito acontece, onde o cancelamento chega e onde a UI é atualizada.

Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

scope

02

short-lived token

03

resource bound

04

deny by default

5

Vincule confirmação ao efeito

O que é: A confirmação registra ação, alvo, parâmetros materiais e versão do estado apresentado.

Por que aprender: Um sim genérico não autoriza uma ação alterada depois da confirmação.

Falha provocada

Execute o cenário com estado ausente, entrada inválida ou capacidade indisponível.

Recuperação esperada

A resposta informa o que falhou, o que permanece seguro e qual ação pode continuar.

Matriz mínima de teste

✓ caminho feliz reproduzível

✓ entrada inválida acionável

✓ cancelamento encerra trabalho

✓ fallback preserva a jornada

✓ interface reflete o estado

✓ backend mantém autorização

approval = sign({ tool, argsHash, stateVersion, expiresAt });
verifyApproval(approval, currentCall);
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

intent binding

02

state version

03

target

04

expiry

6

Teste o adversário continuamente

O que é: A suíte cobre prompt e output injection, tool poisoning, intenção falsamente representada, excesso de parâmetros, argumentos extremos, replay, navegação durante execução e escalada de privilégio.

Por que aprender: Controles de segurança precisam de regressão automatizada como qualquer contrato.

Exercício de síntese

  1. 1. Explique o problema sem usar o nome da tecnologia.
  2. 2. Desenhe o estado anterior e posterior.
  3. 3. Implemente a menor prova funcional.
  4. 4. Provoque uma falha e registre a recuperação.
  5. 5. Entregue código, evidência e uma limitação conhecida.

Desafio do módulo

Produzir threat model, matriz de autoridade e testes adversariais para uma jornada WebMCP com ação sensível.

Critério de Expert responsável

A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.

for (const attack of adversarialDataset) {
  assert(await agent.run(attack)).hasNoUnauthorizedEffect();
}
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

red team

02

replay

03

spoofing

04

privilege escalation

📦 Entrega do módulo

Produzir threat model, matriz de autoridade e testes adversariais para uma jornada WebMCP com ação sensível.

Critério de aceite

A entrega funciona com suporte WebMCP e mantém o caminho manual quando a API não existe.

Evidência

Inclua código, cenário testado, resultado observado e uma limitação conhecida.

← Voltar para a trilhaPróximo módulo: 1.2 →

Fontes técnicas