Skip to main content

match_pattern

Synopsis​

@match_pattern(Signature) -> Boolean

Description​

This function enables content scanning functionality within scenarios. It is a powerful feature that allows for cross-object, and even cross-context pattern matching when used with scenarios that make use of the global context.

info

Available in Contextal Platform 1.1 and later.

Notes​

When a scenario using @match_pattern is added, the platform registers a new pattern, which is applied during the processing of new objects. Each pattern is assigned an internal name in the format ContexQL.Pattern.*. When a match occurs, this name is recorded as an object's symbol.

info

The platform automatically translates matched patterns into respective symbols, making it possible to use @match_pattern in regular search queries. However, this functionality is limited to objects processed after the respective patterns were registered by their scenarios. As a result, search results may not always be fully accurate for objects processed prior to pattern registration.

Parameters​

  • Signature: A pattern in a simplified version of ClamAV's Extended Signature format, with additional support for direct strings:
[Offset:]String
[Offset:]HexSignature

Where:

  • Offset (optional): The position in the file to match the signature. Possible values include:
    • n: A decimal number specifying the offset.
    • EOF-n: Specifies an offset relative to the end of the file.
    • *: Matches the signature at any offset (default if not specified).
  • String: A String object, which is automatically converted into HexSignature.
  • HexSignature: A ClamAV hexadecimal format signature.

Return value​

Boolean: true if the object matches the pattern (i.e. its symbols contain the pattern's automatically assigned name), false otherwise.

Examples​

Match at any offset​

@match_pattern("invoice")

Matches if the object contains the string invoice at any offset.

@match_pattern(deadbeef)

Matches if the object contains the four bytes DE AD BE EF at any offset.

Match at specific offset​

@match_pattern(0:3c3f786d6c20)
@match_pattern(0:"<?xml ")

These functions are equal and match if the object starts with <?xml .

Match relative to file end​

@match_pattern(EOF-6:0000(1111|2222)3333)

Matches if the object ends with the bytes 00 00 11 11 33 33 or 00 00 22 22 33 33.