Skip to content

ci(codeql): enforce that py/unsafe-cyclic-import suppression stays narrow #229

@cagataycali

Description

@cagataycali

Problem

.github/codeql/config.yml ships a global query-filters exclude for py/unsafe-cyclic-import. The simulation triple (base.py, policy_runner.py, benchmark.py) is the only file shape in the repository that fires the rule today, but query-filters doesn't support path scoping, so the exclude is repository-wide.

The README in .github/codeql/ documents a manual six-month audit recipe to verify no new legitimate violations have been silently suppressed. A calendar-pin is a maintainer-rotation failure mode: when the maintainer who wrote the audit cadence rotates off the project, the assumption drifts silently.

Proposed fix

Add a CI step (or a workflow_dispatch job) that:

  1. Drops the query-filters exclude block from .github/codeql/config.yml (in-memory only -- not committed).
  2. Runs the CodeQL CLI locally per the recipe in .github/codeql/README.md:
    codeql database create db --language=python --source-root=.
    codeql database analyze db codeql/python-queries:Imports/UnsafeCyclicImport.ql --format=sarif-latest --output=cyclic-import.sarif
  3. Parses the SARIF and asserts the violating file set is exactly {strands_robots/simulation/base.py, strands_robots/simulation/policy_runner.py, strands_robots/simulation/benchmark.py}.
  4. Fails the workflow with a clear diagnostic if the set has expanded -- the maintainer must either drop the suppression entirely (preferred -- fix the new cycle properly) or explicitly extend it with a documented rationale.

Acceptance criteria

  • CI step exists that runs the CodeQL CLI with the suppression dropped
  • The step asserts the violating file set against the canonical simulation triple
  • Failure mode is loud (red CI, clear diagnostic, points at .github/codeql/README.md for the override path)
  • Step runs on every PR that touches strands_robots/simulation/ or .github/codeql/ (path filter), and on a weekly cron for everything else
  • Documented in .github/codeql/README.md next to the existing manual audit recipe

Design questions to resolve in the implementing PR

  • Where to install the CodeQL CLI in CI: on ubuntu-latest via the bundled action, or via curl from the GitHub release? (The bundled action is simpler but less explicit about version pinning.)
  • Runtime cost: the recipe builds a database from scratch -- estimate is 60-120s per run on the simulation triple alone. Acceptable for path-filtered PRs; the weekly cron is no concern.
  • Whether to make the assertion a hard fail or a soft warning on first introduction. Hard fail is the loud-on-misconfig posture this issue exists to enforce.
  • Whether the assertion should also catch removal of one of the three triple modules from the violating set (e.g. someone refactors benchmark.py so it no longer participates in the cycle). That's not strictly a regression, but it changes the suppression's scope and deserves a docs update.

Context


Filed by autonomous agent. Strands Agents.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    Status
    Backlog

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions