Skip to main content

PRD-013 — Agentic Security, Audit & Compliance Fabric

1. Objetivo​

O Agentic Security, Audit & Compliance Fabric define a camada transversal de segurança, auditoria, rastreabilidade e conformidade para todas as operações executadas pelo agente.

O princípio central é:

Toda ação relevante do agente deve ser explicável, rastreável, autorizável e auditável.

O sistema deve conseguir reconstruir uma operação completa sem depender do histórico textual da conversa.

Usuário
   ↓
Mensagem
   ↓
Intent
   ↓
Contexto
   ↓
Capability
   ↓
Policy Decision
   ↓
Plan
   ↓
Execution
   ↓
API
   ↓
Database
   ↓
Verification
   ↓
UI
   ↓
Resultado

Cada etapa deverá possuir correlação.

2. Problema

Um agente convencional pode registrar apenas:

“Usuário solicitou alteração da validade.”

Isso é insuficiente para um sistema empresarial crítico.

Precisamos saber:

Quem?
Haroldo / User ID

Qual tenant?
Tenant 42

Quando?
2026-09-01T...

O quê?
Alterar validade

Qual entidade?
WP-123

Valor anterior?
30 dias

Novo valor?
60 dias

Qual capability?
workPermit.updateValidity

Qual política?
policy.workPermit.validity.update.v3

Houve confirmação?
Sim

Qual plano?
plan_...

Qual execução?
exec_...

Qual API?
...

Resultado?
Sucesso

3. Princípio Zero Trust

Todas as operações devem seguir:

AUTHENTICATE
      ↓
IDENTIFY
      ↓
AUTHORIZE
      ↓
VALIDATE
      ↓
PLAN
      ↓
CONFIRM
      ↓
EXECUTE
      ↓
VERIFY
      ↓
AUDIT

Nenhuma etapa deve assumir que uma etapa anterior continua válida indefinidamente.

4. Security Fabric

A camada será transversal:

                  Agent
                    │
        ┌───────────┴───────────┐
        │   Security Fabric     │
        └───────────┬───────────┘
                    │
     ┌──────────────┼──────────────┐
     ▼              ▼              ▼
 Identity        Policy          Audit
     │              │              │
     └──────────────┼──────────────┘
                    ▼
                Execution

5. Escopo

O PRD cobre:

  • identidade;
  • tenant isolation;
  • authorization context;
  • audit events;
  • immutable audit trail;
  • operation correlation;
  • policy decisions;
  • confirmation evidence;
  • before/after state;
  • sensitive data protection;
  • security events;
  • anomaly detection;
  • compliance reporting;
  • retention;
  • audit search;
  • forensic reconstruction;
  • administrative access;
  • emergency controls.

Não cobre a implementação do Identity Provider.

O sistema deverá consumir a identidade autenticada já existente.

6. Security Principal

Toda operação deverá estar associada a um principal.

interface SecurityPrincipal {
  userId: string;

  tenantId: string;

  sessionId?: string;

  roles: string[];

  permissions?: string[];

  authenticationMethod: string;

  authenticatedAt: string;
}

O userId e tenantId deverão vir de uma fonte confiável de autenticação.

Nunca do prompt.

7. Agent Identity

O agente não deve ser tratado como substituto do usuário.

Arquiteturalmente:

Human Principal
       +
Agent Execution Context

Exemplo:

actor.userId = USER-123
actor.type = HUMAN

executor.type = AGENT
executor.agentVersion = 1.7.2

Isso permite distinguir:

quem solicitou

de:

quem executou tecnicamente.

8. Impersonation Proibido por padrão

O agente não deve simplesmente assumir identidade administrativa.

Errado:

User
 ↓
Agent
 ↓
Admin API

Correto:

User authentication
 ↓
User authorization
 ↓
Agent operation
 ↓
Existing permission boundary

9. Tenant Isolation

Todo objeto operacional deverá carregar o tenant quando aplicável:

tenantId
conversationId
operationId
resourceId

Uma capability jamais poderá acessar silenciosamente recursos pertencentes a outro tenant.

10. Resource Authorization

A autorização deve considerar:

User
+
Tenant
+
Capability
+
Resource
+
Operation
+
Current State

Exemplo:

User can update Work Permit

não significa necessariamente:

User can update every Work Permit.

11. Authorization Recheck

A autorização deve acontecer:

No planejamento​

Intent
 ↓
Policy

e novamente:

Na execução​

