CyberMind-FR ce543762cc chore: Update GitHub repo URL to CyberMind-FR organization

Replace github.com/gkerma/secubox-openwrt with
github.com/CyberMind-FR/secubox-openwrt across all files.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-14 09:44:01 +01:00

11 KiB

Raw Permalink Blame History

SecuBox Core Framework

Version: 0.8.0 License: GPL-2.0 Category: Administration

Overview

SecuBox Core is the foundational framework for the modular SecuBox system. It provides a unified infrastructure for managing OpenWrt-based security appliances through a plugin-based architecture.

Features

Core Capabilities

Modular AppStore: Plugin-based module discovery, installation, and management
Profile System: Declarative configuration profiles, templates, and macros
Unified CLI: Single secubox command for all operations
Health Monitoring: Comprehensive diagnostics and health checks
Recovery System: Automatic snapshots, rollback, and disaster recovery
ubus Integration: Full RPC API for LuCI and third-party integration

Architecture

secubox-core
├── Core Services
│   ├── secubox-core daemon (procd)
│   ├── ubus RPC interface
│   └── Health monitoring
│
├── Module Management
│   ├── AppStore catalog
│   ├── Module discovery
│   ├── Dependency resolution
│   └── Lifecycle hooks
│
├── Configuration
│   ├── Profile engine
│   ├── Template rendering
│   └── Macro execution
│
└── Operations
    ├── Diagnostics
    ├── Snapshot/recovery
    └── Verification

Installation

From Package

opkg update
opkg install secubox-core

From Source

# In OpenWrt buildroot
make package/secubox/secubox-core/compile
make package/secubox/secubox-core/install

Quick Start

1. Check System Status

secubox device status

Output:

Version: 0.8.0
Uptime: 1 day, 3:42
CPU Load: 0.45
Memory: 45%
Storage: 12%
WAN: 192.0.2.1 (eth0)
LAN: 192.168.1.1

2. Browse Available Modules

secubox app list

3. Install a Module

secubox app install wireguard-vpn

4. Run Health Check

secubox diag health

CLI Reference

Main Commands

secubox <command> [subcommand] [options]

Command	Description
`app`	Manage modules and AppStore
`profile`	Manage profiles and templates
`device`	Device information and management
`net`	Network management
`diag`	Diagnostics and health checks
`ai`	AI copilot (optional, experimental)

App Commands

secubox app list                 # List all modules
secubox app search <query>       # Search for modules
secubox app info <module>        # Show module details
secubox app install <module>     # Install a module
secubox app remove <module>      # Remove a module
secubox app update [module]      # Update module(s)
secubox app health               # Check module health

Profile Commands

secubox profile list                  # List available profiles
secubox profile show <profile>        # Show profile details
secubox profile apply <profile>       # Apply a profile
secubox profile validate <profile>    # Validate profile syntax
secubox profile export [file]         # Export current config

Device Commands

secubox device info           # Show device information
secubox device status         # Show system status
secubox device reboot         # Reboot device
secubox device factory-reset  # Factory reset
secubox device backup [file]  # Backup configuration

Diagnostics Commands

secubox diag health           # Run health check
secubox diag logs [service]   # View system logs
secubox diag trace <target>   # Network trace
secubox diag report           # Generate diagnostic report

Configuration

UCI Configuration

File: /etc/config/secubox

config core 'main'
    option enabled '1'
    option log_level 'info'
    option appstore_url 'https://repo.secubox.org/catalog'
    option health_check_interval '300'
    option ai_enabled '0'

config security 'enforcement'
    option sandboxing '1'
    option module_signature_check '0'
    option auto_update_check '1'

config diagnostics 'settings'
    option health_threshold_cpu '80'
    option health_threshold_memory '90'
    option health_threshold_storage '85'

Directories

Path	Purpose
`/etc/config/secubox`	UCI configuration
`/etc/secubox/profiles/`	Profile definitions
`/etc/secubox/templates/`	Configuration templates
`/etc/secubox/macros/`	Reusable macros
`/usr/share/secubox/plugins/catalog/`	Module catalog
`/usr/share/secubox/modules/`	Module metadata
`/var/run/secubox/`	Runtime state
`/var/log/secubox/`	Log files
`/overlay/secubox-backups/`	Configuration snapshots

Module System

Module Catalog

Modules are discovered through catalog entries in JSON format:

Location: /usr/share/secubox/plugins/catalog/<module-id>.json

Example:

{
  "id": "wireguard-vpn",
  "name": "WireGuard VPN Manager",
  "version": "1.0.0",
  "category": "networking",
  "runtime": "native",
  "packages": {
    "required": ["luci-app-wireguard-vpn", "wireguard-tools"]
  },
  "capabilities": ["vpn-server", "vpn-client"],
  "requirements": {
    "min_ram_mb": 64,
    "min_storage_mb": 10
  }
}

