Charon/docs/plans/current_spec.md

CodeQL Go Coverage RCA (2026-02-18)

1) Observed Evidence (exact commands/workflow paths/config knobs that control scope)

• Local CI-aligned command in VS Code task Security: CodeQL Go Scan (CI-Aligned) [~60s]:
  • codeql database create codeql-db-go --language=go --source-root=backend --codescanning-config=.github/codeql/codeql-config.yml --overwrite --threads=0
  • codeql database analyze codeql-db-go --additional-packs=codeql-custom-queries-go --format=sarif-latest --output=codeql-results-go.sarif --sarif-add-baseline-file-info --threads=0
• Local pre-commit CodeQL Go scan command (scripts/pre-commit-hooks/codeql-go-scan.sh):
  • codeql database analyze codeql-db-go codeql/go-queries:codeql-suites/go-security-and-quality.qls --format=sarif-latest --output=codeql-results-go.sarif --sarif-add-baseline-file-info --threads=0
• Reproduced analyzer output from local run:
  • CodeQL scanned 175 out of 436 Go files in this invocation.
  • Path filters have no effect for Go... 'paths' and 'paths-ignore' ... have no effect for this language.
• Workflow controlling CI scan: .github/workflows/codeql.yml
  • on.pull_request.branches: [main, nightly]
  • on.push.branches: [main, nightly, development]
  • Uses github/codeql-action/init + autobuild + analyze.
  • init currently does not set queries, so suite selection is implicit.
  • Uses config file ./.github/codeql/codeql-config.yml.
• Config file: .github/codeql/codeql-config.yml
  • Only paths-ignore entries for coverage/build artifacts; no Go-specific exclusions.
• Ground-truth file counts:
  • find backend -type f -name '*.go' | wc -l => 436
  • find backend -type f -name '*.go' ! -name '*_test.go' | wc -l => 177
  • go list -json ./... | jq -s 'map((.GoFiles|length)+(.CgoFiles|length))|add' => 175
• Target file verification:
  • Local scan output includes extraction of backend/internal/api/handlers/system_permissions_handler.go.
  • SARIF contains go/path-injection findings in that file.

2) Why 175/436 happens (expected vs misconfiguration)

• Expected behavior (primary):
  • 436 is a raw repository count including *_test.go and non-build files.
  • Go CodeQL analyzes build-resolved files (roughly Go compiler view), not all raw .go files.
  • Build-resolved count is 175, which exactly matches go list compiled files.
• Denominator inflation details:
  • 259 files are *_test.go and are not part of normal build-resolved extraction.
  • Two non-test files are also excluded from compiled set:
    • backend/internal/api/handlers/security_handler_test_fixed.go (//go:build ignore)
    • backend/.venv/.../empty_template_main.go (not in module package graph)
• Conclusion: 175/436 is mostly expected Go extractor semantics, not a direct scope misconfiguration by itself.

3) How this could miss findings

• Build tags / ignored files:
  • Files behind build constraints (for example //go:build ignore) are excluded from compiled extraction; findings there are missed.
• Path filters:
  • For Go, paths / paths-ignore do not reduce extraction scope (confirmed by CodeQL diagnostic).
  • Therefore .github/codeql/codeql-config.yml is not the cause of reduced Go coverage.
• Generated or non-module files:
  • Files outside the module/package graph (for example under .venv) can appear in raw counts but are not analyzed.
• Uncompiled packages/files:
  • Any code not reachable in package resolution/build context will not be analyzed.
• Trigger gaps (CI event coverage):
  • pull_request only targets main and nightly; PRs to development are not scanned by CodeQL workflow.
  • push only scans main/nightly/development; feature-branch pushes are not scanned.
• Baseline behavior:
  • --sarif-add-baseline-file-info adds baseline metadata; it does not itself suppress extraction.
  • Alert visibility can still appear delayed based on when a qualifying workflow run uploads SARIF.
• Local/CI suite drift (explicit evidence):
  • CI workflow (.github/workflows/codeql.yml) and VS Code CI-aligned task (.vscode/tasks.json) use implicit/default suite selection.
  • Pre-commit Go scan (scripts/pre-commit-hooks/codeql-go-scan.sh) pins explicit go-security-and-quality.qls.

4) Why finding appeared now (most plausible ranked causes with confidence)

