2026-01-04 19:50:25 +01:00

13 KiB

Raw Blame History

SecuBox Module Validation Guide

Version: 1.0.0
Last Updated: 2025-12-28
Status: Active

📚 Complete Reference: This is a detailed validation guide. For quick commands, see QUICK-START.md

Related Documentation:

Complete guide: DEVELOPMENT-GUIDELINES.md §8

Pre-commit checklist: DEVELOPMENT-GUIDELINES.md §8.1

Post-deploy checklist: DEVELOPMENT-GUIDELINES.md §8.3

Permissions guide: PERMISSIONS-GUIDE.md

Automation briefing: CODEX.md

Overview

SecuBox uses a multi-layered validation approach:

Module Generation Validation - Validates newly created/modified modules
Pre-Push Validation - Blocks git push if critical issues are found
Runtime Validation - Continuous checks on deployed modules

Validation Tools

1. validate-module-generation.sh

Comprehensive validation for a single module during/after generation.

Usage:

./secubox-tools/validate-module-generation.sh luci-app-cdn-cache

Checks performed:

✅ Makefile completeness and correctness
✅ RPCD script naming convention (must use luci. prefix)
✅ RPCD script executable permissions
✅ RPCD script structure (list/call handlers)
✅ ACL file JSON validity
✅ ACL permissions cover RPCD methods
✅ Menu file JSON validity
✅ Menu paths match view file locations
✅ JavaScript view files exist
✅ JavaScript strict mode usage
✅ RPC method calls match RPCD methods
✅ ubus object names match RPCD script names
✅ UCI config validity (if present)
✅ Security scan (hardcoded credentials, dangerous commands)
✅ Documentation presence

Exit codes:

0 - All checks passed
1 - Critical errors found (module should not be deployed)

2. pre-push-validation.sh

Validates all modules before allowing git push.

Usage:

# Automatic (via git hook):
git push  # validation runs automatically

# Manual:
./secubox-tools/pre-push-validation.sh

Checks performed:

✅ Git staged changes check
✅ RPCD naming conventions across all modules
✅ Menu path validation across all modules
✅ JSON syntax validation
✅ RPCD executable permissions
✅ ACL method coverage
✅ Makefile validation
✅ Security scans
✅ Full module validation on modified modules

Exit codes:

0 - Push allowed
1 - Push blocked (critical errors)

3. validate-modules.sh

Fast validation of all modules (existing tool).

Usage:

./secubox-tools/validate-modules.sh

See secubox-tools/README.md for details.

Installing Git Hooks

To enable automatic validation before git push:

./secubox-tools/install-git-hooks.sh

This creates a symbolic link from .git/hooks/pre-push to secubox-tools/pre-push-validation.sh.

Critical Naming Conventions

1. RPCD Script MUST Match ubus Object

Rule: The RPCD script filename MUST exactly match the ubus object name declared in JavaScript.

Why: LuCI's RPC system looks for RPCD scripts by their filename. If the name doesn't match, you get:

RPC call failed with error -32000: Object not found
Command failed: Method not found

Example:

// JavaScript (htdocs/luci-static/resources/view/cdn-cache/overview.js)
var callStatus = rpc.declare({
    object: 'luci.cdn-cache',  // ← This must match RPCD filename
    method: 'status'
});

# RPCD script filename MUST be:
root/usr/libexec/rpcd/luci.cdn-cache  # ← Exactly 'luci.cdn-cache'

Common mistakes:

❌ root/usr/libexec/rpcd/cdn-cache (missing luci. prefix)
❌ root/usr/libexec/rpcd/luci-cdn-cache (using dash instead of dot)
❌ root/usr/libexec/rpcd/cdn_cache (using underscore)

Validation:

# Check naming:
./secubox-tools/validate-module-generation.sh luci-app-cdn-cache

# Look for:
# ✓ RPCD script follows naming convention (luci.* prefix)
# ✓ CRITICAL: RPCD script name matches ACL ubus object

Rule: Menu JSON path entries MUST correspond to actual view file paths.

Why: LuCI loads views based on the path in the menu. Wrong path = HTTP 404.

Example:

// Menu (root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json)
{
    "action": {
        "type": "view",
        "path": "netifyd-dashboard/overview"  // ← Must match file location
    }
}

# View file MUST exist at:
htdocs/luci-static/resources/view/netifyd-dashboard/overview.js
#                                  ↑ Same path as menu ↑

Common mistakes:

❌ Menu: "path": "netifyd/overview" but file at view/netifyd-dashboard/overview.js
❌ Menu: "path": "overview" but file at view/netifyd-dashboard/overview.js

Validation:

# Check paths:
./secubox-tools/validate-module-generation.sh luci-app-netifyd-dashboard

