diff --git a/package/secubox/secubox-console/README.md b/package/secubox/secubox-console/README.md index bfd9b144..f14631d3 100644 --- a/package/secubox/secubox-console/README.md +++ b/package/secubox/secubox-console/README.md @@ -1,87 +1,373 @@ -# SecuBox Console & Frontend +# SecuBox Console & CLI Tools Reference **Remote Management Point for SecuBox Devices** -Two applications for centralized management of multiple SecuBox devices: - -1. **secubox-console** - CLI-focused management tool -2. **secubox-frontend** - Modern TUI dashboard with Textual - KISS modular self-enhancing architecture. -## Features +## Overview -- **Device Discovery** - Automatic network scanning for SecuBox nodes -- **Multi-Device Management** - Manage multiple SecuBox devices from one console -- **Remote Commands** - Execute commands on any device via SSH -- **Mesh Integration** - P2P mesh sync and catalog management -- **Snapshot Orchestration** - Trigger and manage backups across devices -- **Live Dashboard** - Real-time TUI with device status -- **Plugin System** - Extend functionality with custom plugins -- **Self-Updating** - Auto-update from mesh network +Two applications for centralized management of multiple SecuBox devices: -## Installation +1. **secubox-console** - CLI-focused management tool (OpenWrt native) +2. **secubox-frontend** - Modern TUI dashboard with Textual (Linux/PC) + +## Quick Install ### On SecuBox (OpenWrt) ```bash opkg install secubox-console ``` -### On Any PC (Python) +### On Any Linux PC ```bash -# Clone or copy secubox_console.py -pip install paramiko rich httpx - -# Run -python3 secubox_console.py +pip install textual paramiko httpx rich +python3 secubox_frontend.py ``` -## Usage - -### Interactive Dashboard +### One-Line Installer ```bash -secubox-console +curl -sL https://feed.maegia.tv/install-console.sh | bash ``` -### Commands +--- + +## SecuBox CLI Tools Lexical + +Complete reference of all `secubox-*` command-line tools. + +### Core System Tools + +#### secubox-core +Primary SecuBox control center CLI. ```bash -# Device Management -secubox-console discover # Scan network for devices -secubox-console add mybox 192.168.1.1 -secubox-console remove mybox -secubox-console list - -# Status & Monitoring -secubox-console status # All devices -secubox-console status mybox # Specific device - -# Remote Execution -secubox-console connect mybox # SSH shell -secubox-console exec mybox "uptime" -secubox-console mybox "df -h" # Shortcut - -# Backup & Recovery -secubox-console snapshot mybox -secubox-console sync # Sync all mesh nodes - -# System -secubox-console plugins # List plugins -secubox-console update # Self-update from mesh -secubox-console help +secubox-core status # Deployment status and service health +secubox-core info # System and SecuBox information +secubox-core config # Manage configuration settings +secubox-core services # List installed services +secubox-core version # Version information ``` -### Dashboard Keys +#### secubox-swiss +Multi-purpose Swiss Army knife utility. +```bash +secubox-swiss # Interactive menu +secubox-swiss mesh # Mesh operations +secubox-swiss recover # Recovery tools +secubox-swiss console # Remote console +secubox-swiss mitm # MITM proxy logs +``` + +#### secubox-state +System state management and persistence. +```bash +secubox-state get # Query state +secubox-state set # Update state +secubox-state list # List all state +``` + +#### secubox-component +Component lifecycle management. +```bash +secubox-component list # List components +secubox-component status # Component status +secubox-component update # Update components +``` + +--- + +### Recovery & Backup + +#### secubox-recover +Full backup/restore system with profiles and snapshots. +```bash +secubox-recover snapshot [name] # Create snapshot +secubox-recover list # List snapshots +secubox-recover restore # Restore snapshot +secubox-recover profile save # Save profile +secubox-recover profile apply # Apply profile +secubox-recover apps sync # Sync app configs +secubox-recover reborn # Generate reborn script +``` + +#### secubox-recovery +Configuration backup and rollback. +```bash +secubox-recovery snapshot [name] # Create config snapshot +secubox-recovery list [--json] # List snapshots +secubox-recovery restore # Restore from snapshot +secubox-recovery rollback # Rollback to latest +secubox-recovery enter # Interactive recovery mode +``` + +#### secubox-restore +Self-recovery bootstrap from Gitea. +```bash +secubox-restore --interactive +secubox-restore [token] +secubox-restore --branch dev --include-network +``` + +--- + +### Mesh & P2P Networking + +#### secubox-mesh +P2P mesh networking configuration. +```bash +secubox-mesh status # Mesh status +secubox-mesh peers # List peers +secubox-mesh sync # Sync catalogs +secubox-mesh discover # Discover peers +``` + +#### secubox-p2p +P2P Hub Manager for peer discovery and federation. +```bash +secubox-p2p daemon # Run discovery daemon +secubox-p2p discover [timeout] # mDNS peer discovery +secubox-p2p peers # List known peers +secubox-p2p add-peer [name]# Add peer manually +secubox-p2p remove-peer # Remove peer +secubox-p2p services # List local services +secubox-p2p shared-services # Aggregate from peers +secubox-p2p sync # Sync service catalog +secubox-p2p broadcast # Execute on all peers +secubox-p2p settings # Show P2P config +``` + +#### secubox-sync-registry +Service registry synchronization across mesh. +```bash +secubox-sync-registry sync # Sync with peers +secubox-sync-registry status # Sync status +``` + +#### secubox-catalog-sync +Application catalog synchronization. +```bash +secubox-catalog-sync update # Sync catalog +secubox-catalog-sync list # List catalog +``` + +--- + +### Service Registry & Exposure + +#### secubox-registry +Unified service management with HAProxy/Tor integration. +```bash +secubox-registry list # List published services +secubox-registry show # Service details +secubox-registry publish --domain example.com --tor +secubox-registry unpublish # Remove from registry +secubox-registry landing # Landing page status +secubox-registry categories # List categories +``` + +#### secubox-landing-gen +Multi-theme landing page generator. +```bash +secubox-landing-gen # Generate with default theme +secubox-landing-gen --theme cyberpunk # Neon synthwave +secubox-landing-gen --theme terminal # Green terminal +secubox-landing-gen --theme minimal # Clean flat design +secubox-landing-gen --theme light # Bright professional +``` + +#### secubox-exposure +Port management, Tor hidden services, HAProxy backends. +```bash +secubox-exposure scan # Discover listening ports +secubox-exposure conflicts # Identify port conflicts +secubox-exposure fix-port # Auto-assign free port +secubox-exposure status # Exposure status +secubox-exposure tor add # Add Tor hidden service +secubox-exposure tor list # List .onion addresses +secubox-exposure ssl add # Add HAProxy SSL backend +``` + +#### secubox-wan-access +External WAN access configuration. +```bash +secubox-wan-access enable # Enable remote access +secubox-wan-access disable # Disable remote access +secubox-wan-access status # Current status +``` + +--- + +### Application Management + +#### secubox-app +Apps CLI for plugin manifests and installations. +```bash +secubox-app list # Show all plugins +secubox-app show # Plugin manifest details +secubox-app install # Install with dependencies +secubox-app remove # Uninstall plugin +secubox-app status # Plugin status +secubox-app update # Update to latest +secubox-app validate # Validate all manifests +``` + +#### secubox-appstore +Application package discovery and management. +```bash +secubox-appstore list # Available applications +secubox-appstore search # Search apps +secubox-appstore install # Install application +secubox-appstore info # App details +``` + +#### secubox-skill +Skills/Plugins management system. +```bash +secubox-skill list # List skills +secubox-skill enable # Enable skill +secubox-skill disable # Disable skill +secubox-skill install # Install skill +``` + +#### secubox-profile +User and role profile management. +```bash +secubox-profile list # List profiles +secubox-profile create # Create profile +secubox-profile apply # Apply profile +secubox-profile export # Export profile +``` + +--- + +### Package Feed Management + +#### secubox-feed +Local and remote package feed manager. +```bash +secubox-feed update # Regenerate Packages index +secubox-feed sync # Sync to opkg-lists +secubox-feed fetch # Download IPK from URL +secubox-feed fetch-release

