diff --git a/TOOLS.md b/TOOLS.md new file mode 100644 index 00000000..3264f83a --- /dev/null +++ b/TOOLS.md @@ -0,0 +1,438 @@ +# SecuBox-DEB Tools Reference + +This document describes the build, deployment, and utility scripts in `image/` and `scripts/` directories. + +--- + +## Image Building Tools (`image/`) + +### build-live-usb.sh + +Build a bootable live USB image for **amd64** systems (x86_64). + +```bash +sudo bash image/build-live-usb.sh [OPTIONS] +``` + +**Options:** +| Option | Description | +|--------|-------------| +| `--suite SUITE` | Debian suite (default: bookworm) | +| `--out DIR` | Output directory (default: ./output) | +| `--size SIZE` | Total image size (default: 8G) | +| `--local-cache` | Use local APT cache for faster builds | +| `--no-kiosk` | Disable GUI kiosk mode | +| `--no-persistence` | Don't include persistent storage partition | +| `--no-compress` | Skip gzip compression (faster for testing) | +| `--preseed FILE` | Include preseed config archive | + +**Output:** +- `secubox-live-amd64-bookworm.img` - Raw bootable image +- `secubox-live-amd64-bookworm.img.gz` - Compressed image + +**Features:** +- UEFI + Legacy BIOS hybrid boot +- All SecuBox packages pre-installed +- Root autologin on console +- Optional GUI kiosk mode (Chromium-based) +- Network auto-detection at first boot + +**Flash to USB:** +```bash +zcat output/secubox-live-amd64-bookworm.img.gz | sudo dd of=/dev/sdX bs=4M status=progress +``` + +--- + +### build-rpi-usb.sh + +Build a bootable USB/SD image for **Raspberry Pi** (arm64). + +```bash +sudo bash image/build-rpi-usb.sh [OPTIONS] +``` + +**Options:** +| Option | Description | +|--------|-------------| +| `--board BOARD` | Target board: rpi4, rpi5, rpi400 (default: rpi4) | +| `--suite SUITE` | Debian suite (default: bookworm) | +| `--out DIR` | Output directory | +| `--size SIZE` | Image size (default: 8G) | +| `--local-cache` | Use local APT cache | +| `--no-kiosk` | Console-only mode | + +**Supported Boards:** +- Raspberry Pi 4 Model B +- Raspberry Pi 400 +- Raspberry Pi 5 + +**Output:** +- `secubox-rpi4-bookworm.img.gz` - Compressed bootable image + +--- + +### build-image.sh + +Build SecuBox images for **Marvell ARM boards** (MOCHAbin, ESPRESSObin). + +```bash +sudo bash image/build-image.sh --board --out +``` + +**Options:** +| Option | Description | +|--------|-------------| +| `--board BOARD` | Target: mochabin, espressobin-v7, espressobin-ultra | +| `--out FILE` | Output .img path | +| `--suite SUITE` | Debian suite (default: bookworm) | + +**Boards:** +- `mochabin` - Armada 7040, SecuBox Pro +- `espressobin-v7` - Armada 3720, SecuBox Lite +- `espressobin-ultra` - Armada 3720 Ultra + +--- + +### build-installer-iso.sh + +Build a Debian installer ISO with SecuBox preseed. + +```bash +sudo bash image/build-installer-iso.sh [OPTIONS] +``` + +Creates an unattended Debian installer that: +- Partitions disk automatically +- Installs base Debian + SecuBox packages +- Configures network and services + +--- + +### build-c3box-clone.sh + +Clone an existing C3BOX installation for deployment. + +```bash +sudo bash image/build-c3box-clone.sh +``` + +--- + +### firstboot.sh + +First boot initialization script (runs on target device). + +- Generates SSH host keys +- Creates JWT secrets +- Sets unique hostname +- Initializes network config + +--- + +### preseed-apply.sh + +Apply preseed configuration to a running system. + +```bash +sudo bash image/preseed-apply.sh +``` + +--- + +### create-vbox-vm.sh + +Create a VirtualBox VM from a SecuBox image. + +```bash +bash image/create-vbox-vm.sh +``` + +--- + +## Package Building (`scripts/`) + +### build-packages.sh + +Build all SecuBox .deb packages. + +```bash +bash scripts/build-packages.sh [SUITE] [ARCH] +``` + +**Arguments:** +- `SUITE` - Debian suite: bookworm, trixie (default: bookworm) +- `ARCH` - Architecture: amd64, arm64 (default: host arch) + +**Output:** `output/debs/` + +Builds packages in dependency order, starting with `secubox-core`. + +--- + +### build-all-local.sh + +Build all packages using local APT cache. + +```bash +bash scripts/build-all-local.sh +``` + +--- + +### build-add-local.sh + +Build and add a single package to the local repo. + +```bash +bash scripts/build-add-local.sh +``` + +--- + +## Deployment (`scripts/`) + +### deploy.sh + +Deploy packages to a SecuBox device via SSH. + +```bash +bash scripts/deploy.sh [--restart] +``` + +**Examples:** +```bash +# Deploy single package +bash scripts/deploy.sh secubox-crowdsec root@192.168.1.1 + +# Deploy and restart service +bash scripts/deploy.sh secubox-hub root@192.168.1.1 --restart + +# Deploy all packages +bash scripts/deploy.sh --all root@192.168.1.1 +``` + +--- + +## Frontend Porting (`scripts/`) + +### port-frontend.sh + +Copy frontend assets from secubox-openwrt source. + +```bash +bash scripts/port-frontend.sh +``` + +Copies `htdocs/` from the OpenWrt luci-app to `www/` in the Debian package. + +--- + +### rewrite-xhr.py + +Rewrite LuCI ubus calls to REST API calls. + +```bash +python3 scripts/rewrite-xhr.py packages/secubox-/www/ +``` + +Transforms: +```javascript +// Before (LuCI/ubus) +rpc.declare({object: 'luci.crowdsec', method: 'get_stats'}) + +// After (REST) +fetch('/api/v1/crowdsec/stats') +``` + +--- + +## Theme Tools (`scripts/`) + +### apply-crt-theme.py + +Apply CRT/retro terminal theme to console CSS. + +```bash +python3 scripts/apply-crt-theme.py +``` + +--- + +### apply-light-theme.py + +Generate light mode variant of SecuBox theme. + +```bash +python3 scripts/apply-light-theme.py +``` + +--- + +## Documentation (`scripts/`) + +### generate-docs.py + +Generate API documentation from FastAPI modules. + +```bash +python3 scripts/generate-docs.py +``` + +Scans all `packages/*/api/main.py` and generates OpenAPI docs. + +--- + +### screenshot-tool.py + +Capture screenshots of SecuBox dashboards for documentation. + +```bash +python3 scripts/screenshot-tool.py --url http://localhost:8080 +``` + +Requires: `pip install -r scripts/requirements-screenshot.txt` + +--- + +## Module Scaffolding (`scripts/`) + +### new-package.sh + +Scaffold a new SecuBox Debian package. + +```bash +bash scripts/new-package.sh +``` + +Creates: +``` +packages/secubox-/ +├── api/main.py # FastAPI stub +├── debian/ +│ ├── control +│ ├── rules +│ ├── changelog +│ └── ... +└── www/ # Frontend placeholder +``` + +--- + +### new-module.sh + +Extended module scaffolding with tests and config. + +```bash +bash scripts/new-module.sh +``` + +--- + +## System Setup (`scripts/`) + +### setup-local-cache.sh + +Set up local APT cache for offline/faster builds. + +```bash +bash scripts/setup-local-cache.sh +``` + +Creates `cache/repo/` with pooled .deb files. + +--- + +### local-repo-add.sh + +Add a .deb to the local repository. + +```bash +bash scripts/local-repo-add.sh +``` + +--- + +### install-apparmor.sh + +Install AppArmor profiles for SecuBox services. + +```bash +sudo bash scripts/install-apparmor.sh +``` + +--- + +### install-audit.sh + +Configure audit logging for CSPN compliance. + +```bash +sudo bash scripts/install-audit.sh +``` + +--- + +## Nginx Tools (`scripts/`) + +### retrofit-nginx-modular.sh + +Convert monolithic nginx.conf to modular includes. + +```bash +bash scripts/retrofit-nginx-modular.sh +``` + +--- + +### update-nginx-modular.sh + +Update nginx module configs after package changes. + +```bash +bash scripts/update-nginx-modular.sh +``` + +--- + +### fix-navbar.sh + +Fix navigation bar links across all frontend modules. + +```bash +bash scripts/fix-navbar.sh +``` + +--- + +## Quick Reference + +| Task | Command | +|------|---------| +| Build all packages | `bash scripts/build-packages.sh` | +| Build live USB (x86) | `sudo bash image/build-live-usb.sh` | +| Build RPi image | `sudo bash image/build-rpi-usb.sh --board rpi4` | +| Deploy to device | `bash scripts/deploy.sh --all root@192.168.1.1` | +| Create new package | `bash scripts/new-package.sh mymodule` | +| Setup local cache | `bash scripts/setup-local-cache.sh` | + +--- + +## Environment Requirements + +**Build Host:** +- Debian 12+ or Ubuntu 22.04+ +- Packages: `debootstrap qemu-user-static dpkg-dev debhelper dh-python` +- Root access for image building + +**Cross-compilation (arm64 on amd64):** +```bash +sudo apt install qemu-user-static binfmt-support +``` + +--- + +## Author + +Gerald KERMA +CyberMind — https://cybermind.fr diff --git a/packages/secubox-console/console/theme.py b/packages/secubox-console/console/theme.py index 04fe65f1..707d964d 100644 --- a/packages/secubox-console/console/theme.py +++ b/packages/secubox-console/console/theme.py @@ -1,11 +1,71 @@ """ SecuBox-Deb :: Console TUI — Theme System Board-specific theming for Textual TUI. + +Works standalone (without secubox-core) with auto-detection fallback. """ from __future__ import annotations -from typing import Dict, Tuple +from typing import Dict +import platform +import os +from pathlib import Path -from secubox_core.kiosk import detect_board_type, get_board_model +# Try to import secubox_core, fallback to local detection if not available +try: + from secubox_core.kiosk import detect_board_type, get_board_model + HAS_SECUBOX_CORE = True +except ImportError: + HAS_SECUBOX_CORE = False + + def detect_board_type() -> str: + """Fallback board detection for standalone mode.""" + # Check DMI/device-tree for board info + try: + # Check device-tree (ARM boards) + dt_model = Path("/proc/device-tree/model") + if dt_model.exists(): + model = dt_model.read_text().strip().lower() + if "raspberry" in model: + return "rpi" + if "mochi" in model or "7040" in model: + return "mochabin" + if "espresso" in model or "3720" in model: + return "espressobin-v7" + + # Check DMI (x86) + dmi_vendor = Path("/sys/class/dmi/id/sys_vendor") + if dmi_vendor.exists(): + vendor = dmi_vendor.read_text().strip().lower() + if "virtualbox" in vendor or "vmware" in vendor or "qemu" in vendor: + return "x64-vm" + return "x64-baremetal" + + # Fallback based on architecture + arch = platform.machine() + if arch in ("x86_64", "amd64"): + return "x64-baremetal" + elif arch in ("aarch64", "arm64"): + return "unknown-arm64" + + except Exception: + pass + + return "unknown" + + def get_board_model() -> str: + """Fallback model detection for standalone mode.""" + try: + dt_model = Path("/proc/device-tree/model") + if dt_model.exists(): + return dt_model.read_text().strip() + + dmi_name = Path("/sys/class/dmi/id/product_name") + if dmi_name.exists(): + return dmi_name.read_text().strip() + except Exception: + pass + + return platform.machine() # Board-specific color schemes diff --git a/packages/secubox-console/debian/changelog b/packages/secubox-console/debian/changelog index 1a88a26d..be464985 100644 --- a/packages/secubox-console/debian/changelog +++ b/packages/secubox-console/debian/changelog @@ -1,3 +1,13 @@ +secubox-console (1.2.0-1) bookworm; urgency=medium + + * Standalone mode: Works without secubox-core installed + * Fallback board detection for non-SecuBox systems + * secubox-core moved from Depends to Recommends + * Can now be installed on any Debian/Ubuntu system + * Fix: BoardHeader import in SOC screens + + -- Gerald KERMA Tue, 01 Apr 2026 16:00:00 +0200 + secubox-console (1.1.0-1) bookworm; urgency=medium * Add SOC integration for fleet monitoring diff --git a/packages/secubox-console/debian/control b/packages/secubox-console/debian/control index 3c796a05..2c3a4194 100644 --- a/packages/secubox-console/debian/control +++ b/packages/secubox-console/debian/control @@ -11,12 +11,13 @@ Package: secubox-console Architecture: all Depends: ${misc:Depends}, python3 (>= 3.11), - secubox-core (>= 1.1.0), python3-textual (>= 0.40.0), python3-httpx, python3-rich +Recommends: secubox-core (>= 1.1.0) Suggests: secubox-hub, - secubox-watchdog + secubox-watchdog, + secubox-soc-gateway Description: SecuBox Console TUI — Terminal Dashboard Terminal-based dashboard for SecuBox appliances using Python Textual. Provides system monitoring, service management, and network status diff --git a/packages/secubox-console/debian/secubox-console.service b/packages/secubox-console/debian/secubox-console.service index bd7f3691..7af0b448 100644 --- a/packages/secubox-console/debian/secubox-console.service +++ b/packages/secubox-console/debian/secubox-console.service @@ -1,10 +1,8 @@ [Unit] -Description=SecuBox Console TUI on TTY1 -After=multi-user.target secubox-runtime.service -Wants=secubox-runtime.service -ConditionPathExists=!/var/lib/secubox/.kiosk-enabled -ConditionPathExists=/var/lib/secubox/.console-enabled -Conflicts=getty@tty1.service +Description=SecuBox Console TUI +Documentation=https://cybermind.fr/secubox +After=multi-user.target +ConditionPathExists=/usr/bin/secubox-console [Service] Type=simple @@ -15,24 +13,8 @@ TTYPath=/dev/tty1 TTYReset=yes TTYVHangup=yes TTYVTDisallocate=yes - -User=secubox -Group=secubox -SupplementaryGroups=tty dialout - -Environment=TERM=linux -Environment=HOME=/var/lib/secubox - Restart=on-failure RestartSec=5 -TimeoutStartSec=30 - -# Security hardening -NoNewPrivileges=false -ProtectSystem=strict -ProtectHome=read-only -ReadWritePaths=/var/lib/secubox /run/secubox /tmp -PrivateTmp=true [Install] WantedBy=multi-user.target