# Look for:
# ✓ Menu path 'netifyd-dashboard/overview' → view file EXISTS

3. All ubus Objects MUST Use `luci.` Prefix

Rule: Every ubus object declaration must start with luci.

Why: Consistent naming convention for LuCI applications. ACL system expects it.

Example:

// ✅ Correct:
object: 'luci.cdn-cache'
object: 'luci.system-hub'
object: 'luci.wireguard-dashboard'

// ❌ Wrong:
object: 'cdn-cache'  // Missing luci. prefix
object: 'systemhub'  // Missing luci. prefix

Validation:

# Check convention:
./secubox-tools/validate-modules.sh

# Look for:
# ✓ ubus object 'luci.cdn-cache' follows naming convention

Module Generation Checklist

Use this checklist when generating a new module:

Phase 1: Initial Generation

Create module directory: luci-app-<module-name>/
Generate Makefile with all required fields
Create RPCD script at root/usr/libexec/rpcd/luci.<module-name>
Make RPCD script executable: chmod +x
Add shebang to RPCD: #!/bin/sh
Implement RPCD methods (list, call, status, etc.)
Create ACL file with read/write permissions
Create menu JSON with correct paths
Create view JavaScript files
Add 'use strict'; to all JS files

Phase 2: Validation

Run module generation validation:

./secubox-tools/validate-module-generation.sh luci-app-<module-name>

Fix all ERRORS (critical)
Review all WARNINGS (recommended)

Phase 3: Integration Validation

Verify RPCD script name matches ubus object:

grep -r "object:" luci-app-<module-name>/htdocs --include="*.js"
ls -la luci-app-<module-name>/root/usr/libexec/rpcd/
# Names must match exactly

Verify menu paths match view files:

grep '"path":' luci-app-<module-name>/root/usr/share/luci/menu.d/*.json
ls -R luci-app-<module-name>/htdocs/luci-static/resources/view/
# Paths must align

Verify ACL permissions cover all RPCD methods:

grep 'case "$2"' luci-app-<module-name>/root/usr/libexec/rpcd/*
grep -A 20 '"ubus":' luci-app-<module-name>/root/usr/share/rpcd/acl.d/*.json
# All methods should be in ACL

Phase 4: Pre-Commit

Run comprehensive validation:
```
./secubox-tools/validate-modules.sh
```
Review security scan results

Check JSON validity:

find luci-app-<module-name> -name "*.json" -exec python3 -m json.tool {} \; > /dev/null

Optional: Run shellcheck on RPCD:

shellcheck luci-app-<module-name>/root/usr/libexec/rpcd/*

Phase 5: Git Commit

Stage changes:
```
git add luci-app-<module-name>
```

Commit with descriptive message:

git commit -m "feat: implement <module-name> module

- Add RPCD backend with methods: status, get_*, set_*
- Create views for overview, settings, etc.
- Configure ACL permissions
- Add menu entries

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

Push (validation runs automatically):
```
git push
```

Common Validation Errors and Fixes

Error: RPCD script name doesn't match ubus object

✗ ERROR: luci-app-cdn-cache: RPCD script 'cdn-cache' does NOT match ubus object 'luci.cdn-cache'

Fix:

cd luci-app-cdn-cache/root/usr/libexec/rpcd
mv cdn-cache luci.cdn-cache

✗ ERROR: luci-app-netifyd: Menu path 'netifyd/overview' → file NOT FOUND
Expected: htdocs/luci-static/resources/view/netifyd/overview.js

Fix Option 1: Update menu path to match file:

# Edit root/usr/share/luci/menu.d/luci-app-netifyd-dashboard.json
# Change: "path": "netifyd/overview"
# To:     "path": "netifyd-dashboard/overview"

Fix Option 2: Move view file to match menu:

mv htdocs/luci-static/resources/view/netifyd-dashboard \
   htdocs/luci-static/resources/view/netifyd

Error: RPCD script is NOT executable

✗ ERROR: luci-app-cdn-cache: luci.cdn-cache is NOT executable

Fix:

chmod +x luci-app-cdn-cache/root/usr/libexec/rpcd/luci.cdn-cache

Error: Method 'get_stats' from RPCD not found in ACL

⚠ WARNING: luci-app-cdn-cache: Method 'get_stats' from RPCD not in ACL

Fix:

# Edit root/usr/share/rpcd/acl.d/luci-app-cdn-cache.json
# Add 'get_stats' to the read.ubus array:
{
    "luci-app-cdn-cache": {
        "read": {
            "ubus": {
                "luci.cdn-cache": ["status", "get_config", "get_stats"]
                                                           ↑ Add here
            }
        }
    }
}

Error: Invalid JSON syntax

✗ ERROR: luci-app-cdn-cache: acl.d JSON is INVALID - syntax error

Fix:

# Validate JSON:
python3 -m json.tool root/usr/share/rpcd/acl.d/luci-app-cdn-cache.json

# Common issues:
# - Missing comma between array elements
# - Trailing comma after last element
# - Unescaped quotes in strings

Bypassing Validation (NOT RECOMMENDED)

In rare cases, you may need to bypass validation:

# Skip pre-push validation:
git push --no-verify

# Skip module generation validation:
# (can't bypass - it's informational only)

⚠️ WARNING: Bypassing validation can lead to broken modules in production!

Integration with CI/CD

GitHub Actions

Add validation to your workflow:

name: Validate Modules

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y python3 shellcheck          

      - name: Run module validation
        run: |
          chmod +x secubox-tools/validate-modules.sh
          ./secubox-tools/validate-modules.sh          

      - name: Run pre-push validation
        run: |
          chmod +x secubox-tools/pre-push-validation.sh
          ./secubox-tools/pre-push-validation.sh

Best Practices

Always validate before committing

./secubox-tools/validate-module-generation.sh luci-app-<module>

Install git hooks for automatic validation
```
./secubox-tools/install-git-hooks.sh
```
Fix errors immediately - Don't accumulate validation debt
Review warnings - They often indicate real issues

Test on OpenWrt before marking complete:

scp bin/packages/*/base/luci-app-*.ipk root@192.168.1.1:/tmp/
ssh root@192.168.1.1
opkg install /tmp/luci-app-*.ipk
/etc/init.d/rpcd restart
/etc/init.d/uhttpd restart