Execution
 ↓
Policy
 ↓
API

Isso evita que uma mudança de permissão entre planejamento e execução produza uma ação indevida.

12. Audit Event

Modelo:

interface AuditEvent {
  eventId: string;

  timestamp: string;

  tenantId: string;

  actor: AuditActor;

  conversationId?: string;

  operationId?: string;

  intentId?: string;

  planId?: string;

  executionId?: string;

  capabilityId?: string;

  resource?: ResourceReference;

  eventType: AuditEventType;

  outcome: "SUCCESS" | "DENIED" | "FAILED";

  metadata?: Record<string, unknown>;
}

13. Audit Actor

interface AuditActor {
  type: "HUMAN" | "AGENT" | "SYSTEM";

  userId?: string;

  agentId?: string;

  agentVersion?: string;
}

Exemplo:

{
  "type": "AGENT",
  "agentId": "sst-agent",
  "agentVersion": "1.8.0",
  "userId": "USER-123"
}

14. Correlation IDs

Uma única solicitação poderá possuir:

requestId
conversationId
messageId
intentId
planId
operationId
executionId
auditEventId

O relacionamento será:

request
 └── conversation
      └── message
           └── intent
                └── plan
                     └── operation
                          └── execution
                               └── audit events

Isso permite reconstrução completa.

15. Operation ID

Toda ação de negócio deverá possuir um operationId.

Exemplo:

op_01J...

Mesmo que a operação possua 15 chamadas de API:

operationId = único

Isso permite enxergar uma tarefa como uma unidade.

16. Audit Lifecycle

REQUESTED
   ↓
INTERPRETED
   ↓
AUTHORIZED
   ↓
CONFIRMED
   ↓
EXECUTING
   ↓
VERIFIED
   ↓
COMPLETED

Ou:

REQUESTED
   ↓
DENIED

ou:

EXECUTING
   ↓
FAILED

17. Eventos mínimos

Registrar:

AUTHENTICATION
AUTHORIZATION
INTENT_RESOLUTION
CAPABILITY_SELECTION
POLICY_DECISION
CONFIRMATION
PLAN_CREATED
EXECUTION_STARTED
API_CALL
DATA_MUTATION
VERIFICATION
EXECUTION_COMPLETED
EXECUTION_FAILED
CANCELLATION
UNDO
UI_ACTION
SECURITY_ALERT

18. Policy Audit

Cada decisão do Policy Engine deverá gerar evidência.

{
  "capability": "workPermit.updateValidity",
  "decision": "ALLOW",
  "policyVersion": "3.2.1",
  "risk": "MEDIUM",
  "reasons": [
    "USER_AUTHORIZED",
    "RESOURCE_ACCESSIBLE",
    "WORK_PERMIT_STATE_VALID"
  ]
}

19. Denial Audit

Negativas são particularmente importantes.

Exemplo:

Não posso alterar essa permissão porque ela está aprovada.

Audit:

decision = DENY

reason =
RESOURCE_STATE_FORBIDS_ACTION

Isso evita registrar apenas ações bem-sucedidas.

20. Confirmation Evidence

Quando uma operação exige confirmação, registrar:

confirmationId
userId
timestamp
planId
riskLevel
summary
confirmed = true

Nunca registrar apenas:

user said "yes"

A evidência deve estar vinculada ao plano específico.

21. Before / After

Para operações de alteração, sempre que tecnicamente possível:

BEFORE
   ↓
CHANGE
   ↓
AFTER

Exemplo:

{
  "field": "validityDays",
  "before": 30,
  "after": 60
}

22. Dados sensíveis no Audit

O audit trail não deverá armazenar automaticamente o objeto completo.

Em vez disso:

changedFields:
  - validityDays

Quando necessário:

beforeHash
afterHash

ou valores redigidos.

23. Hashing

Para dados que precisam ser comprováveis sem serem armazenados:

SHA-256(beforeState)
SHA-256(afterState)

Isso permite demonstrar integridade sem manter o conteúdo completo.

24. Audit Immutability

Auditoria não deve ser tratada como uma tabela comum que administradores podem editar.

Idealmente:

Application
     ↓
Append-only audit
     ↓
No UPDATE
No DELETE

Correções devem gerar novos eventos.

Nunca alterar o evento original.

25. Audit Chain

Opcionalmente, eventos poderão possuir:

previousEventHash
currentEventHash

Criando uma cadeia:

Event 1
  ↓ hash
