secubox-openwrt/docs-fr/validation-guide.md

Guide de Validation des Modules SecuBox

🌐 Langues : English | Français | 中文

Version : 1.0.0 Dernière mise à jour : 2025-12-28 Statut : Actif

📚 Référence Complète : Ceci est un guide de validation détaillé. Pour les commandes rapides, voir QUICK-START.md

Documentation Connexe :

• Guide complet : DEVELOPMENT-GUIDELINES.md §8
• Checklist pré-commit : DEVELOPMENT-GUIDELINES.md §8.1
• Checklist post-déploiement : DEVELOPMENT-GUIDELINES.md §8.3
• Guide des permissions : PERMISSIONS-GUIDE.md
• Briefing automatisation : CODEX.md

---

Voir Aussi

• Commandes Rapides : QUICK-START.md
• Référence des Permissions : PERMISSIONS-GUIDE.md
• Garde-fous d'Automatisation : CODEX.md
• Procédures de Déploiement : DEVELOPMENT-GUIDELINES.md §9

Ce guide explique les vérifications de validation effectuées sur les modules SecuBox lors de la génération et avant le push git.

Aperçu

SecuBox utilise une approche de validation multi-niveaux :

1. Validation à la Génération de Module - Valide les modules nouvellement créés/modifiés
2. Validation Pré-Push - Bloque le push git si des problèmes critiques sont trouvés
3. Validation à l'Exécution - Vérifications continues sur les modules déployés

Outils de Validation

1. validate-module-generation.sh

Validation complète pour un seul module pendant/après la génération.

Utilisation :

./secubox-tools/validate-module-generation.sh luci-app-cdn-cache

Vérifications effectuées :

• ✅ Complétude et exactitude du Makefile
• ✅ Convention de nommage des scripts RPCD (doit utiliser le préfixe luci.)
• ✅ Permissions d'exécution des scripts RPCD
• ✅ Structure des scripts RPCD (gestionnaires list/call)
• ✅ Validité JSON du fichier ACL
• ✅ Les permissions ACL couvrent les méthodes RPCD
• ✅ Validité JSON du fichier menu
• ✅ Les chemins de menu correspondent aux emplacements des fichiers de vue
• ✅ Les fichiers de vue JavaScript existent
• ✅ Utilisation du mode strict JavaScript
• ✅ Les appels de méthodes RPC correspondent aux méthodes RPCD
• ✅ Les noms d'objets ubus correspondent aux noms des scripts RPCD
• ✅ Validité de la configuration UCI (si présente)
• ✅ Scan de sécurité (identifiants codés en dur, commandes dangereuses)
• ✅ Présence de documentation

Codes de sortie :

• 0 - Toutes les vérifications réussies
• 1 - Erreurs critiques trouvées (le module ne doit pas être déployé)

2. pre-push-validation.sh

Valide tous les modules avant d'autoriser le push git.

Utilisation :

# Automatique (via hook git) :
git push  # la validation s'exécute automatiquement

# Manuel :
./secubox-tools/pre-push-validation.sh

Vérifications effectuées :

• ✅ Vérification des modifications git indexées
• ✅ Conventions de nommage RPCD sur tous les modules
• ✅ Validation des chemins de menu sur tous les modules
• ✅ Validation de la syntaxe JSON
• ✅ Permissions d'exécution RPCD
• ✅ Couverture des méthodes ACL
• ✅ Validation du Makefile
• ✅ Scans de sécurité
• ✅ Validation complète des modules modifiés

Codes de sortie :

• 0 - Push autorisé
• 1 - Push bloqué (erreurs critiques)

3. validate-modules.sh

Validation rapide de tous les modules (outil existant).

Utilisation :

./secubox-tools/validate-modules.sh

Voir secubox-tools/README.md pour plus de détails.

Installation des Hooks Git

Pour activer la validation automatique avant le push git :

./secubox-tools/install-git-hooks.sh

