function call arguments syntax

[williballenthin]

In #771 we describe a potential new rule feature that lets authors describe the parameters passed to functions. While the exact behavior is not yet specified, let's discuss here how rules should look that use this feature.

Some things to consider when proposing a syntax:

• is this a new subscope? therefore does it stand on its own as a rule scope?
• or, is this a new block?
• how is the function name specified? is it required?
• how to handle indirect calls?
• how are the arguments specified?
• can logic be mixed with function name/arguments? e.g. "path is foo.exe OR bar.exe"

[williballenthin]

extend the existing API feature to optionally expect a block that specifies arguments:

- api: CreateFileA
  - ...: "bad.exe"

pros:

• works well with existing rules and syntax

cons:

• complexity of handling optional block
• can't have logic around the function name, like "CreateFile" OR "DeleteFile"

[williballenthin]

Let users refer to arguments by their declared name, such as those displayed by MSDN:

- api: CreateFileA
  args: 
  - lpFileName: "bad.exe"

lpFileName is an alias for args[0] in the context of CreateFileA

pros:

• very readable for humans

cons:

• have to maintain a database of functions and argument names
• what if the argument name is invalid? can handle this in the linter

[williballenthin]

Specify arguments in array-like manner args[0], args[1], etc. (versus keyword-like args0).

- api: CreateFileA
  args[0]: "bad.exe"

[williballenthin]

this doesn't actually have to be an array, but the syntax should look like this

[williballenthin]

this type of syntax is implemented for the instruction scope in #930

[williballenthin]

Introduce a new block for call scope, like:

- call:
  - name: CreateFileA
  - args[0]: "bad.exe"

this would enable logic around the function name, maybe like:

- call:
  - or:
    - name: CreateFileA
    - name: DeleteFile
  - args[0]: "bad.exe"

pro:

• more flexible logic

cons:

• do we need this logic? do parameters often overlap like this?
• yet another block type/keyword

[williballenthin]

perhaps this can be the underlying implementation, because it maps nicely to a new block/scope/subscope. the other syntax (api: foo with args) can translate into this behind the scenes.

[williballenthin]

this approach also enables rules with scope: call

[williballenthin]

i think we'd better require that at least one name must be specified. otherwise, i think it will be difficult to optimize the matching here.

probably also should not support not: name: foo because this doesn't let us optimize.

furthermore, we can't reason about argument names between most functions, so care is needed here that the functions have compatible prototypes.

[mr-tz]

I like this syntax with a new call scope the most.

• call should have no (indirect call) or one name (no or needed, IMO)
• logical combinations of multiple arguments should be supported

[williballenthin]

Specify arguments by keywords arg0, arg1, etc. (versus array-like args[0]):

- api: CreateFileA
  - arg0: "bad.exe"

[williballenthin]

this is one of the few proposals here that i don't like.

[williballenthin]

Enable rules to specify logic for the values of arguments, like:

- api: CreateFileA
  args: 
    - or:
      - dwCreationDisposition: 2 = CREATE_ALWAYS
      - dwCreationDisposition: 1 = CREATE_NEW

pro:

• otherwise would need many similar blocks, combinatorial explosion

con:

• ?

[williballenthin]

im not sure if the parameter names need to be nested under args.* or not.

if so, its nicely namespaced and separated from any other features we might add here (like calling convention, return value, etc). but, its a little noisy. so not using the namespace is easier to read.

[williballenthin]

Enable rules to specify regular expression for the string value of arguments, like:

- api: CreateFileA
  args:  
  - lpFileName: /.exe$/

pro:

• more expressive
• consistent with other string matching features

con:

• performance?

[williballenthin]

Enable rules to specify a description related to argument features, like:

- api: CreateFileA
  args:  
  - lpFileName: "bad.exe"
    description: the name of some malware

pro:

• thorough documentation
• consistent with other features

con:

• ?

[williballenthin]

Make the argument specification literally an array.

- api: CreateFileA
  args:
  - *
  - GENERIC_READ  

pro:

• its literal yaml

con:

• the values are dissociated from their names/indices
• what about trailing args? do they have to be specified?

[williballenthin]

i don't like this, but providing for completeness

[williballenthin]

Consider making the top level node an AND implicitly, such that the following are equivalent:

  - api: CreateFileA
    lpFilePath: "bad.exe"
    dwCreationDisposition: 1 = CREATE_NEW

- call:
  - and: 
    - api: CreateFileA
    - lpFilePath: "bad.exe"
    - dwCreationDisposition: 1 = CREATE_NEW

pros:

• more succinct

cons:

• a little magic
• vverbose rendering will take a little work

[williballenthin]

this type of syntax is implemented for the instruction scope in #930

[mr-tz]

One concern with the specified arguments (args[] index or specific name) is the reliability of the analysis engines to recognize these. Should we maybe explore this first before betting on it to work in most cases?

For the most rules we currently have, the specific argument offset is nice to have, but not needed, because we look for API + constant mostly there.

I would favor the more detailed feature extraction and rule syntax, however, don't have much experience on how vivisect (or SMDA) perform here.

[williballenthin]

I agree that viv and/or SMDA may have a hard time extracting arguments. TBH I think this remains a risk for our x86 backend. We probably have to do some research to figure out whats feasible here; perhaps if we emulate the prior BB and then inspect reg/stack we can approximate most arguments.

I think we'll be able to reliably recover .NET arguments (though still not proven).

I think we can translate exact argument indices into a "bag of arguments" if we have to fall back on a simpler mechanism to extract arguments. e.g. we could duplicate args[0], args[1], ... to unnamed argument features while we figure things out. but, for backends that support nearly exact extraction, we can use the specificity correctly.