Emulazione avversaria open-source per agenti AI e server 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>Emulazione dell'avversario open-source per agenti AI, app LLM e server MCP.</strong><br/>
Testa la tua IA come farebbe un vero attaccante — dal tuo CLI, dal tuo IDE o da un'estensione del browser che chiunque nel tuo team può usare.
</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="License: 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="GitHub stars"></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="OWASP coverage"></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/">Sito web</a> ·
<a href="https://docs.agentopfor.ai">Documentazione</a> ·
<a href="https://github.com/KeyValueSoftwareSystems/agent-opfor">GitHub</a> ·
<a href="https://chromewebstore.google.com/detail/blkflfeicejfnbecanjaolbllmoobenp">Estensione browser</a> ·
<a href="https://discord.gg/Sb8xfmrjjW">Discord</a>
</p>
OPFOR è l'abbreviazione di _Opposition Force_ — un termine militare per l'unità che interpreta il nemico durante l'addestramento, così il resto dell'esercito impara come sono i veri attacchi prima che arrivino. Abbiamo chiamato lo strumento ispirandoci a questa idea: per difendere meglio gli agenti IA, devi attaccarli per primi.
<p align="center">
<img src="https://raw.githubusercontent.com/keyvaluesoftwaresystems/agent-opfor/HEAD/assets/opfor-high-level.svg" alt="Come funziona OPFOR" width="860" />
</p>
## Perché l'abbiamo costruito
Negli ultimi dieci anni abbiamo rilasciato 130 prodotti per 90 startup. Negli ultimi 18 mesi, quasi tutti includevano un agente IA — e ogni singolo team ha incontrato lo stesso muro quando si trattava di testarli.
Così abbiamo costruito OPFOR. Prima per noi stessi. Ora open source.
Apache 2.0. Costruito dall'India.
## Avvio rapido
```bash
npm install -g @keyvaluesystems/agent-opfor-cli
export OPENAI_API_KEY=your-key # oppure GEMINI_API_KEY, ANTHROPIC_API_KEY, ecc.
```
**Unico comando** — avvia la procedura guidata e subito la scansione:
```bash
opfor run
```
**Due passaggi** — salva una configurazione riutilizzabile o da committare in CI:
```bash
opfor setup # la procedura guidata salva una configurazione in .opfor/configs/
opfor run --config .opfor/configs/<file> # esegui in qualsiasi momento con la configurazione salvata
```
https://github.com/user-attachments/assets/a6a3cff2-2cf9-4486-944e-ac0163e7ea04
## Cosa fa opfor
Opfor esegue red-team sull'intera superficie degli agenti IA — prompt, strumenti, server MCP, memoria e ragionamento multi-turno. Genera attacchi mirati per OWASP LLM Top 10, OWASP Agentic AI Top 10, OWASP MCP Top 10, OWASP API Security e suite di bias dell'EU AI Act, li invia al tuo target e valuta ogni risposta con un LLM come giudice.
La maggior parte degli strumenti di red-teaming in questo spazio è eccellente in una cosa — una libreria di probe, un valutatore per sviluppatori, un framework programmatico. Opfor copre più terreno con un unico strumento:
- **Estensione browser per non sviluppatori** — chiunque nel tuo team può fare red-team a un chatbot in produzione, senza codice, senza variabili d'ambiente, senza YAML
- **Esegui opfor come server MCP** — lascia che il tuo agente di codifica AI in Cursor o Claude Desktop faccia red-team ad altri tuoi agenti tramite linguaggio naturale
- **Copertura completa OWASP in un unico strumento** — LLM Top 10, Agentic AI Top 10, MCP Top 10, API Security Top 10
- **Nessuna scatola nera** — ogni prompt di attacco, richiesta, risposta e verdetto del giudice viene registrato; riproducibile, verificabile, forkabile
- **Progettato per agenti, non solo per modelli** — pensato sin dall'inizio per chiamate a strumenti, MCP, memoria e stato multi-turno
- **Consapevole delle tracce** — si integra con Langfuse e Netra in modo che il giudice LLM veda ciò che il tuo agente ha fatto internamente, non solo ciò che ha detto
## Cinque modi per eseguire opfor
Persone diverse nel tuo team hanno bisogno di punti di ingresso diversi. Opfor ne offre cinque.
| Modalità | Come | Ideale per |
| --------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 🖥️ **CLI** | `opfor setup` → `opfor run` | Ingegneri, CI/CD, flussi di lavoro basati su terminale |
| 🌐 **Estensione browser** | Installa l'estensione, clicca l'icona su qualsiasi interfaccia chat | Product manager, designer, QA, analisti di sicurezza — chiunque non possa o voglia scrivere codice |
| 🤖 **Server MCP** | Registra opfor in Cursor o Claude Desktop, poi chiedi in chat | Agenti di codifica AI che testano altri tuoi agenti |
| ⚡ **Skills** | `/opfor-setup` · `/opfor-run` · `/opfor-mcp-setup` · `/opfor-mcp-run` | Sviluppatori che vogliono test con un solo comando all'interno del loro IDE |
| 📦 **SDK** | `npm install @keyvaluesystems/agent-opfor-sdk`, poi chiama `run` / `hunt` dal tuo codice | Red-teaming programmatico e flussi di lavoro personalizzati |
Tutti e cinque condividono gli stessi valutatori, template di attacco e logica del giudice.
→ [Riferimento CLI](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/cli.md) · [Configurazione estensione browser](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/browser-extension.md) · [Configurazione MCP](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/mcp.md) · [Configurazione Skills](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/skills.md) · [Riferimento SDK](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/sdk.md) · [Gestione sessioni](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/sessions.md)
## Come funziona
<p align="center">
<img src="https://raw.githubusercontent.com/keyvaluesoftwaresystems/agent-opfor/HEAD/assets/opfor-execution-flow.svg" alt="Cosa succede durante opfor run" width="860" />
</p>
Quando esegui una scansione, opfor:
1. **Recupera le informazioni del target** — si connette al tuo agente, rileva gli strumenti disponibili, gli endpoint MCP, le capacità
2. **Pianifica gli attacchi per categoria** — genera prompt mirati per ogni valutatore nella suite selezionata
3. **Emula l'attacco** — esegue conversazioni avversarie multi-turno (richieste reali, risposte reali)
4. **Valuta con un giudice** — un giudice LLM classifica ogni risposta con pass/fail + motivazione
5. **Genera un report** — HTML per la navigazione, JSON per CI/CD, tutti gli artefatti registrati per riproducibilità
Ogni esecuzione finisce nella propria sottocartella sotto `.opfor/reports/run-report-<compactTs>-<slug>-<shortId>/` contenente `<slug>-report.html` e `<slug>-report.json`. Le esecuzioni autonome `opfor hunt` usano la stessa struttura sotto `hunt-report-<compactTs>-<slug>-<shortId>/`.
## Copertura dei valutatori
Opfor viene fornito con suite curate che mappano agli standard del settore. Scegli una suite o esegui singoli valutatori.
| Suite ID | Standard | Focus |
| ------------------ | ------------------------- | ------------------------------------------------------------------------- |
| `owasp-llm-top10` | OWASP LLM Top 10 (2025) | Iniezione di prompt, jailbreak, divulgazione di dati sensibili, fuga del prompt di sistema |
| `owasp-agentic-ai` | OWASP Agentic AI Top 10 | Agenzia eccessiva, abuso degli strumenti, dirottamento degli obiettivi dell'agente, avvelenamento della memoria |
| `owasp-mcp-top10` | OWASP MCP Top 10 (2025) | Esposizione di segreti, escalation di ambito, iniezione nella descrizione dello strumento, SSRF |
| `owasp-api` | OWASP API Security Top 10 | BOLA, BFLA, SQL injection |
| `eu-ai-act-bias` | EU AI Act — Bias | Età, genere, razza, disabilità |
→ [Riferimento completo dei valutatori e mappatura OWASP](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/evaluators.md)
## Test consapevoli delle tracce
Collega opfor al tuo stack di osservabilità e il giudice LLM vede non solo la risposta finale — ma ogni chiamata a strumento, recupero e passaggio intermedio di ragionamento. Opfor si integra nativamente con **[Langfuse](https://langfuse.com)** e **[Netra](https://getnetra.ai)**.
```json
"telemetry": {
"provider": "langfuse",
"langfuse": { "baseUrl": "https://cloud.langfuse.com" }
}
```
Questo cattura ciò che il solo test input/output non rileva — PII che finisce in una chiamata a strumento ma non arriva mai all'utente, escalation di ambito in MCP che non modificano il testo della risposta, agenti che recuperano dati non autorizzati ma restituiscono una risposta pulita.
→ [Guida ai test consapevoli delle tracce](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/telemetry.md)
## Red-Teaming Autonomo
`opfor hunt` salta completamente il file di configurazione. Dagli un endpoint e un obiettivo, e un sistema multi-agente — comandante, operatori, esploratore — esegue autonomamente una campagna di attacco adattiva: ricognizione, strategia, probing multi-turno, report. A differenza di `opfor run`, gli agenti girano solo su Claude (tramite una chiave API Claude, `claude setup-token` o la tua sessione locale `claude login`) — il tuo target può essere qualsiasi cosa.
```bash
opfor hunt \
--endpoint "https://your-agent.com/v1/chat" \
--objective "Trova jailbreak, fuga del prompt di sistema e bypass di sicurezza."
```
Aggiungi `--ui` per vedere l'albero degli attacchi dispiegarsi in una dashboard live.
→ [Riferimento completo](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/hunt.md)
## Estensione browser — red-team a un chatbot
L'estensione del browser è il percorso senza codice di opfor. Installala dal Chrome Web Store, apri qualsiasi interfaccia chat, clicca sull'icona di opfor, scegli una suite e guardala eseguire.
https://github.com/user-attachments/assets/80c2692f-b18b-4899-99df-e7eb8d50b02a
Rileva automaticamente l'interfaccia di chat, invia prompt di attacco come se li stessi digitando tu, osserva le risposte e scarica un report HTML al termine. Nessun CLI, nessuna configurazione del target, nessun YAML.
Questo è il percorso per la metà di ogni team di prodotto che non apre un terminale.
→ [Installa dal Chrome Web Store](https://chromewebstore.google.com/detail/blkflfeicejfnbecanjaolbllmoobenp) · [Guida all'installazione](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/browser-extension.md)
## SDK — incorpora il red-teaming nel tuo codice
L'SDK è il percorso programmatico di opfor. Installa `@keyvaluesystems/agent-opfor-sdk`, chiama `run` o `hunt` e ottieni risultati strutturati — nessun CLI, nessun file di configurazione, nessun sottoprocesso.
```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",
});
```
Usalo in CI, in suite di test, o ovunque tu abbia bisogno di red-teaming senza lasciare TypeScript.
→ [Riferimento SDK](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/docs/sdk.md)
## Esempi
| Esempio | Descrizione |
| ----------------------------------------------------- | --------------------------------------------------------------- |
| [vanilla-chat](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/tests/e2e/agents/vanilla-chat) | Chatbot di supporto clienti semplice — testa vulnerabilità a livello LLM |
| [customer-support](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/tests/e2e/agents/customer-support) | Agente con chiamata a strumenti e PostgreSQL — testa BOLA, BFLA, RBAC, PII |
| [vulnerable-server](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/tests/e2e/mcp/vulnerable-server) | Server MCP di esempio con vulnerabilità intenzionali |
## Provider LLM supportati
| Provider | Variabile d'ambiente | Modello predefinito |
| ----------------- | ------------------------------ | -------------------------------------- |
| 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` |
| Compatibile OpenAI | `OPFOR_API_KEY` + `baseURL` | LiteLLM, OpenRouter, Azure, Ollama |
## Contribuire
Leggi [CONTRIBUTING.md](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/CONTRIBUTING.md) per dettagli sul nostro codice di condotta e sul processo per inviare pull request.
## Autori
Costruito dal team di [KeyValue Software Systems](https://keyvalue.systems). Contatta [[email protected]](mailto:[email protected]) per qualsiasi richiesta.
## Sicurezza
Usa opfor solo su sistemi di tua proprietà o per cui sei autorizzato a fare test. Per segnalare una vulnerabilità in opfor stesso, consulta [SECURITY.md](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/SECURITY.md) — non aprire un issue pubblico.
## Licenza
Opfor è concesso in licenza Apache 2.0 — vedi il file [LICENSE](https://github.com/keyvaluesoftwaresystems/agent-opfor/blob/master/LICENSE) per i dettagli.
---
<p align="center">
Costruito con ❤️ da <a href="https://keyvalue.systems">KeyValue</a>
</p>