Security: Python SAST (CodeQL) + dependency vulnerability scanning (pip-audit / osv-scanner)

[caidurbin]

What to build

Add code-level security analysis for the Python surface. Enable CodeQL (free for public repos) for the integration + library, optionally complemented by Bandit/Semgrep, and add dependency vulnerability scanning (pip-audit and/or osv-scanner over uv.lock) to CI so known-vulnerable dependencies are caught.

Acceptance criteria

• CodeQL analysis runs in CI for Python and surfaces results in the Security tab
• pip-audit and/or osv-scanner runs against uv.lock in CI
• Policy decided for how findings gate CI (fail vs report)

Blocked by

None - can start immediately

[caidurbin]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add Python SAST (CodeQL, advanced setup) + dependency vulnerability scanning (osv-scanner) to CI, with a hybrid gating policy, and close the "optionally complemented by Bandit" clause via ruff's S ruleset rather than a second tool.

This brief is the authoritative spec — it supersedes the original issue body where they differ. Every decision below was settled in a triage grilling session (including two Opus research passes).

Current behavior:
CI has no code-level security analysis and no dependency vulnerability scanning. Workflows are granular, path-scoped, use SHA-pinned actions and astral-sh/setup-uv, and default to permissions: contents: read (see the existing lint-*/test-*/secret-scan workflows as the house-style model). A single root pyproject.toml + uv.lock manage Python; the HA integration consumes the published blustream PyPI package. Ruff runs in the library lint job with select = ["E","F","I","N","W","UP"] — the security ruleset S is not enabled.

Desired behavior:

CodeQL (SAST):

• CodeQL runs via advanced setup — a committed workflow (not the Security-tab default setup), matching house style — analyzing Python with the security-extended (a.k.a. python-security-extended) query suite.
• Results upload as SARIF to the Security tab and are non-blocking — they must not fail PR checks (SAST false positives shouldn't gate a solo maintainer's merges).
• A codeql-config excludes noise so alerts stay actionable: paths-ignore for tests/**, **/_generated.py (codegen output — fixes belong upstream in the spec/templates, not the generated file), and vendored/build dirs (.venv/**, build/**, node_modules/**). Analyze all other first-party Python (blustream/ incl. CLI, custom_components/, spec/, tools/, top-level scripts).
• Triggers: PR + push to main, path-scoped to **/*.py + the workflow file, plus a weekly schedule as a full-coverage safety net.

osv-scanner (dependency vulns):

• On PRs: differential scan — fails the PR only when the PR introduces a new vulnerable dependency (new/changed entries in a lockfile). A PR that doesn't touch dependencies is never blocked by a pre-existing or newly-disclosed CVE.
• On push-to-main + the weekly schedule: full scan → SARIF to the Security tab (non-blocking), so newly-disclosed CVEs on existing deps surface as alerts without wedging unrelated merges.
• Covers both uv.lock (primary) and package-lock.json (npm dev tooling — free bonus).
• A checked-in osv-scanner.toml ignore-list is the escape hatch for consciously-accepted findings — each entry carries a rationale (same suppress-with-rationale model as Security: GitHub Actions static analysis in CI (zizmor / poutine) #43).

ruff S (the "optionally complemented by Bandit" clause):

• Add S (flake8-bandit) to the ruff select in the existing library lint job. This ports Bandit's ruleset into the gate you already run — no second SAST tool, no extra SARIF surface, native inline suppression.
• Suppress the known-intentional findings so the job passes clean: # noqa: S101 on the deliberate assert invariant-guards in the HA config_flow/repairs code, and acknowledge S603/S607 on the two static-argv subprocess calls in tools/ (ping -c 1 <ip> and the pinned git invocation) — both verified injection-free.

Key interfaces / house-style constraints:

• New workflow(s) follow the existing conventions: SHA-pinned action refs, least-privilege permissions (CodeQL needs security-events: write; osv-scanner's SARIF upload likewise), astral-sh/setup-uv where Python deps are needed.
• Organize as separate concern-scoped workflows (e.g. a CodeQL workflow and an osv-scanner workflow) to match the granular lint-*/test-* family — don't bolt onto an unrelated job. Using osv-scanner's official reusable workflows for the differential-PR and scheduled-full patterns is encouraged.
• The ruff change is a one-line select edit in pyproject.toml + the targeted suppressions; the library lint workflow itself shouldn't need structural change.

Acceptance criteria:

• CodeQL analysis runs in CI for Python via a committed (advanced-setup) workflow and surfaces results in the Security tab
• CodeQL is scoped with paths-ignore for tests/**, **/_generated.py, and vendor/build dirs; runs on PR/push (Python-path-scoped) + a weekly schedule; findings are non-blocking
• osv-scanner runs a differential scan on PRs that fails only when the PR introduces a vulnerable dependency, covering uv.lock and package-lock.json
• osv-scanner runs a full scan on push-to-main + weekly schedule, uploading SARIF to the Security tab (non-blocking), with an osv-scanner.toml ignore-list mechanism in place
• ruff S is enabled in the library lint job and the lint job passes green, with intentional assert/subprocess findings suppressed with rationale
• The gating policy is documented (in the workflow(s) or SECURITY notes): CodeQL non-blocking; dependency gate blocks only newly-introduced vulns; ruff-S blocks via the existing lint gate

Out of scope:

• Bandit and Semgrep as standalone tools — deliberately rejected (Opus research: no dangerous sinks present for Bandit to catch; Semgrep's custom-rule value is already covered more precisely by the codegen golden/differential tests). Revisit Semgrep (report-only, p/python + a custom rule) only if the CLI/tools/ later build dynamic subprocess argv or filesystem paths from untrusted/config input.
• Lua/Control4 security analysis — tracked separately in Security: Investigate security analysis tooling for the Lua / Control4 driver #49.
• GitHub Actions workflow static analysis (zizmor/poutine) — that's Security: GitHub Actions static analysis in CI (zizmor / poutine) #43.
• Making CodeQL a required/blocking PR check, or enabling CodeQL default setup via the Security-tab UI.
• Auto-remediation of any findings surfaced by the first scans (fix real ones; this issue is about standing up the scanning, not clearing a backlog).