Desenvolvedores

Documentação para desenvolvedores

Pergunte ao Vulnify se uma ação do agente é permitida antes de executá-la.

Guia rápido

1. Entre, abra Painel → Abrir sandbox demo (ou cadastre seus próprios agentes e recursos).
2. Abra Chaves de API e crie uma chave. Ela é exibida uma única vez.
3. Chame a API antes de o agente executar uma ação sensível:

curl -X POST https://YOUR_API_HOST/v1/events \
  -H "Authorization: Bearer $VULNIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"agent":"SalesBot","action":"EXPORT_DATA","resource":"Customer Database","destination":"EXTERNAL_EMAIL","recordsAffected":12000}'

{
  "id": "0f6c1b1e-...",
  "decision": "BLOCK",
  "evaluatedDecision": "BLOCK",
  "monitored": false,
  "riskLevel": "CRITICAL",
  "riskScore": 100,
  "reasons": [
    "Export operation",
    "Customer PII",
    "External destination",
    "Large data volume (12,000 records)",
    "Policy matched: Block external export of customer PII"
  ],
  "policy": { "id": "a1b2...", "name": "Block external export of customer PII" },
  "review": null
}

Autenticação

Envie a chave de API da sua organização como bearer token: Authorization: Bearer vln_live_... (ou X-API-Key). As chaves pertencem a uma organização, são guardadas apenas como hash e podem ser revogadas a qualquer momento na página de Chaves de API. Mantenha-as no servidor; nunca as envie ao navegador.

POST /v1/events

Avalia uma ação de agente e a registra em Eventos de segurança e no Log de auditoria.

A resposta contém decision (o que você deve obedecer: ALLOW, REVIEW ou BLOCK), evaluatedDecision, monitored, riskScore (0-100), riskLevel, reasons, policy e review.

Tratando decisões

• ALLOW: prossiga.
• REVIEW: não prossiga automaticamente; uma pessoa precisa aprovar (veja Revisão humana).
• BLOCK: não execute a ação. Registre os motivos e explique ao usuário.

Se o Vulnify estiver inacessível, defina seu modo de falha. Recomendamos fail closed para ações destrutivas ou de exportação e fail open apenas para leituras de baixo risco.

Revisão humana

Uma decisão REVIEW cria uma revisão pendente (válida por 24 horas). Os aprovadores a resolvem na tela Revisões, com uma nota opcional; toda aprovação ou negação é registrada no log de auditoria com o revisor. Consulte o evento para saber o resultado:

// decision === "REVIEW" -> a human must approve. The response carries:
"review": { "status": "PENDING", "expiresAt": "2026-09-26T14:00:00Z" }

// Poll until it is resolved (APPROVED | DENIED | EXPIRED):
curl https://YOUR_API_HOST/v1/events/EVENT_ID \
  -H "Authorization: Bearer $VULNIFY_API_KEY"

Modo monitor

Implante sem risco. Em Configurações você pode colocar a organização em Somente monitorar (ou colocar políticas individuais em Monitor). O Vulnify então avalia e registra cada ação, mas devolve ALLOW ao agente, com monitored: true e evaluatedDecision mostrando o que teria acontecido. Confira a contagem de "seriam bloqueadas" no painel e depois ative a aplicação.

SDK Node

npm install @vulnify/sdk

import { Vulnify, VulnifyBlockedError } from '@vulnify/sdk';

const vulnify = new Vulnify({
  apiKey: process.env.VULNIFY_API_KEY!,
  baseUrl: 'https://YOUR_API_HOST',
  failMode: 'closed',   // 'open' allows the action if Vulnify is unreachable
  timeoutMs: 3000,
});

try {
  // Third argument: wait for a human when the decision is REVIEW.
  await vulnify.guard(
    { agent: 'SalesBot', action: 'EXPORT_DATA', resource: 'Customer Database',
      destination: 'EXTERNAL_EMAIL', recordsAffected: 12000 },
    () => exportCustomers(),
    { timeoutMs: 5 * 60_000, pollMs: 2000 },
  );
} catch (err) {
  if (err instanceof VulnifyBlockedError) {
    console.warn(err.result.decision, err.result.reasons);
  } else throw err;
}