# Fetch from GitHub/Gitea +secubox-feed list # List packages in feed +secubox-feed info # Package metadata +secubox-feed install # Install from feed +secubox-feed install all # Install all packages +secubox-feed clean # Remove old versions +secubox-feed serve [port] # Show feed URL config +``` + +#### secubox-feed-health +Feed health monitoring for HAProxy. +```bash +secubox-feed-health # JSON health status +secubox-feed-health simple # Single word status +secubox-feed-health nagios # Nagios-compatible format +``` + +#### secubox-feed-manager +Package feed management and distribution. +```bash +secubox-feed-manager create # Create feed +secubox-feed-manager publish # Publish packages +secubox-feed-manager sync # Sync with remote +``` + +--- + +### Diagnostics & Monitoring + +#### secubox-diagnostics +Comprehensive system diagnostics. +```bash +secubox-diagnostics health # Health checks +secubox-diagnostics report # Diagnostic report +secubox-diagnostics logs # Collect logs +secubox-diagnostics performance # Resource usage +secubox-diagnostics network # Network diagnostics +``` + +#### secubox-log +Central log aggregation tool. +```bash +secubox-log --message "Event occurred" +secubox-log --tag security --message "Alert" +secubox-log --payload '{"key":"value"}' +secubox-log --snapshot # System diagnostic snapshot +secubox-log --tail 50 # Last 50 lines +``` + +#### secubox-stats +Quick security stats overview. +```bash +secubox-stats # JSON security statistics +``` + +#### secubox-verify +Configuration and package integrity verification. +```bash +secubox-verify config # Verify configs +secubox-verify packages # Check signatures +secubox-verify system # System consistency +``` + +--- + +### Specialized Tools + +#### secubox-webapp-setup +Dashboard configuration utility. +```bash +secubox-webapp-setup status # Dashboard config +secubox-webapp-setup enable # Enable CORS/ubus +secubox-webapp-setup disable # Disable access +secubox-webapp-setup check # Verify dependencies +``` + +#### secubox-netifyd-configure +Netifyd configuration helper. +```bash +secubox-netifyd-configure # Interactive setup +``` + +#### secubox-mitm-logs +MITM proxy analytics viewer. +```bash +secubox-mitm-logs # View analytics +secubox-mitm-logs --tail 100 # Last 100 entries +secubox-mitm-logs --country # By country +secubox-mitm-logs --scans # Scan attempts +``` + +#### secubox-feedback +Feedback collection and telemetry. +```bash +secubox-feedback send "message" # Send feedback +secubox-feedback status # Telemetry status +``` + +--- + +## Frontend TUI Application + +### Features +- Multi-device dashboard with real-time status +- Device discovery (network scan, mDNS, mesh API) +- SSH-based remote command execution +- Backup orchestration across devices +- Tabbed interface: Dashboard, Alerts, Mesh, Settings +- Graceful degradation: Textual -> Rich -> Simple CLI + +### Keyboard Shortcuts | Key | Action | |-----|--------| | `q` | Quit | | `r` | Refresh status | | `s` | Sync all devices | | `d` | Run discovery | +| `b` | Backup selected | +| `Tab` | Switch tabs | -## Configuration - -Config files stored in `~/.secubox-console/`: - +### Configuration ``` ~/.secubox-console/ ├── devices.json # Saved devices @@ -106,13 +392,51 @@ Config files stored in `~/.secubox-console/`: } ``` +--- + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ SecuBox Console/Frontend │ +├─────────────────────────────────────────────────────────────┤ +│ Core Commands │ Plugin System │ SSH Manager │ TUI │ +├──────────────────┼─────────────────┼───────────────┼────────┤ +│ Device Store │ Mesh Client │ Discovery │ Textual│ +└─────────────────────────────────────────────────────────────┘ + │ │ │ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │ SecuBox │ ... │ SecuBox │ ... │ SecuBox │ + │ Node 1 │ │ Node 2 │ │ Node N │ + └──────────┘ └──────────┘ └──────────┘ +``` + +### Key Infrastructure +- **Configuration**: UCI-based (`/etc/config/secubox-*`) +- **Communication**: UBUS JSON-RPC +- **Web Server**: uhttpd + LuCI +- **Exposure**: HAProxy (domains, SSL), Tor (.onion) +- **Packages**: opkg with custom feed +- **Backup**: Git-based via Gitea +- **Mesh**: P2P discovery, sync, federation +- **JSON Parsing**: `jsonfilter` (not jq) + +### Storage Locations +- UCI configs: `/etc/config/` +- Backups: `/overlay/secubox-backups/` +- Package feed: `/www/secubox-feed/` +- P2P state: `/tmp/secubox-p2p-*.json` +- Logs: `/var/log/secubox.log` + +--- + ## Plugin Development Create plugins in `~/.secubox-console/plugins/`: ```python # my_plugin.py - PLUGIN_INFO = { "name": "my-plugin", "version": "1.0.0", @@ -122,39 +446,23 @@ PLUGIN_INFO = { } def register_commands(console): - """Register plugin commands with console""" - console.register_command("mycommand", cmd_mycommand, "My command description") + console.register_command("mycommand", cmd_mycommand, "Description") def cmd_mycommand(args): - """Handler for mycommand""" - print("Hello from my plugin!") - # Access console.devices, console.ssh_exec(), etc. + print("Hello from plugin!") ``` -## Architecture - -``` -┌─────────────────────────────────────────────────────┐ -│ SecuBox Console │ -├─────────────────────────────────────────────────────┤ -│ Core Commands │ Plugin System │ SSH Manager │ -├───────────────────┼──────────────────┼──────────────┤ -│ Device Store │ Mesh Client │ TUI (rich) │ -└─────────────────────────────────────────────────────┘ - │ │ - ▼ ▼ - ┌──────────┐ ┌──────────┐ - │ SecuBox │ ... │ SecuBox │ - │ Node 1 │ │ Node N │ - └──────────┘ └──────────┘ -``` +--- ## Requirements - Python 3.8+ -- `paramiko` - SSH connections -- `rich` - TUI dashboard (optional) -- `httpx` - HTTP/mesh API calls (optional) +- `textual>=0.40.0` - Modern TUI framework +- `paramiko>=3.0.0` - SSH connections +- `httpx>=0.25.0` - HTTP/API calls +- `rich>=13.0.0` - Rich console (fallback) + +--- ## License