Security: Investigate security analysis tooling for the Lua / Control4 driver

[caidurbin]

What to build

Close — or consciously accept — the Lua security-analysis gap. luacheck is a linter, not a security scanner, and the Python SAST tools don't cover Lua. Research options (e.g. Semgrep Lua rules, or custom rules) for the Control4 driver, then either adopt a tool or document the residual risk and rationale.

Acceptance criteria

• Available Lua/Control4 security-analysis options researched and summarized
• A tool is adopted into CI, or a decision to accept the gap is documented (e.g. in an ADR / SECURITY notes)

Blocked by

None - can start immediately

[caidurbin]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Document the conscious decision to accept the Lua/Control4 static-security-analysis gap in a new ADR + a SECURITY.md residual-risk note. The landscape research is already done and validated (below) — the deliverable is authoring the decision record, not re-running the research from scratch.

This brief is the authoritative spec, settled in a triage grilling session plus an Opus research pass. The decision (accept vs adopt) and its rubric are fixed; do not re-litigate them — transcribe and, if you wish, spot-verify the findings against the current tree.

Current behavior:
The Control4 Lua driver (control4/dmp168/src/) has CI linting via luacheck (lint-control4.yml, Lua 5.1.5) and busted unit tests (test-control4.yml), including a shared Python↔Lua differential vector suite (vector_runner.lua). But luacheck is a linter, not a security scanner, and the Python SAST added in #48 doesn't cover Lua. There is no explicit, recorded decision about the Lua security-analysis gap.

Desired behavior:
A reasoned accept-the-gap decision is recorded, with compensating controls and a revisit trigger, so the gap is a conscious choice rather than an oversight:

1. New ADR docs/adr/0015-*.md (follow the existing ADR format; next number is 0015) recording:
   • Decision: accept the Lua/Control4 static-security-analysis gap; do not adopt a Lua SAST tool at this time.
   • Landscape summary (validated — see "Research findings" below): no mature OSS Lua SAST exists; Semgrep's Lua support is experimental-tier (syntactic only, no taint mode, no security ruleset) and clears none of the adoption bar's value criteria.
   • Rationale / adoption bar: a tool would have to be OSS, run on GitHub Actions against Lua 5.1, be low-noise on C4:/generated-code idioms, and catch a real vuln class that luacheck + the differential vector tests miss. Nothing clears it, and the driver has essentially no dangerous sink for one to bite on.
   • Compensating controls (enumerate — see list below).
   • Revisit trigger (see below).
   • Cross-link to the SECURITY.md note.
2. A short residual-risk note in SECURITY.md, adjacent to the existing "Third-party device findings" section: state plainly that the Lua driver relies on luacheck + differential tests + the Composer sandbox rather than a dedicated Lua SAST, and why. Cross-link to ADR-0015.

Research findings to transcribe into the ADR (validated against the current sources):

• No dynamic-code sinks in shipped src/: zero load/loadstring/setfenv/getfenv/dofile/loadfile; require(...) is called only with literal module names; no os.execute. (vector_runner.lua's io.open is a test harness, not shipped in the .c4z.)
• String-pattern use on device bytes is linear (Lua patterns, not PCRE — no backtracking/alternation), so classic ReDoS does not apply. Worth stating explicitly.
• No device-count-driven allocation (string.rep, table pre-sizing, or loop bounds from wire data); tonumber on wire fields fails safe to nil, which the parser handles.
• Semgrep Lua = experimental tier: syntactic matching only, no reliable mode: taint, ~1 registry rule tagged #lua, no p/lua security pack; the notable community set is antipatterns/error-handling, not security. Free + offline-capable (bars 1–2) but fails the value bar (Command.format_result + RenderContext + DMP168 formatters #4).

Compensating controls to cite:

• Composer Lua 5.1 sandbox — no filesystem, no os.execute, network only via the C4: API.
• Static-only module graph — no dynamic code loading; require on literal names only.
• Codegen (ADR-0007) — generated.lua is emitted from a vetted YAML protocol spec, not hand-written wire handling.
• Differential vector tests — shared YAML vectors run through both Python and Lua; divergence on malformed device bytes fails CI.
• Defensive pcall around status_parser.parse in the network-receive path.
• luacheck (std=lua51) — flags undefined/global writes, the closest analog to detecting sandbox-global leakage.
• Narrow untrusted surface — device TCP bytes through a pure, no-I/O status parser, plus Composer-set config (host/port).

Revisit trigger (commit to this in the ADR): reconsider adoption if any of —

• the driver introduces load/loadstring/loadfile/dofile/setfenv, or a dynamic require() whose name derives from config/device data;
• hand-written (non-generated) wire serialization/parsing that builds Lua/command strings appears;
• any allocation/loop bound becomes driven by a device-controlled count;
• Semgrep promotes Lua to beta/GA with working taint mode and a real p/lua security pack — at which point evaluate a report-only (never blocking) lane.

Acceptance criteria:

• docs/adr/0015-*.md exists, follows the repo ADR format, and records the accept-the-gap decision with landscape summary, adoption-bar rationale, compensating controls, and the revisit trigger
• SECURITY.md has a short residual-risk note (by "Third-party device findings") describing the Lua security posture, cross-linked to ADR-0015
• No new CI tool is added (accept-the-gap outcome); existing lint-control4.yml / test-control4.yml are unchanged
• Claims in the ADR are consistent with the current control4/dmp168/src/ sources (spot-verify the "no dynamic sinks" claim still holds)

Out of scope:

• The unbounded status_buffer growth in driver.lua ReceivedFromNetwork — a real low-severity availability bug found during this research, but a code fix (byte cap + busted test), not a tooling-decision. Tracked separately (see the linked bug issue); do not fix it here.
• Actually adopting a Lua SAST tool — the decision is accept-the-gap; adoption is gated on the revisit trigger.
• .c4z packaging / build supply-chain hardening — that's provenance (Security: Release artifact provenance for c4z (and HACS) — SLSA attestation + checksums #46) and Actions static analysis (Security: GitHub Actions static analysis in CI (zizmor / poutine) #43).
• Python SAST / dependency scanning — that's Security: Python SAST (CodeQL) + dependency vulnerability scanning (pip-audit / osv-scanner) #48.

[caidurbin]

This was generated by AI during triage.

The "linked bug issue" referenced in the brief above (the unbounded status_buffer growth found during this research) is now filed as #81 — ready-for-agent. It stays out of scope for this issue, which is the accept-the-gap decision record only.