secubox-openwrt/DOCS/VALIDATION-GUIDE.md

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

---

See Also

• Quick Commands: QUICK-START.md
• Permissions Reference: PERMISSIONS-GUIDE.md
• Automation Guardrails: CODEX.md
• Deployment Procedures: DEVELOPMENT-GUIDELINES.md §9

This guide explains the validation checks performed on SecuBox modules during generation and before git push.

Overview

SecuBox uses a multi-layered validation approach:

1. Module Generation Validation - Validates newly created/modified modules
2. Pre-Push Validation - Blocks git push if critical issues are found
3. 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

2. Menu Paths MUST Match View File Locations

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: Menu path → file NOT FOUND

✗ 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

1. Always validate before committing

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

2. Install git hooks for automatic validation

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

3. Fix errors immediately - Don't accumulate validation debt

4. Review warnings - They often indicate real issues

5. 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
   

6. 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
• .claude/module-prompts.md - Module generation prompts

Support

If you encounter validation issues:

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