Ingress Filter Details

Carbon Black EDR (Endpoint Detection and Response) is the new name for the product formerly called CB Response.

Note: In EDR 7.7 API routes were changed to use the terms approvedlist and bannedlist. This document covers EDR version 6.0 through 7.6. See Guides- Ingress Filter for the latest version.

General Filter Expressions

Ingress filtering of events is available based on one or more of the following criteria: file path, command line, or MD5 hash. No other filtering criteria, such as network address, are supported.

Any of these filters will be interpreted as a regex if it is prefixed with rx| or rxi|. rxi indicates case insensitive regex

Path filters support globbing expressions. It will be detected automatically by existence of either * or ? character, and will convert all paths to Unix format before matching.

For example, filter **/notepad.exe will match "c:\windows\system32\notepad.exe"

Ingress Filter Examples

rx|.* - excludes all events of given type
foo - excludes only events whose value is exactly foo
rx|^foo$ - Same as above, but using regex - excludes only events whose value is exactly foo

Migrating Legacy Ingress Filters on Upgrade

Legacy ingress filters (5.2 version) will be imported to this data model when found on the system one-time (and identified with some predefined legacy id) and then renamed (.61_upgrade suffix appended). Reference to the ingress filter will also be removed from the cb.conf file (IngressFilterConfigFile property). In case of cluster, only ingress filter on the master node will be migrated into new model, assuming that filters should be configured the same on each node. Release notes should call that out. Legacy filter will be imported as series of new filters with unique ids:

legacy-filter-process (filter for process)
legacy-filter-process-child (filter for process and children)
legacy-filter-process-child-descendants (filter for process and all descendants)
legacy-filter-registry (filter for registry entries)
legacy-filter-events (filter for event types)

Event type ignore filters will only be partially migrated, mapping only types supported by the new ingress filters. This means, we will migrate filters for regmod, filemod, modload, moduleload (synonym for modload), crossprocopen, remotethread (NOTE: the latter two will apply to all crossproc events) but not , netconn, childproc, process, module, procstart, procend, processblock, tamper, procmeta, emetmitigation since they don’t have representation in new ingress filters.

API Examples

All examples here use curl, with raw API call. Note that api token needs to be replaced with actual token used on your server.

Importing a Legacy Filter

Let’s import a legacy ingress filter (type of filter used in 5.2 and earlier versions of EDR). Note that there can only be one legacy filter (spread over one or more filter objects as noted before), and importing will simply overwrite it.

curl -XPUT -H "X-Auth-Token: b201b7c1e6c5acf45cc5b55dd22464ca504af6e4" -H "Content-Type: application/json" "https://localhost/api/v1/ingress_whitelist/legacy" -k --data "@/etc/cb/ingressFilter.json"

Getting the Current Legacy Filter

The current legacy filter may be reviewed:

curl -XGET -H "X-Auth-Token: b201b7c1e6c5acf45cc5b55dd22464ca504af6e4" "https://localhost/api/v1/ingress_whitelist/legacy" -k

Example response:

{
 "filterProcMd5s": [
 "9de093dfc1216704ce1b7025b0a93aa3",
 "fa9e0665912d2190a1494a4b08569fdc",
 "fa3df983922312523c5923af8f47a1c8"
 ],
 "filterProcAndChildPaths": [
 "c:\\windows\\system32\\csrss.exe"
 ]
}

Retrieve All Installed Filters in New Format

Let’s check all the filters we have installed. In this case, we get back two filters corresponding to our legacy filter and one new filter:

curl -XGET -H "X-Auth-Token: b201b7c1e6c5acf45cc5b55dd22464ca504af6e4" "https://localhost/api/v1/ingress_whitelist" -k

Example Response:

[
  {
    "md5_filters": [
      "9de093dfc1216704ce1b7025b0a93aa3",
      "fa9e0665912d2190a1494a4b08569fdc",
      "fa3df983922312523c5923af8f47a1c8"
    ],
    "create_user_id": 1,
    "name": "Legacy ingress filter for processes",
    "modify_user_id": 1,
    "global": true,
    "enabled": true,
    "modify_timestamp": "2017-03-09T09:12:43.127Z",
    "create_timestamp": "2017-03-09T09:04:13.309Z",
    "filter_all_events": true,
    "descendant_filtering_level": 0,
    "hit_rate": 0.0,
    "id": "legacy-filter-process"
  },
  {
    "create_user_id": 1,
    "name": "Legacy ingress filter for processes and children",
    "modify_user_id": 1,
    "global": true,
    "enabled": true,
    "modify_timestamp": "2017-03-09T09:12:43.127Z",
    "create_timestamp": "2017-03-09T09:04:13.309Z",
    "filter_all_events": true,
    "descendant_filtering_level": 1,
    "hit_rate": 0.0,
    "id": "legacy-filter-process-child",
    "path_filters": [
      "c:\\windows\\system32\\csrss.exe"
    ]
  },
  {
    "modify_timestamp": "2017-03-01T19:04:57.225Z",
    "create_user_id": 1,
    "description": "New filter test",
    "modify_user_id": 1,
    "sensor_ids": [
      1
    ],
    "enabled": true,
    "id": "test1",
    "filter_on_sensor": false,
    "filter_on_server": true,
    "create_timestamp": "2017-03-01T19:04:57.192Z",
    "filter_all_events": true,
    "md5_filters": [
      "aca5cbbad69e24b8445b9c8633bf66e8"
    ],
    "hit_rate": 0.0,
    "internal": false,
    "name": "test"
  }
]

Creating a New Filter

This filter will cause events from processes that match the path *\unimportant.exe to be ignored on all windows sensors in groups 1 and 2. Note that system uses default settings for some parameters that were not provided, such as enabled=True, descendant_filtering_level=0 and filter_all_events=True.

curl -XPOST -H "X-Auth-Token: b201b7c1e6c5acf45cc5b55dd22464ca504af6e4" -H "Content-Type: application/json" "https://localhost/api/v1/ingress_whitelist" -k -d '
[
  {
    "id":"test2",
    "global": false,
    "group_ids": [1, 2],
    "os_mask":1,
    "path_filters":["*\\unimportant.exe"]
  }
]'

Example response:

["test2"]

Modifying Ingress Filters

Let’s modify a newly-added filter to filter out additional processes by adding a path criterion.

curl -XPUT -H "X-Auth-Token: b201b7c1e6c5acf45cc5b55dd22464ca504af6e4" "https://localhost/api/v1/ingress_whitelist/test2" -k -d '
  {
    "os_mask":1,
    "global": false,
    "group_ids": [1, 2],
    "path_filters":["*\\unimportant.exe", "*\\really_unimportant.exe"]
  }'

Viewing Ingress Filters

Let’s view filter we just changed

curl -XGET -H "X-Auth-Token: b201b7c1e6c5acf45cc5b55dd22464ca504af6e4" "https://localhost/api/v1/ingress_whitelist/test2" -k

Example Response:

{
 "create_user_id": 1,
 "global": false,
 "group_ids": [1, 2],
 "path_filters": [
  "*\\unimportant.exe",
  "*\\really_unimportant.exe"
 ],
 "modify_user_id": 1,
 "create_timestamp": "2017-03-10T13:44:54.455Z",
 "modify_timestamp": "2017-03-10T13:44:54.479Z",
 "id": "test2",
 "hit_rate": 0.1,
 "os_mask": 1
}

Notice addition of the hit rate field, telling us that 10% of events were discarded for this filter in the past 15 minutes.

Deleting a Filter

Finally, let’s delete the newly added filter:

curl -XDELETE -H "X-Auth-Token: b201b7c1e6c5acf45cc5b55dd22464ca504af6e4" "https://localhost/api/v1/ingress_whitelist/test2" -k

Last modified on February 14, 2022

Carbon Black EDR

Page Contents