secubox-openwrt/CLAUDE.md

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

# Build a single package
make package/luci-app-<module-name>/compile V=s

# Clean build for a package
make package/luci-app-<module-name>/clean
make package/luci-app-<module-name>/compile V=s

# Install package to staging directory
make package/luci-app-<module-name>/install

Testing Packages

# 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

# 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-<module-name>

Architecture

LuCI Package Structure

All SecuBox modules follow a standard LuCI application structure:

luci-app-<module-name>/
├── Makefile                              # OpenWrt package definition
├── README.md                             # Module documentation
├── htdocs/luci-static/resources/
│   ├── view/<module-name>/               # JavaScript UI views
│   │   ├── overview.js                   # Main dashboard view
│   │   └── *.js                          # Additional views
│   └── <module-name>/
│       ├── api.js                        # RPC API client module
│       └── dashboard.css                 # Module-specific styles
└── root/
    ├── etc/config/<module-name>          # UCI configuration (optional)
    └── usr/
        ├── libexec/rpcd/<module-name>    # RPCD backend script
        └── share/
            ├── luci/menu.d/              # Menu JSON definition
            │   └── luci-app-<module-name>.json
            └── rpcd/acl.d/               # ACL permissions JSON
                └── luci-app-<module-name>.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 <module> <method>

3. Menu Definition: root/usr/share/luci/menu.d/luci-app-<module>.json

   • Defines menu structure and navigation
   • Specifies view paths and dependencies

4. ACL Definition: root/usr/share/rpcd/acl.d/luci-app-<module>.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:

#!/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():

'use strict';
'require view';
'require form';
'require <module>/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:

/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 <file>.json
3. Test shell scripts: shellcheck <script>
4. Build package: make package/luci-app-<name>/compile V=s
5. Install on test router and verify functionality
6. Run repair tool if needed: ./secubox-tools/secubox-repair.sh
7. Commit changes and push (triggers CI validation)
8. Create tag for release: git tag -a v1.0.0 -m "Release 1.0.0"

Important Notes

• All modules use Apache-2.0 license
• RPCD backends must be executable (chmod +x)
• JavaScript files use strict mode: 'use strict';
• Menu entries require proper dependency chain
• ACL must grant both ubus call and luci-cgi access
• UCI config files are optional (many modules don't need them)
• All packages build as architecture all (no compiled code)