Skip to main content

Detailed Element Description

Simple Elements​

The scheme supports the writing of information about multiple entities: classes, methods, variables, etc.

To describe them, common rule elements are often used:

  • Name element describes a name and includes one of the sub-elements: Value, Regex. Value specifies an entity name explicitly, while Regex contains a regular expression defining an entity name.

  • Entity type/class is specified by Type or Class. A Type element contains a string value (primitive type name or full class name), while a Class element may contain more complex conditions (see Class description).

Boolean Logic​

Many elements may contain logical expressions. For example, condition ”method name does not match method” may be written as follows:

<Method>
    <Name>
        <Not>
            <Value>Method</Value>
        </Not>
    </Name>
</Method>

Patterns format does not limit nesting of logical constructs, thus making it possible to define complex methods for vulnerability searching. Logical expressions are permitted for the following elements: Constant, Parameter, Method, Field, Class, Variable, Argument, Instruction, CatchBlock.

Identifiers and References​

Many elements may be used with identifiers, which can identify an entity inside a Definitions (by specifying a unique id) attribute within a pattern and refer to it in this pattern by using a Ref element containing two attributes: id (identifier) and reftype (reference type that may have one of the following values: classref, methodref, instructionref, catchblockref, fieldref, variableref, parameterref, argumentref, constantref). As a result, you can specify a class1 identifier for a class as follows:

<Class id="class1">
    ...
</Class>

You can refer to the class in the given pattern as follows:

<Class>
    <Ref id="class1" reftype="classref"/>
</Class>

Constants​

You can use a Constant element to write down conditions containing constants. A Constant element contains one of the following elements: ConstantString, ConstantInt, ConstantBoolean, Null.

A ConstantString contains one of the following elements: Value, Regex (similar to Name).

ConstantInt contains an integer constant or a logical expression containing conditions with integer constants and supporting Boolean logic and arithmetic conditions: Eq (equal), Ne (not equal), Lt (less than), Gt (greater than), Le (less than or equal), Ge (greater than or equal).

Pattern Flags​

Source and passthrough pattern flags​

Source and passthrough patterns show how flags must be changed under specific conditions. These conditions are set in the ChangeFlags element.

The ChangeFlags element contains one or more FlagsSet element. Each FlagsSet element shows how flags must be changed for a specified set of entities (arguments).

The FlagsSet element contains the following elements: To, From, FlagsDiff and an optional clearAll attribute that can be either true or false.

To and From elements define entities (or references to entities specified in Definitions) involved in flag changing, with it being possible to flag the following entities: Argument, Range (see Description of an instruction in a code). A passthrough pattern contains both To and From elements, while a source pattern contains only a To element.

FlagsDiff contains a string specifying flag changes, which are separated by commas and have the following format:

  • +FLAG: add FLAG
  • -FLAG: remove FLAG if it exists
  • !FLAG: change value of FLAG if it exists

Flags are changed according to the following algorithm:

  • If clearAll element is true, then remove all flags from entities specified in To
  • Assign flags of entities specified in From, to entities specified in To
  • Change flags of entities specified in To according to FlagsDiff

Sink Pattern Flags​

The Flags element in sink patterns specifies a condition for entity (usually argument) flags which, when being executed, makes the construct insecure.

The Flags element consists of one or more Flag elements, each of which specifies a single flag, with logical constructs being allowed. For example, the condition ”FLAG1 is set or FLAG2 is not set” may be written as follows:

<Flags>
    <Or>
        <Flag>FLAG1</Flag>
        <Not>
            <Flag>FLAG2</Flag>
        </Not>
    </Or>
</Flags>

By default, flags are connected by AND predicate. For example, the

<Flags>
    <Flag>FLAG1</Flag>
    <Flag>FLAG2</Flag>
</Flags>

expression specifies the condition ”FLAG1 is set and FLAG2 is set”.

Class Description​

Class element contains the following elements:

  • Modifier to specify class modifiers
  • Name to specify class name
  • Supers to specify a condition for superclasses. For example, the following record:
<Class includeSelf="true">
    <Supers>
        <Class>...

corresponds to a condition ”there is a class that meets the condition among superclasses”. The includeSelf attribute specifies whether the class itself should be included into a set of superclasses and can be either true or false.

  • Method: specifies a condition for a class method (see Method description).
  • Field to specify a condition for a class field.

Method Description​

Method element contains the following elements:

  • Modifier to specify method modifiers.
  • Name to specify method name. If the method is a constructor, then a special empty element Constructor is used instead of a Name.
  • Parameters to specify a condition for a set of formal class parameters and to include one or more Parameter, WildCard, Range.
  • Parameter to contain Type or Class element and to specify if a method has a parameter of this particular type on a current position.
  • WildCard to specify if a method has several parameters of arbitrary types in the quantity from min to max or in the quantity strictly equal to num (min, max, num are attributes of WildCard element), with min equal to 0 by default and max equal to infinity. Therefore, <WildCard min="2" /> means "with two or more parameters" and <WildCard /> means "with any set of parameters".
  • Throws to define types of exceptions that a class may generate.

Description of an Instruction in Code​

Instruction element contains the following elements: Class, Method, Arguments and defines a call of a specified method of a specified class with specified arguments.

Class, Method elements are described in Class description and Method description.

Arguments element defines a set of actual call arguments and contains one or more Argument or Range elements.

Argument element defines a condition for one actual argument and contains the following elements:

  • Pos (argument position, starting from 0) or This (if Argument is a current object) or Return (if Argument is a value to be returned).

  • Type or Class.

  • Constant if a condition for argument value is specified by using constants (see Constants).

  • Flags if a condition is specified for flags (see Sink pattern flags).

Range element contains sub-elements PosMin, PosMax, Flags and defines a group of consecutive arguments, starting from the PosMin index and ending with (inclusive) the PosMax index (numbering starts from 0). The Flags element specifies conditions for flags for a group of arguments (see Sink pattern flags).