gandalf/secubox-openwrt
gandalf/secubox-openwrt
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add GitHub Pages documentation site with MkDocs Material

Browse Source 
Generated professional documentation site structure:
- mkdocs.yml: Material theme with dark/light mode, search, navigation
- docs/: Complete documentation sync from DOCS/ (13 files + archive)
- docs/stylesheets/extra.css: SecuBox custom styling (indigo/violet)
- docs/archive/: Archived historical documents (4 files)

Features:
- Material Design theme matching SecuBox design system
- Dark/Light mode toggle with indigo/purple palette
- Advanced navigation (tabs, sections, instant loading)
- Search with suggestions and highlighting
- Mermaid diagram support for architecture visuals
- Code syntax highlighting with copy button
- Mobile responsive layout
- Custom CSS with gradient headings and card effects

Setup:
- Updated scripts/setup-github-pages.sh for Ubuntu 24.04 compatibility
- Added dependency check and auto-install (apt or pip)
- Fixed Python externally-managed-environment handling
- Updated .gitignore to exclude site/, .venv/, docs/.DS_Store

Next steps:
1. Test locally: mkdocs serve
2. Enable GitHub Pages: Settings → Pages → Source: master, Folder: /docs
3. Site will be live at: https://gkerma.github.io/secubox-openwrt/

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
CyberMind-FR 2025-12-28 10:06:23 +01:00
parent dcdbd7bca6
commit 75042a8efb
21 changed files with 12373 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
.gitignore vendored
View File

@ -8,3 +8,10 @@ secubox-tools/local-feed/
# IDE settings
.vscode/
luci-app-secubox.backup-*
.venv/
# MkDocs / GitHub Pages
site/
.venv/
docs/.DS_Store

193
docs/archive/build-issues.md Normal file
View File

@ -0,0 +1,193 @@
# Build Issues & Solutions
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Active
## Current Problem: No IPK Generated on GitHub Actions
### Root Cause
The OpenWrt **SDK** cannot compile LuCI core dependencies (`lucihttp`, `cgi-io`) because it lacks the necessary `ubus` development headers. When building SecuBox packages, the SDK tries to compile all dependencies from source, which fails with:
```
ERROR: package/feeds/luci/lucihttp failed to build.
ubus_include_dir-NOTFOUND
```
###Why This Works Locally
Locally, you likely have one of these setups:
1. **Full OpenWrt build tree** - Has all headers and can compile everything
2. **ImageBuilder** - Uses pre-compiled packages, doesn't compile from source
3. **Pre-installed dependencies** - lucihttp/cgi-io already exist
### Why It Fails on GitHub Actions
GitHub Actions uses the **OpenWrt SDK** which:
- ✅ Can compile packages with compiled code
- ❌ Cannot compile certain LuCI core packages (missing headers)
- ❌ Tries to rebuild all dependencies from source
## Solutions
### Option 1: Use OpenWrt ImageBuilder (Recommended)
**Best for:** Creating firmware images with SecuBox pre-installed
ImageBuilder uses pre-compiled packages and doesn't require compilation:
```yaml
# New workflow using ImageBuilder
- name: Download ImageBuilder
run: |
wget https://downloads.openwrt.org/releases/${VERSION}/targets/${TARGET}/${SUBTARGET}/openwrt-imagebuilder-*.tar.xz
tar xf openwrt-imagebuilder-*.tar.xz
- name: Add custom packages
run: |
mkdir -p imagebuilder/packages/custom
cp *.ipk imagebuilder/packages/custom/
- name: Build image
run: |
cd imagebuilder
make image PACKAGES="luci luci-app-secubox luci-app-*-dashboard"
```
**Pros:**
- ✅ No compilation issues
- ✅ Creates complete firmware images
- ✅ Fast builds (uses binaries)
**Cons:**
- ❌ Requires specifying target device
- ❌ Not suitable for multi-architecture package builds
### Option 2: Use Full OpenWrt Build System
**Best for:** Complete control, custom kernels, or when you need to modify core packages
Clone and build complete OpenWrt:
```yaml
- name: Clone OpenWrt
run: |
git clone https://github.com/openwrt/openwrt.git
cd openwrt
./scripts/feeds update -a
./scripts/feeds install -a
- name: Add SecuBox packages
run: |
cp -r ../luci-app-* openwrt/package/
- name: Build
run: |
cd openwrt
make defconfig
make -j$(nproc)
```
**Pros:**
- ✅ Can compile everything
- ✅ Full control over build
- ✅ Can modify core packages
**Cons:**
- ❌ Very slow (1-2 hours per architecture)
- ❌ Requires significant disk space (30-50GB)
- ❌ Complex configuration
### Option 3: Package-Only Repository (Alternative)
**Best for:** Distributing packages that users install on existing OpenWrt systems
Create a custom package feed:
```bash
# On your server/GitHub Pages
mkdir -p packages/${ARCH}/secubox
cp *.ipk packages/${ARCH}/secubox/
scripts/ipkg-make-index packages/${ARCH}/secubox > Packages
gzip -c Packages > Packages.gz
```
Users add to `/etc/opkg/customfeeds.conf`:
```
src/gz secubox https://yourdomain.com/packages/${ARCH}/secubox
```
**Pros:**
- ✅ No build needed (distribute sources)
- ✅ Users compile locally or use binaries
- ✅ Easy updates
**Cons:**
- ❌ Users need to manually install
- ❌ Doesn't provide firmware images
### Option 4: Fix SDK Build (Current Attempt)
The current workflow attempts workarounds:
1. Download package indices
2. Configure SDK to prefer binaries (CONFIG_BUILDBOT=y)
3. Fallback to direct packaging if compile fails
**Status:** Experimental, may not work reliably
**Pros:**
- ✅ Keeps existing workflow structure
- ✅ Multi-architecture builds
**Cons:**
- ❌ Fragile, depends on SDK quirks
- ❌ May break with OpenWrt updates
- ❌ Not officially supported
## Recommended Approach
### For Package Distribution
Use **Option 3** (Package Repository) combined with **Option 1** (ImageBuilder for sample firmwares):
1. **Distribute source packages** via GitHub releases
2. **Provide pre-built .ipk** for common architectures (x86-64, ARM)
3. **Create sample firmwares** with ImageBuilder for popular devices
4. **Document installation** for users who want to install on existing OpenWrt
### Implementation Steps
1. **Create package feed workflow** (replaces current SDK build)
2. **Add ImageBuilder workflow** for sample firmwares (ESPRESSObin, x86-64, etc.)
3. **Update README** with installation instructions
4. **Tag releases** with both source and binaries
## Next Steps
To implement the recommended solution:
```bash
# 1. Create new workflow for ImageBuilder
cp .github/workflows/build-secubox-images.yml .github/workflows/build-imagebuilder.yml
# Edit to use ImageBuilder instead of full build
# 2. Update package build workflow to create feed instead of compiling
# (Keep source distribution, skip compilation)
# 3. Update documentation
# Add INSTALL.md with instructions for different scenarios
```
## Temporary Workaround
Until the proper solution is implemented, users can:
1. **Download source** from GitHub
2. **Build locally** using local-build.sh (requires SDK setup)
3. **Or use existing firmware builds** (when available)
## References
- OpenWrt SDK: https://openwrt.org/docs/guide-developer/toolchain/using_the_sdk
- OpenWrt ImageBuilder: https://openwrt.org/docs/guide-user/additional-software/imagebuilder
- Package Feeds: https://openwrt.org/docs/guide-developer/feeds

506
docs/archive/completion-report.md Normal file
View File