1. Trigger-path visibility gap (Plausible hypothesis, 0.60)
   • The code likely existed before, but this remains a hypothesis unless workflow history shows explicit missing qualifying runs for the affected branch/PR path.
2. Local/CI command drift labeled as “CI-aligned” (Medium-High, 0.70)
   • Different entrypoints use different suite semantics (explicit in pre-commit vs implicit in workflow/task), increasing chance of inconsistent detection timing.
3. Query/toolpack evolution over time (Medium, 0.55)
   • Updated CodeQL packs/engines can surface dataflow paths not previously reported.
4. Extractor file-count misunderstanding (Low, 0.25)
   • 175/436 itself did not hide system_permissions_handler.go; that file is in the extracted set.

5) Prevention controls (local + CI): exact changes to scan commands/workflows/policies

• CI workflow controls (.github/workflows/codeql.yml):
  • Expand PR coverage to include development:
    • on.pull_request.branches: [main, nightly, development]
  • Expand push coverage to active delivery branches (or remove push branch filter if acceptable).
  • Pin query suite explicitly in init (avoid implicit defaults):
    • add queries: security-and-quality
• Local command controls (make truly CI-aligned):
  • Require one canonical local invocation path (single source of truth):
    • Prefer VS Code task calling scripts/pre-commit-hooks/codeql-go-scan.sh.
  • If task remains standalone, it must pin explicit suite:
    • codeql database analyze codeql-db-go codeql/go-queries:codeql-suites/go-security-and-quality.qls --additional-packs=codeql-custom-queries-go ...
• Policy controls:
  • Require CodeQL checks as branch-protection gates on main, nightly, and development.
  • Add a parity check that fails when suite selection diverges across workflow, VS Code local task, and pre-commit script.
  • Keep reporting both metrics in documentation/logs:
    • raw .go count
    • compiled/extracted .go count (go list-derived)
  • Add metric guardrail: fail the run when extracted compiled Go count diverges from the go list compiled baseline beyond approved tolerance.

6) Verification checklist

• Run and record raw vs compiled counts:
  • find backend -type f -name '*.go' | wc -l
  • cd backend && go list -json ./... | jq -s 'map((.GoFiles|length)+(.CgoFiles|length))|add'
• Run local CodeQL Go scan and confirm diagnostic line:
  • CodeQL scanned X out of Y Go files...
• Compare extraction metric to compiler baseline and fail on unexpected divergence:
  • baseline: cd backend && go list -json ./... | jq -s 'map((.GoFiles|length)+(.CgoFiles|length))|add'
  • extracted: parse CodeQL scanned X out of Y Go files... and assert X == baseline (or documented tolerance)
• Confirm target file is extracted:
  • local output includes Done extracting .../system_permissions_handler.go
• Confirm SARIF includes expected finding for file:
  • jq filter on system_permissions_handler.go
• Validate CI workflow trigger coverage includes intended PR targets/branches.
• Validate workflow and local command both use explicit security-and-quality suite.

7) PR Slicing Strategy

• Decision: Multiple PRs (3), to reduce rollout risk and simplify review.

• Trigger reasons: Cross-domain change (workflow + local tooling + policy), security-sensitive, and high review impact if combined.

• PR-1: CI Trigger/Suite Hardening

  • Scope: .github/workflows/codeql.yml
  • Changes: broaden pull_request branch targets, keep/expand push coverage, set explicit queries: security-and-quality.
  • Dependencies: none.
  • Validation gate: actionlint + successful CodeQL run on PR to development.
  • Rollback: revert workflow file only.

• PR-2: Local Command Convergence

  • Scope: .vscode/tasks.json and/or canonical script wrapper.
  • Changes: enforce explicit go-security-and-quality.qls in local Go task, keep custom pack additive only.
  • Dependencies: PR-1 preferred, not hard-required.
  • Validation gate: local task output shows explicit suite and reproducible SARIF.
  • Rollback: revert tasks/scripts without affecting CI.

• PR-3: Governance/Policy Guardrails

  • Scope: branch protection requirements + parity check job/documentation.
  • Changes: require CodeQL checks on main/nightly/development; add drift guard.
  • Dependencies: PR-1 and PR-2.
  • Validation gate: blocked merge when CodeQL missing/failing or parity check fails.