mirror of
https://github.com/CyberMind-FR/secubox-deb.git
synced 2026-07-28 21:17:36 +00:00
feat(console): Standalone mode + tools documentation
- secubox-console v1.2.0: Works without secubox-core installed - Fallback board detection for non-SecuBox systems - secubox-core moved from Depends to Recommends - Simplified systemd service for standalone mode - Added TOOLS.md: comprehensive documentation for image/ and scripts/ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
befcc3f3a3
commit
c0f5b4b4e8
438
TOOLS.md
Normal file
438
TOOLS.md
Normal file
|
|
@ -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 <BOARD> --out <OUTPUT>
|
||||
```
|
||||
|
||||
**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 <source-ip> <output-img>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 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 <preseed-archive.tar.gz>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### create-vbox-vm.sh
|
||||
|
||||
Create a VirtualBox VM from a SecuBox image.
|
||||
|
||||
```bash
|
||||
bash image/create-vbox-vm.sh <image.img> <vm-name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 <package-name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment (`scripts/`)
|
||||
|
||||
### deploy.sh
|
||||
|
||||
Deploy packages to a SecuBox device via SSH.
|
||||
|
||||
```bash
|
||||
bash scripts/deploy.sh <package|--all> <user@host> [--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 <module-name>
|
||||
```
|
||||
|
||||
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-<module>/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 <input.css> <output.css>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 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 <module-name>
|
||||
```
|
||||
|
||||
Creates:
|
||||
```
|
||||
packages/secubox-<module>/
|
||||
├── 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 <module-name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 <package.deb>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 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 <devel@cybermind.fr>
|
||||
CyberMind — https://cybermind.fr
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <devel@cybermind.fr> Tue, 01 Apr 2026 16:00:00 +0200
|
||||
|
||||
secubox-console (1.1.0-1) bookworm; urgency=medium
|
||||
|
||||
* Add SOC integration for fleet monitoring
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user