Skip to content

tree-sitter: fit script constants and attributes into existing feature set #3158

Open

Description

@mike-hunhoff

Imported constants and environment/module attributes are currently extracted as API features formatted with :: (e.g., api(socket::AF_INET), api(os::environ), api(win32con::FILE_ATTRIBUTE_HIDDEN)).

This causes a few issues for rule authoring:

  1. Misleading feature semantics: socket.AF_INET and os.environ are not callable routines/APIs. Treating them as api confuses rule authors.
  2. Lost rule reuse: Existing rules for native and .NET binaries already match on number: 2 = AF_INET or property/read: .... Having script-specific api(socket::AF_INET) prevents existing rules from matching scripts without adding duplicate statements.
  3. No read vs. write distinction: Module attributes like os.environ can be read or modified, but cannot match property/read or property/write.

Proposed Solution

Fit script constants and attributes into capa's existing feature set without extending rule syntax:

1. Numeric & Enum Constants $\rightarrow$ Number

Map known enum/flag constants in signature files (py.json, cs.json, etc.) to their numeric values and emit them as Number with descriptions:

  • socket.AF_INET $\rightarrow$ number(0x2 = AF_INET)
  • socket.SOCK_STREAM $\rightarrow$ number(0x1 = SOCK_STREAM)
  • win32con.FILE_ATTRIBUTE_HIDDEN $\rightarrow$ number(0x2 = FILE_ATTRIBUTE_HIDDEN)
  • subprocess.PIPE $\rightarrow$ number(-0x1 = PIPE)

Rule Example:
Existing rules written for compiled binaries immediately match scripts:

- and:
  - api: socket.socket
  - number: 2 = AF_INET
  - number: 1 = SOCK_STREAM

2. Object & Environment Attributes $\rightarrow$ Property

Emit module/object attributes (like os.environ, sys.executable, process.env, Process.StartInfo.FileName) as Property using the standard Scope::Member convention (os::environ).

Use AST parent inspection to detect access mode:

  • property/write: Property is the target (left child) of an assignment (e.g., os.environ["appdata"] = "...", p.StartInfo.FileName = "...").
  • property/read: Property is read in an expression, condition, or function argument.
  • property: Generic match for either access type.

Rule Example:

- property/read: os::environ
- property/write: os::environ

Benefits

  • Zero rule syntax changes: Reuses existing number, property, property/read, and property/write keywords.
  • Consistent across languages: Scales cleanly across Python, C#, PowerShell ($env:APPDATA), JavaScript (process.env), and native binaries.
  • Maximized rule reuse: Rules looking for standard OS numbers/flags work across both compiled binaries and scripts out of the box.

Activity

  1. added
    enhancementNew feature or request
    questionFurther information is requested
    gsocWork related to Google Summer of Code project.
    tree-sitterrelated to tree-sitter feature extraction
    on Aug 17, 2026
  2. mike-hunhoff commented on Aug 17, 2026

    @mike-hunhoff
    CollaboratorAuthor

    @saniyafatima07 thoughts on these proposed changes?

  3. saniyafatima07 commented on Aug 18, 2026

    @saniyafatima07
    Collaborator

    @saniyafatima07 thoughts on these proposed changes?

    @mike-hunhoff The proposed changes look convincing to me. Since it's better for us to use the existing capa rule syntax, the above solution would work efficiently.

  4. self-assigned this
    on Aug 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestgsocWork related to Google Summer of Code project.questionFurther information is requestedtree-sitterrelated to tree-sitter feature extraction

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions