CyberMind-FR
8c062b6d60
- README.md: Update to v0.16.0 with all 38 modules categorized - CHANGELOG.md: Create comprehensive changelog (v0.12.0-v0.16.0) - CLAUDE.md: Add toolchain build rules for Go/CGO packages - secubox-tools/README.md: Add SDK vs toolchain build guidance - TODO-ANALYSE.md: Mark completed tasks, update health score - HISTORY.md: Document ARM64 toolchain discovery, multi-instance - dev-status-widget.js: Update stats (38 modules, 1500 commits) SDK builds produce LSE atomics that crash on some ARM64 CPUs. Go/CGO packages (crowdsec, netifyd) must use full toolchain. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
# Claude Instructions for SecuBox OpenWrt
|
|
|
|
## OpenWrt Shell Scripting Guidelines
|
|
|
|
### Process Detection
|
|
- **Use `pgrep crowdsec` instead of `pgrep -x crowdsec`**
|
|
- The `-x` flag requires an exact process name match which doesn't work reliably on OpenWrt/BusyBox
|
|
- Same applies to other daemons: use `pgrep <name>` without `-x`
|
|
|
|
### Command Availability
|
|
- `timeout` command is NOT available on OpenWrt by default - use alternatives or check with `command -v timeout`
|
|
- `ss` command may not be available - use `netstat` or `/proc/net/tcp` as fallbacks
|
|
- `sqlite3` may not be installed - provide fallback methods (e.g., delete database file instead of running SQL)
|
|
|
|
### JSON Parsing
|
|
- **Use `jsonfilter` instead of `jq`** - jsonfilter is native to OpenWrt (part of libubox), jq is often not installed
|
|
- Syntax examples:
|
|
```bash
|
|
# Get a field value
|
|
jsonfilter -i /path/to/file.json -e '@.field_name'
|
|
|
|
# Get nested field
|
|
jsonfilter -i /path/to/file.json -e '@.parent.child'
|
|
|
|
# Get array length (count elements)
|
|
jsonfilter -i /path/to/file.json -e '@[*]' | wc -l
|
|
|
|
# Get array element
|
|
jsonfilter -i /path/to/file.json -e '@[0]'
|
|
```
|
|
- Always check for empty results: `[ -z "$result" ] && result=0`
|
|
|
|
### Port Detection
|
|
When checking if a port is listening, use this order of fallbacks:
|
|
1. `/proc/net/tcp` (always available) - ports are in hex (e.g., 8080 = 1F90)
|
|
2. `netstat -tln` (usually available)
|
|
3. `ss -tln` (may not be available)
|
|
|
|
### Logging
|
|
- OpenWrt uses `logread` instead of traditional log files
|
|
- Use `logread -l N` to get last N lines
|
|
- CrowdSec writes to `/var/log/crowdsec.log`
|
|
|
|
## Build & Sync Workflow
|
|
|
|
### Local Feeds Hygiene
|
|
- Clean and resync local feeds before build iterations when dependency drift is suspected
|
|
- Prefer the repo helpers; avoid ad-hoc `rm` unless explicitly needed
|
|
|
|
### Local Build Flow
|
|
- Use `./secubox-tools/local-build.sh build <module>` for cached SDK builds
|
|
- If CI parity is required, use `make package/<module>/compile V=s`
|
|
|
|
### Sync Build Artifacts
|
|
- After building, synchronize results into the build output folder used by local-build.sh
|
|
- Use the repo sync helper scripts where available to avoid missing `root/` vs `htdocs/` payloads
|
|
|
|
### Toolchain Usage
|
|
- **CRITICAL: Non-LuCI SecuBox apps MUST be built with the full OpenWrt toolchain, NOT the SDK**
|
|
- Go packages (crowdsec, crowdsec-firewall-bouncer) require the full toolchain due to CGO and ARM64 compatibility
|
|
- Native C/C++ binaries (netifyd, nodogsplash) require the full toolchain
|
|
- The SDK produces binaries with LSE atomic instructions that crash on some ARM64 CPUs (like MochaBin's Cortex-A72)
|
|
|
|
- Packages requiring full toolchain build (in `secubox-tools/openwrt`):
|
|
- `crowdsec` - Go binary with CGO
|
|
- `crowdsec-firewall-bouncer` - Go binary with CGO
|
|
- `netifyd` - C++ native binary
|
|
- `nodogsplash` - C native binary
|
|
|
|
- To build with full toolchain:
|
|
```bash
|
|
cd secubox-tools/openwrt
|
|
make package/<package-name>/compile V=s
|
|
```
|
|
|
|
- LuCI apps and pure shell/Lua packages can use the SDK:
|
|
```bash
|
|
cd secubox-tools/sdk
|
|
make package/<package-name>/compile V=s
|
|
# Or use local-build.sh for LuCI apps
|
|
```
|
|
|
|
- If unsure, check `OPENWRT_ONLY_PACKAGES` in `secubox-tools/local-build.sh`
|