408 lines
13 KiB
Markdown
408 lines
13 KiB
Markdown
# SecuBox Project Context for Claude AI
|
|
|
|
## 🎯 Project Identity
|
|
|
|
**Name**: SecuBox
|
|
**Type**: Modular security suite for OpenWrt routers
|
|
**Version**: 2.0.0
|
|
**Author**: CyberMind.fr (Gandalf)
|
|
**License**: Apache-2.0
|
|
|
|
## 🏗️ Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ LuCI Web Interface │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
│ │ View.js │ │ View.js │ │ View.js │ │ View.js │ ... │
|
|
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
|
│ │ │ │ │ │
|
|
│ └───────────┴─────┬─────┴───────────┘ │
|
|
│ │ JSON-RPC │
|
|
├─────────────────────────┼───────────────────────────────────┤
|
|
│ RPCD Daemon │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
│ │ Script │ │ Script │ │ Script │ │ Script │ ... │
|
|
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
|
│ │ │ │ │ │
|
|
├───────┼───────────┼───────────┼───────────┼─────────────────┤
|
|
│ │ UCI │ Shell │ System │ │
|
|
│ │ Config │ Commands │ Services │ │
|
|
└───────┴───────────┴───────────┴───────────┴─────────────────┘
|
|
```
|
|
|
|
## 📁 Module Structure Template
|
|
|
|
```
|
|
luci-app-{module-name}/
|
|
├── Makefile # OpenWrt package definition
|
|
├── README.md # Module documentation
|
|
├── htdocs/
|
|
│ └── luci-static/
|
|
│ └── resources/
|
|
│ └── view/
|
|
│ └── {module_name}/ # Underscore version
|
|
│ ├── main.js # Main view
|
|
│ └── {subview}.js # Optional subviews
|
|
└── root/
|
|
├── etc/
|
|
│ ├── config/
|
|
│ │ └── {module_name} # UCI configuration
|
|
│ ├── init.d/
|
|
│ │ └── {module_name} # Service init script (optional)
|
|
│ └── uci-defaults/
|
|
│ └── 99-{module_name} # First-run setup
|
|
└── usr/
|
|
├── libexec/
|
|
│ └── rpcd/
|
|
│ └── {module-name} # Hyphen version - RPCD backend
|
|
└── share/
|
|
├── luci/
|
|
│ └── menu.d/
|
|
│ └── luci-app-{module-name}.json
|
|
└── rpcd/
|
|
└── acl.d/
|
|
└── luci-app-{module-name}.json
|
|
```
|
|
|
|
## 📋 Naming Conventions
|
|
|
|
| Context | Format | Example |
|
|
|---------|--------|---------|
|
|
| Package name | luci-app-{module-name} | luci-app-vhost-manager |
|
|
| RPCD script | {module-name} | vhost-manager |
|
|
| UCI config | {module_name} | vhost_manager |
|
|
| View path | {module_name}/ | vhost_manager/ |
|
|
| ubus object | luci.{module-name} | luci.vhost-manager |
|
|
| Menu path | admin/services/{module_name} | admin/services/vhost_manager |
|
|
|
|
## 🔧 Code Standards
|
|
|
|
### Makefile Template
|
|
|
|
```makefile
|
|
include $(TOPDIR)/rules.mk
|
|
|
|
PKG_NAME:=luci-app-{module-name}
|
|
PKG_VERSION:=2.0.0
|
|
PKG_RELEASE:=1
|
|
PKG_LICENSE:=Apache-2.0
|
|
PKG_MAINTAINER:=CyberMind <contact@cybermind.fr>
|
|
|
|
LUCI_TITLE:=LuCI - {Module Title}
|
|
LUCI_DESCRIPTION:={Description}
|
|
LUCI_DEPENDS:=+luci-base +rpcd {+other-deps}
|
|
LUCI_PKGARCH:=all
|
|
|
|
include $(TOPDIR)/feeds/luci/luci.mk
|
|
```
|
|
|
|
### RPCD Script Template
|
|
|
|
```sh
|
|
#!/bin/sh
|
|
# RPCD backend for {module-name}
|
|
|
|
. /lib/functions.sh
|
|
. /usr/share/libubox/jshn.sh
|
|
|
|
json_init
|
|
|
|
case "$1" in
|
|
list)
|
|
# MUST list all available methods
|
|
json_add_object "status"
|
|
json_close_object
|
|
json_add_object "get_config"
|
|
json_close_object
|
|
json_add_object "set_config"
|
|
json_add_string "config" "object"
|
|
json_close_object
|
|
# Add more methods here
|
|
json_dump
|
|
;;
|
|
|
|
call)
|
|
case "$2" in
|
|
status)
|
|
# MUST implement status method
|
|
json_add_string "module" "{module-name}"
|
|
json_add_string "version" "2.0.0"
|
|
json_add_boolean "enabled" 1
|
|
json_add_string "status" "running"
|
|
json_dump
|
|
;;
|
|
|
|
get_config)
|
|
# Read from UCI
|
|
json_add_object "config"
|
|
# config_load "{module_name}"
|
|
json_close_object
|
|
json_dump
|
|
;;
|
|
|
|
set_config)
|
|
read -r input
|
|
json_load "$input"
|
|
# Apply to UCI
|
|
json_init
|
|
json_add_boolean "success" 1
|
|
json_dump
|
|
;;
|
|
|
|
*)
|
|
json_add_int "error" -32601
|
|
json_add_string "message" "Method not found"
|
|
json_dump
|
|
;;
|
|
esac
|
|
;;
|
|
esac
|
|
```
|
|
|
|
### 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)
|