Mahoraga Webapp Defender

Sistema di difesa reattivo per webapp basato su IA progettato per resistere a hack basati su IA in tempo reale.

Indice

Mahoraga Webapp Defender

Introduzione

Mahoraga Defender è una prova di concetto di un sistema di difesa in tempo reale, reattivo e indipendente dal tipo di attaccante. Il meccanismo principale consiste nell'indurre un avversario a effettuare scoperte e attacchi su un ambiente benigno e fittizio (ambiente "ombra") e registrare questi attacchi. Quindi, un agente LLM analizza i log e passa i dettagli di eventuali exploit rilevati ad altri agenti LLM per correggere le vulnerabilità e distribuire le patch.

Il sistema è progettato per essere completamente automatizzato con un'attenzione all'ottimizzazione dei costi delle API. È stata creata un'interfaccia grafica per monitorare facilmente i log del traffico, l'attività degli agenti e la pipeline di patching, e per controllare il numero di agenti da distribuire.

Sito web target

Il sito web target (vittima) è un fork di crAPI (Completely Ridiculous API), un'applicazione web intenzionalmente vulnerabile creata da OWASP per l'insegnamento del test di sicurezza delle API. crAPI simula una piattaforma per proprietari di veicoli con microservizi che coprono le vulnerabilità API OWASP Top 10. Il difensore è progettato per distinguere chiaramente tra sessioni utente normali e avversarie, in modo che gli utenti normali non subiscano alcuna diminuzione della qualità dell'esperienza utente mentre il difensore protegge il sito dagli attaccanti.

Il nostro fork (crapi-fork/) aggiunge:

Honeypot piantati (credenziali, endpoint, token esca) per il rilevamento degli attaccanti
Totale di 12 flag in stile CTF incorporate su tutta la superficie d'attacco
Uno stack "ombra" parallelo con servizi identici e database separati per l'osservazione sicura degli attaccanti
Routing di sessione basato su nginx Lua che reindirizza trasparentemente le sessioni sospette dalla produzione all'ombra

Una copia integra è conservata in crapi-original/ in modo che l'ambiente possa essere resettato tra un esperimento e l'altro.

Architettura di Mahoraga Defender

Ambienti duali

Prod: serve utenti reali tramite proxy inverso nginx (porta 8888)
Shadow: stack esca identico con database separati, riceve il traffico dell'attaccante reindirizzato in modo trasparente

Pipeline degli agenti

Orchestrator: coordina l'intera pipeline. Gestisce i cicli di vita degli agenti, le code di patch/revisione, lo stato dei ticket, la distribuzione e il recupero da crash. Ridimensiona il numero di agenti fixer/reviewer in esecuzione.
Watcher (basato su regole): monitora i log del traffico di produzione e assegna un punteggio alle sessioni in base al livello di minaccia utilizzando il pattern matching (brute force, injection, enumerazione, accesso a honeypot, ecc.). Una volta che il punteggio di minaccia supera una soglia, attiva l'azione di reindirizzamento.
Shadow Analyzer (agente LLM): legge i log del traffico dell'ambiente ombra a intervalli configurabili per rilevare exploit riusciti. Deduplica le voci di log, rileva i pattern di attacco e inserisce gli exploit confermati nella coda di correzione.
Fixer (agente LLM): riceve i report degli exploit, legge il codice sorgente pertinente e lo corregge direttamente in crapi-fork/. Opera in un ambiente bash sandboxed con accesso limitato solo a crapi-fork/.
Reviewer (agente LLM): verifica le patch per correttezza, ambito e sicurezza. Le patch approvate attivano l'azione di distribuzione; le patch rifiutate vengono rispedite al fixer con feedback.

Al momento della distribuzione, i servizi Python vengono ricaricati a caldo tramite gunicorn (istantaneo), mentre i servizi Java/Go vengono ricostruiti tramite docker compose up -d --build.

Perché nessun agente Tester? Avevamo considerato di aggiungere un agente di test utente dedicato e un ambiente di test separato, ma li abbiamo rimossi entrambi per mantenere il sistema leggero.

Come iniziare

Preparazione

Si consiglia di utilizzare un ambiente virtuale conda o python (ad esempio, conda create -n XYZ python=3.13, quindi conda activate XYZ).
Installa i requisiti: pip install -r requirements.txt

