Definition Files

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

Contents

• Contents
• What Are They?
• What Is The Syntax?
• List of Supported Fields

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
query	Free-form query in the native EDR language	Supported	Supported	Supported	Supported	Supported
process_name	File name of executing process	Supported	Supported	Supported	Supported	Supported
cmdline	Command line of executing proccess	Supported	Supported	Supported	Supported	Supported
product_name	Product name listed in binary metadata	Supported	Unsupported	Unsupported	Unsupported	Unsupported
digsig_publisher	Digital signature publisher listed in binary metadata	Supported	Supported	Supported	Supported	Supported
domain	Network connection to domain	Supported	Supported	Supported	Supported	Supported
ipaddr	Network connection to IPv4 address	Supported	Supported	Supported	Supported	Unsupported*
filemod	Name (without or without path) of modified file	Supported	Unsupported*	Supported	Supported	Supported
internal_name	Internal name listed in binary metadata	Supported	Supported	Supported	Supported	Supported
company_name	Company name listed in binary metadata	Supported	Unsupported	Unsupported	Unsupported	Unsupported
modload	Name (with or without path) of image loaded	Supported	Unsupported*	Unsupported*	Supported	Supported
md5	MD5 hash	Supported	Supported	Supported	Supported	Unsupported*
ipport	Network connection port	Supported	Unsupported*	Unsupported*	Unsupported*	Unsupported*
process_file_description	Display name of executing process	Unsupported	Unsupported	Unsupported	Supported	Supported

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