Ansible Role : Nginx ModSecurity

Description

 

🛡️ Protégez vos applications web avec un WAF de niveau entreprise !

Le rôle Ansible nginx_modsecurity déploie un serveur WAF (Web Application Firewall) basé sur Nginx et ModSecurity avec les règles OWASP Core Rule Set (CRS). Protégez vos applications contre les injections SQL, XSS, et autres attaques web en quelques minutes.

 

✨ Fonctionnalités Clés

• 🔒 Protection ModSecurity : Détection et blocage des attaques web courantes (SQL injection, XSS, RCE, LFI/RFI, etc.) grâce au moteur ModSecurity v3.
• 📋 OWASP Core Rule Set (CRS) : Règles de sécurité maintenues par la communauté OWASP, régulièrement mises à jour pour contrer les nouvelles menaces.
• 🔍 Mode Observation (DetectionOnly) : Démarrez en mode observation pour identifier les faux-positifs avant d’activer le blocage. Zéro risque de casser vos applications !
• 📊 Niveaux de Paranoïa Ajustables (1-4) : Adaptez la sensibilité du WAF selon vos besoins, du niveau basique au mode paranoïaque.
• 🔐 Certificats SSL Automatiques : Intégration Certbot/Let’s Encrypt avec renouvellement automatique via Cron.
• 💻 Large Compatibilité d’OS : Déployez sur Debian 12/13 et Ubuntu 22.04/24.04 LTS.
• ⚙️ Exclusions Personnalisables : Gérez facilement les faux-positifs via de simples variables Ansible.
• 📁 Chemin d’Installation Configurable : Personnalisez l’emplacement d’installation du WAF selon vos conventions.
• 🔀 Double Mode d’Utilisation : Mode server pour déployer le WAF complet, mode client pour ajouter des sites sur un WAF existant.
• 🔑 Sécurité TLS Renforcée : Paramètres DH 4096 bits, TLS 1.2/1.3, ciphers modernes.

 

🏗️ Architecture WAF

 

---

 

⚙️ Configuration & Usage

 

Prérequis

• Système d’exploitation : Debian 12/13 ou Ubuntu 22.04/24.04.
• Ansible : Installé sur votre machine de contrôle.
• Docker : Docker doit être installé sur les serveurs cibles (peut être réalisé via le rôle devops_store.docker_engine).
• Privilèges : Un utilisateur avec des droits sudo sur les serveurs cibles (become: true dans votre playbook).

 

Exemple de Playbook (votre_playbook.yml)

---
- hosts: nginx_modsecurity
  become: true

  vars:
    # =============================================================================
    # MODE D'UTILISATION DU RÔLE
    # =============================================================================
    # Définit si le rôle déploie la partie serveur (nginx + modsecurity + certbot)
    # ou la partie client (configuration nginx + certificat letsencrypt)
    #   - "server" : Déploie la partie serveur (défaut)
    #   - "client" : Déploie la partie client
    nginx_modsecurity_role_usage: "server"

    # =============================================================================
    # IMAGE DOCKER (OWASP ModSecurity CRS avec Nginx)
    # =============================================================================
    modsecurity_image: "owasp/modsecurity-crs"
    modsecurity_version: "4.21.0-nginx-202512071012"

    # Version Certbot pour Let's Encrypt
    certbot_version: "v4.2.0"

    # =============================================================================
    # CONFIGURATION MODSECURITY
    # =============================================================================
    # Activer/désactiver ModSecurity
    modsecurity_enabled: true

    # Mode de fonctionnement :
    #   - "DetectionOnly" : Journalise les attaques sans bloquer (recommandé pour débuter)
    #   - "On" : Bloque les requêtes malveillantes
    modsecurity_mode: "DetectionOnly"

    # Niveau de paranoïa OWASP CRS (1 à 4)
    #   - 1 : Faible (peu de faux positifs, détection basique)
    #   - 2 : Modéré (bon équilibre)
    #   - 3 : Élevé (plus de détections, plus de faux positifs)
    #   - 4 : Paranoïaque (maximum de détection, beaucoup de faux positifs)
    modsecurity_paranoia_level: 1

    # Seuil d'anomalie pour déclencher le blocage (mode On)
    # Plus la valeur est basse, plus c'est strict
    modsecurity_anomaly_inbound: 5
    modsecurity_anomaly_outbound: 4

    # Exclusions de règles (pour les faux-positifs connus)
    # Exemple:
    #   modsecurity_rules_exclusions:
    #     - rule_id: 920350
    #       reason: "Faux-positif sur header Host"
    #     - rule_id: 942100
    #       reason: "Faux-positif SQL injection sur champ recherche"
    modsecurity_rules_exclusions: []

    # =============================================================================
    # CHEMIN D'INSTALLATION
    # =============================================================================
    # Chemin d'installation du WAF (répertoire racine)
    # nginx_modsecurity_install_path: "/home/{{ ansible_user }}/nginx_modsecurity"

    # =============================================================================
    # CONFIGURATION NGINX / PROXY
    # =============================================================================
    # Interface réseau pour le binding (laisser vide pour toutes les interfaces)
    nginx_modsecurity_bind_interface: ""

    # Ports exposés
    nginx_modsecurity_http_port: 80
    nginx_modsecurity_https_port: 443

    # =============================================================================
    # LOGGING LABELS (Promtail / Loki)
    # =============================================================================
    # Activer l'ajout des labels pour Promtail/Loki
    nginx_modsecurity_enable_logging_labels: false

    # =============================================================================
    # VARIABLES DE GENERATION CERTS
    # =============================================================================
    # Taille des paramètres DH pour SSL (défaut: 4096)
    dh_param_size: 4096

    # =============================================================================
    # UTILISATEUR OWASP
    # =============================================================================
    # UID de l'utilisateur owasp
    modsecurity_uid: 101

    # =============================================================================
    # CONFIGURATION CLIENT
    # =============================================================================
    # Nom du hostname associé au virtual host (requis en mode client)
    # nginx_hostname: "example.com"

  roles:
    - role: devops_store.nginx_modsecurity

 