Event 2
  ↓ hash
Event 3
  ↓ hash
Event 4

Isso dificulta adulteração silenciosa.

26. Storage

O armazenamento poderá utilizar:

D1
 ↓
Operational audit index

R2
 ↓
Long-term immutable audit archives

A arquitetura deverá permitir retenção diferente conforme o tipo de evento.

27. Retention Policy

Cada categoria poderá possuir TTL próprio.

Exemplo:

Operational events → 90 dias
Security events → 1 ano
Compliance audit → conforme política empresarial
Aggregated metrics → longo prazo

Os valores reais devem ser configuráveis conforme requisitos legais e contratuais.

28. Audit Search

Administradores autorizados poderão pesquisar:

user
tenant
date range
operation
capability
resource
entity
outcome
policy decision
risk

Exemplo:

Mostre todas as alterações feitas pelo agente na Permissão 123.

Resultado:

14 operações
12 sucesso
1 negada
1 falha

29. Forensic Reconstruction

Deverá ser possível reconstruir:

09:42:11
User message

09:42:11
Intent resolved

09:42:11
WP-123 identified

09:42:11
Capability selected

09:42:11
Policy ALLOW

09:42:12
Confirmation received

09:42:12
Execution started

09:42:12
API mutation

09:42:12
Verification succeeded

09:42:12
UI refreshed

Isso é essencial para suporte e auditoria.

30. Agent Version Pinning

Toda execução deverá registrar:

agentVersion
manifestVersion
knowledgeVersion
capabilityVersion
policyVersion
uiManifestVersion

Assim, meses depois será possível responder:

Qual versão do sistema tomou essa decisão?

31. Reprodutibilidade

Quando possível, guardar:

intent snapshot
context snapshot
policy version
capability version
knowledge version
plan

Isso permite reproduzir a lógica operacional.

Não é necessário armazenar chain-of-thought.

32. Prompt Audit

O sistema não deve necessariamente armazenar todos os prompts completos.

Deverá registrar:

model
modelVersion
promptTemplateId
promptTemplateVersion
inputContextHash
outputSchema
latency
tokenUsage

Quando retenção do conteúdo for permitida, poderá ser armazenada sob política específica.

33. LLM Security

O modelo nunca deve ser considerado autoridade.

Mesmo que o LLM produza:

{
  "authorized": true
}

isso não possui valor de autorização.

Somente o Policy Engine pode produzir:

ALLOW
DENY
REQUIRE_CONFIRMATION

34. Prompt Injection Audit

Se o sistema detectar conteúdo suspeito em:

  • documentos;
  • comentários;
  • campos;
  • páginas;
  • knowledge base;

deverá registrar:

SECURITY_EVENT
type = POSSIBLE_PROMPT_INJECTION
source = knowledge/resource

O conteúdo continua sendo tratado como dados, nunca como instruções privilegiadas.

35. Security Anomaly Detection

A camada poderá detectar padrões anômalos.

Exemplo:

User normally:
5 operations/hour

Current:
700 delete attempts/hour

Pode gerar:

SECURITY_ALERT

36. Agent Abuse Detection

Também:

muitas tentativas negadas
+
múltiplas entidades
+
operações destrutivas

podem indicar tentativa de abuso.

O sistema poderá:

ALERT
RATE_LIMIT
REQUIRE_HUMAN_REVIEW

dependendo da política.

37. Rate Limiting

O agente deverá respeitar limites:

per user
per tenant
per capability
per resource
per time window

Exemplo:

workPermit.delete:
5/minute/user

Valores serão configuráveis.

38. Mass Action Protection

Uma solicitação:

Exclua todos os registros encontrados.

não deve ser tratada como 5.000 operações normais.

O Policy Engine deverá detectar:

scope = batch
count = 5000
risk = HIGH

e aplicar política específica.

39. Two-Person Rule

Para operações extremamente críticas poderá existir:

User A requests
        ↓
Agent prepares
        ↓
User B approves
        ↓
Execution

Isso implementa segregação de funções.

40. Human Review

O resultado:

REQUIRE_HUMAN_REVIEW

deverá interromper a execução.

Exemplo:

Essa operação exige aprovação de outro usuário autorizado.

Nenhum prompt do usuário poderá contornar isso.

41. Emergency Disable

Deverá existir mecanismo operacional para desabilitar:

Agent globally
Agent by tenant
Agent by capability
Agent by domain
Agent destructive actions

Exemplo:

