General filter expression

Any filter (path_filter, command_line_filter, regmod_filter, etc.) will be interpreted as a regex if it is prefixed with rx| or rxi|. rxi indicates case insensitive regex

For all path filters (path_filters, filemod_filters, non_binary_filemod_filters), globbing expression is also supported. It will be detected automatically by existence of either * or ? character, and will convert all path to Unix format before matching.

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

Additionally, for all event filters, replace-type regex is also supported, in which case event will not be excluded, but its value will be replaced.

For replacements, syntax to use is rr|@...@... or rri|@...@... (for case insensitive replacement) where: @ is arbitrary symbol that will server as a delimiter between search and replace string. Any character can be used instead, as long as it is not needed inside the find/replace rule

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
• rri|@[0-fa-f]{8}-[0-fa-f]{4}-[0-fa-f]{4}-[0-fa-f]{4}-[0-fa-f]{12}@<GUID> - replaces any guid (case insensitive) in event with the word <GUID>

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, netconn, filemod, modload, moduleload (synonym for modload), crossprocopen, remotethread (NOTE: the latter two will apply to all crossproc events) but not 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 legacy filter

Let’s import legacy ingress filter (type of filter used in 5.2 and earlier versions of CB Response). 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 current legacy filter

Current legacy filter can 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 6.1 Format

Let’s check all filters we have installed. In this case, we got 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 new filter

This filter will cause all events from process *\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 newly added filter to filter out additional process

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 filter

Finally, let’s delete newly added filter

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