You can use these FAQs, tips, and examples to get started with Data Forwarder custom query filters. Carbon Black Cloud uses Lucene, a powerful query syntax, for Alert, Event, and Process search as well as query-based Watchlists.

Which fields can I filter on?
The Data Forwarder Data Guide has a list of filterable fields.
Can I use an Investigate or Watchlist query in the Data Forwarder?
  • There are a few differences between Investigate/Watchlist and Data Forwarder Custom Query Filter syntax.
  • Some fields may not be available in Data Forwarder Custom Query Filters. You can reference the Search Field Guide and Data Forwarder Data Guide for a full list of searchable and filterable fields.
  • Some fields have slightly different names, most notably:
    • Investigate/Watchlist: process_name; Custom Query Filter: process_path
    • Investigate/Watchlist: event_type; Custom Query Filter: type
  • Wildcards are required by most fields in Data Forwarder Custom Query Filters.
    • Investigate/Watchlist: process_name:powershell.exe
    • Custom Query Filter: process_path:*\\powershell.exe
  • Data Forwarder Custom Queries do not support value-only searches; you must specify the field name.
      • Investigate/Watchlist: powershell
      • Custom Query Filter: process_path:*powershell*
Which characters do I need to escape?
If the following characters appear in a value in your query filter, you must escape them with a single \

Characters: + - && || ! ( ) { } [ ] ^ " ~ * ? : \ / space

  • Example 1: Escaping a normal windows path c:\windows\system32\.

    Note the colon and directory delimiters are escaped. The asterisk on the end is not, because it’s a wildcard, not searching for the literal asterisk character in the process path

    • process_path:c\:\\windows\\system32\\*
  • Example 2: Looking for the –encoded flag in a process cmdline
    • process_cmdline:\-encoded
  • Example 3: Escaping spaces
    • process_path:*Google\ Chrome*
    • process_publisher:Google\ LLC
Are wildcard or tokenized searches case sensitive?
The following query types are converted to lowercase at the time of comparison, thus making these queries not case sensitive. We do not store the original query in lowercase.
  • CIDR (in the case of IPv6)
  • Field
  • Quoted Field
  • Wildcard
  • Fuzzy

Filtering is case sensitive. For explicit filters, we perform a direct string/rune match (that is, process_path == "value"), with single/multi character wildcards, (that is, "X" != "x").

Using Wildcards
Data Forwarder Custom Query Filters supports two wildcard characters:
  • * matches 0 or more characters
  • ? matches 1 single character
  • Example 1: Any process path ending in \powershell.exe
    • process_path:*\\powershell.exe
  • Example 2: Any Mac or Linux process path containing a directory called temp
    • process_path:*\/temp\/*
  • Example 3: Any process path containing temp and command with a single character in between. Matches Windows (\temp\command\) and Mac/Linux (/temp/command) but also possibly unexpected directories (/stempocommandcenter/)
    • process_path:*temp?command*
Paths
In Carbon Black Cloud, Windows paths generally use the \ character delimiter, while Linux paths generally use the / character delimiter.
  • Example 1: Windows c:\windows\system32
    • process_path:c\:\\windows\\system32\\*
  • Example 2: Linux /usr/bin/bash
    • process_path:\/usr\/bin\/bash
Using CIDR
IP fields support CIDR ranges. Note, the / denoting the range must be escaped.
  • Example: Standard IPv4 internal ranges
    • remote_ip:(10.0.0.0\/8 OR 172.16.0.0\/12 OR 192.168.0.0\/16)
Using Ranges
Ranges currently only support alphabetical sorting.
  • Example 1: Match any c:\ and d:\ drives, but not e:\
    • process_path:[c TO d]
  • Example 2: Numeric ranges are not yet supported, alphabetical ordering still applied. This will match ports 20, 25, 30, and 2500, but not port 40.
    • remote_port:[20 TO 300]
Grouping
Group with parenthesis, AND, OR, and NOT statements support more complex queries.
  • AND/OR/NOT must be capitalized
  • Example 1: Multiple values for a single field
    • process_path:(*\\powershell.exe OR *\\pwsh.exe)
  • Example 2: Network connections, except those made by Chrome to ports 443 or 80
    • type:endpoint.event.netconn AND NOT (process_path:*\\chrome.exe AND remote_port:(443 OR 80) AND netconn_inbound:false)
  • Example 3: Fileless Scriptload events, all scriptload events from
    • type:endpoint.event.fileless_scriptload OR (type:endpoint.event.scriptload AND (device_os:(WINDOWS OR MAC) OR scriptload_publisher_state:FILE_SIGNATURE_STATE_NOT_SIGNED))
Query Depth
Query depth is the number of nested groups within a custom query filter.
  • The maximum query depth is 3.

    Queries with a depth above 3 will result in the error "query too deep"

  • Example 1: This query has a depth of 4 and would result in an error:
    event_origin:NGAV OR (type:endpoint.event.netconn AND (remote_port:80 OR (remote_port:443
          AND process_path:*\\chrome.exe)))
  • Example 2: These 2 queries combined have the same logic as Example 1, but do not violate the depth limit. The second query does not need to specify the event type, as the remote_port field will only ever appear on endpoint.event.netconn events:
    • (Include filter 1) event_origin:NGAV
    • (Include filter 2) remote_port:80 OR (remote_port:443 AND process_path:*\\chrome.exe)