agent.enabled = false

ou:

workPermit.delete.enabled = false

Isso deve funcionar independentemente do LLM.

42. Kill Switch

Para incidentes críticos:

KILL SWITCH

deve bloquear novas execuções.

Operações já em andamento deverão seguir política definida para:

  • terminar;
  • pausar;
  • cancelar;
  • entrar em revisão.

43. Security Policy Hierarchy

As políticas devem ser avaliadas nesta ordem conceitual:

Global Security
      ↓
Tenant Policy
      ↓
User Permissions
      ↓
Domain Policy
      ↓
Capability Policy
      ↓
Resource Policy
      ↓
Operation Policy

Um DENY explícito em nível superior não poderá ser sobrescrito por nível inferior.

44. Audit vs Application Logs

Não confundir:

Application Logs​

Para debugging técnico.

Audit Events​

Para rastreabilidade de negócio e segurança.

Metrics​

Para agregação estatística.

Security Events​

Para incidentes e ameaças.

São sistemas relacionados, mas semanticamente diferentes.

45. Audit API

Interface conceitual:

interface AuditService {
  append(event: AuditEvent): Promise<void>;

  getOperation(
    operationId: string
  ): Promise<AuditEvent[]>;

  search(
    query: AuditQuery
  ): Promise<AuditEvent[]>;

  verifyIntegrity(
    operationId: string
  ): Promise<IntegrityResult>;
}

46. Security Decision Record

Cada operação crítica poderá possuir:

interface SecurityDecisionRecord {
  decisionId: string;

  operationId: string;

  policyVersion: string;

  decision:
    | "ALLOW"
    | "DENY"
    | "REQUIRE_CONFIRMATION"
    | "REQUIRE_HUMAN_REVIEW";

  reasons: string[];

  evaluatedAt: string;
}

47. Compliance Report

O sistema deverá permitir relatórios como:

Todas as alterações realizadas pelo agente durante agosto.

ou:

Todas as operações de alto risco que exigiram confirmação.

ou:

Todas as operações negadas pelo Policy Engine.

48. Example — Alteração de validade

Usuário:

Mude a validade para 60 dias.

Audit trail:

MESSAGE_RECEIVED
      ↓
INTENT_RESOLVED
      ↓
TARGET_RESOLVED = WP-123
      ↓
CAPABILITY_SELECTED
      ↓
POLICY_ALLOWED
      ↓
CONFIRMATION_REQUESTED
      ↓
CONFIRMATION_ACCEPTED
      ↓
EXECUTION_STARTED
      ↓
DATA_MUTATION
      ↓
VERIFICATION_SUCCESS
      ↓
UI_REFRESH
      ↓
EXECUTION_COMPLETED

Resultado:

WP-123
30 dias → 60 dias

49. Example — Unauthorized operation

Usuário:

Exclua a permissão 123.

Policy:

DENY
reason = USER_NOT_AUTHORIZED

Nenhuma API de delete deve ser chamada.

Audit:

request = received
policy = denied
execution = not_started

50. Example — Stale Context

Usuário:

Mude a validade para 60.

Plano criado para:

WP-123
contextVersion = 104

Enquanto aguarda confirmação:

contextVersion = 105

O sistema detecta alteração relevante.

Resultado:

CONTEXT_STALE

A operação deverá ser revalidada antes da execução.

51. Performance

Auditoria não deve tornar o agente lento.

Objetivo:

Business operation latency
+
minimal synchronous audit overhead

Eventos não críticos poderão ser enviados de forma assíncrona.

Já eventos necessários para segurança deverão ser confirmados antes da execução.

52. Audit Failure

Uma falha no sistema de auditoria deverá ter política explícita.

Para operações críticas:

Audit unavailable
      ↓
FAIL CLOSED

Para operações de baixo risco:

Audit unavailable
      ↓
queue event
      ↓
continue

A decisão deverá ser definida por nível de risco.

53. First Vertical Slice

Implementar inicialmente:

workPermit.updateValidity
workPermit.components.add
workPermit.components.remove

Registrar:

user
tenant
intent
capability
policy
confirmation
before
after
execution
verification
agent version
manifest version

54. Critérios de aceitação

Identidade​

  • cada operação possui usuário;
  • tenant é identificado;
  • agente é distinguido do usuário;
  • identidade não vem do prompt.

Autorização​

  • policy decision é registrada;
  • authorization ocorre antes da execução;
  • authorization é revalidada durante execução;
  • DENY impede chamada de negócio.

