agent-opfor

Emulação adversária open‑source para agentes de IA, aplicações LLM e servidores MCP.
Teste sua IA como um atacante real faria — a partir do terminal, da sua IDE ou de uma extensão de navegador que qualquer membro da equipa pode usar.

Site · Documentação · GitHub · Extensão para navegador · Discord

OPFOR é a abreviatura de Opposition Force — um termo militar para a unidade que faz o papel de inimigo nos treinos, para que o resto do exército aprenda como são os ataques reais antes que eles aconteçam. Nomeámos a ferramenta com essa ideia em mente: para defender melhor os agentes de IA, primeiro tens de os atacar.

Porque construímos isto

Entregámos 130 produtos para 90 startups nos últimos dez anos. Nos últimos 18 meses, quase todos tinham um agente de IA — e todas essas equipas bateram no mesmo muro ao testá-lo.

Por isso construímos o OPFOR. Primeiro para nós. Agora open source.

Apache 2.0. Feito na Índia.

Início rápido

npm install -g @keyvaluesystems/agent-opfor-cli
export OPENAI_API_KEY=your-key    # or GEMINI_API_KEY, ANTHROPIC_API_KEY, etc.

Passo único — executa o assistente de configuração e inicia imediatamente a verificação:

opfor run

Dois passos — guarda uma configuração que podes reutilizar ou enviar para CI:

opfor setup                               # wizard saves a config to .opfor/configs/
opfor run --config .opfor/configs/<file>  # run any time against the saved config

https://github.com/user-attachments/assets/a6a3cff2-2cf9-4486-944e-ac0163e7ea04

O que o opfor faz

O opfor testa a superfície completa de agentes de IA — prompts, ferramentas, servidores MCP, memória e raciocínio multi‑turno. Gera ataques direcionados para OWASP LLM Top 10, OWASP Agentic AI Top 10, OWASP MCP Top 10, OWASP API Security e conjuntos de preconceito da EU AI Act, dispara‑os contra o teu alvo e avalia cada resposta com um LLM.

A maioria das ferramentas de red‑team neste espaço é excelente numa coisa — uma biblioteca de sondas, um avaliador para programadores, um framework programático. O Opfor cobre mais terreno com uma única ferramenta:

• Extensão de navegador para não‑programadores — qualquer membro da equipa pode fazer red‑team a um chatbot implantado, sem código, sem variáveis de ambiente, sem YAML
• Executa o opfor como servidor MCP — deixa o teu agente de IA no Cursor ou Claude Desktop testar os teus outros agentes em linguagem natural
• Cobertura OWASP completa numa só ferramenta — LLM Top 10, Agentic AI Top 10, MCP Top 10, API Security Top 10
• Sem caixa‑negra — cada prompt de ataque, pedido, resposta e veredito do juiz é registado; reproduzível, auditável, bifurcável
• Feito para agentes, não apenas para modelos — desenhado desde o primeiro dia para chamadas de ferramentas, MCP, memória e estado multi‑turno
• Consciente de rastreios — integra‑se com Langfuse e Netra para que o juiz LLM veja o que o teu agente fez internamente, não apenas o que disse

Cinco formas de executar o opfor

Diferentes pessoas na tua equipa precisam de diferentes pontos de entrada. O Opfor fornece cinco.

Todos os cinco partilham os mesmos avaliadores, modelos de ataque e lógica de juiz.

→ Referência do CLI · Configuração da extensão para navegador · Configuração do MCP · Configuração de Skills · Referência do SDK · Gestão de sessões

Como funciona

Quando executas uma verificação, o opfor:

1. Obtém informações do alvo — liga‑se ao teu agente, deteta ferramentas disponíveis, endpoints MCP, capacidades
2. Planeia ataques por categoria — gera prompts direcionados para cada avaliador no conjunto selecionado
3. Emula o ataque — executa conversas adversárias multi‑turno (pedidos reais, respostas reais)
4. Avalia com um juiz — um juiz LLM classifica cada resposta com passou/falhou + raciocínio
5. Gera um relatório — HTML para navegação, JSON para CI/CD, todos os artefactos registados para reprodutibilidade