Esperimento completo: Difensore vs Attaccante

Esegui ./start.sh dalla directory radice del progetto — resetta il codice sorgente di crapi-fork/ da crapi-original/, ricostruisce tutti i servizi, pianta flag e honeypot.
Esegui il difensore: python3 -m harness.main --app-url http://localhost:8888 -v.
Inizia il penetration testing del sito su localhost:8888 (la descrizione della sfida si trova su localhost:8888/challenge). Se esegui il pentesting usando un agente IA, l'agente non dovrebbe avere accesso ai processi docker interni, poiché ciò sarebbe considerato imbroglio.
Durante il pentesting, monitora la dashboard del difensore su localhost:3000 per vedere log in tempo reale, azioni degli agenti, patch, flag catturati, ecc.
Dopo la fine della sessione, esegui docker compose down -v per rimuovere i container docker e i database avviati per questo progetto.

Dashboard

Dashboard: http://localhost:3000

Una barra di stato globale degli agenti è visibile in tutte le schede che mostra lo stato degli agenti (attivo/bloccato/inattivo/errore) con controlli di ridimensionamento.

Log

Visualizzatore di log delle richieste in tempo reale a schermo diviso produzione/ombra con voci colorate per gravità e raggruppamento del traffico

Agenti

Feed di attività per agente con prompt di sistema, chiamate a strumenti ed etichette del modello LLM

Pipeline

Tabellone Kanban: Rilevato → In correzione → In revisione → Distribuito, con pannello dei dettagli ridimensionabile

Patch

Differenze di codice, file modificati, comandi di rollback e cronologia per patch

Configurazione LLM

Il sistema utilizza qualsiasi API compatibile con OpenAI. Configura i modelli in config/llm.yaml:

# Shadow Analyzer — reads shadow logs to detect exploits (no tool calling)
shadow_analyzer:
  provider: gemini
  model: gemini-2.5-flash
  api_key_env: GEMINI_API_KEY # defined in harness/.env
  pricing:
    input_per_million: 0.30
    output_per_million: 2.50

# Fixer — patches source code (tool-calling agent)
fixer:
  provider: gemini
  model: gemini-3-flash-preview
  api_key_env: GEMINI_API_KEY # defined in harness/.env
  pricing:
    input_per_million: 0.50
    output_per_million: 3.00

# Reviewer — verifies patches (tool-calling agent)
reviewer:
  provider: gemini
  model: gemini-3-flash-preview
  api_key_env: GEMINI_API_KEY # defined in harness/.env
  pricing:
    input_per_million: 0.50
    output_per_million: 3.00

Per cambiare provider, modifica provider e model, quindi imposta la chiave API corrispondente in harness/.env:

Provider supportati: OpenAI, Gemini, Anthropic, Groq, Together, Ollama, Mistral, DeepSeek, Fireworks, xAI, Perplexity, OpenRouter, Zhipu. Aggiungi provider personalizzati aggiungendo il loro URL di base alla sezione providers nel YAML.

providers:
  openai: https://api.openai.com/v1
  gemini: https://generativelanguage.googleapis.com/v1beta/openai/
  anthropic: https://api.anthropic.com/v1/
  groq: https://api.groq.com/openai/v1
  ... # add more if needed

Nota: Solo pochi provider API hanno un limite di frequenza sufficientemente elevato per supportare 3 o più agenti che lavorano contemporaneamente. Google Gemini è uno di questi.

Stack tecnologico

LLM: Qualsiasi API compatibile con OpenAI (predefinito: Gemini 3 Flash Preview per gli agenti, Gemini 2.5 Flash per l'analizzatore)
App target: crAPI modificata (Python/Django, Java/Spring Boot, Go, MongoDB, PostgreSQL)
Routing: nginx con scripting Lua per il reindirizzamento trasparente delle sessioni
Punteggio: punteggio delle minacce basato su Redis tramite piano di controllo FastAPI
Dashboard: React + Tailwind CSS, servita da FastAPI con WebSocket per aggiornamenti in tempo reale
Orchestrazione: Python asyncio con coordinamento degli agenti basato su code

Ringraziamenti speciali

Un ringraziamento speciale a d3lta05 (LinkedIn) e aleemladha per il loro aiuto con i test di penetrazione.

Più Popolari

Mahoraga-Webapp-Defender