Repository navigation
Description
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:
- Misleading feature semantics:
socket.AF_INETandos.environare not callable routines/APIs. Treating them asapiconfuses rule authors. - Lost rule reuse: Existing rules for native and .NET binaries already match on
number: 2 = AF_INETorproperty/read: .... Having script-specificapi(socket::AF_INET)prevents existing rules from matching scripts without adding duplicate statements. - No read vs. write distinction: Module attributes like
os.environcan be read or modified, but cannot matchproperty/readorproperty/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_STREAM2. 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 (leftchild) 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::environBenefits
- Zero rule syntax changes: Reuses existing
number,property,property/read, andproperty/writekeywords. - 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
mike-hunhoff commentedon Aug 17, 2026
@saniyafatima07 thoughts on these proposed changes?
saniyafatima07 commentedon Aug 18, 2026
@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.