secubox-openwrt/.claude/context.md

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

{
    "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

{
    "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

'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

# 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)