Emulação de adversário de código aberto para agentes de IA e servidores MCP.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/Opfor_white%20text.svg" />
<source media="(prefers-color-scheme: light)" srcset="assets/Opfor_black%20text.svg" />
<img src="https://raw.githubusercontent.com/keyvaluesoftwaresystems/agent-opfor/HEAD/assets/Opfor_black%20text.svg" alt="OPFOR" width="250" />
</picture>
</p>
<p align="center">
<strong>Emulação adversária open‑source para agentes de IA, aplicações LLM e servidores MCP.</strong><br/>
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.
</p>
<p align="center">
<a href="https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-Apache_2.0-444441?style=flat&labelColor=3d3d3a" alt="Licença: Apache 2.0"></a>
<a href="https://github.com/KeyValueSoftwareSystems/agent-opfor/stargazers"><img src="https://img.shields.io/github/stars/KeyValueSoftwareSystems/agent-opfor?style=flat&labelColor=3d3d3a&color=444441" alt="Estrelas no GitHub"></a>
<a href="https://discord.gg/Sb8xfmrjjW"><img src="https://img.shields.io/badge/Discord-join-5865F2?style=flat&logo=discord&logoColor=white&labelColor=3d3d3a" alt="Discord"></a>
<a href="#evaluator-coverage"><img src="https://img.shields.io/badge/OWASP-LLM%20+%20Agentic%20+%20MCP%20+%20API-185FA5?style=flat&labelColor=3d3d3a" alt="Cobertura OWASP"></a>
</p>
<p align="center">
<a href="https://trendshift.io/repositories/75655?utm_source=trendshift-badge&utm_medium=badge&utm_campaign=badge-trendshift-75655" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/75655/daily?language=TypeScript" alt="KeyValueSoftwareSystems%2Fagent-opfor | Trendshift" width="250" height="55"/></a>
</p>
<p align="center">
<a href="https://agentopfor.ai/">Site</a> ·
<a href="https://docs.agentopfor.ai">Documentação</a> ·
<a href="https://github.com/KeyValueSoftwareSystems/agent-opfor">GitHub</a> ·
<a href="https://chromewebstore.google.com/detail/blkflfeicejfnbecanjaolbllmoobenp">Extensão para navegador</a> ·
<a href="https://discord.gg/Sb8xfmrjjW">Discord</a>
</p>
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.
<p align="center">
<img src="https://raw.githubusercontent.com/keyvaluesoftwaresystems/agent-opfor/HEAD/assets/opfor-high-level.svg" alt="Como o OPFOR funciona" width="860" />
</p>
## 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
```bash
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:
```bash
opfor run
```
**Dois passos** — guarda uma configuração que podes reutilizar ou enviar para CI:
```bash
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.
| Modo | Como | Melhor para |
| ------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 🖥️ **CLI** | `opfor setup` → `opfor run` | Engenheiros, CI/CD, fluxos centrados no terminal |
| 🌐 **Extensão de navegador** | Instala a extensão, clica no ícone em qualquer interface de chat | Gestores de produto, designers, QA, analistas de segurança — qualquer um que não consiga ou não queira escrever código |
| 🤖 **Servidor MCP** | Regista o opfor no Cursor ou Claude Desktop, depois pergunta no chat | Agentes de IA que programam e testam os teus outros agentes |
| ⚡ **Skills** | `/opfor-setup` · `/opfor-run` · `/opfor-mcp-setup` · `/opfor-mcp-run` | Programadores que querem testes com um comando dentro da IDE |
| 📦 **SDK** | `npm install @keyvaluesystems/agent-opfor-sdk`, depois chama `run` / `hunt` a partir do teu código | Red‑teaming programático e fluxos personalizados |
Todos os cinco partilham os mesmos avaliadores, modelos de ataque e lógica de juiz.
→ [Referência do CLI](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/cli.md) · [Configuração da extensão para navegador](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/browser-extension.md) · [Configuração do MCP](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/mcp.md) · [Configuração de Skills](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/skills.md) · [Referência do SDK](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/sdk.md) · [Gestão de sessões](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/sessions.md)
## Como funciona
<p align="center">
<img src="https://raw.githubusercontent.com/keyvaluesoftwaresystems/agent-opfor/HEAD/assets/opfor-execution-flow.svg" alt="O que acontece durante o opfor run" width="860" />
</p>
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.
| ID do Conjunto | Norma | Foco |
| ------------------ | ------------------------- | ------------------------------------------------------------------------- |
| `owasp-llm-top10` | OWASP LLM Top 10 (2025) | Injeção de prompt, jailbreaks, divulgação de informação sensível, fuga do prompt do sistema |
| `owasp-agentic-ai` | OWASP Agentic AI Top 10 | Agência excessiva, uso indevido de ferramentas, sequestro do objetivo do agente, envenenamento da memória |
| `owasp-mcp-top10` | OWASP MCP Top 10 (2025) | Exposição de segredos, escalada de âmbito, injeção na descrição da ferramenta, SSRF |
| `owasp-api` | OWASP API Security Top 10 | BOLA, BFLA, SQL injection |
| `eu-ai-act-bias` | EU AI Act — Preconceito | Idade, género, raça, deficiência |
→ [Referência completa dos avaliadores e mapeamento OWASP](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/evaluators.md)
## 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](https://langfuse.com)** e **[Netra](https://getnetra.ai)** .
```json
"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](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/telemetry.md)
## 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.
```bash
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](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/hunt.md)
## 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](https://chromewebstore.google.com/detail/blkflfeicejfnbecanjaolbllmoobenp) · [Guia de configuração](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/browser-extension.md)
## 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.
```typescript
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](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/sdk.md)
## Exemplos
| Exemplo | Descrição |
| ----------------------------------------------------- | --------------------------------------------------------------- |
| [vanilla-chat](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/tests/e2e/agents/vanilla-chat) | Chatbot simples de suporte ao cliente — testa vulnerabilidades ao nível do LLM |
| [customer-support](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/tests/e2e/agents/customer-support) | Agente com chamadas de ferramentas e PostgreSQL — testa BOLA, BFLA, RBAC, PII |
| [vulnerable-server](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/tests/e2e/mcp/vulnerable-server) | Servidor MCP de exemplo com vulnerabilidades intencionais |
## Fornecedores de LLM suportados
| Fornecedor | Variável de ambiente | Modelo predefinido |
| ----------------- | ------------------------------ | ---------------------------------- |
| Groq | `GROQ_API_KEY` | `llama-3.3-70b-versatile` |
| OpenAI | `OPENAI_API_KEY` | `gpt-4o-mini` |
| Anthropic | `ANTHROPIC_API_KEY` | `claude-3-5-haiku-20241022` |
| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | `gemini-2.0-flash` |
| Compatível com OpenAI | `OPFOR_API_KEY` + `baseURL` | LiteLLM, OpenRouter, Azure, Ollama |
## Contribuir
Lê [CONTRIBUTING.md](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/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](https://keyvalue.systems). Contacta [[email protected]](mailto:[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](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/SECURITY.md) — não abras um issue público.
## Licença
O Opfor está licenciado sob Apache 2.0 — consulta o ficheiro [LICENSE](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/LICENSE) para mais detalhes.
---
<p align="center">
Construído com ❤️ pela <a href="https://keyvalue.systems">KeyValue</a>
</p>