Skip to content

Definition Files

Jump to bottom
Cori Smith edited this page Jul 5, 2023 · 5 revisions

All about definition files: what they are and how to write them.

Contents

What Are They?

Definition files are collections of queries in JSON format. Not all EDR products support all query fields but the syntax is standardized so all EDR products can parse the data and, if necessary, gracefully skip unsupported fields.

Use-cases include

  • Search for IOCs across all machines in an EDR platform
  • Baseline environments and identify commonly used tools and any outliers
  • Inventory programs based on execution history
  • Test detector logic to reduce noise and tune for accuracy
  • Hunt for behavior too noisy or false-positive prone to be used as automated detector logic.

What Is The Syntax?

A definition file is a collection of queries targeted for a specific hunt or purpose. For example, there is a definition file in the Surveyor repo dedicated to remote admin tools.

Within a definition file, there are groups of queries. Groups divide the definition file into sections that are more granular than the definition file's name itself. For example, the definition file for remote admin tools has groups called "TeamViewer" and "AnyDesk".

Within groups, you can define one or more search fields. If multiple fields are defined within a group, each field will be treated as an independent query. A full list of supported field names can be found below.

For each field, you can specify an array of values. This list of values are joined together with "OR" statements.

To use "AND" statements, you must use the query field.

Example:

{
  "AnyDesk":{
    "process_name":["anydesk.exe"],
    "domain":["anydesk.com"]
  },
  "TeamViewer":{
    "process_name":["teamviewer.exe","teamviewerhost"]
  },
  "NetSupportManager":{
    "query":["process_name:client32.exe AND internal_name:client32", "domain:geo.netsupportsoftware.com"]
  }
}

The above definition file would execute four separate queries

Note the query language in this example is for VMware Carbon Black EDR

  • Query 1 (AnyDesk): process_name:anydesk.exe
  • Query 2 (AnyDesk): domain:anydesk.com
  • Query 3 (TeamViewer): (process_name:teamviewer.exe) OR (process_name:teamviewerhost)
  • Query 4 (NetSupportManager): (process_name:client32.exe AND internal_name:client32) OR (domain:geo.netsupportsoftware.com)

Generic format:

{
  "GROUP_NAME_1":{
    "FIELD_NAME_1":["VALUE_1","VALUE_2"],
    "FIELD_NAME_2": ["VALUE_1"]
  },
  "GROUP_NAME_2":{
    "FIELD_NAME_1":["VALUE_1"]
  }
}

List of Supported Fields

Note: Surveyor uses Carbon Black EDR's naming convention for definition file fields.

Field Name Description Carbon Black EDR Carbon Black Enterprise EDR Microsoft Defender for Endpoint SentinelOne - Deep Visiblity SentinelOne - PowerQuery Cortex XDR
query Free-form query in the native EDR language Supported Supported Supported Supported Supported Supported
process_name File name of executing process Supported Supported Supported Supported Supported Supported
cmdline Command line of executing proccess Supported Supported Supported Supported Supported Supported
product_name Product name listed in binary metadata Supported Unsupported Unsupported Unsupported Unsupported Unsupported
digsig_publisher Digital signature publisher listed in binary metadata Supported Supported Supported Supported Supported Supported
domain Network connection to domain Supported Supported Supported Supported Supported Unsupported
ipaddr Network connection to IPv4 address Supported Supported Supported Supported Unsupported* Supported
filemod Name (without or without path) of modified file Supported Unsupported* Supported Supported Supported Supported
internal_name Internal name listed in binary metadata Supported Supported Supported Supported Supported Unsupported
company_name Company name listed in binary metadata Supported Unsupported Unsupported Unsupported Unsupported Unsupported
modload Name (with or without path) of image loaded Supported Unsupported* Unsupported* Supported Supported Supported
md5 MD5 hash Supported Supported Supported Supported Unsupported Supported
ipport Network connection port Supported Supported Supported Supported Supported Supported
process_file_description Display name of executing process Unsupported Unsupported Unsupported Supported Supported Unsupported
sha256 Supported Unsupported* Unsupported* Unsupported* Unsupported* Unsupported* Supported

*Denotes EDR platform can support that field but Surveyor code needs to be updated

Clone this wiki locally