Lua: Add Lua as a new CodeQL language

[prankster009]

Summary

This PR adds Lua 5.1 analysis as a new, self-contained language capability in CodeQL.

The work is derived from the Lua analysis component of our security research, FirmCross: Detecting Taint-style Vulnerabilities in Modern C-Lua Hybrid Web Services of Linux-based Firmware. That analysis was validated on real-world Lua services and helped identify 610 previously unknown vulnerabilities.

This PR ports that Lua analysis capability into CodeQL's extractor, database schema, QL libraries, queries, and test infrastructure. The resulting implementation is self-contained in this repository and does not depend on external analysis projects at runtime.

Analysis capabilities

The implementation analyzes compiled Lua 5.1 bytecode:

• Existing .luac files can be analyzed directly.
• Lua source can be analyzed by first compiling .lua files with luac5.1 while preserving their relative directory layout.
• Plain .lua files are retained as source inventory; semantic and taint analysis is derived from bytecode facts.

The analysis currently provides:

• Lua 5.1 bytecode parsing and explicit malformed/unsupported-input diagnostics
• Prototypes, instructions, constants, closures, upvalues, registers, and call sites
• Control flow, dominance, reaching definitions, and def-use relationships
• Global, upvalue, table, alias, and overwrite semantics
• Local call-target and literal-module resolution
• Cross-module exports and module-field calls
• Interprocedural argument, return, vararg, open-result, and tail-call flow
• Callsite-balanced local and cross-module taint tracking
• Resolved API-name source, sink, and sanitizer models
• Active command-injection findings with native CodeQL paths
• Sanitized-path and detailed bytecode-fact diagnostic queries
• BQRS, CSV, JSON, and SARIF result workflows

The analysis core is mature. The initial public queries use CodeQL's experimental query lifecycle while the new language is being adopted upstream.

Review guidance

The implementation is organized into the following review areas:

• Language overview, capability matrix, and usage
• Database schema and stable identity conventions
• Query interfaces and output formats
• Automated test matrix
• Complex integration manifest
• Complex integration oracle

The complex integration test contains 46 Lua source files and 46 corresponding stripped Lua 5.1 bytecode files in a realistic module layout. Its compact oracle verifies artifact acceptance, diagnostics, module resolution, interprocedural flow, cross-module taint flow, active findings, and sanitizer behavior.

Validation

Run the extractor unit tests:

python3 -m unittest discover -s lua/tools/tests -p 'test_*.py' 

Run the complete Lua QL test suite:

CODEQL=/absolute/path/to/codeql
ROOT=$(pwd)

"$CODEQL" test run lua/ql/test \
--search-path="$ROOT:$ROOT/lua"  

Run the complex multi-file integration test independently: 

"$CODEQL" test run \
lua/ql/test/library-tests/complex-bytecode-integration \  
--search-path="$ROOT:$ROOT/lua" 

Compile all public queries with warnings treated as errors:   

"$CODEQL" query compile --check-only --warnings=error \   
--search-path="$ROOT:$ROOT/lua" \   
lua/ql/src/experimental/Security/CWE-078/CommandInjection.ql \  
lua/ql/src/experimental/Diagnostics/SanitizedCommandFlow.ql \   
lua/ql/src/experimental/Diagnostics/LuaBytecodeFacts.ql 

Verify the extractor and QL schema mirrors:

cmp lua/lua.dbscheme lua/ql/lib/lua.dbscheme
cmp lua/lua.dbscheme.stats lua/ql/lib/lua.dbscheme.stats   

## Documentation

- Language overview, capability matrix, and usage (lua/README.md) 
- Database schema and stable identity conventions (lua/SCHEMA.md) 
- Query interfaces and output formats (lua/ql/src/README.md)  
- Automated test matrix (lua/ql/test/library-tests/README.md) 
- Complex integration manifest (lua/ql/test/library-tests/complex-bytecode-integration/SAMPLE-MANIFEST.md) 
- Complex integration oracle (lua/ql/test/library-tests/complex-bytecode-integration/CorpusAcceptance.expected)
- Library change note (lua/ql/lib/change-notes/2026-07-21-lua-bytecode-analysis.md)
- Query change note (lua/ql/src/change-notes/2026-07-21-lua-bytecode-queries.md)   

Generated databases, BQRS files, SARIF reports, logs, and other runtime outputs are intentionally not committed.