AIVP [AI Vulnerabilities Playground]

AIVP è una piattaforma pratica di laboratorio di sicurezza AI che copre 4 fasi e 50+ laboratori (attualmente 50+ scenari nel codebase). Combina Ollama + Llama 3.1, un backend FastAPI e un frontend React/Vite per consentire ai professionisti di esercitarsi in sicurezza su tecniche offensive e difensive di sicurezza AI.

Se questo progetto ti è utile, per favore ⭐ metti una stella / metti mi piace al repo, fai un fork, e sentiti libero di aprire PR!

Sommario

• Panoramica
• Passaggi di esecuzione
• Prerequisiti
• Struttura del progetto
• Requisiti hardware
• Setup e installazione
  • Avvio rapido (Windows PowerShell)
  • Avvio rapido (bash macOS/Linux)
  • Passaggi manuali
• Esecuzione dei laboratori
• Configurazione
• Screenshot
• Risoluzione dei problemi
• Contribuire
• Problemi e feedback
• Licenza

Passaggi di esecuzione

Usa la guida dedicata: RUN_STEPS.md. Copre i flussi manuale (Vite + uvicorn) e Docker (nginx + API + Redis, Ollama sull'host), inclusi i prerequisiti per un accesso affidabile ai laboratori.

Il comportamento della configurazione è rigoroso nei percorsi di runtime attivi: i valori env obbligatori mancanti possono far fallire l'avvio per progettazione.

Panoramica

La piattaforma copre quattro percorsi formativi:

• Fase 1 (PI): injection di prompt e pattern di abuso delle istruzioni
• Fase 2 (DE): sistemi agenziali, perdite di tool/memoria/RAG ed estrazione di dati multi-sistema
• Fase 3 (MM): manipolazione del modello e superfici d'attacco solo-modello
• Fase 4 (MCP): confini di fiducia MCP e scenari di rischio allineati a OWASP MCP

Ogni laboratorio usa segreti dinamici specifici e una validazione esplicita, così puoi verificare il successo dell'exploit in un ambiente sicuro.

Solo a scopo educativo — I laboratori simulano scenari di sicurezza AI offensivi e difensivi su sistemi locali. Non prendere di mira servizi, dati o infrastrutture reali che non possiedi o per cui non hai esplicita autorizzazione al test. I segreti in questi laboratori sono sintetici e rigenerati per ogni laboratorio; non sono credenziali di produzione. Utilizzo a proprio rischio. Nessuna garanzia fornita.

• Modello: Llama 3.1 tramite Ollama (locale)
• Backend: FastAPI (streaming SSE) — POST /api/labs/{lab}/chat
• Frontend: React + Vite (interfaccia Tailwind)
• Segreti: generati per ogni laboratorio a runtime; azzerati al riavvio dell'API (o tramite endpoint di reset)
• Funzionalità uniche: simulazione reale di sottosistemi (agent/tool/memoria/RAG), telemetria di tracciamento delle esecuzioni, modalità di configurazione rigorosa e flussi di lavoro manuale + Docker

Prerequisiti

• Python 3.10+ (3.12 funziona)
• Node.js 18+ (consigliato Node 20 LTS)
• Ollama installato e in esecuzione in locale
• Git (opzionale ma consigliato)

Esegui il pull del modello almeno una volta: ollama pull llama3.1 (o un'altra variante compatibile con llama3.1 che preferisci)

Struttura del progetto

apps/
  api/                # Backend FastAPI (SSE -> Ollama)
    main.py
    requirements.txt
    .env.example
  web/                # Frontend React + Vite
    src/
    .env.example

Requisiti hardware

• Minimo (solo CPU): 4 core, 16 GB di RAM, 10 GB di disco libero, nessuna GPU → funziona, generazioni più lente
• Consigliato: 8 core, 32 GB di RAM, SSD con 20+ GB liberi, NVIDIA 8–12 GB di VRAM (o Apple Silicon) → esperienza fluida

CPU

• CPU a 64 bit con AVX2 (Intel/AMD moderni) o Apple Silicon (M1/M2/M3).
• 4 core minimo; consigliati 8+ core per chat parallela + strumenti di sviluppo.

RAM (Llama 3 8B tramite Ollama, quantizzato)

• Q4_K_M (~4–5 GB di modello): richiede ~6–8 GB a runtime.
• Q5/Q6 (~6–8 GB): ~10–12 GB a runtime.
• Q8 (~9–10 GB): ~14–16 GB a runtime.

Suggerimento: 16 GB di RAM di sistema funzionano; 32 GB offrono un margine confortevole per browser, Node, Python e IDE.

GPU (opzionale)

• Windows/Linux (CUDA): NVIDIA RTX con ≥8 GB di VRAM (es. 3060 12 GB è ottima).
• macOS (Metal): qualsiasi Apple Silicon.
• Solo CPU va bene; le risposte saranno solo più lente.

Disco

• Modelli: 5–10 GB a seconda della quantizzazione.
• Repo + node_modules + venv: 1–2 GB.
• Prevedi 15–20 GB liberi.

Sistema operativo

• Windows 10/11, macOS 12+, Ubuntu 20.04+ (o simili). Anche WSL2 funziona (la GPU richiede configurazione aggiuntiva).

Strumenti di sviluppo

• Python 3.10+, Node 18+ (20 LTS ideale), Ollama installato e in esecuzione.

Suggerimenti sulle prestazioni

• Inizia con llama3 (8B) Q4; aumenta la quantizzazione solo se hai RAM/VRAM disponibile.
• Mantieni prompt/contesto ragionevoli (2–4k token) per evitare picchi di memoria.
• Chiudi le app pesanti se hai 16 GB di RAM.

Setup e installazione

Avvio rapido (Windows PowerShell)

Dalla radice del repo (la cartella che contiene apps\api e apps\web):

# 0) Assicurati che il modello sia disponibile
ollama pull llama3.1

# 1) venv backend + dipendenze + avvio
cd apps/api
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
uvicorn main:app --reload --port 8000

Apri una nuova finestra PowerShell per il frontend:

cd apps/web
npm install
copy .env.example .env
npm run dev   # http://localhost:5173

Avvio rapido (bash macOS/Linux)

# 0) Modello
ollama pull llama3.1

# 1) Backend
cd apps/api
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn main:app --reload --port 8000

In un'altra shell:

cd apps/web
npm install
cp .env.example .env
npm run dev   # http://localhost:5173

Passaggi manuali

1. Avvia Ollama e lascialo in esecuzione (ollama serve se necessario).
2. Esegui il pull di Llama 3.1: ollama pull llama3.1.
3. Avvia il backend (FastAPI) sulla porta :8000.
4. Avvia il frontend (Vite) sulla porta :5173.

Il frontend riceve in streaming gli eventi Server‑Sent Events (SSE) dal backend; assicurati che le origini CORS in apps/api/.env includano http://localhost:5173.

Esecuzione dei laboratori

• Apri il frontend su http://localhost:5173.
• Vai su Esplora laboratori → scegli un laboratorio → Avvia laboratorio.
• Usa la chat per attaccare l'assistente (valgono le regole sui prompt specifiche del laboratorio).
• Una volta ottenuto il segreto, incollalo in Invia la tua risposta.

Formati ID laboratorio accettati (dal backend): PI-01, PI_01, pi01, p01 → tutti normalizzati a PI_01.

Segreti dinamici vengono creati al primo utilizzo di un laboratorio dopo un riavvio del backend. Puoi anche reimpostare un segreto:

POST /api/secrets/reset/{labId}

Il segreto di ogni laboratorio è diverso e viene rigenerato al riavvio del backend (in memoria). Valuta di usare un file/DB come supporto se ti serve la persistenza.

Configurazione

Backend (apps/api/.env)

OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1
CORS_ORIGINS=http://localhost:5173
SERVER_SALT=change-me-in-production
AIVP_DEFAULT_MODE=off
ENABLE_TRAINING_LABS=false
OLLAMA_MODEL_TRAINING_LABS=llama3.1
REDIS_URL=redis://localhost:6379/0
REDIS_HOST=localhost
REDIS_PORT=6379
MEMORY_TTL_SECONDS=3600
SESSION_TTL_SECONDS=3600
AGENT_B_URL=http://localhost:8001
MM_API_BASE=http://localhost:8000
API_BASE_URL=http://localhost:8000
JIRA_URL=https://example.atlassian.net
GITHUB_API_BASE_URL=https://api.github.com
SLACK_API_BASE_URL=https://slack.com/api

Frontend (apps/web/.env)

# Sviluppo locale: URL completo dell'API (Vite inoltra /api anche in vite.config)
VITE_API_BASE=http://localhost:8000/api
VITE_DEV_API_TARGET=http://localhost:8000
[email protected]

Le build in stile Docker/produzione usano VITE_API_BASE=/api così il browser usa percorsi same-origin dietro nginx (vedi RUN_STEPS.md → Opzione B).

Endpoint

• POST /api/labs/{lab}/chat — stream SSE con data: {"content": "..."}
• POST /api/secrets/validate — { labId, answer } → { success, message }
• POST /api/secrets/reset/{lab} — (opzionale, per test)

Screenshot

Aggiungi i tuoi screenshot in docs/screenshots/ e referenziali qui:

![Home](https://raw.githubusercontent.com/owasp/ai-vulnerabilities-playground/HEAD/docs/screenshots/home.png)
![PI‑01 Running](https://raw.githubusercontent.com/owasp/ai-vulnerabilities-playground/HEAD/docs/screenshots/about_labs.png)
![Explore Labs](https://raw.githubusercontent.com/owasp/ai-vulnerabilities-playground/HEAD/docs/screenshots/explore_labs.png)
![PI‑01 Running](https://raw.githubusercontent.com/owasp/ai-vulnerabilities-playground/HEAD/docs/screenshots/PI01.png)

Risoluzione dei problemi

``
Esegui npm install dentro apps/web.

``
Aggiungi from typing import Iterator (o rimuovi l'annotazione) in main.py.

CORS / SSE bloccati
Assicurati che CORS_ORIGINS includa http://localhost:5173.

Errori di Ollama
Assicurati che ollama serve sia in esecuzione e che il modello sia stato scaricato: ollama pull llama3.1.

Verifica rapida con curl

curl -N -X POST http://localhost:8000/api/labs/PI_01/chat \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Say hello in one sentence."}'

Dovresti vedere righe in streaming come data: {"content":"Hello …"}.

Contribuire

I contributi sono benvenuti! Per favore:

1. Fai un fork del repo e crea un branch per la funzionalità.
2. Segui lo stile di codice esistente (TypeScript/React + Python/FastAPI).
3. Aggiungi test o una demo rapida dove possibile.
4. Apri una PR con una descrizione chiara e screenshot se ci sono modifiche all'interfaccia.

Aree suggerite:

• Nuovi laboratori (Fase 1–4)
• Migliori guardrail / harness di valutazione
• Segreti persistenti (SQLite/JSON)
• Packaging e Docker

Problemi e feedback

Se trovi un bug o hai un'idea:

• Apri un Issue con i passaggi per riprodurre il problema e i dettagli dell'ambiente.
• Oppure avvia una Discussion per proporre miglioramenti.

Se ti piace questo progetto, per favore ⭐ metti una stella / metti mi piace e condividilo con altri!

Licenza

MIT.

Email

[email protected]