Document module-specific requirements in module README

Troubleshooting

Validation script fails to run

# Make sure scripts are executable:
chmod +x secubox-tools/*.sh

# Check dependencies:
which python3  # For JSON validation
which shellcheck  # For shell script validation

Git hook not running

# Check hook is installed:
ls -la .git/hooks/pre-push

# Reinstall hooks:
./secubox-tools/install-git-hooks.sh

False positives in validation

If validation incorrectly reports an error, please report it:

Create issue with full validation output
Include module name and specific check that failed
We'll update validation logic

Additional Resources

CLAUDE.md - Main project documentation
secubox-tools/README.md - Tools documentation
Feature Regeneration Prompts - Module generation prompts

Support

If you encounter validation issues:

Check this guide for common errors
Run validation with verbose output
Review CLAUDE.md for naming conventions
Create issue on GitHub with validation output

13 KiB

Raw Blame History

SecuBox Module Validation Guide

See Also

Overview

Validation Tools

1. validate-module-generation.sh

2. pre-push-validation.sh

3. validate-modules.sh

Installing Git Hooks

Critical Naming Conventions

1. RPCD Script MUST Match ubus Object

2. Menu Paths MUST Match View File Locations

3. All ubus Objects MUST Use `luci.` Prefix

Module Generation Checklist

Phase 1: Initial Generation

Phase 2: Validation

Phase 3: Integration Validation

Phase 4: Pre-Commit

Phase 5: Git Commit

Common Validation Errors and Fixes

Error: RPCD script name doesn't match ubus object

Error: Menu path → file NOT FOUND

Error: RPCD script is NOT executable

Error: Method 'get_stats' from RPCD not found in ACL

Error: Invalid JSON syntax

Bypassing Validation (NOT RECOMMENDED)

Integration with CI/CD

GitHub Actions

Best Practices

Troubleshooting

Validation script fails to run

Git hook not running

False positives in validation

Additional Resources

Support

13 KiB Raw Blame History

SecuBox Module Validation Guide

See Also

Overview

Validation Tools

1. validate-module-generation.sh

2. pre-push-validation.sh

3. validate-modules.sh

Installing Git Hooks

Critical Naming Conventions

1. RPCD Script MUST Match ubus Object

2. Menu Paths MUST Match View File Locations

3. All ubus Objects MUST Use luci. Prefix

Module Generation Checklist

Phase 1: Initial Generation

Phase 2: Validation

Phase 3: Integration Validation

Phase 4: Pre-Commit

Phase 5: Git Commit

Common Validation Errors and Fixes

Error: RPCD script name doesn't match ubus object

Error: Menu path → file NOT FOUND

Error: RPCD script is NOT executable

Error: Method 'get_stats' from RPCD not found in ACL

Error: Invalid JSON syntax

Bypassing Validation (NOT RECOMMENDED)

Integration with CI/CD

GitHub Actions

Best Practices

Troubleshooting

Validation script fails to run

Git hook not running

False positives in validation

Additional Resources

Support

13 KiB

Raw Blame History

3. All ubus Objects MUST Use `luci.` Prefix