Erros de configuração (chave inválida, agente ou recurso desconhecido, payload inválido) sempre lançam exceção, então nunca são ignorados silenciosamente pelo failMode.

Chaves de API e escopos

Crie chaves em Chaves de API. Cada chave pode ser limitada a um ambiente, um agente, um conjunto de IPs de origem e uma data de expiração:

• vln_live_... chaves de produção; vln_test_... chaves de sandbox: seus eventos são avaliados normalmente, mas ficam fora dos painéis e do uso (sandbox: true).
• Uma chave vinculada a um agente só pode reportar eventos desse agente (403 caso contrário) e pode omitir o campo agent.
• Uma lista de IPs permitidos rejeita requisições de outros endereços (403). Chaves expiradas ou revogadas retornam 401.

Idempotência

Envie o cabeçalho Idempotency-Key (qualquer texto único, até 200 caracteres). Repetir com a mesma chave devolve a decisão original (com o cabeçalho Idempotent-Replay: true) e nunca cria um segundo evento, mesmo com tentativas concorrentes. As chaves são lembradas por 24 horas. Os SDKs fazem isso por você.

Conteúdo sensível (DLP)

Opcionalmente envie content (até 100.000 caracteres). O Vulnify o analisa em memória em busca de CPF, CNPJ, cartões de pagamento (Luhn), e-mails, chaves de API e chaves privadas. A resposta lista os tipos em dlpFindings e a pontuação de risco sobe 25. O conteúdo em si nunca é armazenado: apenas os tipos detectados são mantidos.

POST /v1/events  { ..., "content": "Ana Souza, CPF 529.982.247-25" }

{
  "decision": "ALLOW",
  "riskScore": 30,
  "dlpFindings": ["CPF"],
  "reasons": ["Read operation", "Sensitive data detected in content: CPF"]
}

Permissões dos agentes

As permissões concedem ações sobre tipos de dados (por exemplo READ_DATA em FINANCIAL). Com a aplicação ativa, uma ação fora das permissões do agente é BLOQUEADA com o motivo "Sem permissão", e toda ação de um agente pausado ou desativado é bloqueada. Gerencie em Agentes → Permissões.

SDK Python e adaptadores

from vulnify import Vulnify, VulnifyBlockedError

vulnify = Vulnify(api_key=os.environ["VULNIFY_API_KEY"], base_url="https://YOUR_API_HOST")

vulnify.guard(export_customers, agent="SalesBot", action="EXPORT_DATA",
              resource="Customer Database", destination="EXTERNAL_EMAIL",
              records_affected=12000, wait={"timeout": 300})

O SDK Node inclui adaptadores para tool calls da OpenAI/Anthropic (guardedTools), LangChain (guardLangChainTool), servidores MCP (guardMcpHandler) e qualquer função (guardFunction). Veja a pasta examples do repositório.

Uma referência OpenAPI interativa é servida pela API em /docs-api (e a especificação JSON em /docs-api-json) em ambientes que não são de produção.

Como o risco é calculado

As notas são baseadas em regras e explicáveis, limitadas a 100. Níveis: 0-24 BAIXO, 25-49 MÉDIO, 50-74 ALTO, 75-100 CRÍTICO. BAIXO e MÉDIO são permitidos, ALTO exige revisão, CRÍTICO é bloqueado, a menos que uma política diga o contrário.

As políticas (Bloquear / Revisar / Permitir) são avaliadas depois da nota. Uma política Bloquear ou Revisar sempre prevalece; uma política Permitir é uma exceção explícita.

Erros e limites

• 400 payload inválido (campos desconhecidos são rejeitados).
• 401 chave de API ausente, inválida ou revogada.
• 404 agente, recurso ou evento desconhecido na sua organização.
• 403 chave vinculada a outro agente, ou IP de origem não permitido.
• 413 corpo maior que 200 KB.
• 429 limite de requisições excedido (1.200 por minuto por IP, por padrão).