Exemple d’Inventaire (votre_inventaire)

[nginx_modsecuritys]
waf-01 ansible_host=192.168.1.50

[nginx_modsecuritys:vars]
ansible_user=ubuntu
ansible_ssh_private_key_file=~/.ssh/id_rsa

 

Lancement

ansible-playbook -i votre_inventaire votre_playbook.yml

 

---

 

🔬 Détails Techniques

• Image Docker : Utilise l’image officielle owasp/modsecurity-crs:nginx maintenue par la communauté OWASP.
• Idempotence Garantie : Vous pouvez exécuter ce rôle plusieurs fois en toute sécurité. La génération DH n’est effectuée que si le fichier n’existe pas.
• Chemin d’Installation Configurable : Par défaut /home/<user>/nginx_modsecurity, personnalisable via la variable nginx_modsecurity_install_path.
• Configuration Nginx : Après déploiement, ajoutez vos virtual hosts dans {{ nginx_modsecurity_install_path }}/nginx/conf/.
• Logs ModSecurity : Visualisez les alertes avec docker logs nginx 2>&1 | grep -i modsecurity.
• Tests Complets Inclus : Suite de tests Molecule fournie pour les 4 OS supportés.
• Dépendance Docker : Ce rôle nécessite que Docker soit installé (manuel ou via devops_store.docker_engine).

 

---

 

📚 Documentation Opérationnelle

Ce rôle inclut une documentation complète dans le dossier docs/ :

• Guide Jour 1 (docs/day1-guide.md) : Vérification WAF, tests d’attaques, configuration virtual hosts, certificats SSL.
• Runbook Jour 2+ (docs/day2-runbook.md) : Passage mode blocage, gestion des faux-positifs, tuning des règles CRS, protection DDoS, maintenance, scénarios catastrophe.
  
  👀 Voir la table des matières complète

  1. 🔧 Troubleshooting Courant : Nginx ne démarre pas, erreurs 503/502, blocage requêtes légitimes
  2. 🛡️ Passage en Mode Blocage : Pré-requis, procédure, rollback rapide
  3. ⚠️ Gestion des Faux-Positifs : Identification, types d’exclusions, exclusions courantes
  4. 🎚️ Tuning des Règles OWASP CRS : Niveaux de paranoïa, seuils d’anomalie, catégories
  5. 🔐 Gestion des Certificats SSL : Let’s Encrypt, renouvellement auto, certificats entreprise
  6. 📊 Analyse des Logs : Scripts d’analyse, logs centralisés, alertes attaques
  7. 🔴 Scénarios Catastrophe : WAF bloque tout, nginx ne recharge plus, DDoS, certificats expirés
  8. ⚡ Performance et Optimisation : Optimisations Nginx, ModSecurity, monitoring
  9. 🔄 Maintenance et Upgrade : Mise à jour images, mise à jour règles CRS, backup

 

---

 

📦 Détails du Produit

• Nom du rôle : devops_store.nginx_modsecurity
• Cible OS : Debian (12/13), Ubuntu (22.04/24.04)
• Composants déployés : Nginx, ModSecurity v3, OWASP CRS, Certbot
• Dépendances : Aucune (Docker requis)

 

🛡️ Garantie de Qualité et Support

Trois durées de garantie sont disponibles : 3 mois, 1 an et 5 ans. Ces garanties incluent le support technique et les mises à jour du code pour les plateformes supportées.

N.B. : Le support du rôle se base sur le cycle de vie des OS pour lesquels il a été développé. Cela signifie que si un OS atteint sa date d’EOL durant la période de garantie, le support et les mises à jour du rôle s’arrêtent pour cet OS. A contrario, si une nouvelle version majeure d’un OS est publiée durant la période de garantie, le support et les mises à jour du rôle seront assurés pour cette nouvelle version.

 

🔑 Licence d’Utilisation

Trois niveaux de licence sont disponibles :

• Standard : Usage pour les projets internes de l’acheteur. Pas de redistribution, pas d’utilisation pour des clients tiers. Idéale pour les indépendants, PME gérant leur propre infra, passionnés.
• Entreprise : Inclut tous les droits Standard et permet d’utiliser le rôle pour configurer les serveurs de clients finaux. Droit d’intégration dans des produits et services vendus. Idéale pour les ESN, Agences Web, Infogérants (MSP), Consultants DevOps.
• Marque Blanche : Inclut tous les droits Entreprise avec l’autorisation exclusive de supprimer les mentions de l’auteur (attribution) pour présenter le code comme votre propre technologie. Idéale pour les grands Infogérants et éditeurs exigeant une image de marque unifiée sans trace de tiers.