Mahoraga Webapp Defender

Système de défense d'application Web réactif alimenté par l'IA, conçu pour résister aux piratages par IA en temps réel.

Table des matières

• Mahoraga Webapp Defender
  • Table des matières
  • Introduction
  • Site Web cible
  • Architecture du défenseur Mahoraga
    • Double environnement
    • Pipeline d'agents
  • Comment démarrer
    • Préparation
    • Expérience complète : défenseur contre attaquant
  • Tableau de bord
    • Journaux
    • Agents
    • Pipeline
    • Correctifs
  • Configuration LLM
  • Technologies utilisées
  • Remerciements spéciaux

Introduction

Mahoraga Defender est une POC d'un système de défense réactif, agnostique quant au type d'attaquant, en temps réel. Le mécanisme central consiste à piéger un adversaire pour qu'il effectue des découvertes et des attaques sur un environnement bénin et factice (environnement « shadow ») et à enregistrer ces attaques. Ensuite, un agent LLM analyse les journaux et transmet les détails des exploits détectés à d'autres agents LLM pour corriger les vulnérabilités et déployer les correctifs.

Le système est conçu pour être entièrement automatisé avec une optimisation des coûts d'API en tête. Une interface graphique a été créée pour surveiller facilement les journaux de trafic, l'activité des agents et le pipeline de correctifs, et pour contrôler le nombre d'agents à déployer.

Site Web cible

Le site Web cible (victime) est un fork de crAPI (Completely Ridiculous API), une application Web intentionnellement vulnérable créée par OWASP pour l'enseignement des tests de sécurité d'API. crAPI simule une plateforme de propriétaires de véhicules avec des microservices couvrant les 10 principales vulnérabilités d'API de l'OWASP. Le défenseur est conçu pour distinguer clairement les sessions utilisateur normales des sessions adverses, afin que les utilisateurs normaux ne subissent aucune baisse de qualité d'expérience utilisateur pendant que le défenseur protège le site Web des attaquants.

Notre fork (crapi-fork/) ajoute :

• Des honeypots plantés (identifiants factices, points de terminaison, jetons) pour la détection des attaquants
• Un total de 12 drapeaux de type CTF répartis sur la surface d'attaque
• Une pile « shadow » parallèle avec des services identiques et des bases de données séparées pour une observation sécurisée des attaquants
• Un routage de session basé sur nginx/Lua qui redirige de manière transparente les sessions suspectes de la production vers l'environnement shadow

Une copie vierge est conservée dans crapi-original/ afin que l'environnement puisse être réinitialisé entre les expériences.

Architecture du défenseur Mahoraga

Double environnement

• Prod : sert les vrais utilisateurs via un proxy inverse nginx (port 8888)
• Shadow : pile factice identique avec des bases de données séparées, reçoit le trafic des attaquants redirigé de manière transparente

Pipeline d'agents

• Orchestrateur : coordonne l'ensemble du pipeline. Gère les cycles de vie des agents, les files d'attente de correctifs/révision, l'état des tickets, le déploiement et la reprise après incident. Permet d'augmenter ou de réduire le nombre d'agents correcteurs/réviseurs en cours d'exécution.
• Observateur (basé sur des règles) : surveille les journaux de trafic de production et note les sessions en fonction du niveau de menace à l'aide de la reconnaissance de formes (force brute, injection, énumération, accès aux honeypots, etc.). Une fois que le score de menace dépasse un seuil, il déclenche l'action de redirection.
• Analyseur Shadow (agent LLM) : lit les journaux de trafic de l'environnement shadow à un intervalle configurable pour détecter les exploits réussis. Déduplique les entrées de journal, détecte les schémas d'attaque et pousse les exploits confirmés vers la file d'attente de correction.
• Correcteur (agent LLM) : reçoit les rapports d'exploit, lit le code source concerné et le corrige directement dans crapi-fork/. Fonctionne dans un environnement bash cloisonné avec un accès limité à crapi-fork/ uniquement.
• Réviseur (agent LLM) : vérifie les correctifs pour leur exactitude, leur portée et leur sécurité. Les correctifs approuvés déclenchent l'action de déploiement ; les correctifs rejetés sont renvoyés au correcteur avec des commentaires.