Module Lifecycle

Discovery: Catalog scanned for available modules
Validation: Manifest and dependencies checked
Pre-install: Pre-install hooks executed
Installation: opkg packages installed
Post-install: Post-install configuration
Health Check: Module health verified

Hooks

Modules can define lifecycle hooks:

pre_install: Run before installation
post_install: Run after installation
pre_remove: Run before removal
post_remove: Run after removal

Profile System

Profile Structure

Profiles are declarative YAML/JSON configurations:

profile:
  id: home-office
  name: "Home Office Network"

modules:
  required:
    - wireguard-vpn
    - dns-filter
    - bandwidth-manager

uci_overrides:
  network:
    lan:
      ipaddr: "192.168.10.1"
      netmask: "255.255.255.0"

Applying Profiles

# Dry-run first
secubox profile apply home-office --dryrun

# Apply profile
secubox profile apply home-office

Recovery and Snapshots

Automatic Snapshots

Snapshots are automatically created:

Before profile application
Before module installation
On first boot

Manual Snapshots

# Create snapshot
secubox-recovery snapshot "my-snapshot"

# List snapshots
secubox-recovery list

# Restore from snapshot
secubox-recovery restore my-snapshot

Recovery Mode

secubox-recovery enter

ubus API

Available Objects

ubus list luci.secubox

Objects:

luci.secubox - Core operations
luci.secubox.appstore - Module management (legacy, use luci.secubox)
luci.secubox.profile - Profile management (legacy, use luci.secubox)
luci.secubox.diagnostics - Health checks (legacy, use luci.secubox)

Example Usage

# Get system status
ubus call luci.secubox getStatus

# List modules
ubus call luci.secubox getModules

# Install module
ubus call luci.secubox installModule '{"module":"wireguard-vpn"}'

# Run diagnostics
ubus call luci.secubox runDiagnostics '{"target":"all"}'

Health Monitoring

Health Checks

The system monitors:

CPU load
Memory usage
Storage capacity
Network connectivity
Module status
Service health

Thresholds

Configure in /etc/config/secubox:

config diagnostics 'settings'
    option health_threshold_cpu '80'
    option health_threshold_memory '90'
    option health_threshold_storage '85'

Automated Checks

Health checks run automatically every 5 minutes (configurable):

uci set secubox.main.health_check_interval='300'
uci commit secubox

Security

Module Verification

Enable signature verification:

uci set secubox.enforcement.module_signature_check='1'
uci commit secubox

Sandboxing

Modules run with resource limits (when supported by kernel):

procd_set_param cgroup.memory.limit_in_bytes 134217728  # 128 MB

ACL Integration

All ubus methods are protected by LuCI ACL system.

Troubleshooting

Check Service Status

/etc/init.d/secubox-core status

View Logs

logread | grep secubox

tail -f /var/log/secubox/core.log

Restart Service

/etc/init.d/secubox-core restart

Reset to Defaults

uci revert secubox
/etc/init.d/secubox-core restart

Recovery

If system becomes unresponsive:

secubox-recovery enter

Development

Adding New Modules

Create module catalog entry:

/usr/share/secubox/plugins/catalog/my-module.json

Define manifest with required fields:
- id, name, version
- category, runtime
- packages, capabilities
(Optional) Add lifecycle hooks
Test installation:
```
secubox app install my-module
```

Custom Profiles

Create profile YAML/JSON in /etc/secubox/profiles/
Validate:
```
secubox profile validate my-profile
```

Test with dry-run:

secubox profile apply my-profile --dryrun

Apply:
```
secubox profile apply my-profile
```

Dependencies

Required:

libubox
libubus
libuci
rpcd
bash
coreutils-base64
jsonfilter

Optional:

python3 (for YAML profile support)
signify-openbsd or openssl (for signature verification)

Files

Executables

/usr/sbin/secubox - Main CLI entrypoint
/usr/sbin/secubox-core - Core daemon
/usr/sbin/secubox-appstore - AppStore manager
/usr/sbin/secubox-profile - Profile engine
/usr/sbin/secubox-diagnostics - Diagnostics system
/usr/sbin/secubox-recovery - Recovery tools
/usr/sbin/secubox-verify - Verification tools

RPCD Scripts

/usr/libexec/rpcd/luci.secubox - Main ubus interface

Init Scripts

/etc/init.d/secubox-core - procd service
/etc/uci-defaults/99-secubox-firstboot - First-boot provisioning

License

GPL-2.0

Support

Documentation: https://docs.secubox.org
Issues: https://github.com/CyberMind-FR/secubox-openwrt/issues
Community: https://forum.secubox.org

Version History

0.8.0 (Current)

Initial framework implementation
Core module system
Profile engine
Health monitoring
Recovery system
CLI interface
ubus API

11 KiB Raw Permalink Blame History