Auditoria​

  • operações possuem operationId;
  • eventos são correlacionáveis;
  • audit é append-only;
  • operações podem ser reconstruídas;
  • versões dos componentes são registradas.

Segurança​

  • dados sensíveis são minimizados;
  • tenant isolation existe;
  • mass actions possuem proteção;
  • rate limits existem;
  • kill switch existe;
  • human review pode bloquear execução.

Compliance​

  • histórico pesquisável;
  • relatórios por período;
  • relatórios por usuário;
  • relatórios por capability;
  • relatórios de operações críticas.

Evidência de implementação e produção — 2026-09-05​

O Agent deriva principal e tenant do runtime autenticado, mantém operationId/correlation em traces e registra decisões de policy, controles de emergência e ledger append-only. O ledger conserva hashes e versões necessárias para reconstrução sem incluir dados sensíveis; guards de tenant, lote e kill switch bloqueiam a operação antes da chamada de negócio quando aplicáveis.

Em 2026-09-04, GET /audit/summary passou a entregar agregados bounded por usuário, ação e tipo de recurso, filtrados por período e sempre por tenant autenticado/super-admin. O endpoint não expõe entradas individuais fora do escopo e limita a 500 grupos.

Em 2026-09-05, o gate verify:audit-examination-governance passou com 72 testes em 9 arquivos. O canário autenticado contra o Worker de produção concluiu o ciclo DRAFT_TO_CLOSED, cinco métodos de amostragem, ações corretivas e verificações independentes, pacote de evidências reproduzível, relatório FINAL imutável, acesso externo limitado a metadados, isolamento de tenant, negação anônima e consulta auditável somente leitura. A tentativa de adulterar o ledger foi rejeitada pelo trigger AUDIT_GOVERNANCE_EVENT_IMMUTABLE; a execução comprovou 51 eventos e 84 despachos correlacionados, sem autoridade para executar operações de negócio, e removeu os dados sintéticos ao final (remainingRows: 0).

Em 2026-09-06, a regressão atual de autenticação, controle emergencial, tipos/ledger, auditoria e governança de evidências passou com 51 testes, e o typecheck do Agent passou novamente. O health público do Worker confirmou runtime e bindings. O estado continua PARTIAL: faltam o reporting consolidado e a aplicação de retenção/legal hold ao ledger geral, além da Evidence Fabric já protegida.

55. Resultado arquitetural

Com o PRD-013, a plataforma passa a ter uma camada transversal:

                     AGENT PLATFORM
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
     Security            Audit             Compliance
        │                  │                  │
        └──────────────────┼──────────────────┘
                           │
                     Agent Runtime
                           │
       ┌───────────────────┼───────────────────┐
       ▼                   ▼                   ▼
 Knowledge            Capabilities          UI
       │                   │                   │
       └───────────────────┼───────────────────┘
                           ▼
                        APIs

O resultado é que nenhuma operação do agente fica sem identidade, autorização ou rastreabilidade.

PRD-014 — Agentic Testing, Simulation & Evaluation Framework

O próximo PRD deverá atacar um problema crítico que aparece quando todos esses componentes começarem a trabalhar juntos:

Como provar que o agente está correto antes de colocá-lo em produção?

Não basta testar:

API → response 200

Precisaremos testar o comportamento completo:

Natural Language
      ↓
Context
      ↓
Intent
      ↓
Reference Resolution
      ↓
Capability
      ↓
Plan
      ↓
Policy
      ↓
Confirmation
      ↓
Execution
      ↓
Verification
      ↓
UI
      ↓
Final Response

O PRD-014 deverá definir uma infraestrutura de testes que permita criar cenários determinísticos de agentes, incluindo:

  • testes de intenção;
  • testes de contexto;
  • testes de referência;
  • testes de planejamento;
  • testes de policy;
  • testes de capabilities;
  • testes de UI semântica;
  • testes de segurança;
  • testes multi-tenant;
  • testes de prompt injection;
  • testes de confirmação;
  • testes de undo;
  • testes de falhas;
  • testes de concorrência;
  • testes de performance;
  • testes de regressão;
  • avaliação de respostas do LLM;
  • simulation mode;
  • shadow execution;
  • replay de operações reais anonimizadas.

A meta será permitir que uma alteração em qualquer parte da plataforma responda automaticamente:

“Essa mudança melhorou ou piorou o comportamento do agente?”