@ -0,0 +1,506 @@
# Rapport de Complétion - SecuBox Components
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Active
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Archived
**Report Date:** 2025-12-23
---
## Résumé Exécutif
Les 13 composants LuCI SecuBox ont été complétés avec succès. Tous les fichiers essentiels sont maintenant présents et fonctionnels.
### Statistiques Globales
- **Composants totaux:** 13
- **Composants complets:** 13 (100%)
- **Fichiers CSS créés:** 4
- **Fichiers JavaScript:** 79 total
- **Backends RPCD:** 14 total
---
## Composants Complétés
### ✅ 1. luci-app-secubox (Hub Central)
**Fichiers:**
- Makefile ✓
- RPCD backends: 2 (luci.secubox, secubox)
- JavaScript: 4 fichiers
- CSS: 1 fichier (dashboard.css)
- Menu JSON ✓
- ACL JSON ✓
**Fonctionnalités:**
- Dashboard centralisé pour tous les modules SecuBox
- Navigation unifiée
- Monitoring intégré
---
### ✅ 2. luci-app-system-hub (Centre de Contrôle Système)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (753 lignes)
- JavaScript: 8 fichiers
- CSS: 1 fichier (dashboard.css)
- Menu JSON ✓
- ACL JSON ✓
**Fonctionnalités:**
- Gestion des composants (start/stop/restart)
- Health monitoring avec score 0-100
- Assistance à distance RustDesk
- Collection de diagnostics
- Logs unifiés
- Tâches planifiées
---
### ✅ 3. luci-app-crowdsec-dashboard (Sécurité Collaborative)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (267 lignes)
- JavaScript: 5 fichiers
- CSS: 1 fichier (dashboard.css)
- Menu JSON ✓
- ACL JSON ✓
**Fonctionnalités:**
- Monitoring des bans en temps réel
- Gestion des décisions IP
- Dashboard de métriques
- Visualisation géographique des menaces
- Thème cybersécurité dark
---
### ✅ 4. luci-app-netdata-dashboard (Monitoring Système)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (463 lignes)
- JavaScript: 5 fichiers
- CSS: 1 fichier (dashboard.css)
- Menu JSON ✓
- ACL JSON ✓
**Fonctionnalités:**
- Monitoring CPU, mémoire, disque, réseau
- Capteurs de température
- Moniteur de processus
- Gauges et sparklines animés
- Rafraîchissement toutes les 2 secondes
---
### ✅ 5. luci-app-netifyd-dashboard (Deep Packet Inspection)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (505 lignes)
- JavaScript: 7 fichiers
- CSS: 1 fichier (dashboard.css)
- Menu JSON ✓
- ACL JSON ✓
**Fonctionnalités:**
- Détection d'applications (Netflix, YouTube, Zoom)
- Identification de protocoles (HTTP, HTTPS, DNS, QUIC)
- Suivi des flux réseau en direct
- Découverte automatique d'appareils
- Catégorisation du trafic
---
### ✅ 6. luci-app-network-modes (Configuration Réseau)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (698 lignes)
- JavaScript: 6 fichiers
- CSS: 1 fichier (dashboard.css)
- Menu JSON ✓
- ACL JSON ✓
**Fonctionnalités:**
- **Mode Sniffer**: Bridge transparent pour analyse
- **Mode Access Point**: WiFi AP avec 802.11r/k/v
- **Mode Relay**: Extension réseau avec WireGuard
- **Mode Router**: Routeur complet avec proxy et HTTPS
- Changement de mode en un clic avec backup
---
### ✅ 7. luci-app-wireguard-dashboard (Gestion VPN)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (555 lignes)
- JavaScript: 6 fichiers
- CSS: 1 fichier (dashboard.css)
- Menu JSON ✓
- ACL JSON ✓
**Fonctionnalités:**
- Monitoring des tunnels
- Gestion des peers (actif/idle/inactif)
- Statistiques de trafic par peer
- Visualisation de configuration
- Sécurisé (clés privées jamais exposées)
---
### ✅ 8. luci-app-client-guardian (Contrôle d'Accès Réseau)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (775 lignes)
- JavaScript: 8 fichiers
- CSS: 1 fichier (dashboard.css)
- Menu JSON ✓
- ACL JSON ✓
**Fonctionnalités:**
- Détection et monitoring en temps réel des clients
- Gestion des zones (LAN, IoT, Invités, Quarantaine)
- Politique de quarantaine par défaut
- Portail captif moderne
- Contrôle parental (limites de temps, filtrage de contenu)
- Alertes SMS/Email
---
### ✅ 9. luci-app-auth-guardian (Système d'Authentification)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (147 lignes)
- JavaScript: 7 fichiers
- **CSS: 1 fichier** ⭐ **NOUVEAU**
- Menu JSON ✓
- ACL JSON ✓
**CSS Créé:**
- `dashboard.css` (380+ lignes)
- Thème rouge sécurité (#ef4444)
- Cartes de statistiques avec hover effects
- Styles pour OAuth, vouchers, sessions
- Animations pulse pour états actifs
**Fonctionnalités:**
- Portail captif personnalisable
- Intégration OAuth (Google, GitHub, Facebook, Twitter)
- Système de vouchers avec limites
- Gestion de sessions sécurisées
- Règles de bypass MAC/IP/Domain
---
### ✅ 10. luci-app-bandwidth-manager (QoS & Quotas)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (192 lignes)
- JavaScript: 7 fichiers
- **CSS: 1 fichier** ⭐ **NOUVEAU**
- Menu JSON ✓
- ACL JSON ✓
**CSS Créé:**
- `dashboard.css` (600+ lignes)
- Thème violet gradient (#8b5cf6 → #6366f1)
- Classes QoS avec barres de progression
- Styles pour quotas avec états (normal/warning/exceeded)
- Détection de médias avec cartes de services
- Timeline de trafic avec graphiques
**Fonctionnalités:**
- 8 classes de priorité QoS configurables
- Quotas journaliers et mensuels
- Détection automatique de médias (VoIP, Gaming, Streaming)
- Planification basée sur le temps
- Statistiques par client
---
### ✅ 11. luci-app-media-flow (Détection de Trafic Média)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (125 lignes)
- JavaScript: 5 fichiers
- **CSS: 1 fichier** ⭐ **NOUVEAU**
- Menu JSON ✓
- ACL JSON ✓
**CSS Créé:**
- `dashboard.css` (680+ lignes)
- Thème rose-violet gradient (#ec4899 → #8b5cf6)
- Cartes de services de streaming
- Détection de protocoles avec badges
- Appels VoIP avec indicateur live pulsant
- Quality of Experience meter avec scores
- Timeline de trafic avec graphiques à barres
**Fonctionnalités:**
- Détection de services de streaming en temps réel
- Identification de protocoles (RTSP, HLS, DASH, RTP)
- Monitoring VoIP/Vidéo calls
- Suivi de bande passante par service
- Métriques de qualité d'expérience
**Services Supportés:**
- Netflix, YouTube, Twitch, Disney+
- Spotify, Apple Music, Tidal
- Zoom, Teams, Google Meet, WebEx
---
### ✅ 12. luci-app-cdn-cache (Optimisation de Bande Passante)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (692 lignes)
- JavaScript: 7 fichiers
- CSS: 1 fichier (dashboard.css)
- Menu JSON ✓
- ACL JSON ✓
**Fonctionnalités:**
- Cache intelligent du contenu fréquemment accédé
- Statistiques de hit ratio et économies en temps réel
- Policies configurables par domaine/extension
- Purge et préchargement automatiques
- Graphiques statistiques et tendances
**Policies de Cache:**
- Windows Update, dépôts Linux
- Contenu statique (JS, CSS, images)
- TTL configurable par type
---
### ✅ 13. luci-app-vhost-manager (Gestion d'Hôtes Virtuels)
**Fichiers:**
- Makefile ✓
- RPCD backend: 1 (145 lignes)
- JavaScript: 5 fichiers
- **CSS: 1 fichier** ⭐ **NOUVEAU**
- Menu JSON ✓
- ACL JSON ✓
**CSS Créé:**
- `dashboard.css` (700+ lignes)
- Thème cyan (#06b6d4)
- Cartes de vhosts avec badges SSL
- Redirections avec flèches animées
- Templates de services avec hover effects
- Preview de configuration Nginx/HAProxy
- Setup Let's Encrypt ACME avec domaines vérifiés
**Fonctionnalités:**
- Hôtes virtuels internes avec domaines personnalisés
- Redirection de services externes
- SSL/TLS avec Let's Encrypt ou auto-signé
- Configuration automatique de reverse proxy nginx
**Services Supportés:**
- Nextcloud, GitLab, Jellyfin
- Home Assistant et plus
---
## Fichiers CSS Créés
### 1. auth-guardian/dashboard.css
**Lignes:** 380+
**Thème:** Rouge sécurité
**Caractéristiques:**
- Variables CSS pour couleurs cohérentes
- Cartes de statistiques avec hover effects
- Styles OAuth avec boutons colorés par provider
- Système de vouchers avec badges de statut
- Table de sessions avec indicateurs actifs pulsants
- Règles de bypass avec badges typés
- Formulaires et boutons d'action
- Responsive design
### 2. bandwidth-manager/dashboard.css
**Lignes:** 600+
**Thème:** Violet gradient
**Caractéristiques:**
- Grid de statistiques avec cartes animées
- 8 classes QoS avec barres de progression
- Variations de couleurs par priorité
- Système de quotas avec états (normal/warning/exceeded)
- Détection de médias avec grille de services
- Planifications temporelles avec badges de jours
- Table de statistiques clients avec barres d'usage
- Indicateur live en temps réel
### 3. media-flow/dashboard.css
**Lignes:** 680+
**Thème:** Rose-violet gradient
**Caractéristiques:**
- Grille de services de streaming avec icônes
- Filtres de catégories avec états actifs
- Détection de protocoles avec compteurs
- Appels VoIP avec statut pulsant
- Quality of Experience meter avec scores colorés
- Timeline de trafic avec graphiques interactifs
- États loading et empty avec animations
- Design responsive complet
### 4. vhost-manager/dashboard.css
**Lignes:** 700+
**Thème:** Cyan
**Caractéristiques:**
- Liste de vhosts avec badges SSL
- Statut online/offline avec dots animés
- Redirections avec flèches et routes
- Templates de services avec hover scale
- Preview de configuration code (Nginx/HAProxy)
- Setup ACME Let's Encrypt avec tags de domaines
- Info boxes avec styles par type
- États loading, empty et responsive
---
## Patterns et Standards CSS Utilisés
### Variables CSS Root
Chaque dashboard définit ses propres variables pour:
- Couleurs primaires et secondaires
- Tons dark/darker/light
- Couleurs de bordure
- Couleurs de statut (success/warning/danger/info)
- Gradients spécifiques
### Composants Communs
- **Containers**: Background gradients, border-radius, padding, shadow
- **Headers**: Flexbox, border-bottom, titre avec emoji et gradient text
- **Stats Grid**: Auto-fit responsive grid, cards avec hover effects
- **Buttons**: Variantes primary/secondary/danger avec transitions
- **Forms**: Inputs, selects, textareas avec focus states
- **Tables**: Hover states, border-collapse, padding cohérent
- **Badges**: Pills avec backgrounds transparents colorés
- **Loading States**: Animations avec emojis et keyframes
- **Empty States**: Centré avec emojis de grande taille
### Animations
- `pulse`: Opacité clignotante pour indicateurs
- `blink`: Clignotement pour dots live
- `spin`/`rotate`: Rotation pour loading
- `pulse-green`: Pulse avec box-shadow pour VoIP
- Hover transforms: `translateY(-2px)`, `scale(1.05)`
### Responsive Design
- Grid auto-fit avec minmax
- Media queries à 768px pour mobile
- Colonnes 1fr pour petits écrans
- Font sizes et paddings adaptés
---
## Architecture Technique
### Structure Standard de Package
```
luci-app-<module>/
├── Makefile # Définition package OpenWrt
├── README.md # Documentation module
├── htdocs/luci-static/resources/
│ ├── view/<module>/ # Vues JavaScript UI
│ │ ├── overview.js # Dashboard principal
│ │ └── *.js # Vues additionnelles
│ └── <module>/
│ ├── api.js # Client API RPC
│ └── dashboard.css # Styles du module
└── root/
├── etc/config/<module> # Config UCI (optionnel)
└── usr/
├── libexec/rpcd/<module> # Backend RPCD
└── share/
├── luci/menu.d/ # Définition menu JSON
│ └── luci-app-<module>.json
└── rpcd/acl.d/ # Permissions ACL JSON
└── luci-app-<module>.json
```
### Technologies Utilisées
- **Frontend**: LuCI framework (JavaScript)
- **Backend**: Shell scripts (RPCD)
- **Styling**: CSS3 avec variables et animations
- **Configuration**: UCI (Unified Configuration Interface)
- **API**: ubus RPC calls
- **Packaging**: OpenWrt Makefile system
---
## Validation et Tests
### Checks Effectués
✅ Présence de tous les Makefiles
✅ Backends RPCD existants et exécutables
✅ Fichiers JavaScript présents (79 total)
✅ Fichiers CSS présents (13 total, 4 nouveaux)
✅ Fichiers menu.d JSON valides
✅ Fichiers ACL JSON valides
### Prochaines Étapes Recommandées
1. **Build Test**: Compiler chaque package avec OpenWrt SDK
2. **Lint Validation**:
```bash
shellcheck luci-app-*/root/usr/libexec/rpcd/*
jsonlint luci-app-*/root/usr/share/{luci/menu.d,rpcd/acl.d}/*.json
```
3. **Installation Test**: Déployer sur un routeur OpenWrt de test
4. **Functional Test**: Vérifier chaque fonctionnalité UI
5. **Integration Test**: Tester l'interopérabilité entre modules
6. **CI/CD**: Déclencher le workflow GitHub Actions
---
## Outils et Scripts
### Outils de Réparation
- `secubox-tools/secubox-repair.sh`: Auto-fix des problèmes Makefile et RPCD
- `secubox-tools/secubox-debug.sh`: Validation et diagnostics
### Scripts de Validation
```bash
# Vérifier tous les composants
for comp in luci-app-*; do
echo "Checking $comp..."
[ -f "$comp/Makefile" ] && echo " ✓ Makefile"
[ -d "$comp/root/usr/libexec/rpcd" ] && echo " ✓ RPCD"
[ -d "$comp/htdocs" ] && echo " ✓ Frontend"
done
```
---
## Licence
Tous les modules SecuBox sont sous licence **Apache-2.0** © 2025 CyberMind.fr
---
## Auteur
**Gandalf** - [CyberMind.fr](https://cybermind.fr)
---
## Conclusion
✅ **Mission accomplie!** Les 13 composants LuCI SecuBox sont maintenant complets et prêts pour:
- Build et packaging
- Tests fonctionnels
- Déploiement sur OpenWrt
- Intégration dans SecuBox Suite
**Date de complétion:** 23 décembre 2025
**Status final:** 🎉 **100% COMPLET**
---
*Rapport généré automatiquement par Claude Code*

28
docs/archive/index.md Normal file
View File

@ -0,0 +1,28 @@
# Documentation Archive
Historical and completed documentation.
## Purpose
This archive contains documents that:
- Represent completed project milestones
- Describe implemented features
- Document resolved issues
## Archived Documents
- [Build Issues](build-issues.md) - Historical build troubleshooting (resolved)
- [Completion Report](completion-report.md) - Project completion milestone
- [Module Enable/Disable Design](module-enable-disable-design.md) - Feature design (implemented)
## Archive Policy
Documents are archived when:
1. ✅ Feature/project is completed
2. ✅ Information is outdated but historically valuable
3. ✅ Content has been migrated to active documentation
4. ✅ Document serves as historical reference only
---
[← Back to Home](../index.md){ .md-button }

356
docs/archive/module-enable-disable-design.md Normal file
View File

@ -0,0 +1,356 @@
# Module Enable/Disable Design Document
**Version:** 0.3.1
**Date:** 2025-12-27
**Author:** Claude Code + CyberMind
## 🎯 Objectif
Remplacer la logique **start/stop** des modules SecuBox par une logique **enable/disable** (activé/désactivé), car les modules sont des **plugins installés** qu'on souhaite activer ou désactiver, plutôt que des services qu'on démarre ou arrête ponctuellement.
## 📋 Changements Conceptuels
### Avant (v0.2.x)
```
Module installé → peut être "Running" ou "Stopped"
Actions: Start / Stop / Restart
État affiché: "Running" (vert) ou "Stopped" (gris)
```
### Après (v0.3.1+)
```
Module installé → peut être "Enabled" ou "Disabled"
Actions: Enable / Disable
État affiché: "Activé" (vert) ou "Désactivé" (gris)
Info complémentaire: "Service running" (si enabled + running)
```
## 🏗️ Architecture Technique
### 1. Configuration UCI
Chaque module dans `/etc/config/secubox` aura un champ `enabled`:
```uci
config module 'crowdsec'
option name 'CrowdSec Dashboard'
option package 'luci-app-crowdsec-dashboard'
option config 'crowdsec'
option category 'security'
option enabled '1' # NEW: 1 = activé, 0 = désactivé
option icon '🛡️'
option color '#ef4444'
```
### 2. Méthodes RPCD (`luci.secubox`)
#### Anciennes méthodes (DEPRECATED)
- ❌ `start_module(module_id)` → démarre le service
- ❌ `stop_module(module_id)` → arrête le service
- ❌ `restart_module(module_id)` → redémarre le service
#### Nouvelles méthodes (v0.3.1+)
```javascript
// Active un module (config UCI + démarrage service)
enable_module(module_id)
→ uci set secubox.${module}.enabled='1'
→ uci commit secubox
→ /etc/init.d/${service} enable
→ /etc/init.d/${service} start
→ return { success: true, message: "Module activé" }
// Désactive un module (config UCI + arrêt service)
disable_module(module_id)
→ uci set secubox.${module}.enabled='0'
→ uci commit secubox
→ /etc/init.d/${service} disable
→ /etc/init.d/${service} stop
→ return { success: true, message: "Module désactivé" }
// Vérifie si un module est activé
check_module_enabled(module_id)
→ return uci get secubox.${module}.enabled == '1'
// Vérifie si le service tourne (info complémentaire)
check_service_running(module_id)
→ return pgrep -f ${service} > /dev/null
```
### 3. Structure de données retournée
```json
{
"modules": [
{
"id": "crowdsec",
"name": "CrowdSec Dashboard",
"category": "security",
"installed": true,
"enabled": true, // État principal (config UCI)
"running": true, // État du service (info)
"status": "active", // enabled + running = "active"
"icon": "🛡️",
"color": "#ef4444"
},
{
"id": "netdata",
"name": "Netdata Monitoring",
"category": "monitoring",
"installed": true,
"enabled": false, // Module désactivé
"running": false,
"status": "disabled", // Status affiché
"icon": "📊",
"color": "#22c55e"
}
]
}
```
### 4. États Possibles
| enabled | running | status | Badge UI | Description |
|---------|---------|----------|---------------|-------------|
| `true` | `true` | `active` | ✓ Activé | Module activé et service tourne |
| `true` | `false` | `error` | ⚠️ Erreur | Module activé mais service arrêté (problème) |
| `false` | `false` | `disabled` | ○ Désactivé | Module désactivé (état normal) |
| `false` | `true` | `unknown` | ? Inconnu | État incohérent (rare) |
## 🎨 Interface Utilisateur
### Dashboard Principal (SecuBox Hub)
**Avant:**
```
[CrowdSec Dashboard] ● Running [Stop] [Restart]
[Netdata Monitor] ○ Stopped [Start]
```
**Après:**
```
[CrowdSec Dashboard] ✓ Activé [Désactiver]
[Netdata Monitor] ○ Désactivé [Activer]
```
### Module Individual Card
```html
<div class="module-card enabled">
<div class="module-header">
<span class="module-icon">🛡️</span>
<span class="module-name">CrowdSec Dashboard</span>
<span class="module-badge enabled">✓ Activé</span>
</div>
<div class="module-status">
<span class="status-dot running"></span>
<span>Service en cours d'exécution</span>
</div>
<div class="module-actions">
<button class="btn-disable">Désactiver</button>
</div>
</div>
```
### Classes CSS
```css
/* Module states */
.module-badge.enabled {
background: linear-gradient(135deg, #22c55e, #16a34a);
color: white;
}
.module-badge.disabled {
background: var(--sh-bg-secondary);
color: var(--sh-text-muted);
}
.module-badge.error {
background: linear-gradient(135deg, #f59e0b, #d97706);
color: white;
}
/* Status indicators */
.status-dot.running {
background: #22c55e;
animation: pulse 2s infinite;
}
.status-dot.stopped {
background: #94a3b8;
}
```
## 📝 API JavaScript
### Fichier: `secubox/api.js`
```javascript
// Anciennes méthodes (DEPRECATED - à supprimer)
startModule: callStartModule, // DEPRECATED
stopModule: callStopModule, // DEPRECATED
restartModule: callRestartModule, // DEPRECATED
// Nouvelles méthodes (v0.3.1+)
enableModule: callEnableModule, // NEW
disableModule: callDisableModule, // NEW
// Déclarations RPC
var callEnableModule = rpc.declare({
object: 'luci.secubox',
method: 'enable_module',
params: ['module_id'],
expect: { success: false, message: '' }
});
var callDisableModule = rpc.declare({
object: 'luci.secubox',
method: 'disable_module',
params: ['module_id'],
expect: { success: false, message: '' }
});
```
## 🔄 Migration des Données
### Script de migration (à exécuter une fois)
```bash
#!/bin/sh
# migrate-to-enable-disable.sh
. /lib/functions.sh
migrate_module() {
local module="$1"
local running=$(pgrep -f "$module" > /dev/null && echo "1" || echo "0")
# Si le service tourne actuellement, on l'active
if [ "$running" = "1" ]; then
uci set secubox.${module}.enabled='1'
else
# Sinon, on le désactive par défaut
uci set secubox.${module}.enabled='0'
fi
}
# Migrer tous les modules
config_load secubox
config_foreach migrate_module module
uci commit secubox
echo "Migration completed"
```
## 📚 Documentation Utilisateur
### README.md (à ajouter)
```markdown
## Gestion des Modules
Les modules SecuBox sont des plugins installés qui peuvent être **activés** ou **désactivés**.
### Activer un module
- Cliquez sur le bouton **"Activer"** sur la carte du module
- Le module sera configuré pour démarrer automatiquement au boot
- Le service associé démarrera immédiatement
### Désactiver un module
- Cliquez sur le bouton **"Désactiver"** sur la carte du module
- Le module ne démarrera plus automatiquement au boot
- Le service associé s'arrêtera immédiatement
### États des modules
| Badge | Signification |
|-------|---------------|
| ✓ Activé | Module activé et service en cours d'exécution |
| ⚠️ Erreur | Module activé mais service arrêté (vérifier les logs) |
| ○ Désactivé | Module désactivé (normal) |
**Note:** Les modules restent installés même lorsqu'ils sont désactivés. Pour les supprimer complètement, utilisez le gestionnaire de paquets APK.
```
## 🧪 Tests à Effectuer
### Tests Unitaires RPCD
```bash
# Test enable_module
ubus call luci.secubox enable_module '{"module_id":"crowdsec"}'
# Expected: {"success":true,"message":"Module activé"}
# Vérifier config UCI
uci get secubox.crowdsec.enabled
# Expected: 1
# Vérifier service
/etc/init.d/crowdsec enabled && echo "OK" || echo "FAIL"
pgrep crowdsec && echo "Running" || echo "Not running"
# Test disable_module
ubus call luci.secubox disable_module '{"module_id":"crowdsec"}'
# Expected: {"success":true,"message":"Module désactivé"}
# Vérifier
uci get secubox.crowdsec.enabled
# Expected: 0
```
### Tests Interface
1. ✅ Ouvrir le dashboard SecuBox
2. ✅ Vérifier que les modules affichent "Activé" ou "Désactivé"
3. ✅ Cliquer sur "Désactiver" → badge passe à "○ Désactivé"
4. ✅ Cliquer sur "Activer" → badge passe à "✓ Activé"
5. ✅ Vérifier que le service démarre/s'arrête réellement
6. ✅ Rafraîchir la page → état persiste (UCI)
## 📦 Modules Affectés
### SecuBox Hub (`luci-app-secubox`)
**Fichiers à modifier:**
- ✅ `root/usr/libexec/rpcd/luci.secubox` - Backend RPCD
- ✅ `htdocs/luci-static/resources/secubox/api.js` - API JS
- ✅ `htdocs/luci-static/resources/view/secubox/dashboard.js` - Dashboard
- ✅ `htdocs/luci-static/resources/view/secubox/modules.js` - Module list
- ✅ `htdocs/luci-static/resources/secubox/dashboard.css` - Styles
- ✅ `root/usr/share/rpcd/acl.d/luci-app-secubox.json` - ACL permissions
- ✅ `README.md` - Documentation
### System Hub (`luci-app-system-hub`)
**Fichiers à modifier:**
- ✅ `htdocs/luci-static/resources/view/system-hub/components.js` - Vue composants
- ✅ `htdocs/luci-static/resources/view/system-hub/services.js` - Vue services
- ✅ `README.md` - Documentation
## 🎯 Bénéfices
1. **Clarté conceptuelle**: "Activer/Désactiver" est plus clair que "Démarrer/Arrêter" pour des plugins
2. **Persistance**: L'état persiste après redémarrage (UCI + init.d enable/disable)
3. **Cohérence**: Tous les modules suivent la même logique
4. **Meilleure UX**: L'utilisateur comprend qu'il active/désactive des fonctionnalités
5. **Alignement OpenWrt**: Utilise les mécanismes natifs (`/etc/init.d/${service} enable/disable`)
## 🔜 Prochaines Étapes
- [x] Créer ce document de design
- [ ] Implémenter les modifications RPCD
- [ ] Mettre à jour l'API JavaScript
- [ ] Mettre à jour les interfaces UI
- [ ] Mettre à jour les ACL permissions
- [ ] Créer script de migration UCI
- [ ] Mettre à jour la documentation
- [ ] Tester sur router de test
- [ ] Déployer en production
---
**Maintainer:** CyberMind <contact@cybermind.fr>
**License:** Apache-2.0

553
docs/claude.md Normal file
View File

@ -0,0 +1,553 @@
# CLAUDE.md
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Active
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## 📚 Documentation Index
**IMPORTANT:** Before working on any code, consult these guides:
1. **[DEVELOPMENT-GUIDELINES.md](development-guidelines.md)** - ⭐ **GUIDE COMPLET**
- Design System & UI Guidelines (palettes, typographie, composants)
- Architecture & Naming Conventions (RPCD, menu paths, prefixes)
- RPCD & ubus Best Practices (erreurs communes, solutions)
- ACL & Permissions (templates, validations)
- JavaScript Patterns (API modules, views, event handling)
- CSS/Styling Standards (variables, responsive, dark mode)
- Common Errors & Solutions (diagnostics, fixes)
- Validation Checklist (pre-commit, pre-deploy, post-deploy)
- Deployment Procedures (scripts, rollback, versioning)
2. **[QUICK-START.md](quick-start.md)** - ⚡ **AIDE-MÉMOIRE RAPIDE**
- Règles critiques (RPCD naming, menu paths, permissions)
- Design system essentials (couleurs, fonts, classes)
- Common commands (validation, build, deploy, debug)
- Quick code templates (RPCD, View, Headers, Cards)
- Error quick fixes
3. **CLAUDE.md** (ce fichier) - 🏗️ **ARCHITECTURE & BUILD**
- Build commands (OpenWrt SDK, local build)
- Module structure (files, directories)
- CI/CD workflows
- Common issues techniques
**⚠️ RÈGLES CRITIQUES À TOUJOURS RESPECTER:**
1. **RPCD Script Naming:** Nom fichier = objet ubus (`luci.system-hub`)
2. **Menu Path Matching:** Path menu = fichier vue (`system-hub/overview.js`)
3. **Permissions:** RPCD = 755, CSS/JS = 644
- **Auto-fix:** `./secubox-tools/fix-permissions.sh --local` (avant commit)
- **Auto-fix remote:** `./secubox-tools/fix-permissions.sh --remote` (après deploy)
4. **Validation:** Toujours exécuter `./secubox-tools/validate-modules.sh` avant commit
- **7 checks automatiques:** RPCD naming, menu paths, view files, RPCD permissions, JSON syntax, ubus naming, **htdocs permissions**
5. **CSS Variables:** Toujours utiliser `var(--sh-*)`, jamais hardcoder les couleurs
6. **Dark Mode:** Toujours supporter dark mode avec `[data-theme="dark"]`
7. **Typography:** Inter (texte), JetBrains Mono (valeurs numériques)
8. **Gradient Effects:** Utiliser `--sh-primary` → `--sh-primary-end` pour dégradés
## Project Overview
SecuBox is a comprehensive security and network management suite for OpenWrt. The repository contains 13 LuCI application packages that provide dashboards for security monitoring, network intelligence, access control, bandwidth management, and system administration.
## Build Commands
### OpenWrt SDK Build
```bash
# Build a single package
make package/luci-app-<module-name>/compile V=s
# Clean build for a package
make package/luci-app-<module-name>/clean
make package/luci-app-<module-name>/compile V=s
# Install package to staging directory
make package/luci-app-<module-name>/install
```
### Testing Packages
```bash
# Transfer to router
scp bin/packages/*/base/luci-app-*.ipk root@192.168.1.1:/tmp/
# Install on router
ssh root@192.168.1.1
opkg install /tmp/luci-app-*.ipk
/etc/init.d/rpcd restart
/etc/init.d/uhttpd restart
```
### Validation
```bash
# Fix file permissions FIRST (CRITICAL)
./secubox-tools/fix-permissions.sh --local
# Run comprehensive module validation (RECOMMENDED - 7 checks)
./secubox-tools/validate-modules.sh
# Checks:
# 1. RPCD script names vs ubus objects
# 2. Menu paths vs view file locations
# 3. View files have menu entries
# 4. RPCD script permissions (755)
# 5. JSON syntax validation
# 6. ubus object naming convention
# 7. htdocs file permissions (644 for CSS/JS) ← NEW
# Validate shell scripts (RPCD backends)
shellcheck luci-app-*/root/usr/libexec/rpcd/*
# Validate JSON files
find . -name "*.json" -exec jsonlint {} \;
# Run automated repair tool
./secubox-tools/secubox-repair.sh
# Fix permissions on deployed router
./secubox-tools/fix-permissions.sh --remote
# Run diagnostics
./secubox-tools/secubox-debug.sh luci-app-<module-name>
```
### Local Build (Replicates GitHub Actions)
The `local-build.sh` script allows you to build and test packages locally, replicating the GitHub Actions workflows:
```bash
# Validate all packages (syntax, JSON, shell scripts)
./secubox-tools/local-build.sh validate
# Build all packages for x86_64
./secubox-tools/local-build.sh build
# Build single package
./secubox-tools/local-build.sh build luci-app-system-hub
# Build for specific architecture
./secubox-tools/local-build.sh build --arch aarch64-cortex-a72
# Full validation + build
./secubox-tools/local-build.sh full
# Clean build artifacts
./secubox-tools/local-build.sh clean
```
Supported architectures:
- `x86-64` - PC, VMs (default)
- `aarch64-cortex-a53` - ARM Cortex-A53 (ESPRESSObin)
- `aarch64-cortex-a72` - ARM Cortex-A72 (MOCHAbin, RPi4)
- `aarch64-generic` - Generic ARM64
- `mips-24kc` - MIPS 24Kc (TP-Link)
- `mipsel-24kc` - MIPS LE (Xiaomi, GL.iNet)
The script automatically:
- Downloads and caches the OpenWrt SDK
- Configures feeds (packages, luci) with correct branch for version
- Copies your packages to the SDK
- Builds packages (.apk for 25.12+, .ipk for older versions)
- Collects artifacts in `build/<arch>/`
**Package Format Support:**
- OpenWrt 25.12+ and SNAPSHOT: `.apk` format (new Alpine-based package manager)
- OpenWrt 24.10 and earlier: `.ipk` format (opkg package manager)
Environment variables:
- `OPENWRT_VERSION` - OpenWrt version (default: 24.10.5, also supports: 25.12.0-rc1, 23.05.5, SNAPSHOT)
- `SDK_DIR` - SDK directory (default: ./sdk)
- `BUILD_DIR` - Build output directory (default: ./build)
- `CACHE_DIR` - Download cache directory (default: ./cache)
## Architecture
### LuCI Package Structure
All SecuBox modules follow a standard LuCI application structure:
```
luci-app-<module-name>/
├── Makefile # OpenWrt package definition
├── README.md # Module documentation
├── htdocs/luci-static/resources/
│ ├── view/<module-name>/ # JavaScript UI views
│ │ ├── overview.js # Main dashboard view
│ │ └── *.js # Additional views
│ └── <module-name>/
│ ├── api.js # RPC API client module
│ └── dashboard.css # Module-specific styles
└── root/
├── etc/config/<module-name> # UCI configuration (optional)
└── usr/
├── libexec/rpcd/
│ └── luci.<module-name> # RPCD backend script (MUST use luci. prefix!)
└── share/
├── luci/menu.d/ # Menu JSON definition
│ └── luci-app-<module-name>.json
└── rpcd/acl.d/ # ACL permissions JSON
└── luci-app-<module-name>.json
```
### Frontend-Backend Communication
1. **Frontend (JavaScript)**: Located in `htdocs/luci-static/resources/`
- Views use LuCI's `form` and `view` classes
- API calls via `api.js` module using `L.resolveDefault()`
- UI components from `ui.js` (Dropdown, Checkbox, Combobox, etc.)
2. **Backend (RPCD)**: Located in `root/usr/libexec/rpcd/`
- Shell scripts that implement RPC methods
- Must output JSON to stdout
- Methods are called via ubus: `ubus call <module> <method>`
3. **Menu Definition**: `root/usr/share/luci/menu.d/luci-app-<module>.json`
- Defines menu structure and navigation
- Specifies view paths and dependencies
4. **ACL Definition**: `root/usr/share/rpcd/acl.d/luci-app-<module>.json`
- Defines access control for ubus methods
- Maps read/write permissions to user groups
### Critical Naming Conventions
**IMPORTANT**: The following naming rules are MANDATORY for modules to work correctly:
#### 1. RPCD Script Must Match ubus Object Name
The RPCD script filename MUST exactly match the ubus object name used in JavaScript:
```javascript
// In JavaScript (htdocs/luci-static/resources/view/*/):
var callStatus = rpc.declare({
object: 'luci.cdn-cache', // ← This object name
method: 'status'
});
```
```bash
# RPCD script filename MUST match:
root/usr/libexec/rpcd/luci.cdn-cache # ← Must be exactly 'luci.cdn-cache'
```
**Common Error**: If the names don't match, you'll get:
- `RPC call to luci.cdn-cache/status failed with error -32000: Object not found`
- `Command failed: Method not found`
**Solution**: All RPCD scripts MUST use the `luci.` prefix:
- ✅ Correct: `luci.cdn-cache`, `luci.system-hub`, `luci.wireguard-dashboard`
- ❌ Wrong: `cdn-cache`, `system-hub`, `wireguard-dashboard`
#### 2. Menu Paths Must Match View File Locations
Menu JSON path entries MUST correspond to actual view files:
```json
// In menu.d/luci-app-netifyd-dashboard.json:
{
"action": {
"type": "view",
"path": "netifyd-dashboard/overview" // ← Must match file location
}
}
```
```bash
# View file MUST exist at:
htdocs/luci-static/resources/view/netifyd-dashboard/overview.js
# ↑ Same path as menu ↑
```
**Common Error**: If paths don't match:
- `HTTP error 404 while loading class file '/luci-static/resources/view/netifyd/overview.js'`
**Solution**: Ensure menu paths match directory structure:
- ✅ Correct: Menu path `netifyd-dashboard/overview` → file `view/netifyd-dashboard/overview.js`
- ❌ Wrong: Menu path `netifyd/overview` → file `view/netifyd-dashboard/overview.js`
#### 3. ubus Object Naming Convention
All ubus objects MUST start with `luci.` prefix:
```javascript
// ✅ Correct:
object: 'luci.cdn-cache'
object: 'luci.system-hub'
object: 'luci.wireguard-dashboard'
// ❌ Wrong:
object: 'cdn-cache'
object: 'systemhub'
```
#### 4. Validation Before Deployment
**ALWAYS** run validation before deploying:
```bash
./secubox-tools/validate-modules.sh
```
This script checks:
- RPCD script names match ubus objects
- Menu paths match view file locations
- View files have corresponding menu entries
- RPCD scripts are executable
- JSON files are valid syntax
- ubus objects follow naming convention
### Makefile Structure
Each package Makefile must define:
- `PKG_NAME`: Package name (must match directory)
- `PKG_VERSION`: Version number
- `PKG_RELEASE`: Package release number
- `LUCI_TITLE`: Display title in LuCI
- `LUCI_DEPENDS`: Package dependencies (e.g., `+luci-base +rpcd`)
- `LUCI_DESCRIPTION`: Brief description
- `PKG_MAINTAINER`: Maintainer name and email
- `PKG_LICENSE`: License (typically Apache-2.0)
The Makefile includes `luci.mk` from the LuCI build system which handles installation.
## Common Development Patterns
### Creating a New Module
1. Copy template: `cp -r templates/luci-app-template luci-app-newmodule`
2. Update Makefile with new PKG_NAME, LUCI_TITLE, etc.
3. Create directory structure under `htdocs/` and `root/`
4. Implement RPCD backend in shell
5. Create JavaScript views
6. Define menu and ACL JSON files
### RPCD Backend Pattern
RPCD backends are shell scripts that:
- Parse `$1` for the method name
- Output valid JSON using `printf` or `echo`
- Use `case` statements for method routing
- Source UCI config if needed: `. /lib/functions.sh`
Example:
```bash
#!/bin/sh
case "$1" in
list)
echo '{ "status": {}, "stats": {} }'
;;
call)
case "$2" in
status)
# Output JSON
printf '{"running": true, "version": "1.0.0"}\n'
;;
esac
;;
esac
```
### JavaScript View Pattern
Views extend `L.view` and implement `load()` and `render()`:
```javascript
'use strict';
'require view';
'require form';
'require <module>/api as API';
return L.view.extend({
load: function() {
return Promise.all([
API.getStatus(),
API.getStats()
]);
},
render: function(data) {
var m, s, o;
m = new form.Map('config', _('Title'));
s = m.section(form.TypedSection, 'section');
// Add form fields...
return m.render();
}
});
```
## Module Categories
1. **Core Control** (2 modules)
- luci-app-secubox: Central hub
- luci-app-system-hub: System control center
2. **Security & Monitoring** (2 modules)
- luci-app-crowdsec-dashboard: CrowdSec security
- luci-app-netdata-dashboard: System monitoring
3. **Network Intelligence** (2 modules)
- luci-app-netifyd-dashboard: Deep packet inspection
- luci-app-network-modes: Network mode configuration
4. **VPN & Access Control** (3 modules)
- luci-app-wireguard-dashboard: WireGuard VPN
- luci-app-client-guardian: NAC & captive portal
- luci-app-auth-guardian: Authentication system
5. **Bandwidth & Traffic** (2 modules)
- luci-app-bandwidth-manager: QoS & quotas
- luci-app-media-flow: Media traffic detection
6. **Performance & Services** (2 modules)
- luci-app-cdn-cache: CDN proxy cache
- luci-app-vhost-manager: Virtual host manager
## CI/CD Integration
### GitHub Actions Workflows
1. **build-openwrt-packages.yml**: Compiles packages for all architectures
- Triggers on push, PR, and tags
- Matrix build for 13 architectures
- Uploads artifacts per architecture
2. **build-secubox-images.yml**: Builds custom OpenWrt images
- Creates complete firmware images with SecuBox pre-installed
3. **test-validate.yml**: Validation and testing
- Validates Makefile structure
- Checks JSON syntax
- Runs shellcheck on scripts
- Verifies file permissions
### Supported Architectures
ARM64: aarch64-cortex-a53, aarch64-cortex-a72, aarch64-generic, mediatek-filogic, rockchip-armv8, bcm27xx-bcm2711
ARM32: arm-cortex-a7-neon, arm-cortex-a9-neon, qualcomm-ipq40xx, qualcomm-ipq806x
MIPS: mips-24kc, mipsel-24kc, mipsel-74kc
x86: x86-64, x86-generic
## Key Files and Directories
- `makefiles/`: Reference Makefiles for modules (backup/templates)
- `secubox-tools/`: Repair and debugging utilities
- `secubox-repair.sh`: Auto-fixes Makefile and RPCD issues
- `secubox-debug.sh`: Validates package structure
- `templates/`: Package templates for creating new modules
- `.github/workflows/`: CI/CD automation scripts
## Common Issues and Solutions
### RPC Errors: "Object not found" or "Method not found"
**Error**: `RPC call to luci.cdn-cache/status failed with error -32000: Object not found`
**Cause**: RPCD script name doesn't match ubus object name in JavaScript
**Solution**:
1. Check JavaScript files for ubus object name:
```bash
grep -r "object:" luci-app-*/htdocs --include="*.js"
```
2. Rename RPCD script to match exactly (including `luci.` prefix):
```bash
mv root/usr/libexec/rpcd/cdn-cache root/usr/libexec/rpcd/luci.cdn-cache
```
3. Restart RPCD on router:
```bash
/etc/init.d/rpcd restart
```
### HTTP 404 Errors: View Files Not Found
**Error**: `HTTP error 404 while loading class file '/luci-static/resources/view/netifyd/overview.js'`
**Cause**: Menu path doesn't match actual view file location
**Solution**:
1. Check menu JSON for path:
```bash
grep '"path":' root/usr/share/luci/menu.d/*.json
```
2. Verify view file exists at matching location:
```bash
ls htdocs/luci-static/resources/view/
```
3. Update menu path to match file location OR move file to match menu path
### RPCD Not Responding
After installing/updating a package:
```bash
/etc/init.d/rpcd restart
/etc/init.d/uhttpd restart
```
### Menu Not Appearing
Check that:
1. Menu JSON is valid: `jsonlint root/usr/share/luci/menu.d/*.json`
2. ACL grants access: Check `root/usr/share/rpcd/acl.d/*.json`
3. Dependencies are installed: Check Makefile `LUCI_DEPENDS`
4. Menu path matches view file location (see above)
### Build Failures
Common causes:
1. Missing fields in Makefile (PKG_NAME, LUCI_TITLE, etc.)
2. Invalid JSON syntax in menu.d or acl.d
3. RPCD script not executable (chmod +x needed)
4. Wrong include path (should be `include ../../luci.mk`)
5. RPCD script name doesn't match ubus object (must use `luci.` prefix)
Use repair tool: `./secubox-tools/secubox-repair.sh`
### Quick Diagnosis
Run the validation script to check all naming conventions:
```bash
./secubox-tools/validate-modules.sh
```
## Development Workflow
1. Make changes to module files
2. **Run validation checks** (CRITICAL):
```bash
./secubox-tools/validate-modules.sh
# Or use the local build tool:
./secubox-tools/local-build.sh validate
```
3. Test JSON syntax: `jsonlint <file>.json`
4. Test shell scripts: `shellcheck <script>`
5. Build and test package locally (recommended):
```bash
# Build single package
./secubox-tools/local-build.sh build luci-app-<name>
# Or build with manual SDK:
make package/luci-app-<name>/compile V=s
```
6. Install on test router and verify functionality
7. Run repair tool if needed: `./secubox-tools/secubox-repair.sh`
8. Commit changes and push (triggers CI validation)
9. Create tag for release: `git tag -a v1.0.0 -m "Release 1.0.0"`
## Important Notes
- **CRITICAL**: RPCD script names MUST match ubus object names (use `luci.` prefix)
- **CRITICAL**: Menu paths MUST match view file directory structure
- **CRITICAL**: Always run `./secubox-tools/validate-modules.sh` before committing
- All modules use Apache-2.0 license
- RPCD backends must be executable (chmod +x)
- JavaScript files use strict mode: `'use strict';`
- Menu entries require proper dependency chain
- ACL must grant both ubus call and luci-cgi access
- UCI config files are optional (many modules don't need them)
- All packages build as architecture `all` (no compiled code)

1405
docs/code-templates.md Normal file
View File

File diff suppressed because it is too large Load Diff

1857
docs/development-guidelines.md Normal file
View File

File diff suppressed because it is too large Load Diff

402
docs/documentation-index.md Normal file
View File

@ -0,0 +1,402 @@
# SecuBox Documentation Index
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Active
**Complete Documentation for SecuBox OpenWrt Project**
---
## 📖 Documentation Overview
This index provides quick access to all SecuBox documentation. Choose the document that matches your needs:
---
## 📅 Version & Status Policy
Every Markdown document in SecuBox must begin with metadata so contributors instantly see freshness:
- Include `Version`, `Last Updated` (YYYY-MM-DD), and `Status` (Active | Draft | Archived).
- New or regenerated docs start at `Version 1.0.0`; bump minor/patch numbers for incremental updates, major for structural rewrites.
- When editing any doc, update the `Last Updated` date and keep statuses in sync with the archive plan outlined in `TODO-ANALYSE.md`.
Follow this template when creating or revising documentation:
```
# Title
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Active
```
---
## 🚀 Getting Started
### For New Contributors
1. Start with **[QUICK-START.md](quick-start.md)** - Essential rules and commands
2. Read **[DEVELOPMENT-GUIDELINES.md](development-guidelines.md)** - Complete development guide
3. Review **[CLAUDE.md](claude.md)** - Build system and architecture
### For AI-Assisted Development
1. Use **[MODULE-IMPLEMENTATION-GUIDE.md](module-implementation-guide.md)** - Step-by-step workflow
2. Copy prompts from **[FEATURE-REGENERATION-PROMPTS.md](feature-regeneration-prompts.md)**
3. Reference **[CODE-TEMPLATES.md](code-templates.md)** for implementation patterns
### For Existing Module Modification
1. Check **[QUICK-START.md](quick-start.md)** - Quick fixes and common commands
2. Run validation: `./secubox-tools/validate-modules.sh`
3. Review **[DEVELOPMENT-GUIDELINES.md](development-guidelines.md)** for specific topics
---
## 📚 Document Descriptions
### 1. Quick Reference Documents
#### **QUICK-START.md** ⚡
*Quick reference for common tasks - Read this first!*
**Contents:**
- Critical naming rules (RPCD, menu paths, permissions)
- Design system essentials (colors, fonts, CSS classes)
- Common commands (validation, build, deploy, debug)
- Quick code templates (RPCD, View, Headers, Cards)
- Error quick fixes
**When to use:** Daily development, quick lookups, debugging
---
#### **CODEX.md** 🤖
*Field manual for Codex/automation agents*
**Contents:**
- Repository context and document map
- Non-negotiable build/design standards
- Prompt template for LLM workflows
- Help & troubleshooting pointers
- Documentation TODO radar and history
**When to use:** Before launching Codex/AI-assisted edits, when crafting prompts, or when aligning work with current documentation initiatives
---
#### **README.md** 📋
*Project overview and compatibility matrix*
**Contents:**
- Project description and features
- OpenWrt version compatibility (24.10.x, 25.12.0-rc1, etc.)
- Package format support (.ipk vs .apk)
- Installation instructions
- Module categories and descriptions
**When to use:** Project overview, version compatibility checks
---
### 2. Complete Reference Documents
#### **DEVELOPMENT-GUIDELINES.md** ⭐
*Complete development guide - The definitive reference*
**Contents:**
- **Design System**: Color palettes, typography, component library
- **Architecture**: File structure, naming conventions, RPCD patterns
- **Best Practices**: RPCD, ubus, ACL, JavaScript, CSS standards
- **Common Errors**: Diagnostics and solutions for typical issues
- **Validation**: Pre-commit, pre-deploy, post-deploy checklists
- **Deployment**: Step-by-step deployment procedures
**When to use:** Detailed technical questions, design decisions, troubleshooting
**Size:** Comprehensive (~500+ lines)
---
#### **CLAUDE.md** 🏗️
*Build system, architecture, and CI/CD reference*
**Contents:**
- OpenWrt SDK build commands
- Package testing procedures
- Validation tools and workflows
- LuCI package structure
- Frontend-backend communication
- Critical naming conventions
- CI/CD integration (GitHub Actions)
- Common issues and solutions
**When to use:** Build issues, CI/CD workflows, architecture questions
---
### 3. Implementation & Regeneration Documents
#### **MODULE-IMPLEMENTATION-GUIDE.md** 🎯
*Master guide for implementing/regenerating modules*
**Contents:**
- Step-by-step workflow for regenerating modules
- How to use Claude.ai for code generation
- Complete implementation example (from prompt to deployment)
- Common implementation patterns (multi-tab dashboards, filters, forms)
- Module-specific notes (System Hub, WireGuard, CrowdSec, etc.)
- Troubleshooting guide with solutions
- Best practices (code organization, error handling, performance, UX)
- Deployment checklist
**When to use:** Implementing new modules, regenerating existing modules, using AI assistance
**Size:** Comprehensive guide (~800+ lines)
---
#### **FEATURE-REGENERATION-PROMPTS.md** 💬
*Ready-to-use prompts for all 15 SecuBox modules*
**Contents:**
- Design system reference (CSS variables, typography, components)
- Complete prompts for all 15 modules:
1. SecuBox Central Hub
2. System Hub (9 tabs)
3. CrowdSec Dashboard
4. Netdata Dashboard
5. Netifyd Dashboard
6. Network Modes
7. WireGuard Dashboard
8. Client Guardian
9. Auth Guardian
10. Bandwidth Manager
11. Traffic Shaper
12. Media Flow
13. CDN Cache
14. VHost Manager
15. KSM Manager
- Common UI patterns across all modules
- Usage instructions for Claude.ai
**When to use:** Getting AI to generate module code, understanding module requirements
**Size:** Extensive (~2000+ lines)
---
#### **CODE-TEMPLATES.md** 💻
*Working code templates extracted from production modules*
**Contents:**
- File structure template
- API module template (api.js)
- JavaScript view template (overview.js)
- RPCD backend template (shell script)
- Menu JSON template
- ACL JSON template
- CSS styling template
- Complete minimal working example
- Common pitfalls and solutions
- Validation checklist
**When to use:** Manual implementation, understanding patterns, copying boilerplate code
**Size:** Detailed templates (~1200+ lines)
---
### 4. Tools & Scripts Documentation
#### **secubox-tools/README.md** 🔧
*Documentation for validation and build tools*
**Contents:**
- Tool descriptions (validate-modules.sh, local-build.sh, etc.)
- Usage examples for each tool
- Supported architectures and devices
- Package building workflows
- Firmware building workflows
- Validation checks (7 automated checks)
- Recommended workflows
- Common fixes
**When to use:** Using validation tools, local builds, firmware generation
---
### 5. Live Demo & Examples
#### **Live Demo Website** 🌐
*Production demo of all modules*
**URL:** https://secubox.cybermood.eu
**Available Demos:**
- Main dashboard: `/`
- System Hub: `/system-hub`
- CrowdSec: `/crowdsec`
- WireGuard: `/wireguard`
- All 15 modules accessible
**When to use:** Visual reference, understanding UI/UX, testing features
---
## 🎯 Quick Lookup by Task
### I want to...
#### ...create a new module from scratch
1. Read: **MODULE-IMPLEMENTATION-GUIDE.md** (Step-by-step workflow)
2. Copy prompt from: **FEATURE-REGENERATION-PROMPTS.md**
3. Use templates from: **CODE-TEMPLATES.md**
4. Validate with: `./secubox-tools/validate-modules.sh`
#### ...regenerate an existing module
1. Read: **MODULE-IMPLEMENTATION-GUIDE.md** (Section: "Step-by-Step: Regenerate a Module with Claude.ai")
2. Copy module specification from: **FEATURE-REGENERATION-PROMPTS.md**
3. Use Claude.ai or copy templates from: **CODE-TEMPLATES.md**
4. Validate and deploy following: **MODULE-IMPLEMENTATION-GUIDE.md**
#### ...fix RPCD "Object not found" error
1. Quick fix: **QUICK-START.md** (Error Quick Fixes section)
2. Detailed troubleshooting: **DEVELOPMENT-GUIDELINES.md** (Common Errors section)
3. Or: **MODULE-IMPLEMENTATION-GUIDE.md** (Troubleshooting Guide)
#### ...understand the design system
1. Quick reference: **QUICK-START.md** (Design System Essentials)
2. Complete guide: **DEVELOPMENT-GUIDELINES.md** (Design System & UI Guidelines)
3. See live examples: **https://secubox.cybermood.eu**
#### ...build packages locally
1. Quick commands: **QUICK-START.md** (Build & Deploy section)
2. Complete guide: **secubox-tools/README.md**
3. Architecture details: **CLAUDE.md** (Build Commands section)
#### ...validate my changes before commit
1. Run: `./secubox-tools/fix-permissions.sh --local`
2. Run: `./secubox-tools/validate-modules.sh`
3. Review checklist: **DEVELOPMENT-GUIDELINES.md** (Validation Checklist)
#### ...understand menu and ACL configuration
1. Quick templates: **CODE-TEMPLATES.md** (Menu JSON Template, ACL JSON Template)
2. Detailed guide: **DEVELOPMENT-GUIDELINES.md** (Architecture & Naming Conventions)
3. Working examples: Look in any `luci-app-*/root/usr/share/` directory
#### ...deploy to test router
1. Quick commands: **QUICK-START.md** (Common Commands)
2. Step-by-step: **MODULE-IMPLEMENTATION-GUIDE.md** (Deploy to Test Router section)
3. Fix permissions after deploy: `./secubox-tools/fix-permissions.sh --remote`
#### ...understand CSS variable system
1. Quick reference: **QUICK-START.md** (CSS Variables section)
2. Complete guide: **DEVELOPMENT-GUIDELINES.md** (CSS/Styling Standards)
3. Template: **CODE-TEMPLATES.md** (CSS Styling Template)
4. Live CSS: `luci-app-system-hub/htdocs/luci-static/resources/system-hub/common.css`
#### ...write RPCD backend script
1. Template: **CODE-TEMPLATES.md** (RPCD Backend Template)
2. Best practices: **DEVELOPMENT-GUIDELINES.md** (RPCD & ubus Best Practices)
3. Working examples: Look in any `luci-app-*/root/usr/libexec/rpcd/` directory
#### ...create multi-tab dashboard
1. Pattern: **MODULE-IMPLEMENTATION-GUIDE.md** (Pattern 1: Multi-Tab Dashboard)
2. Example: See `luci-app-system-hub` (9 tabs)
3. Live demo: https://secubox.cybermood.eu/system-hub
---
## 📊 Documentation Comparison Matrix
| Document | Size | Scope | Use Case | Audience |
|----------|------|-------|----------|----------|
| **QUICK-START.md** | Small | Quick reference | Daily development | All developers |
| **README.md** | Small | Project overview | First introduction | New contributors |
| **DEVELOPMENT-GUIDELINES.md** | Large | Complete reference | Detailed questions | All developers |
| **CLAUDE.md** | Medium | Build & architecture | Build/CI/CD issues | Developers, DevOps |
| **MODULE-IMPLEMENTATION-GUIDE.md** | Large | Implementation workflow | Module creation | AI-assisted dev |
| **FEATURE-REGENERATION-PROMPTS.md** | Very Large | Module specifications | AI prompts | AI-assisted dev |
| **CODE-TEMPLATES.md** | Large | Code templates | Manual coding | Developers |
| **secubox-tools/README.md** | Medium | Tools documentation | Tool usage | Developers, DevOps |
---
## 🔄 Documentation Update Workflow
When making changes to the codebase:
1. **Update code** in module files
2. **Run validation**: `./secubox-tools/validate-modules.sh`
3. **Update documentation** if:
- New pattern introduced → Add to **CODE-TEMPLATES.md**
- New design guideline → Update **DEVELOPMENT-GUIDELINES.md**
- New common error → Add to **QUICK-START.md** and **DEVELOPMENT-GUIDELINES.md**
- New module → Add to **FEATURE-REGENERATION-PROMPTS.md**
- New build feature → Update **CLAUDE.md** and **secubox-tools/README.md**
4. **Update version** and date in modified documents
5. **Commit** documentation along with code changes
---
## 📞 Support & Contact
- **Documentation Issues:** Create issue at [GitHub Issues](https://github.com/anthropics/claude-code/issues)
- **Technical Support:** support@cybermind.fr
- **Live Demo:** https://secubox.cybermood.eu
- **Company:** CyberMind.fr
---
## 🎓 Learning Path
### Beginner (New to SecuBox)
1. Day 1: Read **README.md** + **QUICK-START.md**
2. Day 2: Skim **DEVELOPMENT-GUIDELINES.md** (focus on Design System and Architecture)
3. Day 3: Follow **MODULE-IMPLEMENTATION-GUIDE.md** to implement a simple module
4. Day 4: Study existing modules (start with `luci-app-cdn-cache` - simplest)
5. Day 5: Make your first contribution
### Intermediate (Familiar with OpenWrt/LuCI)
1. Read **DEVELOPMENT-GUIDELINES.md** (full document)
2. Review **CODE-TEMPLATES.md** for patterns
3. Use **FEATURE-REGENERATION-PROMPTS.md** with Claude.ai to generate a module
4. Study **CLAUDE.md** for build system details
5. Contribute new modules or enhance existing ones
### Advanced (Ready for Complex Modules)
1. Study complex modules: System Hub, Network Modes
2. Read all documentation for comprehensive understanding
3. Use **MODULE-IMPLEMENTATION-GUIDE.md** patterns for advanced features
4. Contribute to core design system and tools
5. Help with documentation improvements
---
## 📝 Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2025-12-27 | Initial comprehensive documentation release |
| | | - Created FEATURE-REGENERATION-PROMPTS.md (15 modules) |
| | | - Created CODE-TEMPLATES.md (complete templates) |
| | | - Created MODULE-IMPLEMENTATION-GUIDE.md (master guide) |
| | | - Created DOCUMENTATION-INDEX.md (this file) |
| | | - Enhanced existing documentation |
---
## 🏆 Documentation Quality Goals
- **Completeness:** All aspects of SecuBox development covered
- **Accuracy:** Code examples tested and working
- **Clarity:** Clear explanations with examples
- **Maintainability:** Easy to update as codebase evolves
- **Accessibility:** Multiple entry points for different use cases
- **AI-Friendly:** Structured for AI-assisted development
---
**Last Updated:** 2025-12-27
**Maintainer:** CyberMind.fr
**License:** Apache-2.0

2084
docs/feature-regeneration-prompts.md Normal file
View File

File diff suppressed because it is too large Load Diff

178
docs/index.md Normal file
View File

@ -0,0 +1,178 @@
# SecuBox Documentation
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Project:** OpenWrt LuCI Security & Management Suite
Welcome to the SecuBox documentation! This comprehensive guide covers all aspects of developing, deploying, and maintaining SecuBox modules.
---
## 🏗️ What is SecuBox?
SecuBox is a comprehensive **security and network management suite for OpenWrt** consisting of **15 LuCI application modules** that provide:
- **Security Monitoring** - CrowdSec intrusion prevention, Netdata metrics
- **Network Intelligence** - Deep packet inspection, traffic classification
- **Access Control** - Captive portal, authentication, VPN management
- **Performance Optimization** - QoS, bandwidth management, caching
- **System Administration** - Centralized dashboard, service management
---
## 🚀 Quick Navigation
<div class="grid cards" markdown>
- :fontawesome-solid-rocket:{ .lg .middle } **Getting Started**
---
New to SecuBox? Start here!
[:octicons-arrow-right-24: Quick Start Guide](quick-start.md)
- :fontawesome-solid-book:{ .lg .middle } **Development Guide**
---
Complete development reference with architecture diagrams
[:octicons-arrow-right-24: Development Guidelines](development-guidelines.md)
- :fontawesome-solid-code:{ .lg .middle } **Code Templates**
---
Working examples and implementation patterns
[:octicons-arrow-right-24: Code Templates](code-templates.md)
- :fontawesome-solid-list-check:{ .lg .middle } **Validation**
---
Module validation and testing workflows
[:octicons-arrow-right-24: Validation Guide](validation-guide.md)
</div>
---
## 📦 15 Module Suite
### Core Control (2 modules)
- **SecuBox Central Hub** - Main dashboard and module management
- **System Hub** - System administration (health, services, logs, backup, etc.)
### Security & Monitoring (2 modules)
- **CrowdSec Dashboard** - Intrusion prevention and threat intelligence
- **Netdata Dashboard** - Real-time system monitoring
### Network Intelligence (2 modules)
- **Netifyd Dashboard** - Deep packet inspection and classification
- **Network Modes** - Network profile management
### VPN & Access Control (3 modules)
- **WireGuard Dashboard** - VPN tunnel management
- **Client Guardian** - Network access control and captive portal
- **Auth Guardian** - Authentication system
### Bandwidth & Traffic (2 modules)
- **Bandwidth Manager** - QoS and bandwidth quotas
- **Traffic Shaper** - Advanced traffic shaping
### Performance & Services (2 modules)
- **CDN Cache** - Content delivery network proxy cache
- **VHost Manager** - Virtual host configuration
### System Optimization (2 modules)
- **Media Flow** - Media traffic optimization
- **KSM Manager** - Kernel same-page merging
[View Module Status →](module-status.md){ .md-button .md-button--primary }
---
## 🎨 Design System
SecuBox uses a modern, consistent design system:
- **Color Palette:** Indigo/Violet gradients with dark mode support
- **Typography:** Inter (text) + JetBrains Mono (code/values)
- **Components:** Cards, badges, buttons with gradient effects
- **Layout:** Responsive grid system
See the [Design System section](development-guidelines.md#design-system--ui-guidelines) for complete specifications.
---
## 🔧 Development Workflow
!!! warning "Critical Rules"
1. **RPCD Naming:** Script name must match ubus object (`luci.module-name`)
2. **Menu Paths:** Must match view file locations exactly
3. **Permissions:** 755 for RPCD scripts, 644 for CSS/JS
4. **Validation:** Always run `./secubox-tools/validate-modules.sh` before commit
### Development Tools
```bash
# Validate all modules (7 automated checks)
./secubox-tools/validate-modules.sh
# Fix file permissions automatically
./secubox-tools/fix-permissions.sh --local
# Build packages locally
./secubox-tools/local-build.sh build luci-app-module-name
```
[Complete Development Workflow →](development-guidelines.md#deployment-procedures){ .md-button }
---
## 🌐 Live Demo
Experience SecuBox in action:
**Production Demo:** [https://secubox.cybermood.eu](https://secubox.cybermood.eu)
- Main dashboard: `/`
- System Hub: `/system-hub`
- CrowdSec: `/crowdsec`
- All 15 modules accessible
---
## 📚 Documentation Sections
### For New Contributors
1. [Quick Start Guide](quick-start.md) - Essential rules and commands
2. [Development Guidelines](development-guidelines.md) - Complete reference
3. [CLAUDE.md](claude.md) - Build system and architecture
### For AI-Assisted Development
1. [Module Implementation Guide](module-implementation-guide.md) - Step-by-step workflow
2. [Feature Regeneration Prompts](feature-regeneration-prompts.md) - AI prompts for all modules
3. [Code Templates](code-templates.md) - Implementation patterns
---
## 📞 Support & Resources
- **GitHub Repository:** [gkerma/secubox-openwrt](https://github.com/gkerma/secubox-openwrt)
- **Documentation Issues:** [GitHub Issues](https://github.com/gkerma/secubox-openwrt/issues)
- **Technical Support:** support@cybermind.fr
- **Company:** CyberMind.fr
---
## 📝 License
Apache-2.0
---
<small>**Last Updated:** 2025-12-28 | **Maintainer:** CyberMind.fr</small>

1196
docs/luci-development-reference.md Normal file
View File

File diff suppressed because it is too large Load Diff

884
docs/module-implementation-guide.md Normal file
View File

@ -0,0 +1,884 @@
# SecuBox Module Implementation Guide
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Active
**Purpose:** Complete guide for regenerating SecuBox modules matching the live demo
---
## See Also
- **Automation Briefing:** [CODEX.md](codex.md)
- **Module Prompts:** [FEATURE-REGENERATION-PROMPTS.md](feature-regeneration-prompts.md)
- **Code Templates:** [CODE-TEMPLATES.md](code-templates.md)
- **Quick Commands:** [QUICK-START.md](quick-start.md)
---
## Quick Navigation
📋 **[FEATURE-REGENERATION-PROMPTS.md](feature-regeneration-prompts.md)** - Complete feature specifications for all 15 modules
💻 **[CODE-TEMPLATES.md](code-templates.md)** - Ready-to-use code templates and implementation examples
🏗️ **[DEVELOPMENT-GUIDELINES.md](development-guidelines.md)** - Complete development guidelines and design system
⚡ **[QUICK-START.md](quick-start.md)** - Quick reference for common tasks
🔧 **[CLAUDE.md](claude.md)** - Build system and architecture reference
---
## Document Overview
This guide shows you how to use the comprehensive documentation to regenerate or create SecuBox modules that match the live demo at **secubox.cybermood.eu**.
### What's Included
1. **Feature Specifications** - Detailed requirements for all 15 modules
2. **Code Templates** - Working implementation examples
3. **Design System** - CSS variables, typography, components
4. **Validation Tools** - Automated testing and fixing
5. **Deployment Scripts** - Local build and remote deployment
---
## Implementation Workflow
### Step 1: Choose Your Approach
**Option A: Use Claude.ai for Code Generation**
1. Open [claude.ai](https://claude.ai)
2. Copy the relevant module prompt from [FEATURE-REGENERATION-PROMPTS.md](feature-regeneration-prompts.md)
3. Paste the prompt and request implementation
4. Claude will generate all required files based on the templates
5. Review and integrate the generated code
**Option B: Manual Implementation Using Templates**
1. Copy templates from [CODE-TEMPLATES.md](code-templates.md)
2. Replace placeholders with module-specific values
3. Implement module-specific logic
4. Validate and test
**Option C: Hybrid Approach (Recommended)**
1. Use Claude.ai for initial code generation
2. Refine using templates and guidelines
3. Validate with automated tools
4. Deploy and test on target device
---
## Step-by-Step: Regenerate a Module with Claude.ai
### Example: Regenerating System Hub Module
#### 1. Gather Context
Before prompting Claude, gather these resources:
```bash
# Read the module specification
cat FEATURE-REGENERATION-PROMPTS.md | grep -A 200 "System Hub"
# Review the design system
cat DEVELOPMENT-GUIDELINES.md | grep -A 100 "Design System"
# Check existing implementation (if available)
ls -la luci-app-system-hub/
```
#### 2. Prepare the Prompt
Create a comprehensive prompt for Claude.ai:
```
I need you to implement the System Hub module for OpenWrt LuCI framework.
IMPORTANT CONSTRAINTS:
- OpenWrt uses LuCI framework (not React/Vue)
- JavaScript uses L.view.extend() pattern (not ES6 modules)
- Backend is RPCD (shell scripts) communicating via ubus
- CSS must use variables from system-hub/common.css
- All code must be production-ready and match live demo
- Follow the design system exactly
TECHNICAL REQUIREMENTS:
- RPCD script MUST be named: luci.system-hub
- Menu paths MUST match view file locations
- Use CSS variables (--sh-*) for all colors
- Support dark mode with [data-theme="dark"]
- Implement proper error handling
- Add loading states for async operations
REFERENCE DOCUMENTS:
1. Live Demo: https://secubox.cybermood.eu/system-hub
2. Feature Specification: [paste from FEATURE-REGENERATION-PROMPTS.md]
3. Code Templates: [paste relevant templates from CODE-TEMPLATES.md]
Please provide:
1. Complete JavaScript view files (overview.js, services.js, etc.)
2. RPCD backend script (luci.system-hub)
3. API module (system-hub/api.js)
4. CSS styles (system-hub/dashboard.css)
5. Menu configuration JSON
6. ACL configuration JSON
Make sure all code matches the live demo visual design and functionality.
```
#### 3. Generate Code
Paste your prompt into Claude.ai and let it generate the implementation.
#### 4. Review Generated Code
Check the generated code against these requirements:
**API Module Checklist:**
- [ ] Uses `'use strict';`
- [ ] Requires `baseclass` and `rpc`
- [ ] All RPC methods use `rpc.declare()`
- [ ] Object names match RPCD script name (`luci.system-hub`)
- [ ] Helper functions included if needed
- [ ] Exports from `baseclass.extend()`
**View Module Checklist:**
- [ ] Extends `view.extend()`
- [ ] Implements `load()` method returning Promise
- [ ] Implements `render(data)` method
- [ ] Uses `E()` helper for DOM building
- [ ] Implements `poll.add()` for auto-refresh
- [ ] Proper error handling with try/catch
- [ ] Uses `ui.showModal()` for loading states
- [ ] Uses `ui.addNotification()` for user feedback
**RPCD Backend Checklist:**
- [ ] Starts with `#!/bin/sh`
- [ ] Sources `/lib/functions.sh` and `/usr/share/libubox/jshn.sh`
- [ ] Implements `list` case with method declarations
- [ ] Implements `call` case with method routing
- [ ] All methods output valid JSON using `json_*` functions
- [ ] Proper parameter validation
- [ ] Error handling with appropriate messages
**Menu JSON Checklist:**
- [ ] Paths follow `admin/secubox/<category>/<module>`
- [ ] First entry uses `"type": "firstchild"`
- [ ] View entries use `"type": "view"` with correct `"path"`
- [ ] Paths match view file locations
- [ ] Proper `"order"` values for menu positioning
- [ ] Depends on correct ACL entry
**ACL JSON Checklist:**
- [ ] Entry name matches package name
- [ ] All read methods listed under `"read"."ubus"`
- [ ] All write methods listed under `"write"."ubus"`
- [ ] ubus object names match RPCD script name
- [ ] UCI config access granted if needed
**CSS Checklist:**
- [ ] Imports `system-hub/common.css`
- [ ] Uses CSS variables (`var(--sh-*)`)
- [ ] Supports dark mode with `[data-theme="dark"]`
- [ ] Responsive grid layouts
- [ ] Smooth transitions and animations
- [ ] JetBrains Mono for numeric values
#### 5. Integrate into Codebase
```bash
# Create module directory structure
mkdir -p luci-app-system-hub/htdocs/luci-static/resources/system-hub
mkdir -p luci-app-system-hub/htdocs/luci-static/resources/view/system-hub
mkdir -p luci-app-system-hub/root/usr/libexec/rpcd
mkdir -p luci-app-system-hub/root/usr/share/luci/menu.d
mkdir -p luci-app-system-hub/root/usr/share/rpcd/acl.d
# Copy generated files to appropriate locations
# (Copy from Claude's output to respective files)
# Set RPCD script as executable
chmod +x luci-app-system-hub/root/usr/libexec/rpcd/luci.system-hub
```
#### 6. Validate Implementation
```bash
# Fix permissions first (CRITICAL)
./secubox-tools/fix-permissions.sh --local
# Run comprehensive validation (7 checks)
./secubox-tools/validate-modules.sh
# Expected output:
# ✅ All checks passed
# OR
# ❌ Errors found with specific fix instructions
```
#### 7. Build Locally
```bash
# Build single module
./secubox-tools/local-build.sh build luci-app-system-hub
# Or build all modules
./secubox-tools/local-build.sh build
# Or full validation + build
./secubox-tools/local-build.sh full
```
#### 8. Deploy to Test Router
```bash
# Transfer package
scp build/x86-64/luci-app-system-hub*.ipk root@192.168.1.1:/tmp/
# Install on router
ssh root@192.168.1.1 << 'EOF'
opkg install /tmp/luci-app-system-hub*.ipk
/etc/init.d/rpcd restart
/etc/init.d/uhttpd restart
EOF
# Fix permissions on deployed router (if needed)
./secubox-tools/fix-permissions.sh --remote
```
#### 9. Test in Browser
1. Navigate to `http://192.168.1.1/cgi-bin/luci`
2. Go to SecuBox → System → System Hub
3. Verify:
- Page loads without errors
- Data displays correctly
- Actions work (buttons, forms)
- Auto-refresh updates data
- Styling matches demo
- Dark mode works
- Responsive design works on mobile
#### 10. Iterate and Refine
If issues found:
1. Check browser console for JavaScript errors
2. Check router logs: `ssh root@192.168.1.1 "logread | tail -50"`
3. Verify RPCD methods work: `ubus call luci.system-hub status`
4. Fix issues in local files
5. Rebuild and redeploy
6. Test again
---
## Common Implementation Patterns
### Pattern 1: Multi-Tab Dashboard
**Example:** System Hub with 9 tabs
```javascript
// In render()
var tabs = [
{ id: 'overview', title: 'Overview', icon: '🏠' },
{ id: 'services', title: 'Services', icon: '⚙️' },
{ id: 'logs', title: 'Logs', icon: '📋' }
];
var activeTab = 'overview';
// Render tab navigation
var tabNav = E('div', { 'class': 'sh-nav-tabs' },
tabs.map(function(tab) {
return E('div', {
'class': 'sh-nav-tab' + (activeTab === tab.id ? ' active' : ''),
'click': function() {
// Switch tab logic
document.querySelectorAll('.sh-nav-tab').forEach(function(t) {
t.classList.remove('active');
});
this.classList.add('active');
// Show/hide tab content
}
}, [
E('span', {}, tab.icon),
E('span', {}, tab.title)
]);
})
);
// Render tab content
var tabContent = E('div', { 'class': 'tab-content' }, [
// Overview tab
E('div', { 'class': 'tab-pane' + (activeTab === 'overview' ? ' active' : ''), 'data-tab': 'overview' }, [
this.renderOverviewContent()
]),
// Services tab
E('div', { 'class': 'tab-pane' + (activeTab === 'services' ? ' active' : ''), 'data-tab': 'services' }, [
this.renderServicesContent()
])
]);
```
### Pattern 2: Filter Tabs with Data Filtering
**Example:** SecuBox module grid with category filtering
```javascript
// Filter tabs
var filterTabs = E('div', { 'class': 'sh-filter-tabs' }, [
E('div', {
'class': 'sh-filter-tab active',
'data-filter': 'all',
'click': function(ev) {
document.querySelectorAll('.sh-filter-tab').forEach(function(t) {
t.classList.remove('active');
});
this.classList.add('active');
self.filterModules('all');
}
}, [
E('span', { 'class': 'sh-tab-icon' }, '📦'),
E('span', { 'class': 'sh-tab-label' }, 'All')
]),
E('div', {
'class': 'sh-filter-tab',
'data-filter': 'security',
'click': function(ev) {
document.querySelectorAll('.sh-filter-tab').forEach(function(t) {
t.classList.remove('active');
});
this.classList.add('active');
self.filterModules('security');
}
}, [
E('span', { 'class': 'sh-tab-icon' }, '🛡️'),
E('span', { 'class': 'sh-tab-label' }, 'Security')
])
]);
// Filter function
filterModules: function(category) {
var modules = document.querySelectorAll('.module-card');
modules.forEach(function(module) {
if (category === 'all' || module.dataset.category === category) {
module.style.display = 'block';
} else {
module.style.display = 'none';
}
});
}
```
### Pattern 3: Real-Time Log Viewer
**Example:** System Hub logs tab
```javascript
// Logs view with auto-scroll and auto-refresh
renderLogsTab: function() {
var self = this;
var autoScroll = true;
var autoRefresh = true;
var refreshInterval = 5; // seconds
var logsContainer = E('div', { 'class': 'logs-container' });
// Load logs
var loadLogs = function() {
API.getLogs(100, '').then(function(result) {
var logs = result.logs || [];
dom.content(logsContainer,
logs.map(function(log) {
return E('div', { 'class': 'log-line' }, log);
})
);
// Auto-scroll to bottom
if (autoScroll) {
logsContainer.scrollTop = logsContainer.scrollHeight;
}
});
};
// Initial load
loadLogs();
// Auto-refresh
if (autoRefresh) {
setInterval(loadLogs, refreshInterval * 1000);
}
return E('div', {}, [
// Controls
E('div', { 'class': 'logs-controls' }, [
E('label', {}, [
E('input', {
'type': 'checkbox',
'checked': autoScroll,
'change': function() { autoScroll = this.checked; }
}),
' Auto-scroll'
]),
E('label', {}, [
E('input', {
'type': 'checkbox',
'checked': autoRefresh,
'change': function() { autoRefresh = this.checked; }
}),
' Auto-refresh'
]),
E('button', {
'class': 'sh-btn sh-btn-primary',
'click': loadLogs
}, '🔄 Refresh Now')
]),
// Logs display
logsContainer
]);
}
```
### Pattern 4: Action Buttons with Confirmation
**Example:** Service management buttons
```javascript
// Render action button with confirmation
renderActionButton: function(service, action, label, btnClass) {
var self = this;
return E('button', {
'class': 'sh-btn ' + btnClass,
'click': function(ev) {
// Show confirmation modal
ui.showModal(_('Confirm Action'), [
E('p', {}, _('Are you sure you want to %s service %s?').format(action, service)),
E('div', { 'class': 'right' }, [
E('button', {
'class': 'sh-btn sh-btn-secondary',
'click': ui.hideModal
}, _('Cancel')),
E('button', {
'class': 'sh-btn sh-btn-primary',
'click': function() {
ui.hideModal();
self.performServiceAction(service, action);
}
}, _('Confirm'))
])
]);
}
}, label);
},
// Perform service action
performServiceAction: function(service, action) {
var self = this;
ui.showModal(_('Performing Action'), [
E('p', {}, E('em', { 'class': 'spinning' }, _('Please wait...')))
]);
API.serviceAction(service, action).then(function(result) {
ui.hideModal();
if (result.success) {
ui.addNotification(null, E('p', _('Action completed successfully')), 'success');
self.handleRefresh();
} else {
ui.addNotification(null, E('p', _('Action failed: %s').format(result.message)), 'error');
}
}).catch(function(error) {
ui.hideModal();
ui.addNotification(null, E('p', _('Error: %s').format(error.message)), 'error');
});
}
```
### Pattern 5: Form with Validation
**Example:** Settings page
```javascript
renderSettingsForm: function() {
var self = this;
var settings = this.settingsData || {};
return E('form', { 'class': 'settings-form' }, [
// Text input
E('div', { 'class': 'form-group' }, [
E('label', {}, 'Hostname'),
E('input', {
'type': 'text',
'class': 'form-control',
'value': settings.hostname || '',
'id': 'input-hostname'
})
]),
// Number input with validation
E('div', { 'class': 'form-group' }, [
E('label', {}, 'Refresh Interval (seconds)'),
E('input', {
'type': 'number',
'class': 'form-control',
'value': settings.refresh_interval || 30,
'min': 10,
'max': 300,
'id': 'input-refresh'
})
]),
// Checkbox
E('div', { 'class': 'form-group' }, [
E('label', {}, [
E('input', {
'type': 'checkbox',
'checked': settings.auto_refresh || false,
'id': 'input-auto-refresh'
}),
' Enable auto-refresh'
])
]),
// Submit button
E('div', { 'class': 'form-actions' }, [
E('button', {
'class': 'sh-btn sh-btn-primary',
'type': 'submit',
'click': function(ev) {
ev.preventDefault();
self.handleSaveSettings();
}
}, 'Save Settings')
])
]);
},
handleSaveSettings: function() {
var hostname = document.getElementById('input-hostname').value;
var refreshInterval = parseInt(document.getElementById('input-refresh').value);
var autoRefresh = document.getElementById('input-auto-refresh').checked;
// Validate
if (!hostname) {
ui.addNotification(null, E('p', _('Hostname is required')), 'error');
return;
}
if (refreshInterval < 10 || refreshInterval > 300) {
ui.addNotification(null, E('p', _('Refresh interval must be between 10 and 300 seconds')), 'error');
return;
}
// Save via API
API.saveSettings(hostname, refreshInterval, autoRefresh).then(function(result) {
if (result.success) {
ui.addNotification(null, E('p', _('Settings saved successfully')), 'success');
} else {
ui.addNotification(null, E('p', _('Failed to save settings: %s').format(result.message)), 'error');
}
});
}
```
---
## Module-Specific Notes
### System Hub (luci-app-system-hub)
- **Complexity:** High - 9 tabs, many features
- **Key Features:** Health monitoring, service management, system logs, backup/restore
- **Special Requirements:** Integration with SecuBox for components list
- **Dependencies:** Calls `luci.secubox` for module enumeration
### WireGuard Dashboard (luci-app-wireguard-dashboard)
- **Complexity:** Medium
- **Key Features:** Peer management, QR code generation, traffic stats
- **Special Requirements:** QR code generation (use qrencode or JavaScript library)
- **Dependencies:** WireGuard tools (`wg` command)
### CrowdSec Dashboard (luci-app-crowdsec-dashboard)
- **Complexity:** Medium
- **Key Features:** Threat intelligence, decisions management, bouncers
- **Special Requirements:** Parse CrowdSec CLI output
- **Dependencies:** CrowdSec (`cscli` command)
### Netdata Dashboard (luci-app-netdata-dashboard)
- **Complexity:** Low - mostly embedding iframe
- **Key Features:** Embedded Netdata UI, quick metrics overview
- **Special Requirements:** Netdata API integration
- **Dependencies:** Netdata service
### Network Modes (luci-app-network-modes)
- **Complexity:** High - UCI manipulation
- **Key Features:** Network topology wizard, configuration preview
- **Special Requirements:** UCI config validation, rollback mechanism
- **Dependencies:** Network, firewall, DHCP configs
---
## Troubleshooting Guide
### Issue: "Object not found" Error
**Symptoms:**
```
RPC call to luci.module-name/method failed with error -32000: Object not found
```
**Diagnosis:**
```bash
# 1. Check RPCD script exists and is executable
ls -la luci-app-module-name/root/usr/libexec/rpcd/
# 2. Check RPCD script name matches ubus object
grep "object:" luci-app-module-name/htdocs/luci-static/resources/module-name/api.js
# 3. Test RPCD script manually
ssh root@router "/usr/libexec/rpcd/luci.module-name list"
# 4. Check RPCD logs
ssh root@router "logread | grep rpcd | tail -20"
```
**Solutions:**
1. Rename RPCD script to match ubus object name (must include `luci.` prefix)
2. Make script executable: `chmod +x luci.module-name`
3. Restart RPCD: `/etc/init.d/rpcd restart`
4. Reinstall package if deployed
### Issue: View Not Loading (404)
**Symptoms:**
```
HTTP error 404 while loading class file '/luci-static/resources/view/module-name/overview.js'
```
**Diagnosis:**
```bash
# 1. Check menu path
cat luci-app-module-name/root/usr/share/luci/menu.d/*.json | grep "path"
# 2. Check view file exists
ls -la luci-app-module-name/htdocs/luci-static/resources/view/
# 3. Verify paths match
# Menu: "path": "module-name/overview"
# File: view/module-name/overview.js
```
**Solutions:**
1. Update menu path to match view file location
2. OR move view files to match menu path
3. Rebuild and redeploy package
### Issue: CSS Not Applied
**Symptoms:**
- Unstyled page
- Missing colors, fonts, or layout
**Diagnosis:**
```bash
# 1. Check browser console for CSS 404 errors
# (Open browser developer tools)
# 2. Verify CSS import in view file
grep "stylesheet" luci-app-module-name/htdocs/luci-static/resources/view/*/overview.js
# 3. Check CSS file exists
ls -la luci-app-module-name/htdocs/luci-static/resources/module-name/dashboard.css
```
**Solutions:**
1. Verify CSS import path: `L.resource('module-name/dashboard.css')`
2. Import common.css: `@import url('../system-hub/common.css');`
3. Check file permissions: `644` for CSS files
4. Clear browser cache (Ctrl+Shift+R)
### Issue: Data Not Updating
**Symptoms:**
- Dashboard shows stale data
- Auto-refresh not working
**Diagnosis:**
```bash
# 1. Check poll is registered
# (Look for poll.add() in render() method)
# 2. Check API calls return Promises
# (Verify methods return results from rpc.declare())
# 3. Test API methods directly
ssh root@router "ubus call luci.module-name status"
```
**Solutions:**
1. Add poll.add() to render() method
2. Verify API calls in poll callback return Promises
3. Ensure updateDashboard() updates correct DOM elements
4. Check browser console for JavaScript errors
---
## Best Practices
### 1. Code Organization
**DO:**
- Keep related code together (API methods, helpers)
- Use descriptive variable and function names
- Add comments for complex logic
- Break large functions into smaller helpers
**DON'T:**
- Put all code in one massive function
- Use single-letter variable names (except in loops)
- Duplicate code - create helper functions instead
- Leave commented-out code in production
### 2. Error Handling
**DO:**
```javascript
API.getData().then(function(result) {
if (result && result.data) {
// Process data
} else {
console.warn('No data returned');
// Show empty state
}
}).catch(function(error) {
console.error('API error:', error);
ui.addNotification(null, E('p', 'Failed to load data'), 'error');
});
```
**DON'T:**
```javascript
API.getData().then(function(result) {
// Process data without checking
result.data.forEach(function(item) { ... }); // Will crash if data is null
});
```
### 3. Performance
**DO:**
- Use poll.add() instead of setInterval for auto-refresh
- Update specific DOM elements instead of full re-render
- Debounce search inputs
- Lazy load data only when needed
**DON'T:**
- Re-render entire view on every update
- Poll too frequently (<10 seconds)
- Load all data upfront
- Perform expensive operations in render()
### 4. User Experience
**DO:**
- Show loading states (spinners, skeleton screens)
- Provide feedback for actions (success/error notifications)
- Confirm destructive actions (delete, restart)
- Use descriptive error messages
**DON'T:**
- Leave users waiting without feedback
- Silent failures
- Generic error messages ("Error occurred")
- Allow destructive actions without confirmation
---
## Deployment Checklist
Before deploying to production:
- [ ] **Code Quality**
- [ ] All validation checks pass
- [ ] No JavaScript errors in console
- [ ] No shell script errors (shellcheck)
- [ ] All JSON files valid (jsonlint)
- [ ] **Functionality**
- [ ] All tabs/pages load correctly
- [ ] All actions work as expected
- [ ] Data displays correctly
- [ ] Auto-refresh updates data
- [ ] Forms validate input
- [ ] Error handling works
- [ ] **Design**
- [ ] Matches live demo visually
- [ ] Dark mode works
- [ ] Responsive on mobile
- [ ] Consistent with other modules
- [ ] No layout issues
- [ ] **Performance**
- [ ] Page loads quickly (<2s)
- [ ] Auto-refresh doesn't freeze UI
- [ ] No memory leaks
- [ ] Efficient data fetching
- [ ] **Security**
- [ ] ACL permissions correct
- [ ] Input validation on frontend and backend
- [ ] No hardcoded credentials
- [ ] Safe command execution (no injection)
- [ ] **Documentation**
- [ ] README.md updated
- [ ] Comments in complex code
- [ ] Menu entries have descriptions
- [ ] ACL entries have descriptions
---
## Additional Resources
### Documentation
- [LuCI API Reference](https://openwrt.github.io/luci/api/)
- [OpenWrt Developer Guide](https://openwrt.org/docs/guide-developer/start)
- [UCI Configuration](https://openwrt.org/docs/guide-user/base-system/uci)
- [ubus Documentation](https://openwrt.org/docs/techref/ubus)
### Live Demo
- **Main Demo:** https://secubox.cybermood.eu
- **System Hub:** https://secubox.cybermood.eu/system-hub
- **CrowdSec:** https://secubox.cybermood.eu/crowdsec
- **WireGuard:** https://secubox.cybermood.eu/wireguard
### Internal Documentation
- [FEATURE-REGENERATION-PROMPTS.md](feature-regeneration-prompts.md) - All module specifications
- [CODE-TEMPLATES.md](code-templates.md) - Implementation templates
- [DEVELOPMENT-GUIDELINES.md](development-guidelines.md) - Complete dev guide
- [QUICK-START.md](quick-start.md) - Quick reference
- [CLAUDE.md](claude.md) - Build system reference
### Tools
- [SecuBox Tools](./secubox-tools/) - Validation, build, deployment scripts
- [GitHub Actions](./.github/workflows/) - CI/CD workflows
- [Templates](./templates/) - Module templates
---
## Getting Help
If you encounter issues not covered in this guide:
1. **Check Existing Modules:** Look at working modules for reference implementations
2. **Run Validation:** `./secubox-tools/validate-modules.sh` for automated checks
3. **Check Logs:** `logread | grep -i error` on the router
4. **Review Documentation:** Read DEVELOPMENT-GUIDELINES.md for detailed explanations
5. **Contact Support:** support@cybermind.fr
---
**Document Version:** 1.0.0
**Last Updated:** 2025-12-27
**Maintainer:** CyberMind.fr
**Live Demo:** https://secubox.cybermood.eu

353
docs/module-status.md Normal file
View File

@ -0,0 +1,353 @@
# SecuBox Modules - Implementation Status
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Active
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Active
**Total Modules:** 15
---
## See Also
- **Feature Regeneration Prompts:** [FEATURE-REGENERATION-PROMPTS.md](feature-regeneration-prompts.md)
- **Implementation Workflow:** [MODULE-IMPLEMENTATION-GUIDE.md](module-implementation-guide.md)
- **Automation Guardrails:** [CODEX.md](codex.md)
## Module Categories
### 1. Core Control (3 modules)
#### luci-app-secubox
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: Central SecuBox hub and dashboard
- **Features**: System overview, module management, quick actions
- **Implementation Date**: Pre-existing
- **Files**: 13 files
#### luci-app-system-hub
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: Central system control dashboard
- **Features**: System info, network config, service management, firewall, backup/restore, diagnostics
- **Implementation Date**: 2025-12-24
- **Files**: 19 files, 2100+ lines of code
- **Views**: 7 (overview, network, services, firewall, backup, diagnostics, logs)
- **Commit**: 34fe2dc - "feat: complete System Hub implementation"
#### luci-app-traffic-shaper
- **Status**: ✅ Implemented (NEW)
- **Version**: 1.0.0
- **Description**: Advanced traffic shaping and QoS control
- **Features**: Traffic classes, classification rules, real-time stats, quick presets
- **Implementation Date**: 2025-12-25
- **Files**: 13 files, 1542 lines of code
- **Views**: 5 (overview, classes, rules, stats, presets)
- **Backend**: TC/CAKE integration with HTB qdisc
- **Presets**: Gaming, Streaming, Work From Home, Balanced
- **Validation**: ✅ All checks passed
---
### 2. Security & Monitoring (2 modules)
#### luci-app-crowdsec-dashboard
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: CrowdSec security monitoring dashboard
- **Features**: Threat detection, ban management, bouncer control
- **Implementation Date**: Pre-existing
- **Files**: Multiple views
#### luci-app-netdata-dashboard
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: System monitoring with Netdata
- **Features**: Real-time metrics, performance graphs, resource monitoring
- **Implementation Date**: Pre-existing
- **Files**: Dashboard integration
---
### 3. Network Intelligence (2 modules)
#### luci-app-netifyd-dashboard
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: Deep packet inspection with Netifyd
- **Features**: Application detection, protocol analysis, flow monitoring
- **Implementation Date**: Pre-existing
- **Files**: Multiple views
#### luci-app-network-modes
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: Network mode configuration
- **Features**: Bridge, router, AP modes, VLAN configuration
- **Implementation Date**: Pre-existing
- **Files**: Configuration management
---
### 4. VPN & Access Control (3 modules)
#### luci-app-wireguard-dashboard
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: WireGuard VPN management
- **Features**: Peer management, tunnel configuration, connection monitoring
- **Implementation Date**: Pre-existing
- **Files**: Multiple views
#### luci-app-client-guardian
- **Status**: ✅ Implemented (with known issue)
- **Version**: 1.0.0
- **Description**: Network Access Control and captive portal
- **Features**: Client authentication, MAC filtering, captive portal
- **Implementation Date**: Pre-existing
- **Known Issues**: Missing captive.js view file (validation error)
- **Files**: Most views present
#### luci-app-auth-guardian
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: Advanced authentication system
- **Features**: Multi-factor auth, session management, OAuth integration
- **Implementation Date**: Pre-existing
- **Files**: 6 views (overview, sessions, vouchers, oauth, splash, bypass)
---
### 5. Bandwidth & Traffic (2 modules)
#### luci-app-bandwidth-manager
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: Bandwidth management with QoS and quotas
- **Features**: Bandwidth rules, usage quotas, traffic monitoring
- **Implementation Date**: Pre-existing
- **Commit**: fa9bb2a - "feat: complete Bandwidth Manager implementation"
- **Files**: 5 views (overview, rules, quotas, usage, settings)
#### luci-app-media-flow
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: Media traffic detection and optimization
- **Features**: Media flow detection, streaming optimization
- **Implementation Date**: Pre-existing
- **Files**: Detection engine
---
### 6. Performance & Services (2 modules)
#### luci-app-cdn-cache
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: CDN proxy cache
- **Features**: Content caching, cache policies, statistics, maintenance
- **Implementation Date**: Pre-existing
- **Files**: 6 views (overview, cache, policies, statistics, maintenance, settings)
#### luci-app-vhost-manager
- **Status**: ✅ Implemented
- **Version**: 1.0.0
- **Description**: Virtual host management
- **Features**: VHost configuration, SSL/TLS management, reverse proxy
- **Implementation Date**: Pre-existing
- **Files**: VHost management interface
---
## Implementation Statistics
### Overall Progress
- **Total Modules**: 15
- **Fully Implemented**: 14
- **With Known Issues**: 1 (client-guardian missing captive.js)
- **Completion Rate**: 93.3%
### Recent Development (Dec 2024 - Dec 2025)
1. **System Hub** (Dec 24, 2025):
- 19 files created
- 2100+ lines of code
- 7 comprehensive views
- Full system control integration
2. **Traffic Shaper** (Dec 25, 2025):
- 13 files created
- 1542 lines of code
- 5 views with CRUD interfaces
- TC/CAKE QoS implementation
- 3 quick presets
### Code Statistics
- **Total Files**: ~200+ across all modules
- **JavaScript Files**: ~80+ view files
- **RPCD Backends**: 15 shell scripts
- **Total Lines of Code**: 15,000+ (estimated)
### Validation Status
| Module | RPCD Match | Menu Paths | JS Syntax | JSON Valid |
|--------|-----------|-----------|-----------|-----------|
| auth-guardian | ✅ | ✅ | ✅ | ✅ |
| bandwidth-manager | ✅ | ✅ | ✅ | ✅ |
| cdn-cache | ✅ | ✅ | ✅ | ✅ |
| client-guardian | ✅ | ❌ | ✅ | ✅ |
| crowdsec-dashboard | ✅ | ✅ | ✅ | ✅ |
| media-flow | ✅ | ✅ | ✅ | ✅ |
| netdata-dashboard | ✅ | ✅ | ✅ | ✅ |
| netifyd-dashboard | ✅ | ✅ | ✅ | ✅ |
| network-modes | ✅ | ✅ | ✅ | ✅ |
| secubox | ✅ | ✅ | ✅ | ✅ |
| system-hub | ✅ | ✅ | ✅ | ✅ |
| traffic-shaper | ✅ | ✅ | ✅ | ✅ |
| vhost-manager | ✅ | ✅ | ✅ | ✅ |
| wireguard-dashboard | ✅ | ✅ | ✅ | ✅ |
---
## Build System Status
### GitHub Actions Workflows
#### 1. build-openwrt-packages.yml
- **Status**: ✅ Operational
- **Purpose**: Build all packages for 13 architectures
- **Architectures**: x86-64, ARM64 (6 variants), ARM32 (4 variants), MIPS (3 variants)
- **Trigger**: Push, PR, tags
- **Output**: .ipk packages per architecture
#### 2. build-secubox-images.yml
- **Status**: ✅ Fixed (Dec 24, 2025)
- **Purpose**: Build complete firmware images
- **Devices**: ESPRESSObin V7/Ultra, MOCHAbin, Sheeva64
- **Fixes Applied**:
- Added image generation flags
- Disabled GDB in toolchain
- Fixed opkg lock file issue
- Added all 15 SecuBox packages
- **Output**: Firmware images (.img.gz, *sysupgrade.bin)
#### 3. test-validate.yml
- **Status**: ✅ Operational
- **Purpose**: Validation and testing
- **Checks**: Makefile structure, JSON syntax, shellcheck, permissions
### Local Build System
#### secubox-tools/local-build.sh
- **Status**: ✅ Enhanced (Dec 24, 2025)
- **Features**:
- Package building (SDK-based)
- Firmware building (full OpenWrt source)
- Validation suite
- Multi-architecture support
- **Commands**:
- `validate` - Check all modules
- `build` - Build packages
- `firmware` - Build firmware images
- `debug-firmware` - Debug configuration
- `full` - Validate + build
- `clean` - Remove artifacts
---
## Known Issues & TODO
### Issues
1. **client-guardian**: Missing `captive.js` view file
- Menu path exists but file not found
- Impact: Captive portal view inaccessible
### Pending Work
1. Fix client-guardian captive.js missing file
2. Test all modules on actual OpenWrt device
3. Create integration tests
4. Performance benchmarking
5. Documentation updates
---
## Version History
### v0.0.5 (2025-12-24)
- Added System Hub module
- Added all 13 packages to firmware builds
- Fixed firmware build workflow
- Enhanced local build script
### v0.0.6 (In Progress)
- Added Traffic Shaper module
- Improved validation tools
- Module status tracking
---
## Architecture Support
### Tier 1 (Full Support)
- **x86-64**: PC, VMs, x86 routers
- **aarch64-cortex-a72**: MOCHAbin, Raspberry Pi 4
- **aarch64-cortex-a53**: ESPRESSObin, Sheeva64
### Tier 2 (Package Support)
- **ARM64**: mediatek-filogic, rockchip-armv8, bcm27xx
- **ARM32**: cortex-a7/a9, ipq40xx, ipq806x
- **MIPS**: 24kc, mipsel variants
---
## Maintenance
### Regular Tasks
- Run `./secubox-tools/validate-modules.sh` before commits
- Update version in Makefile when making changes
- Test on target devices before tagging releases
- Keep CLAUDE.md updated with conventions
### Release Process
1. Validate all modules
2. Update version numbers
3. Build and test locally
4. Create git tag (e.g., `v0.0.6`)
5. Push tag to trigger CI builds
6. Verify GitHub Actions completion
7. Download and test artifacts
---
## Resources
### Documentation
- `CLAUDE.md` - Developer guide and conventions
- `secubox-tools/README.md` - Build system documentation
- Individual module `README.md` files
### Tools
- `secubox-tools/validate-modules.sh` - Module validation
- `secubox-tools/secubox-repair.sh` - Auto-fix common issues
- `secubox-tools/secubox-debug.sh` - Package diagnostics
- `secubox-tools/local-build.sh` - Local build system
### Templates
- `templates/luci-app-template` - Module template
---
## License
All modules: Apache License 2.0
## Maintainer
SecuBox Project <secubox@example.com>
---
*This status file is automatically maintained. Last generated: 2025-12-25*

248
docs/permissions-guide.md Normal file
View File

@ -0,0 +1,248 @@
# OpenWrt Package Permissions Guide
**Version:** 0.3.1
**Last Updated:** 2025-12-28
**Status:** Active
**Author:** CyberMind
> **📚 This is a quick reference guide.**
> For complete deployment procedures, see [DEVELOPMENT-GUIDELINES.md §9](./DEVELOPMENT-GUIDELINES.md#deployment-procedures)
>
> **Related Documentation:**
> - Complete guide: [DEVELOPMENT-GUIDELINES.md](development-guidelines.md)
> - Quick reference: [QUICK-START.md](quick-start.md)
> - Validation tools: [VALIDATION-GUIDE.md](validation-guide.md)
> - Automation briefing: [CODEX.md](codex.md)
---
## See Also
- **Deployment Procedures:** [DEVELOPMENT-GUIDELINES.md §9](./DEVELOPMENT-GUIDELINES.md#deployment-procedures)
- **Quick Rules & Commands:** [QUICK-START.md](quick-start.md)
- **Validation Checklist:** [VALIDATION-GUIDE.md](validation-guide.md)
- **Automation Standards:** [CODEX.md](codex.md)
## 🎯 Objectif
Assurer que tous les fichiers des packages SecuBox ont les **bonnes permissions** dès l'installation, sans nécessiter de correction manuelle.
## 📋 Permissions Requises
### Fichiers Exécutables (755)
Ces fichiers **DOIVENT** avoir les permissions d'exécution:
```
-rwxr-xr-x (755)
```
**Liste des fichiers:**
- `/usr/libexec/rpcd/luci.*` - Scripts RPCD backend
- `/usr/libexec/secubox/*.sh` - Scripts utilitaires
- `/etc/init.d/*` - Scripts d'initialisation
- `/etc/uci-defaults/*` - Scripts de configuration initiale
### Fichiers Non-Exécutables (644)
Ces fichiers **NE DOIVENT PAS** être exécutables:
```
-rw-r--r-- (644)
```
**Liste des fichiers:**
- `/www/luci-static/resources/**/*.js` - Fichiers JavaScript
- `/www/luci-static/resources/**/*.css` - Fichiers CSS
- `/usr/share/rpcd/acl.d/*.json` - Permissions ACL
- `/usr/share/luci/menu.d/*.json` - Définitions de menu
- `/etc/config/*` - Fichiers de configuration UCI
## 🔧 Configuration dans le Makefile
### Méthode Recommandée: PKG_FILE_MODES
OpenWrt supporte la variable `PKG_FILE_MODES` pour définir les permissions des fichiers lors de l'installation du package.
**Syntaxe:**
```makefile
PKG_FILE_MODES:=/path/to/file:permissions
```
**Exemple complet:**
```makefile
include $(TOPDIR)/rules.mk
PKG_NAME:=luci-app-example
PKG_VERSION:=0.3.1
PKG_RELEASE:=1
PKG_LICENSE:=Apache-2.0
PKG_MAINTAINER:=CyberMind <contact@cybermind.fr>
LUCI_TITLE:=LuCI - Example Module
LUCI_DESCRIPTION:=Example SecuBox module
LUCI_DEPENDS:=+luci-base +rpcd
LUCI_PKGARCH:=all
# File permissions (RPCD scripts must be executable)
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.example:755
include $(TOPDIR)/feeds/luci/luci.mk
# call BuildPackage - OpenWrt buildroot signature
```
### Plusieurs Fichiers Exécutables
Si vous avez plusieurs fichiers exécutables:
```makefile
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.example:755 \
/usr/libexec/example/helper.sh:755 \
/etc/init.d/example:755
```
**Note:** Utilisez `\` pour continuer sur la ligne suivante.
## 📦 Modules SecuBox avec PKG_FILE_MODES
### luci-app-secubox
```makefile
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.secubox:755 \
/usr/libexec/secubox/fix-permissions.sh:755
```
### luci-app-system-hub
```makefile
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:755
```
### luci-app-network-modes
```makefile
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.network-modes:755
```
## 🧪 Vérification
### Lors du Développement
Avant de déployer un package, vérifiez les permissions:
```bash
# Vérifier les scripts RPCD
ls -l root/usr/libexec/rpcd/luci.*
# Vérifier les scripts helper
ls -l root/usr/libexec/*/
# Vérifier les fichiers web
find root/www -type f -name "*.js" -o -name "*.css" | xargs ls -l
```
### Après Installation du Package
Vérifiez que les permissions sont correctes sur le routeur:
```bash
# RPCD scripts doivent être 755
ls -l /usr/libexec/rpcd/luci.*
# Fichiers web doivent être 644
ls -l /www/luci-static/resources/secubox/*.js
ls -l /www/luci-static/resources/secubox/*.css
```
## 🛠️ Script de Vérification Automatique
Un script de vérification est inclus dans `luci-app-secubox`:
```bash
# Vérifier et corriger toutes les permissions
/usr/libexec/secubox/fix-permissions.sh
# Via ubus
ubus call luci.secubox fix_permissions
# Via l'interface web
Dashboard → Quick Actions → "🔧 Fix Perms"
```
## ⚠️ Erreurs Communes
### 1. RPCD Script Non-Exécutable
**Symptôme:**
```bash
ubus call luci.example status
# Command failed: Permission denied
```
**Cause:** Le script RPCD n'a pas les permissions 755
**Solution:**
```makefile
# Ajouter dans le Makefile
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.example:755
```
### 2. Fichiers Web Exécutables
**Symptôme:** Fichiers JavaScript/CSS avec permissions 755
**Cause:** Mauvaise manipulation ou script mal configuré
**Solution:** Les fichiers web sont 644 par défaut avec LuCI, pas besoin de les spécifier dans PKG_FILE_MODES
### 3. Script Helper Non-Exécutable
**Symptôme:**
```bash
/usr/libexec/example/helper.sh
# -bash: /usr/libexec/example/helper.sh: Permission denied
```
**Solution:**
```makefile
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.example:755 \
/usr/libexec/example/helper.sh:755
```
## 📚 Références
- **LuCI Build System:** `$(TOPDIR)/feeds/luci/luci.mk`
- **OpenWrt Package Build:** https://openwrt.org/docs/guide-developer/packages
- **PKG_FILE_MODES:** https://openwrt.org/docs/guide-developer/build-system/use-buildsystem#build_system_variables
## ✅ Checklist Pré-Déploiement
Avant de créer un package `.ipk` ou `.apk`:
- [ ] Tous les scripts RPCD ont 755 dans PKG_FILE_MODES
- [ ] Tous les scripts helper ont 755 dans PKG_FILE_MODES
- [ ] Les fichiers web (JS/CSS) ne sont PAS dans PKG_FILE_MODES (ils sont 644 par défaut)
- [ ] Les fichiers ACL/Menu ne sont PAS dans PKG_FILE_MODES (ils sont 644 par défaut)
- [ ] Le Makefile utilise `include $(TOPDIR)/feeds/luci/luci.mk`
- [ ] PKG_FILE_MODES est défini AVANT le `include $(TOPDIR)/feeds/luci/luci.mk`
## 🔄 Migration des Modules Existants
Pour ajouter PKG_FILE_MODES à un module existant:
```bash
cd luci-app-mymodule
# Éditer le Makefile
vi Makefile
# Ajouter avant 'include $(TOPDIR)/feeds/luci/luci.mk'
PKG_FILE_MODES:=/usr/libexec/rpcd/luci.mymodule:755
# Reconstruire le package
make package/luci-app-mymodule/clean
make package/luci-app-mymodule/compile
```
---
**Maintainer:** CyberMind <contact@cybermind.fr>
**License:** Apache-2.0

335
docs/quick-start.md Normal file
View File

@ -0,0 +1,335 @@
# Quick Start Guide - SecuBox Development
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Active
**⚡ Aide-mémoire rapide pour développement**
Pour le guide complet, voir [DEVELOPMENT-GUIDELINES.md](development-guidelines.md)
---
## See Also
- **Complete Guide:** [DEVELOPMENT-GUIDELINES.md](development-guidelines.md)
- **Architecture & Build:** [CLAUDE.md](claude.md)
- **Code Templates:** [CODE-TEMPLATES.md](code-templates.md)
- **Module Prompts:** [FEATURE-REGENERATION-PROMPTS.md](feature-regeneration-prompts.md)
- **Automation Briefing:** [CODEX.md](codex.md)
---
## ⚠️ RÈGLES CRITIQUES (À NE JAMAIS OUBLIER)
### 1. RPCD Script Naming
```bash
# Le nom DOIT correspondre EXACTEMENT à l'objet ubus
JavaScript: object: 'luci.system-hub'
Fichier: root/usr/libexec/rpcd/luci.system-hub ✅
# Sinon: Error -32000 "Object not found"
```
### 2. Menu Path Matching
```json
Menu JSON: "path": "system-hub/overview"
Fichier: view/system-hub/overview.js ✅
# Sinon: HTTP 404 Not Found
```
### 3. Permissions Files
```bash
# RPCD scripts = exécutable
chmod 755 root/usr/libexec/rpcd/luci.*
# CSS/JS = lecture seule
chmod 644 htdocs/**/*.{css,js}
# Sinon: 403 Forbidden ou script non exécuté
```
### 4. Pre-Deployment Checks
```bash
# TOUJOURS vérifier avant déploiement:
# 1. Espace disque (doit être < 90%)
ssh root@192.168.8.191 "df -h | grep overlay"
# 2. Permissions après déploiement
ssh root@192.168.8.191 "find /www/luci-static -name '*.js' -perm 600"
# ⚠️ Si résultats: fichiers ont 600 au lieu de 644 → Erreur 403!
# 3. Correction rapide si nécessaire
ssh root@192.168.8.191 "find /www/luci-static -name '*.css' -exec chmod 644 {} \;"
ssh root@192.168.8.191 "find /www/luci-static -name '*.js' -exec chmod 644 {} \;"
```
### 5. Common Errors Quick Fix
```bash
# HTTP 403 Forbidden (BEST: use automated script)
./secubox-tools/fix-permissions.sh --remote # Auto-fix all permissions
# OR manual fix:
chmod 644 /www/luci-static/resources/**/*.{js,css}
# No space left on device
rm -rf /tmp/*.ipk /tmp/luci-*
find /root -name '*.backup-*' -mtime +7 -delete
# Object not found -32000
chmod 755 /usr/libexec/rpcd/luci.*
ubus list | grep luci.module-name # Vérifier disponibilité
```
---
## 🎨 Design System Essentials
### Color Palette (Dark Mode)
```css
--sh-bg-primary: #0a0a0f; /* Fond principal */
--sh-bg-card: #12121a; /* Cartes */
--sh-border: #2a2a35; /* Bordures */
--sh-primary: #6366f1; /* Indigo */
--sh-primary-end: #8b5cf6; /* Violet */
```
### Fonts
```css
/* Général */
font-family: 'Inter', sans-serif;
/* Valeurs numériques */
font-family: 'JetBrains Mono', monospace;
```
### Component Classes
```css
.sh-page-header /* Page header */
.sh-page-title /* Title (gradient text) */
.sh-stat-badge /* Stat badge (130px min) */
.sh-card /* Card (gradient border on hover) */
.sh-btn-primary /* Button (gradient) */
.sh-filter-tab /* Filter tab */
```
### Grid Sizes
```css
/* Stats */
grid-template-columns: repeat(auto-fit, minmax(130px, 1fr));
/* Metrics */
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
/* Info cards */
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
```
---
## 🔧 Common Commands
### Validation
```bash
# Valider TOUT avant commit (7 checks incluant permissions)
./secubox-tools/validate-modules.sh
# Corriger automatiquement les permissions
./secubox-tools/fix-permissions.sh --local
# JSON
jsonlint file.json
# Shell
shellcheck root/usr/libexec/rpcd/*
```
### Build
```bash
# Build local
./secubox-tools/local-build.sh build luci-app-module-name
# Build OpenWrt SDK
make package/luci-app-module-name/compile V=s
```
### Deploy
```bash
# Copier fichiers
scp file.js root@192.168.8.191:/www/luci-static/resources/
# Fix permissions
ssh root@192.168.8.191 "chmod 644 /www/luci-static/resources/**/*.css"
# Clear cache + restart
ssh root@192.168.8.191 "rm -f /tmp/luci-indexcache /tmp/luci-modulecache/* && /etc/init.d/rpcd restart && /etc/init.d/uhttpd restart"
```
### Debug
```bash
# Test RPCD
ssh root@router "ubus list | grep luci.module"
ssh root@router "ubus call luci.module-name getStatus"
# Check files
ssh root@router "ls -la /www/luci-static/resources/view/module-name/"
# Logs
ssh root@router "logread | grep -i error"
```
---
## 🚨 Common Errors & Quick Fixes
| Error | Quick Fix |
|-------|-----------|
| **-32000 Object not found** | Rename RPCD file to match ubus object |
| **404 View not found** | Fix menu path to match file location |
| **403 Forbidden CSS** | `chmod 644 *.css` |
| **[object HTMLButtonElement]** | Remove array wrapper: `E('div', {}, renderButtons())` |
| **Styles not updating** | Clear browser cache (Ctrl+Shift+R) + mode privé |
---
## 📋 Pre-Commit Checklist
- [ ] `./secubox-tools/fix-permissions.sh --local` ✅ (auto-fix)
- [ ] `./secubox-tools/validate-modules.sh` ✅ (7 checks)
- [ ] RPCD name = ubus object name
- [ ] Menu path = view file path
- [ ] Permissions: 755 (RPCD), 644 (CSS/JS) - auto-verified
- [ ] JSON valide (jsonlint)
- [ ] CSS: variables utilisées (pas hardcode)
- [ ] CSS: dark mode supporté
- [ ] JS: gestion d'erreur sur API calls
- [ ] Version incrémentée (PKG_VERSION)
---
## 📁 File Structure Template
```
luci-app-<module>/
├── Makefile
├── htdocs/luci-static/resources/
│ ├── view/<module>/
│ │ └── overview.js
│ └── <module>/
│ ├── api.js
│ ├── common.css
│ └── overview.css
└── root/
├── usr/libexec/rpcd/
│ └── luci.<module> ⚠️ MUST match ubus object!
└── usr/share/
├── luci/menu.d/
│ └── luci-app-<module>.json
└── rpcd/acl.d/
└── luci-app-<module>.json
```
---
## 🎯 Quick Code Templates
### RPCD Script
```bash
#!/bin/sh
case "$1" in
list)
echo '{"getStatus": {}, "getHealth": {}}'
;;
call)
case "$2" in
getStatus)
printf '{"enabled": true}\n'
;;
esac
;;
esac
```
### View (JavaScript)
```javascript
'use strict';
'require view';
'require <module>/api as API';
return view.extend({
load: function() {
return API.getStatus();
},
render: function(data) {
return E('div', { 'class': 'sh-page-header' }, [
E('h2', { 'class': 'sh-page-title' }, 'Title')
]);
},
handleSaveApply: null,
handleSave: null,
handleReset: null
});
```
### Page Header
```javascript
E('div', { 'class': 'sh-page-header' }, [
E('div', {}, [
E('h2', { 'class': 'sh-page-title' }, [
E('span', { 'class': 'sh-page-title-icon' }, '🎯'),
'Page Title'
]),
E('p', { 'class': 'sh-page-subtitle' }, 'Description')
]),
E('div', { 'class': 'sh-stats-grid' }, [
E('div', { 'class': 'sh-stat-badge' }, [
E('div', { 'class': 'sh-stat-value' }, '92'),
E('div', { 'class': 'sh-stat-label' }, 'Score')
])
])
])
```
### Card with Gradient Border
```javascript
E('div', { 'class': 'sh-card sh-card-success' }, [
E('div', { 'class': 'sh-card-header' }, [
E('h3', { 'class': 'sh-card-title' }, [
E('span', { 'class': 'sh-card-title-icon' }, '⚙️'),
'Card Title'
])
]),
E('div', { 'class': 'sh-card-body' }, [
// Content
])
])
```
---
## 🌐 Test URLs
```
SecuBox Dashboard:
https://192.168.8.191/cgi-bin/luci/admin/secubox
System Hub:
https://192.168.8.191/cgi-bin/luci/admin/secubox/system/system-hub
```
**TOUJOURS tester en mode privé** (Ctrl+Shift+N) après deploy!
---
## 📚 Documentation
- **Guide complet:** [DEVELOPMENT-GUIDELINES.md](development-guidelines.md)
- **Architecture:** [CLAUDE.md](claude.md)
- **Validation:** `./secubox-tools/validate-modules.sh`
- **Démo design:** https://cybermind.fr/apps/system-hub/demo.html
---
**Version:** 1.0.0 | **Date:** 2025-12-26

44
docs/stylesheets/extra.css Normal file
View File

@ -0,0 +1,44 @@
/* SecuBox custom styling */
:root {
--md-primary-fg-color: #6366f1;
--md-accent-fg-color: #8b5cf6;
}
/* Code blocks */
.highlight {
border-radius: 0.375rem;
}
/* Cards grid */
.grid.cards {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
gap: 1rem;
margin: 1.5rem 0;
}
.grid.cards > * {
border: 1px solid var(--md-default-fg-color--lightest);
border-radius: 0.375rem;
padding: 1rem;
transition: transform 0.2s, box-shadow 0.2s;
}
.grid.cards > *:hover {
transform: translateY(-2px);
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}
/* Gradient headings */
h1 {
background: linear-gradient(135deg, #6366f1, #8b5cf6);
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
background-clip: text;
}
/* Admonitions */
.md-typeset .admonition {
border-radius: 0.375rem;
}

1080
docs/todo-analyse.md Normal file
View File

File diff suppressed because it is too large Load Diff

518
docs/validation-guide.md Normal file
View File

@ -0,0 +1,518 @@
# SecuBox Module Validation Guide
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Status:** Active
> **📚 Complete Reference:**
> This is a detailed validation guide. For quick commands, see [QUICK-START.md](quick-start.md)
>
> **Related Documentation:**
> - Complete guide: [DEVELOPMENT-GUIDELINES.md §8](./DEVELOPMENT-GUIDELINES.md#validation-checklist)
> - Pre-commit checklist: [DEVELOPMENT-GUIDELINES.md §8.1](./DEVELOPMENT-GUIDELINES.md#pre-commit-checklist)
> - Post-deploy checklist: [DEVELOPMENT-GUIDELINES.md §8.3](./DEVELOPMENT-GUIDELINES.md#post-deploy-checklist)
> - Permissions guide: [PERMISSIONS-GUIDE.md](permissions-guide.md)
> - Automation briefing: [CODEX.md](codex.md)
---
## See Also
- **Quick Commands:** [QUICK-START.md](quick-start.md)
- **Permissions Reference:** [PERMISSIONS-GUIDE.md](permissions-guide.md)
- **Automation Guardrails:** [CODEX.md](codex.md)
- **Deployment Procedures:** [DEVELOPMENT-GUIDELINES.md §9](./DEVELOPMENT-GUIDELINES.md#deployment-procedures)
This guide explains the validation checks performed on SecuBox modules during generation and before git push.
## Overview
SecuBox uses a multi-layered validation approach:
1. **Module Generation Validation** - Validates newly created/modified modules
2. **Pre-Push Validation** - Blocks git push if critical issues are found
3. **Runtime Validation** - Continuous checks on deployed modules
## Validation Tools
### 1. validate-module-generation.sh
Comprehensive validation for a single module during/after generation.
**Usage:**
```bash
./secubox-tools/validate-module-generation.sh luci-app-cdn-cache
```
**Checks performed:**
- ✅ Makefile completeness and correctness
- ✅ RPCD script naming convention (must use `luci.` prefix)
- ✅ RPCD script executable permissions
- ✅ RPCD script structure (list/call handlers)
- ✅ ACL file JSON validity
- ✅ ACL permissions cover RPCD methods
- ✅ Menu file JSON validity
- ✅ Menu paths match view file locations
- ✅ JavaScript view files exist
- ✅ JavaScript strict mode usage
- ✅ RPC method calls match RPCD methods
- ✅ ubus object names match RPCD script names
- ✅ UCI config validity (if present)
- ✅ Security scan (hardcoded credentials, dangerous commands)
- ✅ Documentation presence
**Exit codes:**
- `0` - All checks passed
- `1` - Critical errors found (module should not be deployed)
### 2. pre-push-validation.sh
Validates all modules before allowing git push.
**Usage:**
```bash
# Automatic (via git hook):
git push # validation runs automatically
# Manual:
./secubox-tools/pre-push-validation.sh
```
**Checks performed:**
- ✅ Git staged changes check
- ✅ RPCD naming conventions across all modules
- ✅ Menu path validation across all modules
- ✅ JSON syntax validation
- ✅ RPCD executable permissions
- ✅ ACL method coverage
- ✅ Makefile validation
- ✅ Security scans
- ✅ Full module validation on modified modules
**Exit codes:**
- `0` - Push allowed
- `1` - Push blocked (critical errors)
### 3. validate-modules.sh
Fast validation of all modules (existing tool).
**Usage:**
```bash
./secubox-tools/validate-modules.sh
```
See `secubox-tools/README.md` for details.
## Installing Git Hooks
To enable automatic validation before git push:
```bash
./secubox-tools/install-git-hooks.sh
```
This creates a symbolic link from `.git/hooks/pre-push` to `secubox-tools/pre-push-validation.sh`.
## Critical Naming Conventions
### 1. RPCD Script MUST Match ubus Object
**Rule:** The RPCD script filename MUST exactly match the ubus object name declared in JavaScript.
**Why:** LuCI's RPC system looks for RPCD scripts by their filename. If the name doesn't match, you get:
- `RPC call failed with error -32000: Object not found`
- `Command failed: Method not found`
**Example:**
```javascript
// JavaScript (htdocs/luci-static/resources/view/cdn-cache/overview.js)
var callStatus = rpc.declare({
object: 'luci.cdn-cache', // ← This must match RPCD filename
method: 'status'
});
```
```bash
# RPCD script filename MUST be:
root/usr/libexec/rpcd/luci.cdn-cache # ← Exactly 'luci.cdn-cache'
```
**Common mistakes:**
- ❌ `root/usr/libexec/rpcd/cdn-cache` (missing `luci.` prefix)
- ❌ `root/usr/libexec/rpcd/luci-cdn-cache` (using dash instead of dot)
- ❌ `root/usr/libexec/rpcd/cdn_cache` (using underscore)
**Validation:**
```bash
# Check naming:
./secubox-tools/validate-module-generation.sh luci-app-cdn-cache
# Look for:
# ✓ RPCD script follows naming convention (luci.* prefix)
# ✓ CRITICAL: RPCD script name matches ACL ubus object
```
### 2. Menu Paths MUST Match View File Locations
**Rule:** Menu JSON `path` entries MUST correspond to actual view file paths.
**Why:** LuCI loads views based on the path in the menu. Wrong path = HTTP 404.
**Example:**
```json
// Menu (root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json)
{
"action": {
"type": "view",
"path": "netifyd-dashboard/overview" // ← Must match file location
}
}
```
```bash
# View file MUST exist at:
htdocs/luci-static/resources/view/netifyd-dashboard/overview.js
# ↑ Same path as menu ↑
```
**Common mistakes:**
- ❌ Menu: `"path": "netifyd/overview"` but file at `view/netifyd-dashboard/overview.js`
- ❌ Menu: `"path": "overview"` but file at `view/netifyd-dashboard/overview.js`
**Validation:**
```bash
# Check paths:
./secubox-tools/validate-module-generation.sh luci-app-netifyd-dashboard
# Look for:
# ✓ Menu path 'netifyd-dashboard/overview' → view file EXISTS
```
### 3. All ubus Objects MUST Use `luci.` Prefix
**Rule:** Every ubus object declaration must start with `luci.`
**Why:** Consistent naming convention for LuCI applications. ACL system expects it.
**Example:**
```javascript
// ✅ Correct:
object: 'luci.cdn-cache'
object: 'luci.system-hub'
object: 'luci.wireguard-dashboard'
// ❌ Wrong:
object: 'cdn-cache' // Missing luci. prefix
object: 'systemhub' // Missing luci. prefix
```
**Validation:**
```bash
# Check convention:
./secubox-tools/validate-modules.sh
# Look for:
# ✓ ubus object 'luci.cdn-cache' follows naming convention
```
## Module Generation Checklist
Use this checklist when generating a new module:
### Phase 1: Initial Generation
- [ ] Create module directory: `luci-app-<module-name>/`
- [ ] Generate Makefile with all required fields
- [ ] Create RPCD script at `root/usr/libexec/rpcd/luci.<module-name>`
- [ ] Make RPCD script executable: `chmod +x`
- [ ] Add shebang to RPCD: `#!/bin/sh`
- [ ] Implement RPCD methods (list, call, status, etc.)
- [ ] Create ACL file with read/write permissions
- [ ] Create menu JSON with correct paths
- [ ] Create view JavaScript files
- [ ] Add `'use strict';` to all JS files
### Phase 2: Validation
- [ ] Run module generation validation:
```bash
./secubox-tools/validate-module-generation.sh luci-app-<module-name>
```
- [ ] Fix all ERRORS (critical)
- [ ] Review all WARNINGS (recommended)
### Phase 3: Integration Validation
- [ ] Verify RPCD script name matches ubus object:
```bash
grep -r "object:" luci-app-<module-name>/htdocs --include="*.js"
ls -la luci-app-<module-name>/root/usr/libexec/rpcd/
# Names must match exactly
```
- [ ] Verify menu paths match view files:
```bash
grep '"path":' luci-app-<module-name>/root/usr/share/luci/menu.d/*.json
ls -R luci-app-<module-name>/htdocs/luci-static/resources/view/
# Paths must align
```
- [ ] Verify ACL permissions cover all RPCD methods:
```bash
grep 'case "$2"' luci-app-<module-name>/root/usr/libexec/rpcd/*
grep -A 20 '"ubus":' luci-app-<module-name>/root/usr/share/rpcd/acl.d/*.json
# All methods should be in ACL
```
### Phase 4: Pre-Commit
- [ ] Run comprehensive validation:
```bash
./secubox-tools/validate-modules.sh
```
- [ ] Review security scan results
- [ ] Check JSON validity:
```bash
find luci-app-<module-name> -name "*.json" -exec python3 -m json.tool {} \; > /dev/null
```
- [ ] Optional: Run shellcheck on RPCD:
```bash
shellcheck luci-app-<module-name>/root/usr/libexec/rpcd/*
```
### Phase 5: Git Commit
- [ ] Stage changes:
```bash
git add luci-app-<module-name>
```
- [ ] Commit with descriptive message:
```bash
git commit -m "feat: implement <module-name> 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>"
```
- [ ] Push (validation runs automatically):
```bash
git push
```
## Common Validation Errors and Fixes
### Error: RPCD script name doesn't match ubus object
```
✗ ERROR: luci-app-cdn-cache: RPCD script 'cdn-cache' does NOT match ubus object 'luci.cdn-cache'
```
**Fix:**
```bash
cd luci-app-cdn-cache/root/usr/libexec/rpcd
mv cdn-cache luci.cdn-cache
```
### Error: Menu path → file NOT FOUND
```
✗ ERROR: luci-app-netifyd: Menu path 'netifyd/overview' → file NOT FOUND
Expected: htdocs/luci-static/resources/view/netifyd/overview.js
```
**Fix Option 1:** Update menu path to match file:
```bash
# Edit root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json
# Change: "path": "netifyd/overview"
# To: "path": "netifyd-dashboard/overview"
```
**Fix Option 2:** Move view file to match menu:
```bash
mv htdocs/luci-static/resources/view/netifyd-dashboard \
htdocs/luci-static/resources/view/netifyd
```
### Error: RPCD script is NOT executable
```
✗ ERROR: luci-app-cdn-cache: luci.cdn-cache is NOT executable
```
**Fix:**
```bash
chmod +x luci-app-cdn-cache/root/usr/libexec/rpcd/luci.cdn-cache
```
### Error: Method 'get_stats' from RPCD not found in ACL
```
⚠ WARNING: luci-app-cdn-cache: Method 'get_stats' from RPCD not in ACL
```
**Fix:**
```bash
# Edit root/usr/share/rpcd/acl.d/luci-app-cdn-cache.json
# Add 'get_stats' to the read.ubus array:
{
"luci-app-cdn-cache": {
"read": {
"ubus": {
"luci.cdn-cache": ["status", "get_config", "get_stats"]
↑ Add here
}
}
}
}
```
### Error: Invalid JSON syntax
```
✗ ERROR: luci-app-cdn-cache: acl.d JSON is INVALID - syntax error
```
**Fix:**
```bash
# Validate JSON:
python3 -m json.tool root/usr/share/rpcd/acl.d/luci-app-cdn-cache.json
# Common issues:
# - Missing comma between array elements
# - Trailing comma after last element
# - Unescaped quotes in strings
```
## Bypassing Validation (NOT RECOMMENDED)
In rare cases, you may need to bypass validation:
```bash
# Skip pre-push validation:
git push --no-verify
# Skip module generation validation:
# (can't bypass - it's informational only)
```
**⚠️ WARNING:** Bypassing validation can lead to broken modules in production!
## Integration with CI/CD
### GitHub Actions
Add validation to your workflow:
```yaml
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
```
## Best Practices
1. **Always validate before committing**
```bash
./secubox-tools/validate-module-generation.sh luci-app-<module>
```
2. **Install git hooks for automatic validation**
```bash
./secubox-tools/install-git-hooks.sh
```
3. **Fix errors immediately** - Don't accumulate validation debt
4. **Review warnings** - They often indicate real issues
5. **Test on OpenWrt** before marking complete:
```bash
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. **Document module-specific requirements** in module README
## Troubleshooting
### Validation script fails to run
```bash
# Make sure scripts are executable:
chmod +x secubox-tools/*.sh
# Check dependencies:
which python3 # For JSON validation
which shellcheck # For shell script validation
```
### Git hook not running
```bash
# Check hook is installed:
ls -la .git/hooks/pre-push
# Reinstall hooks:
./secubox-tools/install-git-hooks.sh
```
### False positives in validation
If validation incorrectly reports an error, please report it:
- Create issue with full validation output
- Include module name and specific check that failed
- We'll update validation logic
## Additional Resources
- [CLAUDE.md](CLAUDE.md) - Main project documentation
- [secubox-tools/README.md](secubox-tools/README.md) - Tools documentation
- [.claude/module-prompts.md](.claude/module-prompts.md) - Module generation prompts
## Support
If you encounter validation issues:
1. Check this guide for common errors
2. Run validation with verbose output
3. Review CLAUDE.md for naming conventions
4. Create issue on GitHub with validation output

115
mkdocs.yml Normal file
View File

@ -0,0 +1,115 @@
site_name: SecuBox Documentation
site_description: OpenWrt LuCI Security & Management Suite
site_author: CyberMind.fr
site_url: https://gkerma.github.io/secubox-openwrt/
repo_name: gkerma/secubox-openwrt
repo_url: https://github.com/gkerma/secubox-openwrt
edit_uri: edit/master/DOCS/
theme:
name: material
palette:
# Light mode
- media: "(prefers-color-scheme: light)"
scheme: default
primary: indigo
accent: purple
toggle:
icon: material/brightness-7
name: Switch to dark mode
# Dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: indigo
accent: purple
toggle:
icon: material/brightness-4
name: Switch to light mode
features:
- navigation.instant
- navigation.tracking
- navigation.tabs
- navigation.tabs.sticky
- navigation.sections
- navigation.expand
- navigation.top
- search.suggest
- search.highlight
- content.code.copy
- content.code.annotate
icon:
repo: fontawesome/brands/github
edit: material/pencil
view: material/eye
font:
text: Inter
code: JetBrains Mono
extra_css:
- stylesheets/extra.css
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/gkerma/secubox-openwrt
- icon: fontawesome/solid/globe
link: https://secubox.cybermood.eu
version:
provider: mike
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
custom_checkbox: true
- admonition
- pymdownx.details
- attr_list
- md_in_html
- tables
- toc:
permalink: true
nav:
- Home: index.md
- Getting Started:
- Quick Start: quick-start.md
- Documentation Index: documentation-index.md
- Development:
- Development Guidelines: development-guidelines.md
- Code Templates: code-templates.md
- Module Implementation: module-implementation-guide.md
- Reference:
- RPCD & Architecture: claude.md
- Validation Guide: validation-guide.md
- Permissions Guide: permissions-guide.md
- LuCI Development: luci-development-reference.md
- Modules:
- Module Status: module-status.md
- Feature Prompts: feature-regeneration-prompts.md
- Tools & Roadmap:
- TODO Roadmap: todo-analyse.md
- Archive:
- Archive Index: archive/index.md
- Build Issues: archive/build-issues.md
- Completion Report: archive/completion-report.md
- Module Enable/Disable: archive/module-enable-disable-design.md

41
scripts/setup-github-pages.sh
View File

@ -19,25 +19,46 @@ fi
echo "📦 Checking dependencies..."
# Check for Python and pip
# Check for Python
if ! command -v python3 &> /dev/null; then
echo "❌ Python 3 is required but not installed."
echo " Install: sudo apt-get install python3 python3-pip"
exit 1
fi
if ! command -v pip3 &> /dev/null; then
echo "❌ pip3 is required but not installed."
echo " Install: sudo apt-get install python3-pip"
echo " Install: sudo apt-get install python3"
exit 1
fi
# Install mkdocs if not present
if ! command -v mkdocs &> /dev/null; then
echo "📥 Installing MkDocs..."
pip3 install mkdocs mkdocs-material pymdown-extensions
# Check if we're on a Debian/Ubuntu system with apt
if command -v apt-get &> /dev/null; then
echo " Using apt package manager (recommended for Debian/Ubuntu)"
echo " Running: sudo apt-get install -y mkdocs mkdocs-material python3-pymdownx"
sudo apt-get update -qq
sudo apt-get install -y mkdocs mkdocs-material python3-pymdownx
else
# Fallback to pip with virtual environment or user install
echo " Using pip3 (fallback method)"
if python3 -m pip --version &> /dev/null; then
# Try user install first (doesn't require sudo, doesn't break system)
python3 -m pip install --user mkdocs mkdocs-material pymdown-extensions
else
echo "❌ Error: pip not available and apt not found."
echo " Please install mkdocs manually:"
echo " - Debian/Ubuntu: sudo apt-get install mkdocs mkdocs-material"
echo " - macOS: brew install mkdocs"
echo " - Other: pip3 install --user mkdocs mkdocs-material"
exit 1
fi
fi
# Verify installation
if ! command -v mkdocs &> /dev/null; then
echo "❌ Error: MkDocs installation failed."
exit 1
fi
else
echo "✅ MkDocs already installed"
echo "✅ MkDocs already installed ($(mkdocs --version | head -1))"
fi
echo ""