Cela crée un lien symbolique de .git/hooks/pre-push vers secubox-tools/pre-push-validation.sh.

Conventions de Nommage Critiques

1. Le Script RPCD DOIT Correspondre à l'Objet ubus

Règle : Le nom de fichier du script RPCD DOIT correspondre exactement au nom de l'objet ubus déclaré en JavaScript.

Pourquoi : Le système RPC de LuCI recherche les scripts RPCD par leur nom de fichier. Si le nom ne correspond pas, vous obtenez :

• RPC call failed with error -32000: Object not found
• Command failed: Method not found

Exemple :

// JavaScript (htdocs/luci-static/resources/view/cdn-cache/overview.js)
var callStatus = rpc.declare({
    object: 'luci.cdn-cache',  // ← Doit correspondre au nom du fichier RPCD
    method: 'status'
});

# Le nom du fichier script RPCD DOIT être :
root/usr/libexec/rpcd/luci.cdn-cache  # ← Exactement 'luci.cdn-cache'

Erreurs courantes :

• ❌ root/usr/libexec/rpcd/cdn-cache (préfixe luci. manquant)
• ❌ root/usr/libexec/rpcd/luci-cdn-cache (utilise un tiret au lieu d'un point)
• ❌ root/usr/libexec/rpcd/cdn_cache (utilise un underscore)

Validation :

# Vérifier le nommage :
./secubox-tools/validate-module-generation.sh luci-app-cdn-cache

# Rechercher :
# ✓ RPCD script follows naming convention (luci.* prefix)
# ✓ CRITICAL: RPCD script name matches ACL ubus object

2. Les Chemins de Menu DOIVENT Correspondre aux Emplacements des Fichiers de Vue

Règle : Les entrées path du JSON de menu DOIVENT correspondre aux chemins réels des fichiers de vue.

Pourquoi : LuCI charge les vues en fonction du chemin dans le menu. Mauvais chemin = HTTP 404.

Exemple :

// Menu (root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json)
{
    "action": {
        "type": "view",
        "path": "netifyd-dashboard/overview"  // ← Doit correspondre à l'emplacement du fichier
    }
}

# Le fichier de vue DOIT exister à :
htdocs/luci-static/resources/view/netifyd-dashboard/overview.js
#                                  ↑ Même chemin que le menu ↑

Erreurs courantes :

• ❌ Menu : "path": "netifyd/overview" mais fichier à view/netifyd-dashboard/overview.js
• ❌ Menu : "path": "overview" mais fichier à view/netifyd-dashboard/overview.js

Validation :

# Vérifier les chemins :
./secubox-tools/validate-module-generation.sh luci-app-netifyd-dashboard

# Rechercher :
# ✓ Menu path 'netifyd-dashboard/overview' → view file EXISTS

3. Tous les Objets ubus DOIVENT Utiliser le Préfixe luci.

Règle : Chaque déclaration d'objet ubus doit commencer par luci.

Pourquoi : Convention de nommage cohérente pour les applications LuCI. Le système ACL l'attend.

Exemple :

// ✅ Correct :
object: 'luci.cdn-cache'
object: 'luci.system-hub'
object: 'luci.wireguard-dashboard'

// ❌ Incorrect :
object: 'cdn-cache'  // Préfixe luci. manquant
object: 'systemhub'  // Préfixe luci. manquant

Validation :

# Vérifier la convention :
./secubox-tools/validate-modules.sh

# Rechercher :
# ✓ ubus object 'luci.cdn-cache' follows naming convention

Checklist de Génération de Module

Utilisez cette checklist lors de la génération d'un nouveau module :

Phase 1 : Génération Initiale

• Créer le répertoire du module : luci-app-<nom-module>/
• Générer le Makefile avec tous les champs requis
• Créer le script RPCD à root/usr/libexec/rpcd/luci.<nom-module>
• Rendre le script RPCD exécutable : chmod +x
• Ajouter le shebang au RPCD : #!/bin/sh
• Implémenter les méthodes RPCD (list, call, status, etc.)
• Créer le fichier ACL avec les permissions read/write
• Créer le JSON de menu avec les chemins corrects
• Créer les fichiers JavaScript de vue
• Ajouter 'use strict'; à tous les fichiers JS

Phase 2 : Validation

• Exécuter la validation de génération de module :

  ./secubox-tools/validate-module-generation.sh luci-app-<nom-module>
  

• Corriger toutes les ERREURS (critiques)

• Examiner tous les AVERTISSEMENTS (recommandé)

Phase 3 : Validation d'Intégration

• Vérifier que le nom du script RPCD correspond à l'objet ubus :

  grep -r "object:" luci-app-<nom-module>/htdocs --include="*.js"
  ls -la luci-app-<nom-module>/root/usr/libexec/rpcd/
  # Les noms doivent correspondre exactement
  

• Vérifier que les chemins de menu correspondent aux fichiers de vue :

  grep '"path":' luci-app-<nom-module>/root/usr/share/luci/menu.d/*.json
  ls -R luci-app-<nom-module>/htdocs/luci-static/resources/view/
  # Les chemins doivent s'aligner
  

• Vérifier que les permissions ACL couvrent toutes les méthodes RPCD :

  grep 'case "$2"' luci-app-<nom-module>/root/usr/libexec/rpcd/*
  grep -A 20 '"ubus":' luci-app-<nom-module>/root/usr/share/rpcd/acl.d/*.json
  # Toutes les méthodes doivent être dans ACL
  

Phase 4 : Pré-Commit

• Exécuter la validation complète :

  ./secubox-tools/validate-modules.sh
  

• Examiner les résultats du scan de sécurité

• Vérifier la validité JSON :

  find luci-app-<nom-module> -name "*.json" -exec python3 -m json.tool {} \; > /dev/null
  

• Optionnel : Exécuter shellcheck sur RPCD :

  shellcheck luci-app-<nom-module>/root/usr/libexec/rpcd/*
  

Phase 5 : Commit Git

• Indexer les modifications :

  git add luci-app-<nom-module>
  

• Commiter avec un message descriptif :

  git commit -m "feat: implement <nom-module> module
  
  - Add RPCD backend with methods: status, get_*, set_*
  - Create views for overview, settings, etc.
  - Configure ACL permissions
  - Add menu entries
  
  🤖 Generated with [Claude Code](https://claude.com/claude-code)
  
  Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
  

• Pousser (la validation s'exécute automatiquement) :

  git push
  

Erreurs de Validation Courantes et Corrections

Erreur : Le nom du script RPCD ne correspond pas à l'objet ubus

✗ ERROR: luci-app-cdn-cache: RPCD script 'cdn-cache' does NOT match ubus object 'luci.cdn-cache'

Correction :

cd luci-app-cdn-cache/root/usr/libexec/rpcd
mv cdn-cache luci.cdn-cache

Erreur : Chemin menu → fichier NON TROUVÉ

✗ ERROR: luci-app-netifyd: Menu path 'netifyd/overview' → file NOT FOUND
Expected: htdocs/luci-static/resources/view/netifyd/overview.js

Option de correction 1 : Mettre à jour le chemin du menu pour correspondre au fichier :

# Éditer root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json
# Changer : "path": "netifyd/overview"
# En :      "path": "netifyd-dashboard/overview"

Option de correction 2 : Déplacer le fichier de vue pour correspondre au menu :

mv htdocs/luci-static/resources/view/netifyd-dashboard \
   htdocs/luci-static/resources/view/netifyd

Erreur : Le script RPCD N'EST PAS exécutable

✗ ERROR: luci-app-cdn-cache: luci.cdn-cache is NOT executable

Correction :

chmod +x luci-app-cdn-cache/root/usr/libexec/rpcd/luci.cdn-cache

Erreur : Méthode 'get_stats' du RPCD non trouvée dans ACL

⚠ WARNING: luci-app-cdn-cache: Method 'get_stats' from RPCD not in ACL

Correction :

# Éditer root/usr/share/rpcd/acl.d/luci-app-cdn-cache.json
# Ajouter 'get_stats' au tableau read.ubus :
{
    "luci-app-cdn-cache": {
        "read": {
            "ubus": {
                "luci.cdn-cache": ["status", "get_config", "get_stats"]
                                                           ↑ Ajouter ici
            }
        }
    }
}

Erreur : Syntaxe JSON invalide

✗ ERROR: luci-app-cdn-cache: acl.d JSON is INVALID - syntax error

Correction :

# Valider le JSON :
python3 -m json.tool root/usr/share/rpcd/acl.d/luci-app-cdn-cache.json

# Problèmes courants :
# - Virgule manquante entre les éléments du tableau
# - Virgule en fin de dernier élément
# - Guillemets non échappés dans les chaînes

Contourner la Validation (NON RECOMMANDÉ)

Dans de rares cas, vous pourriez avoir besoin de contourner la validation :

# Ignorer la validation pré-push :
git push --no-verify

# Ignorer la validation de génération de module :
# (impossible à contourner - c'est uniquement informatif)

⚠️ AVERTISSEMENT : Contourner la validation peut conduire à des modules cassés en production !

Intégration avec CI/CD

GitHub Actions

Ajouter la validation à votre workflow :

name: Validate Modules

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y python3 shellcheck          

      - name: Run module validation
        run: |
          chmod +x secubox-tools/validate-modules.sh
          ./secubox-tools/validate-modules.sh          

      - name: Run pre-push validation
        run: |
          chmod +x secubox-tools/pre-push-validation.sh
          ./secubox-tools/pre-push-validation.sh          

Bonnes Pratiques

1. Toujours valider avant de commiter

   ./secubox-tools/validate-module-generation.sh luci-app-<module>
   

2. Installer les hooks git pour une validation automatique

   ./secubox-tools/install-git-hooks.sh
   

3. Corriger les erreurs immédiatement - N'accumulez pas de dette de validation

4. Examiner les avertissements - Ils indiquent souvent de vrais problèmes

5. Tester sur OpenWrt avant de marquer comme terminé :

   scp bin/packages/*/base/luci-app-*.ipk root@192.168.1.1:/tmp/
   ssh root@192.168.1.1
   opkg install /tmp/luci-app-*.ipk
   /etc/init.d/rpcd restart
   /etc/init.d/uhttpd restart
   

6. Documenter les exigences spécifiques au module dans le README du module

Dépannage

Le script de validation ne s'exécute pas

# S'assurer que les scripts sont exécutables :
chmod +x secubox-tools/*.sh

# Vérifier les dépendances :
which python3  # Pour la validation JSON
which shellcheck  # Pour la validation des scripts shell

Le hook git ne s'exécute pas

# Vérifier que le hook est installé :
ls -la .git/hooks/pre-push

# Réinstaller les hooks :
./secubox-tools/install-git-hooks.sh

Faux positifs dans la validation

Si la validation signale incorrectement une erreur, veuillez le signaler :

• Créer un ticket avec la sortie complète de la validation
• Inclure le nom du module et la vérification spécifique qui a échoué
• Nous mettrons à jour la logique de validation

Ressources Supplémentaires

• CLAUDE.md - Documentation principale du projet
• secubox-tools/README.md - Documentation des outils
• Feature Regeneration Prompts - Prompts de génération de modules

Support

Si vous rencontrez des problèmes de validation :

1. Consultez ce guide pour les erreurs courantes
2. Exécutez la validation avec une sortie verbeuse
3. Examinez CLAUDE.md pour les conventions de nommage
4. Créez un ticket sur GitHub avec la sortie de la validation