Skip to content

scan: propose a verb for the default vocabulary, with the measurement #113

Description

@arpanghoshal

ctrlrun scan reports the consequential call sites a policy is not covering. It finds them with
a declared vocabulary of verbs — refund, delete, deploy, grant, 26 of them in
src/ctrlrun/scan.py — matched as whole _-separated words in a call
path.

docs/SPEC-scan.md §11 says the list "is a first list and will be wrong in both directions."
This issue is the invitation to correct it in one direction.

What to send

One verb, with the measurement. Not a list of verbs that sound consequential.

  • The verb, and the real SDK call paths it matches — stripe.subscriptions.<verb>,
    boto3.client(...).<verb>_bucket, whatever it is.
  • The count. Run ctrlrun scan --path <a real tree> before and after adding it. Say how
    many findings it added and how many of those were actions somebody would want gated.
  • The unit test, in the file where the vocabulary tests already live.
  • A line for the changelog: a change to this list is a change a release note names.

Why the measurement is the point

execute was in the first draft and was removed, because cursor.execute appears in every
project that touches a database: measured against this repository's own src/, it was 90 of
208 findings. A verb that matches thousands of lines buries the ones that matter. So a verb
arrives with its cost, or it does not arrive.

The reverse direction — a verb in the list that is mostly noise on real code — is just as
welcome, with the same measurement.

Read docs/SPEC-scan.md §3.2 and §11 first. Note that --vocabulary <file> already lets an
operator replace the list entirely, so this is about the default, which is what somebody gets
on their first run.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions