agent-opfor v0.10.1

Emulazione dell'avversario open-source per agenti AI, app LLM e server MCP.
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.

Sito web · Documentazione · GitHub · Estensione browser · Discord

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.

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

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:

opfor run

Due passaggi — salva una configurazione riutilizzabile o da committare in CI:

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.

Tutti e cinque condividono gli stessi valutatori, template di attacco e logica del giudice.

→ Riferimento CLI · Configurazione estensione browser · Configurazione MCP · Configurazione Skills · Riferimento SDK · Gestione sessioni

Come funziona

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.

→ Riferimento completo dei valutatori e mappatura OWASP

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 e Netra.

"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

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.

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

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 · Guida all'installazione

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.

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

Esempi

Provider LLM supportati

Contribuire

Leggi CONTRIBUTING.md per dettagli sul nostro codice di condotta e sul processo per inviare pull request.

Autori

Costruito dal team di KeyValue Software Systems. Contatta [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 — non aprire un issue pubblico.

Licenza

Opfor è concesso in licenza Apache 2.0 — vedi il file LICENSE per i dettagli.

Costruito con ❤️ da KeyValue