CyberMind-FR
6314884f00
- Created help system (help.js, help.css) for all modules - Integrated help button in network-modes module - Fixed menu structure: removed empty Network Management category - Fixed all dashboard and modules page links - Added website deployment script - Created comprehensive documentation New Files: - DOCS/HELP_INTEGRATION_PLAN.md - DOCS/WEBSITE_DEPLOYMENT_GUIDE.md - EXAMPLES/help-button-integration.js - luci-app-secubox/htdocs/luci-static/resources/secubox/help.js - luci-app-secubox/htdocs/luci-static/resources/secubox/help.css - secubox-tools/deploy-website.sh Modified: - luci-app-network-modes: Added help button integration - luci-app-secubox: Fixed menu paths and module links 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
303 lines
14 KiB
Markdown
303 lines
14 KiB
Markdown
# SecuBox Context
|
||
|
||
## What SecuBox OpenWrt Suite Is
|
||
SecuBox is a suite of LuCI applications that ship advanced security, monitoring, and automation dashboards for OpenWrt routers. Each `luci-app-*` package combines LuCI JavaScript views, RPCD backends, UCI integration, ACL policies, and shared CSS built on the SecuBox design system (dark-first palette, Inter + JetBrains Mono). GitHub Actions builds the packages for every supported architecture (`x86`, `ARM`, `MIPS`) and the repo also carries tooling for validation, repair, deployment, and firmware image creation.
|
||
|
||
## Repository Layout
|
||
- `.claude/` – authoritative assistant guidance, prompts, and settings
|
||
- `.github/workflows/` – CI definitions (package build matrix, validation, firmware images)
|
||
- `luci-app-*/` – one directory per LuCI module (Makefile, README, `htdocs/`, `root/`)
|
||
- `secubox-tools/` – validation/build/deploy helpers (`local-build.sh`, `validate-modules.sh`, etc.)
|
||
- `templates/` – scaffolding for new LuCI packages
|
||
- Root docs: `README.md`, `QUICK-START.md`, `DEVELOPMENT-GUIDELINES.md`, `CLAUDE.md`, `DOCUMENTATION-INDEX.md`, `CODE-TEMPLATES.md`, `FEATURE-REGENERATION-PROMPTS.md`, `MODULE_STATUS.md`, `PERMISSIONS-GUIDE.md`, `VALIDATION-GUIDE.md`, etc.
|
||
- Deploy scripts: `deploy-module-template.sh`, `deploy-*.sh` (system hub, secubox, beta releases, etc.)
|
||
- Test fixtures: `test-direct.js`, `test-modules-simple.js`
|
||
|
||
## Module Map (Purpose & Entry Points)
|
||
Each module follows the same structure: `Makefile`, module-specific README, JavaScript views under `htdocs/luci-static/resources/view/<module>/`, API helpers under `htdocs/luci-static/resources/<module>/api.js`, CSS in the same folder, RPCD backend in `root/usr/libexec/rpcd/luci.<module>`, menu JSON under `root/usr/share/luci/menu.d/`, and ACL JSON under `root/usr/share/rpcd/acl.d/`.
|
||
|
||
| Module | Purpose | Primary Views (JS) |
|
||
|--------|---------|--------------------|
|
||
| `luci-app-secubox` | Central SecuBox hub (module launcher, dashboard, dev status) | `secubox/dashboard.js`, `modules.js`, `modules-minimal.js`, `dev-status.js`, `alerts.js`, `monitoring.js`, `settings.js`
|
||
| `luci-app-system-hub` | System control center (health, services, diagnostics, remote) | `system-hub/overview.js`, `health.js`, `services.js`, `components.js`, `logs.js`, `backup.js`, `diagnostics.js`, `remote.js`, `settings.js`, `dev-status.js`
|
||
| `luci-app-crowdsec-dashboard` | CrowdSec decision, alerts, bouncer management | `crowdsec-dashboard/overview.js`, `alerts.js`, `decisions.js`, `bouncers.js`, `metrics.js`, `settings.js`
|
||
| `luci-app-netdata-dashboard` | Netdata monitoring integration | `netdata-dashboard/dashboard.js`, `system.js`, `network.js`, `processes.js`, `realtime.js`, `settings.js`
|
||
| `luci-app-netifyd-dashboard` | DPI / application intelligence | `netifyd-dashboard/overview.js`, `applications.js`, `devices.js`, `flows.js`, `risks.js`, `talkers.js`, `settings.js`
|
||
| `luci-app-network-modes` | Switch router/AP/bridge/sniffer modes | `network-modes/overview.js`, `wizard.js`, `sniffer.js`, `accesspoint.js`, `relay.js`, `router.js`, `settings.js`
|
||
| `luci-app-wireguard-dashboard` | WireGuard VPN monitoring/config | `wireguard-dashboard/overview.js`, `peers.js`, `traffic.js`, `config.js`, `settings.js`, `qrcodes.js`
|
||
| `luci-app-client-guardian` | NAC + captive portal + parental controls | `client-guardian/overview.js`, `clients.js`, `zones.js`, `portal.js`, `captive.js`, `alerts.js`, `parental.js`, `settings.js`, `logs.js`
|
||
| `luci-app-auth-guardian` | Authentication/voucher/OAuth portal | `auth-guardian/overview.js`, `sessions.js`, `vouchers.js`, `oauth.js`, `splash.js`, `bypass.js`
|
||
| `luci-app-bandwidth-manager` | QoS, quotas, priority classes | `bandwidth-manager/overview.js`, `classes.js`, `rules.js`, `schedules.js`, `media.js`, `clients.js`, `usage.js`, `quotas.js`, `settings.js`
|
||
| `luci-app-media-flow` | Streaming/media traffic analytics | `media-flow/dashboard.js`, `services.js`, `clients.js`, `history.js`, `alerts.js`
|
||
| `luci-app-cdn-cache` | Local CDN cache policies & stats | `cdn-cache/overview.js`, `policies.js`, `cache.js`, `statistics.js`, `maintenance.js`, `settings.js`
|
||
| `luci-app-vhost-manager` | Virtual hosts & SSL orchestration | `vhost-manager/overview.js`, `vhosts.js`, `internal.js`, `redirects.js`, `ssl.js`, `certificates.js`, `logs.js`
|
||
| `luci-app-traffic-shaper` | Advanced traffic shaping presets | `traffic-shaper/overview.js`, `classes.js`, `rules.js`, `stats.js`, `presets.js`
|
||
| `luci-app-ksm-manager` | Secure key/certificate management | `ksm-manager/overview.js`, `keys.js`, `secrets.js`, `certificates.js`, `ssh.js`, `hsm.js`, `audit.js`, `settings.js`
|
||
|
||
(Modules not listed explicitly above share the same structure; inspect each `luci-app-*/htdocs/luci-static/resources/view/<module>/` directory for the definitive entrypoints.)
|
||
|
||
## Stack & Integration Points
|
||
- **Frontend**: LuCI JavaScript views (`view.extend`) + SecuBox design system CSS. Every view imports the per-module `api.js` module for ubus calls and includes shared styles like `system-hub/common.css`.
|
||
- **Backend**: RPCD shell scripts under `root/usr/libexec/rpcd/luci.<module>` expose ubus methods (`status`, `get_*`, `set_*`, etc.). Modules often also ship helper scripts under `/usr/libexec/secubox/` and UCI defaults under `root/etc/uci-defaults/`.
|
||
- **UBus / RPC**: JavaScript uses `rpc.declare` with `object: 'luci.<module>'`. RPCD `list` and `call` cases must mirror these names.
|
||
- **Menu/ACL**: JSON files in `root/usr/share/luci/menu.d/` and `root/usr/share/rpcd/acl.d/` keep navigation and permissions consistent with the views and RPCD backend.
|
||
- **Packaging**: OpenWrt LuCI package Makefiles include `luci.mk`, define `PKG_FILE_MODES` for executable scripts (typically RPCD 755), and mark packages as `LUCI_PKGARCH:=all` because they are script-only.
|
||
|
||
## Glossary
|
||
- **LuCI** – OpenWrt web interface framework (Lua backend + JS frontend)
|
||
- **RPCD** – Daemon providing ubus RPC endpoints; modules drop scripts in `/usr/libexec/rpcd/`
|
||
- **ubus** – OpenWrt message bus used for remote procedure calls
|
||
- **UCI** – Unified Configuration Interface (files in `/etc/config/`)
|
||
- **ACL** – RPCD permission JSON files in `/usr/share/rpcd/acl.d/`
|
||
- **PKG_FILE_MODES** – Makefile variable forcing specific permissions for installed files
|
||
- **SecuBox Design System** – Shared CSS variables (`--sh-*`) and components defined in `system-hub/common.css`
|
||
- **Validation suite** – `./secubox-tools/validate-modules.sh`, `validate-module-generation.sh`, `pre-push-validation.sh`
|
||
- **Deploy script** – `deploy-module-template.sh` (backup, copy JS/CSS/RPCD/menu/ACL, fix perms, restart services)
|
||
- **Fix permissions** – Toujours lancer `./secubox-tools/fix-permissions.sh --local` avant commit et `--remote <routeur>` après déploiement pour garantir `644` sur CSS/JS et `755` sur scripts exécutables
|
||
|
||
### ACL File Template
|
||
|
||
```json
|
||
{
|
||
"luci-app-{module-name}": {
|
||
"description": "Grant access to {Module Name}",
|
||
"read": {
|
||
"ubus": {
|
||
"luci.{module-name}": ["status", "get_config", "get_stats"]
|
||
},
|
||
"uci": ["{module_name}"]
|
||
},
|
||
"write": {
|
||
"ubus": {
|
||
"luci.{module-name}": ["set_config", "apply"]
|
||
},
|
||
"uci": ["{module_name}"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Menu File Template
|
||
|
||
```json
|
||
{
|
||
"admin/services/{module_name}": {
|
||
"title": "{Module Title}",
|
||
"order": 50,
|
||
"action": {
|
||
"type": "view",
|
||
"path": "{module_name}/main"
|
||
},
|
||
"depends": {
|
||
"acl": ["luci-app-{module-name}"],
|
||
"uci": {
|
||
"{module_name}": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### View JavaScript Template
|
||
|
||
```javascript
|
||
'use strict';
|
||
'require view';
|
||
'require rpc';
|
||
'require ui';
|
||
'require form';
|
||
'require poll';
|
||
|
||
var callStatus = rpc.declare({
|
||
object: 'luci.{module-name}',
|
||
method: 'status',
|
||
expect: {}
|
||
});
|
||
|
||
var callGetConfig = rpc.declare({
|
||
object: 'luci.{module-name}',
|
||
method: 'get_config',
|
||
expect: {}
|
||
});
|
||
|
||
var callSetConfig = rpc.declare({
|
||
object: 'luci.{module-name}',
|
||
method: 'set_config',
|
||
params: ['config']
|
||
});
|
||
|
||
return view.extend({
|
||
load: function() {
|
||
return Promise.all([
|
||
callStatus(),
|
||
callGetConfig()
|
||
]);
|
||
},
|
||
|
||
render: function(data) {
|
||
var status = data[0] || {};
|
||
var config = data[1] || {};
|
||
|
||
var m, s, o;
|
||
|
||
m = new form.Map('{module_name}', _('Module Title'),
|
||
_('Module description'));
|
||
|
||
// Status section
|
||
s = m.section(form.NamedSection, 'global', 'global', _('Status'));
|
||
s.anonymous = true;
|
||
|
||
o = s.option(form.DummyValue, '_status', _('Status'));
|
||
o.rawhtml = true;
|
||
o.cfgvalue = function() {
|
||
return '<span style="color:' +
|
||
(status.status === 'running' ? 'green' : 'red') +
|
||
'">● ' + (status.status || 'Unknown') + '</span>';
|
||
};
|
||
|
||
// Configuration section
|
||
s = m.section(form.NamedSection, 'global', 'global', _('Configuration'));
|
||
|
||
o = s.option(form.Flag, 'enabled', _('Enabled'));
|
||
o.rmempty = false;
|
||
|
||
return m.render();
|
||
},
|
||
|
||
handleSaveApply: null,
|
||
handleSave: null,
|
||
handleReset: null
|
||
});
|
||
```
|
||
|
||
## 📦 Current Modules Specification
|
||
|
||
### 1. secubox (Hub)
|
||
**Purpose**: Central dashboard aggregating all modules
|
||
**Key Methods**: get_modules_status, get_system_health, get_quick_actions
|
||
**Dependencies**: +luci-base +rpcd +curl +jq
|
||
|
||
### 2. crowdsec-dashboard
|
||
**Purpose**: CrowdSec threat intelligence visualization
|
||
**Key Methods**: get_decisions, get_alerts, get_bouncers, add_decision, delete_decision
|
||
**Dependencies**: +luci-base +rpcd +crowdsec +crowdsec-firewall-bouncer
|
||
|
||
### 3. netdata-dashboard
|
||
**Purpose**: Embedded Netdata monitoring
|
||
**Key Methods**: get_status, get_metrics, restart_service
|
||
**Dependencies**: +luci-base +rpcd +netdata
|
||
|
||
### 4. netifyd-dashboard
|
||
**Purpose**: Deep packet inspection stats
|
||
**Key Methods**: get_flows, get_applications, get_protocols, get_hosts
|
||
**Dependencies**: +luci-base +rpcd +netifyd
|
||
|
||
### 5. wireguard-dashboard
|
||
**Purpose**: WireGuard VPN management with QR codes
|
||
**Key Methods**: list_interfaces, list_peers, add_peer, delete_peer, generate_qr
|
||
**Dependencies**: +luci-base +rpcd +wireguard-tools +qrencode
|
||
|
||
### 6. network-modes
|
||
**Purpose**: Network topology switcher (Router/AP/Bridge/Repeater)
|
||
**Key Methods**: get_current_mode, set_mode, get_available_modes, apply_mode
|
||
**Dependencies**: +luci-base +rpcd
|
||
|
||
### 7. client-guardian
|
||
**Purpose**: Network access control, captive portal
|
||
**Key Methods**: list_clients, authorize_client, block_client, get_sessions, set_policy
|
||
**Dependencies**: +luci-base +rpcd +nodogsplash
|
||
|
||
### 8. system-hub
|
||
**Purpose**: System health and control center
|
||
**Key Methods**: get_system_info, get_services, restart_service, get_logs, backup_config
|
||
**Dependencies**: +luci-base +rpcd
|
||
|
||
### 9. bandwidth-manager
|
||
**Purpose**: QoS, quotas, traffic scheduling
|
||
**Key Methods**: list_rules, add_rule, delete_rule, get_usage, list_quotas, set_quota
|
||
**Dependencies**: +luci-base +rpcd +tc-full +kmod-sched-cake +sqm-scripts
|
||
|
||
### 10. auth-guardian
|
||
**Purpose**: OAuth2 authentication, voucher system
|
||
**Key Methods**: get_providers, set_provider, validate_token, list_vouchers, create_voucher
|
||
**Dependencies**: +luci-base +rpcd +curl +nodogsplash
|
||
|
||
### 11. media-flow
|
||
**Purpose**: Streaming service detection and monitoring
|
||
**Key Methods**: get_active_streams, get_history, get_stats_by_service, get_stats_by_client
|
||
**Dependencies**: +luci-base +rpcd +netifyd
|
||
|
||
### 12. vhost-manager
|
||
**Purpose**: Reverse proxy and SSL certificate management
|
||
**Key Methods**: list_vhosts, add_vhost, delete_vhost, request_cert, list_certs, reload_nginx
|
||
**Dependencies**: +luci-base +rpcd +nginx-ssl +acme
|
||
|
||
### 13. cdn-cache
|
||
**Purpose**: Local content caching
|
||
**Key Methods**: get_status, get_stats, clear_cache, set_rules, get_cached_objects
|
||
**Dependencies**: +luci-base +rpcd +nginx
|
||
|
||
### 14. traffic-shaper
|
||
**Purpose**: Advanced traffic control
|
||
**Key Methods**: list_classes, add_class, set_priority, get_stats, apply_rules
|
||
**Dependencies**: +luci-base +rpcd +tc-full +kmod-sched-cake
|
||
|
||
## 🧪 Testing Commands
|
||
|
||
```bash
|
||
# Test RPCD script locally
|
||
echo '{"method":"list"}' | /usr/libexec/rpcd/{module}
|
||
echo '{"method":"call","params":["status"]}' | /usr/libexec/rpcd/{module}
|
||
|
||
# Test via ubus
|
||
ubus list | grep luci
|
||
ubus call luci.{module} status
|
||
ubus -v list luci.{module}
|
||
|
||
# Validate JSON
|
||
jq . /usr/share/rpcd/acl.d/luci-app-{module}.json
|
||
jq . /usr/share/luci/menu.d/luci-app-{module}.json
|
||
|
||
# Validate JavaScript
|
||
node --check htdocs/luci-static/resources/view/{module}/main.js
|
||
|
||
# Check permissions
|
||
ls -la /usr/libexec/rpcd/{module} # Should be -rwxr-xr-x
|
||
|
||
# Restart RPCD after changes
|
||
/etc/init.d/rpcd restart
|
||
rm -rf /tmp/luci-*
|
||
```
|
||
|
||
## 📝 Important Notes
|
||
|
||
1. **RPCD scripts MUST**:
|
||
- Start with `#!/bin/sh`
|
||
- Source jshn.sh for JSON handling
|
||
- Implement `list` and `call` commands
|
||
- Always call `json_dump` at the end
|
||
- Be executable (chmod +x)
|
||
|
||
2. **Views MUST**:
|
||
- Start with `'use strict';`
|
||
- Use `require('view')` pattern
|
||
- Declare RPC calls with `rpc.declare`
|
||
- Return `view.extend({...})`
|
||
|
||
3. **ACL files MUST**:
|
||
- List ALL RPCD methods
|
||
- Separate read and write permissions
|
||
- Use correct ubus object name (luci.{module-name})
|
||
|
||
4. **Menu files MUST**:
|
||
- Use correct view path ({module_name}/main)
|
||
- Reference correct ACL name
|
||
- Set appropriate order for menu position
|
||
|
||
## 🌐 Links
|
||
|
||
- Website: https://secubox.cybermood.eu
|
||
- Documentation: https://cybermind.fr/docs/secubox
|
||
- GitHub: https://github.com/cybermood-eu/secubox
|
||
- Campaign: https://cybermood.eu (redirects to cybermind.fr/secubox)
|