lua-audit

Lua Code Audit Skill

Perform comprehensive security, correctness, and quality audits on Hull Lua stdlib code.

Target: $ARGUMENTS (default: all stdlib/lua/hull/*.lua files)

Usage

/lua-audit                              # Audit all Lua stdlib modules
/lua-audit stdlib/lua/hull/template.lua # Audit a specific module
/lua-audit --fix                        # Audit and apply fixes

Hull Lua Context

Hull Lua code runs inside a sandboxed Lua 5.4 interpreter:

• Removed globals: io, os, loadfile, dofile, load
• Available libs: base, table, string, math, utf8, coroutine
• Custom require(): resolves only from embedded stdlib registry
• Memory limit: 64 MB (custom allocator)
• C capabilities: db, crypto, time, env, fs, http — accessed through hull globals, NOT Lua standard libs

Audit Categories

1. Sandbox Safety (Critical)

Hull-specific: The template engine's _template._compile() uses luaL_loadbuffer via C bridge — this is the ONLY allowed code compilation path. Verify no Lua-level code compilation exists.

2. Input Validation & Injection

SQL safety check:

-- BAD: string concatenation
db.query("SELECT * FROM users WHERE id = " .. id)

-- GOOD: parameterized
db.query("SELECT * FROM users WHERE id = ?", {id})

Template safety check:

-- BAD: raw output of user data
template.render_string("{{{ user_input }}}", data)

-- GOOD: auto-escaped output
template.render_string("{{ user_input }}", data)

3. Error Handling

Patterns to check:

-- BAD: unchecked
local result = db.query("SELECT * FROM users WHERE id = ?", {id})
local name = result[1].name  -- crashes if result is empty

-- GOOD: nil-safe
local result = db.query("SELECT * FROM users WHERE id = ?", {id})
if not result or #result == 0 then return nil, "not found" end
local name = result[1].name

4. Type Safety

Lua truthiness pitfalls:

-- BAD: 0 is truthy in Lua!
if count then  -- true even when count == 0

-- GOOD:
if count and count > 0 then

-- BAD: empty table is truthy!
if items then  -- true even when items == {}

-- GOOD:
if items and #items > 0 then

5. Resource Management

Performance patterns:

-- BAD: O(n^2) string building
local s = ""
for _, item in ipairs(items) do
    s = s .. item  -- copies entire string each iteration
end

-- GOOD: table.concat
local parts = {}
for _, item in ipairs(items) do
    parts[#parts + 1] = item
end
local s = table.concat(parts)

6. Crypto & Auth Safety

Constant-time comparison:

-- BAD: early-exit comparison
if token == expected then

-- GOOD: use crypto.verify_password or HMAC-then-compare
-- Hull's jwt.verify and csrf.verify use constant-time internally

7. API Consistency (Lua vs JS parity)

8. Template Engine Specific

9. Dead Code & Style

Audit Procedure

When /lua-audit is invoked:

1. Locate Files

   stdlib/lua/hull/*.lua                   # All Lua stdlib modules
   examples/*/app.lua                      # Example apps (reference patterns)
   tests/fixtures/*/app.lua                # Test fixture apps
   

2. Scan for Critical Issues

   • Search for load(, loadstring(, dofile(, loadfile( — sandbox escapes
   • Search for string concatenation in SQL: "SELECT.*".. or "INSERT.*"..
   • Search for {{{ in template strings — raw output of user data
   • Search for == comparison of secrets, tokens, hashes
   • Search for hardcoded secret strings
   • Search for _G. or _G[ — global pollution
   • Search for missing local on function-scoped variables

3. Review Each Module

   • Check public API functions for input validation
   • Check error handling (nil returns, pcall usage)
   • Check resource cleanup (cache sizes, table growth)
   • Verify API parity with JS equivalent

4. Check Template Engine

   • Verify codegen never interpolates user data into generated source
   • Verify HTML escaping covers & < > " '
   • Verify nil-safe dot paths
   • Verify circular extends detection
   • Verify include depth limit

5. Generate Report Format as markdown table with findings, severity, file:line, and suggested fix.

Report Format

## Lua Audit Report: Hull

**Date:** YYYY-MM-DD
**Files Scanned:** N
**Issues Found:** N (Critical: N, High: N, Medium: N, Low: N)

### Critical Issues

| # | File:Line | Issue | Current Code | Suggested Fix |
|---|-----------|-------|--------------|---------------|
| C1 | stdlib/lua/hull/auth.lua:42 | SQL injection | `db.query("... " .. id)` | `db.query("... ?", {id})` |

### High Issues
...

### Medium Issues
...

### Low Issues
...

### Recommendations
1. ...

Fix Mode (--fix)

When --fix is specified:

1. Generate the audit report first
2. For each fixable issue, apply the transformation
3. Rebuild (make)
4. Re-run tests (make test && make e2e-templates)
5. Report any test failures

Auto-fixable Issues:

• SQL string concatenation -> parameterized queries
• Missing local declarations -> add local
• Unused variables -> remove or prefix with _
• s = s .. x in loops -> table.concat pattern
• Missing nil checks -> add guard clause
• Commented-out code blocks -> remove

NOT Auto-fixable (require manual review):

• Logic errors
• Crypto/auth design flaws
• API parity mismatches (may require JS changes too)
• Template codegen injection paths
• Resource leak in complex control flow