2026-01-04 19:50:25 +01:00

25 KiB

Raw Blame History

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

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

Feature Specifications - Detailed requirements for all 15 modules
Code Templates - Working implementation examples
Design System - CSS variables, typography, components
Validation Tools - Automated testing and fixing
Deployment Scripts - Local build and remote deployment

Implementation Workflow

Step 1: Choose Your Approach

Option A: Use Claude.ai for Code Generation

Open claude.ai
Copy the relevant module prompt from FEATURE-REGENERATION-PROMPTS.md
Paste the prompt and request implementation
Claude will generate all required files based on the templates
Review and integrate the generated code

Option B: Manual Implementation Using Templates

Copy templates from CODE-TEMPLATES.md
Replace placeholders with module-specific values
Implement module-specific logic
Validate and test

Option C: Hybrid Approach (Recommended)

Use Claude.ai for initial code generation
Refine using templates and guidelines
Validate with automated tools
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:

# 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

# 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

# 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

# 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

# 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

Navigate to http://192.168.1.1/cgi-bin/luci
Go to SecuBox → System → System Hub
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:

Check browser console for JavaScript errors
Check router logs: ssh root@192.168.1.1 "logread | tail -50"
Verify RPCD methods work: ubus call luci.system-hub status
Fix issues in local files
Rebuild and redeploy
Test again

Common Implementation Patterns

Pattern 1: Multi-Tab Dashboard

Example: System Hub with 9 tabs

// 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

// 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

// 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

// 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

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

Available Modes (v0.3.6)

The production build now includes nine fully supported profiles. Each profile exposes its own RPC (*_config), view, and default values under network-modes.<mode>:

Mode ID	Description	Notable Features
`router`	Standard router	NAT + firewall, DHCP, proxy/HTTPS front-end helpers
`doublenat`	Behind ISP CPE	WAN DHCP client, isolated LAN/guest bridge, UPnP/DMZ controls
`multiwan`	Dual uplink	Health checks, failover hold timers, load-balance/mwan3
`vpnrelay`	VPN gateway	WireGuard/OpenVPN, kill switch, DNS override, split tunnel
`bridge`	Layer-2 pass-through	No NAT, all ports bridged, DHCP client
`accesspoint`	WiFi AP	Bridge upstream, disable routing/DHCP, 802.11r/k/v toggles
`relay`	WiFi repeater	STA+AP, relayd/WDS, WireGuard assist, MTU/MSS tuning
`travel`	Portable router	Client WiFi scan, MAC clone, WPA3 hotspot, sandbox LAN
`sniffer`	TAP/sniffer	Promiscuous bridge, Netifyd integration, pcap support

When adding another mode, update: UCI defaults (root/etc/config/network-modes), the RPC script (get_<mode>_config, update_settings, generate_config, set_mode allow-list), the JS API/view/menu, and the docs.

Troubleshooting Guide

Issue: "Object not found" Error

Symptoms:

RPC call to luci.module-name/method failed with error -32000: Object not found

Diagnosis:

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

Rename RPCD script to match ubus object name (must include luci. prefix)
Make script executable: chmod +x luci.module-name
Restart RPCD: /etc/init.d/rpcd restart
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:

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

Update menu path to match view file location
OR move view files to match menu path
Rebuild and redeploy package

Issue: CSS Not Applied

Symptoms:

Unstyled page
Missing colors, fonts, or layout

Diagnosis:

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

Verify CSS import path: L.resource('module-name/dashboard.css')
Import common.css: @import url('../system-hub/common.css');
Check file permissions: 644 for CSS files
Clear browser cache (Ctrl+Shift+R)

Issue: Data Not Updating

Symptoms:

Dashboard shows stale data
Auto-refresh not working

Diagnosis:

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

Add poll.add() to render() method
Verify API calls in poll callback return Promises
Ensure updateDashboard() updates correct DOM elements
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:

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:

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

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 - All module specifications
CODE-TEMPLATES.md - Implementation templates
DEVELOPMENT-GUIDELINES.md - Complete dev guide
QUICK-START.md - Quick reference
CLAUDE.md - Build system reference

Tools

SecuBox Tools - Validation, build, deployment scripts
GitHub Actions - CI/CD workflows
Templates - Module templates

Getting Help

If you encounter issues not covered in this guide:

Check Existing Modules: Look at working modules for reference implementations
Run Validation: ./secubox-tools/validate-modules.sh for automated checks
Check Logs: logread | grep -i error on the router
Review Documentation: Read DEVELOPMENT-GUIDELINES.md for detailed explanations
Contact Support: support@cybermind.fr

Document Version: 1.0.0 Last Updated: 2025-12-27 Maintainer: CyberMind.fr Live Demo: https://secubox.cybermood.eu

25 KiB Raw Blame History

SecuBox Module Implementation Guide

See Also

Quick Navigation

Document Overview

What's Included

Implementation Workflow

Step 1: Choose Your Approach

Step-by-Step: Regenerate a Module with Claude.ai

Example: Regenerating System Hub Module

1. Gather Context

2. Prepare the Prompt

3. Generate Code

4. Review Generated Code

5. Integrate into Codebase

6. Validate Implementation

7. Build Locally

8. Deploy to Test Router

9. Test in Browser

10. Iterate and Refine

Common Implementation Patterns

Pattern 1: Multi-Tab Dashboard

Pattern 2: Filter Tabs with Data Filtering

Pattern 3: Real-Time Log Viewer

Pattern 4: Action Buttons with Confirmation

Pattern 5: Form with Validation

Module-Specific Notes

System Hub (luci-app-system-hub)

WireGuard Dashboard (luci-app-wireguard-dashboard)

CrowdSec Dashboard (luci-app-crowdsec-dashboard)

Netdata Dashboard (luci-app-netdata-dashboard)

Network Modes (luci-app-network-modes)

Available Modes (v0.3.6)

Troubleshooting Guide

Issue: "Object not found" Error

Issue: View Not Loading (404)

Issue: CSS Not Applied

Issue: Data Not Updating

Best Practices

1. Code Organization

2. Error Handling

3. Performance

4. User Experience

Deployment Checklist

Additional Resources

Documentation

Live Demo

Internal Documentation

Tools

Getting Help

25 KiB

Raw Blame History