Cada execução fica na sua própria sub‑pasta em .opfor/reports/run-report-<compactTs>-<slug>-<shortId>/ contendo <slug>-report.html e <slug>-report.json. As execuções autónomas opfor hunt usam a mesma estrutura em hunt-report-<compactTs>-<slug>-<shortId>/.

Cobertura dos avaliadores

O Opfor inclui conjuntos selecionados que mapeiam os padrões da indústria. Escolhe um conjunto ou executa avaliadores individuais.

→ Referência completa dos avaliadores e mapeamento OWASP

Testes com rastreio

Liga o opfor à tua stack de observabilidade e o juiz LLM vê não só a resposta final — mas cada chamada de ferramenta, cada recuperação e cada passo intermédio de raciocínio. Fora da caixa, o opfor integra‑se com Langfuse e Netra .

"telemetry": {
  "provider": "langfuse",
  "langfuse": { "baseUrl": "https://cloud.langfuse.com" }
}

Isto capta o que os testes de entrada/saída perdem — PII que vaza para uma chamada de ferramenta mas nunca chega ao utilizador, escaladas de âmbito no MCP que não alteram o texto da resposta, agentes que recuperam dados não autorizados mas produzem uma resposta limpa.

→ Guia de testes com rastreio

Red‑teaming autónomo

opfor hunt salta completamente o ficheiro de configuração. Dá‑lhe um endpoint e um objetivo, e um sistema multi‑agente — comandante, operadores, batedor — executa uma campanha de ataque adaptativa por conta própria: reconhecimento, estratégia, sondagens multi‑turno, relatório. Ao contrário de opfor run, os agentes executam apenas no Claude (através de uma chave API do Claude, claude setup‑token ou da tua sessão local claude login) — o teu alvo pode ser qualquer coisa.

opfor hunt \
  --endpoint "https://your-agent.com/v1/chat" \
  --objective "Encontre jailbreaks, fuga do prompt do sistema e desvios de segurança."

Adiciona --ui para ver a árvore de ataque a desenrolar‑se num painel ao vivo.

→ Referência completa

Extensão de navegador — faz red‑team a um chatbot

A extensão de navegador é o caminho sem código do opfor. Instala a partir da Chrome Web Store, abre qualquer interface de chat, clica no ícone do opfor, escolhe um conjunto e vê‑o executar.

https://github.com/user-attachments/assets/80c2692f-b18b-4899-99df-e7eb8d50b02a

Ela deteta automaticamente a interface de chat, envia prompts de ataque como se tu os estivesses a escrever, observa as respostas e descarrega um relatório HTML quando termina. Sem CLI, sem configuração do alvo, sem YAML.

Este é o caminho para a metade de cada equipa de produto que não abre um terminal.

→ Instalar a partir da Chrome Web Store · Guia de configuração

SDK — incorpora red‑teaming no teu código

O SDK é o caminho programático do opfor. Instala @keyvaluesystems/agent-opfor-sdk, chama run ou hunt , e obtém resultados estruturados de volta — sem CLI, sem ficheiros de configuração, sem subprocessos.

import { Opfor } from "@keyvaluesystems/agent-opfor-sdk";

const opfor = new Opfor({ apiKey: process.env.ANTHROPIC_API_KEY });

const results = await opfor.run({
  target: { url: "https://api.example.com/chat" },
  suite: "owasp-llm-top10",
});

Usa‑o em CI, em conjuntos de teste, ou em qualquer sítio onde precises de red‑teaming sem sair do TypeScript.

→ Referência do SDK

Exemplos

Fornecedores de LLM suportados

Contribuir

Lê CONTRIBUTING.md para detalhes sobre o nosso código de conduta e o processo para submeter pull requests.

Autores

Construído pela equipa da KeyValue Software Systems. Contacta [email protected] para qualquer questão.

Segurança

Usa o opfor apenas em sistemas que possuas ou que tenhas autorização para testar. Para reportar uma vulnerabilidade no próprio opfor, vê SECURITY.md — não abras um issue público.

Licença

O Opfor está licenciado sob Apache 2.0 — consulta o ficheiro LICENSE para mais detalhes.

Construído com ❤️ pela KeyValue