Lors du déploiement, les services Python sont rechargés à chaud via gunicorn (instantané), tandis que les services Java/Go sont reconstruits via docker compose up -d --build.

Pourquoi pas d'agent testeur ? Nous avons envisagé d'ajouter un agent de test utilisateur dédié et un environnement de test séparé, mais nous les avons supprimés tous les deux pour garder le système léger.

Comment démarrer

Préparation

• Il est recommandé d'utiliser un environnement virtuel conda ou python (par exemple, conda create -n XYZ python=3.13, puis conda activate XYZ).
• Installez les dépendances : pip install -r requirements.txt

Expérience complète : défenseur contre attaquant

1. Exécutez ./start.sh à partir du répertoire racine du projet – cela réinitialise le code source de crapi-fork/ à partir de crapi-original/, reconstruit tous les services, plante les drapeaux et les honeypots.
2. Lancez le défenseur : python3 -m harness.main --app-url http://localhost:8888 -v.
3. Commencez les tests de pénétration du site Web sur localhost:8888 (la description du défi se trouve à localhost:8888/challenge). Si vous effectuez des tests de pénétration à l'aide d'un agent IA, l'agent ne doit avoir aucun accès aux processus docker internes, car cela serait considéré comme de la triche.
4. Pendant les tests de pénétration, surveillez le tableau de bord du défenseur sur localhost:3000 pour voir les journaux en temps réel, les actions des agents, les correctifs, les drapeaux capturés, etc.
5. Une fois la session terminée, exécutez docker compose down -v pour supprimer les conteneurs docker et les bases de données qui ont été créés pour ce projet.

Tableau de bord

Tableau de bord : http://localhost:3000

Une barre d'état globale des agents est visible sur tous les onglets, indiquant la santé des agents (actif/bloqué/inactif/erreur) avec des contrôles de mise à l'échelle.

Journaux

Visionneuse de journaux de requêtes en écran partagé en temps réel (production/shadow) avec entrées colorées par sévérité et regroupement du trafic

Agents

Flux d'activité par agent avec invites système, appels d'outils et étiquettes de modèle LLM

Pipeline

Tableau Kanban : Détecté → En cours de correction → En cours de révision → Déployé, avec panneau de détails redimensionnable

Correctifs

Différences de code, fichiers modifiés, commandes de restauration et chronologie par correctif

Configuration LLM

Le système utilise toute API compatible OpenAI. Configurez les modèles dans config/llm.yaml :

# Analyseur Shadow — lit les journaux shadow pour détecter les exploits (sans appel d'outil)
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

# Correcteur — corrige le code source (agent avec appel d'outil)
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

# Réviseur — vérifie les correctifs (agent avec appel d'outil)
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

Pour changer de fournisseur, modifiez provider et model, puis définissez la clé API correspondante dans harness/.env :

Fournisseurs pris en charge : OpenAI, Gemini, Anthropic, Groq, Together, Ollama, Mistral, DeepSeek, Fireworks, xAI, Perplexity, OpenRouter, Zhipu. Ajoutez des fournisseurs personnalisés en ajoutant leur URL de base à la section providers du 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
  ... # ajoutez-en d'autres si nécessaire

Remarque : seuls quelques fournisseurs d'API ont une limite de débit suffisamment élevée pour prendre en charge 3 agents ou plus travaillant simultanément. Google Gemini en fait partie.

Technologies utilisées

• LLM : toute API compatible OpenAI (par défaut : Gemini 3 Flash Preview pour les agents, Gemini 2.5 Flash pour l'analyseur)
• Application cible : crAPI modifié (Python/Django, Java/Spring Boot, Go, MongoDB, PostgreSQL)
• Routage : nginx avec scripts Lua pour la redirection transparente de session
• Score : évaluation des menaces basée sur Redis via un plan de contrôle FastAPI
• Tableau de bord : React + Tailwind CSS, servi par FastAPI avec WebSocket pour les mises à jour en direct
• Orchestration : Python asyncio avec coordination des agents basée sur des files d'attente

Remerciements spéciaux

Remerciements spéciaux à d3lta05 (LinkedIn) et aleemladha pour leur aide avec les tests de pénétration.