RFC: Lightweight Data-Flow Tracking for Cross-Instruction Capability Detection

[akshat4703]

RFC: Argument-Aware Matching for Dynamic Analysis (Value-Semantic Call Features)

Motivation

Right now, many dynamic detections rely on the presence of API calls, but they can't easily express constraints on the actual argument values passed at runtime. In practice, the meaning of a capability often depends not just on which API is called, but also on how it is called.

For example:

• flags passed to functions such as CreateFile, OpenProcess, or VirtualAlloc
• command fragments passed to shell execution APIs
• file paths or registry keys used in system modification
• mode or permission values
• container arguments such as arrays or structured parameters

Without argument-aware matching, rules may end up being either too broad (causing false positives) or require awkward workarounds.

This discussion proposes adding argument-aware matching so rules can match on meaningful runtime parameters observed in dynamic analysis.

Goals

The goal is to make detections more precise and allow rules to capture behaviors that are currently difficult to express using API presence alone.

Some high-level goals would be:

• allow rules to match specific argument values
• keep rule syntax readable and simple
• support multiple dynamic analysis providers
• maintain backward compatibility with existing rules

Possible Direction

One idea is to introduce a feature model that lets rules reference arguments of observed API calls.

Conceptually, this could allow rules to express things like:

• API call + specific flag value
• API call + string argument containing a path or command
• API call + structured parameter containing a specific field
• API call + container argument containing a specific element

Example (conceptual):

api: CreateFile
  and
argument[1]: "C:\\Windows\\System32"

Or:

api: OpenProcess
  and
argument[2]: PROCESS_VM_READ

This could help model behaviors such as:

• credential access
• process injection
• persistence using specific registry paths
• suspicious command execution
• targeted file operations

Cross-Provider Considerations

Since capa can work with different dynamic analysis providers (for example VMRay), some normalization may be required so argument values are represented consistently.

Some considerations might include:

• how providers extract and expose argument values
• how to represent structured or container parameters
• how symbolic values like flags should appear in rules

Compatibility

Existing rules should continue to work exactly as they do today. Argument-aware matching would simply be an optional capability used in rules that need it.

Open Questions

A few questions that might be worth discussing:

1. What argument types should be supported initially?

   • scalar values
   • strings
   • arrays or containers
   • structured parameters

2. How expressive should the rule syntax be while still remaining readable?

3. What kind of normalization layer might be needed for cross-provider consistency?

4. Are there performance concerns when extracting and matching arguments from large dynamic traces?

5. Should argument extraction be handled mostly by providers, or partially within capa itself?

Feedback

I'd be interested to hear thoughts from maintainers and the community on:

• whether this idea aligns with capa’s design philosophy
• potential ways to represent argument features in rules
• implementation constraints or performance considerations

[williballenthin]

how does this differ from the existing call scope?

[akshat4703]

@williballenthin From what I understand, the current call scope mainly helps answer the question:
“did these features appear within the same call context?”

So it lets us group things that occur around a specific API call, such as strings, constants, or other indicators observed during that call.

What it doesn’t really capture is the exact value passed to a specific argument position.

The idea behind dynamic argument-aware matching would be to allow rules to reason about those argument values directly. For example:

api: CreateFileW and arg[1] == "C:\Windows\..."
api: RegSetValueExW and arg[0] matches /Run/i
api: CreateServiceW and arg[2] has SERVICE_AUTO_START

So the way I see the difference is:

Current call scope
→ mainly ensures that features occurred in the same call event or context.

Argument-aware matching
→ would allow explicit constraints on argument positions and values, potentially including strings, flags, arrays, or other structured arguments, ideally normalized across providers.

Because of that, it feels more like a larger feature or engine-level capability rather than just another scope option.