From d020678c2f48b381d9fff628431153c2d20b298f Mon Sep 17 00:00:00 2001 From: CyberMind-FR Date: Tue, 23 Dec 2025 02:23:44 +0100 Subject: [PATCH] =?UTF-8?q?Mise=20=C3=A0=20jour=20des=20r=C3=A9f=C3=A9renc?= =?UTF-8?q?es=20des=20submodules?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 290 +++++++ README.md | 670 +++++++++++----- build-openwrt-packages.yml | 556 ------------- build-secubox-images.yml | 432 ---------- cleanup-packages.sh | 147 ---- fix-makefiles.sh | 97 --- generate-rpcd-files.sh | 269 ------- install-rpcd-fix.sh | 129 --- luci-app-secubox | 2 +- secubox-analyzer.sh | 1543 ------------------------------------ secubox-debug.sh | 421 ---------- secubox-makefile-fixes.zip | Bin 7833 -> 0 bytes secubox-repair.sh | 1109 -------------------------- test-validate.yml | 327 -------- 14 files changed, 780 insertions(+), 5212 deletions(-) create mode 100644 CLAUDE.md delete mode 100644 build-openwrt-packages.yml delete mode 100644 build-secubox-images.yml delete mode 100755 cleanup-packages.sh delete mode 100755 fix-makefiles.sh delete mode 100755 generate-rpcd-files.sh delete mode 100755 install-rpcd-fix.sh delete mode 100755 secubox-analyzer.sh delete mode 100755 secubox-debug.sh delete mode 100644 secubox-makefile-fixes.zip delete mode 100755 secubox-repair.sh delete mode 100644 test-validate.yml diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..9db82ea0 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,290 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +SecuBox is a comprehensive security and network management suite for OpenWrt. The repository contains 13 LuCI application packages that provide dashboards for security monitoring, network intelligence, access control, bandwidth management, and system administration. + +## Build Commands + +### OpenWrt SDK Build + +```bash +# Build a single package +make package/luci-app-/compile V=s + +# Clean build for a package +make package/luci-app-/clean +make package/luci-app-/compile V=s + +# Install package to staging directory +make package/luci-app-/install +``` + +### Testing Packages + +```bash +# Transfer to router +scp bin/packages/*/base/luci-app-*.ipk root@192.168.1.1:/tmp/ + +# Install on router +ssh root@192.168.1.1 +opkg install /tmp/luci-app-*.ipk +/etc/init.d/rpcd restart +/etc/init.d/uhttpd restart +``` + +### Validation + +```bash +# Validate shell scripts (RPCD backends) +shellcheck luci-app-*/root/usr/libexec/rpcd/* + +# Validate JSON files +find . -name "*.json" -exec jsonlint {} \; + +# Run automated repair tool +./secubox-tools/secubox-repair.sh + +# Run diagnostics +./secubox-tools/secubox-debug.sh luci-app- +``` + +## Architecture + +### LuCI Package Structure + +All SecuBox modules follow a standard LuCI application structure: + +``` +luci-app-/ +├── Makefile # OpenWrt package definition +├── README.md # Module documentation +├── htdocs/luci-static/resources/ +│ ├── view// # JavaScript UI views +│ │ ├── overview.js # Main dashboard view +│ │ └── *.js # Additional views +│ └── / +│ ├── api.js # RPC API client module +│ └── dashboard.css # Module-specific styles +└── root/ + ├── etc/config/ # UCI configuration (optional) + └── usr/ + ├── libexec/rpcd/ # RPCD backend script + └── share/ + ├── luci/menu.d/ # Menu JSON definition + │ └── luci-app-.json + └── rpcd/acl.d/ # ACL permissions JSON + └── luci-app-.json +``` + +### Frontend-Backend Communication + +1. **Frontend (JavaScript)**: Located in `htdocs/luci-static/resources/` + - Views use LuCI's `form` and `view` classes + - API calls via `api.js` module using `L.resolveDefault()` + - UI components from `ui.js` (Dropdown, Checkbox, Combobox, etc.) + +2. **Backend (RPCD)**: Located in `root/usr/libexec/rpcd/` + - Shell scripts that implement RPC methods + - Must output JSON to stdout + - Methods are called via ubus: `ubus call ` + +3. **Menu Definition**: `root/usr/share/luci/menu.d/luci-app-.json` + - Defines menu structure and navigation + - Specifies view paths and dependencies + +4. **ACL Definition**: `root/usr/share/rpcd/acl.d/luci-app-.json` + - Defines access control for ubus methods + - Maps read/write permissions to user groups + +### Makefile Structure + +Each package Makefile must define: +- `PKG_NAME`: Package name (must match directory) +- `PKG_VERSION`: Version number +- `PKG_RELEASE`: Package release number +- `LUCI_TITLE`: Display title in LuCI +- `LUCI_DEPENDS`: Package dependencies (e.g., `+luci-base +rpcd`) +- `LUCI_DESCRIPTION`: Brief description +- `PKG_MAINTAINER`: Maintainer name and email +- `PKG_LICENSE`: License (typically Apache-2.0) + +The Makefile includes `luci.mk` from the LuCI build system which handles installation. + +## Common Development Patterns + +### Creating a New Module + +1. Copy template: `cp -r templates/luci-app-template luci-app-newmodule` +2. Update Makefile with new PKG_NAME, LUCI_TITLE, etc. +3. Create directory structure under `htdocs/` and `root/` +4. Implement RPCD backend in shell +5. Create JavaScript views +6. Define menu and ACL JSON files + +### RPCD Backend Pattern + +RPCD backends are shell scripts that: +- Parse `$1` for the method name +- Output valid JSON using `printf` or `echo` +- Use `case` statements for method routing +- Source UCI config if needed: `. /lib/functions.sh` + +Example: +```bash +#!/bin/sh +case "$1" in + list) + echo '{ "status": {}, "stats": {} }' + ;; + call) + case "$2" in + status) + # Output JSON + printf '{"running": true, "version": "1.0.0"}\n' + ;; + esac + ;; +esac +``` + +### JavaScript View Pattern + +Views extend `L.view` and implement `load()` and `render()`: + +```javascript +'use strict'; +'require view'; +'require form'; +'require /api as API'; + +return L.view.extend({ + load: function() { + return Promise.all([ + API.getStatus(), + API.getStats() + ]); + }, + + render: function(data) { + var m, s, o; + m = new form.Map('config', _('Title')); + s = m.section(form.TypedSection, 'section'); + // Add form fields... + return m.render(); + } +}); +``` + +## Module Categories + +1. **Core Control** (2 modules) + - luci-app-secubox: Central hub + - luci-app-system-hub: System control center + +2. **Security & Monitoring** (2 modules) + - luci-app-crowdsec-dashboard: CrowdSec security + - luci-app-netdata-dashboard: System monitoring + +3. **Network Intelligence** (2 modules) + - luci-app-netifyd-dashboard: Deep packet inspection + - luci-app-network-modes: Network mode configuration + +4. **VPN & Access Control** (3 modules) + - luci-app-wireguard-dashboard: WireGuard VPN + - luci-app-client-guardian: NAC & captive portal + - luci-app-auth-guardian: Authentication system + +5. **Bandwidth & Traffic** (2 modules) + - luci-app-bandwidth-manager: QoS & quotas + - luci-app-media-flow: Media traffic detection + +6. **Performance & Services** (2 modules) + - luci-app-cdn-cache: CDN proxy cache + - luci-app-vhost-manager: Virtual host manager + +## CI/CD Integration + +### GitHub Actions Workflows + +1. **build-openwrt-packages.yml**: Compiles packages for all architectures + - Triggers on push, PR, and tags + - Matrix build for 13 architectures + - Uploads artifacts per architecture + +2. **build-secubox-images.yml**: Builds custom OpenWrt images + - Creates complete firmware images with SecuBox pre-installed + +3. **test-validate.yml**: Validation and testing + - Validates Makefile structure + - Checks JSON syntax + - Runs shellcheck on scripts + - Verifies file permissions + +### Supported Architectures + +ARM64: aarch64-cortex-a53, aarch64-cortex-a72, aarch64-generic, mediatek-filogic, rockchip-armv8, bcm27xx-bcm2711 + +ARM32: arm-cortex-a7-neon, arm-cortex-a9-neon, qualcomm-ipq40xx, qualcomm-ipq806x + +MIPS: mips-24kc, mipsel-24kc, mipsel-74kc + +x86: x86-64, x86-generic + +## Key Files and Directories + +- `makefiles/`: Reference Makefiles for modules (backup/templates) +- `secubox-tools/`: Repair and debugging utilities + - `secubox-repair.sh`: Auto-fixes Makefile and RPCD issues + - `secubox-debug.sh`: Validates package structure +- `templates/`: Package templates for creating new modules +- `.github/workflows/`: CI/CD automation scripts + +## Common Issues and Solutions + +### RPCD Not Responding + +After installing/updating a package: +```bash +/etc/init.d/rpcd restart +``` + +### Menu Not Appearing + +Check that: +1. Menu JSON is valid: `jsonlint root/usr/share/luci/menu.d/*.json` +2. ACL grants access: Check `root/usr/share/rpcd/acl.d/*.json` +3. Dependencies are installed: Check Makefile `LUCI_DEPENDS` + +### Build Failures + +Common causes: +1. Missing fields in Makefile (PKG_NAME, LUCI_TITLE, etc.) +2. Invalid JSON syntax in menu.d or acl.d +3. RPCD script not executable +4. Wrong include path (should be `include ../../luci.mk`) + +Use repair tool: `./secubox-tools/secubox-repair.sh` + +## Development Workflow + +1. Make changes to module files +2. Test JSON syntax: `jsonlint .json` +3. Test shell scripts: `shellcheck