Advanced Topics: Lists

Policy rules can use lists for even more control over when and how alerts should be fired. Lists are particularly useful for configuring policies to block or allow certain behavior.

List Types

Capsule8 supports five data types for lists: names, hosts, paths, and numbers; along with an experimental lineage type. The list data type corresponds to the data type of the field which is being compared. For example, a rule such as:

ignore programName IN $Process_Injection-programName-allowList

will expect the Process_Injection-programName-allowList to be of data type paths, as programName is a path field.

Names

Name lists store strings, and includes support for glob formatting. For example, both "alpine" and "al*" are valid entries in a name list.

Hosts

Host lists store either IP addresses as CIDR blocks or domain names (which will be resolved to an IP address). For example, both "8.8.8.8/8" and "www.capsule8.io" are valid entries in a host list.

Paths

Path lists store program or file paths. Paths may be written with the wildcard operator `*`, which will match on all paths that fit the pattern. For example, both "/bin/bash" and "/bin/*/bash" are valid entries in a path list.

Numbers

Numbers lists store integers. For example, 10 is a valid entry in a number list.

Lineage (experimental)

Lineage lists store lists of strings that are indicative of process lineage sequences. As lineage is currently an experimental feature, it is not recommended to use lineage lists.

Adjusting Allowlists and Blocklists

Most Capsule8 detections incorporate a number of lists – allowlists and blocklists, specifically – as an extensible way to describe wanted and unwanted system behavior. Detections have lists built-in for common allowlist and blocklist actions. For instance, if a certain detection generates false-positives in your environment, you can add (or remove!) actions to your list to better tailor detection for your environment’s standard operation.

These lists enable customization of allowlists for alert elements such as program name, user name, container image name, as well as parent program name (the program that executed the program currently being inspected by the detection) and ancestor program name (the same as parent program, but will match the parent’s parent, grandparent, etc. – all the way back to the system boot process).

The lists included with Capsule8’s content are named in a consistent manner to facilitate tweaking. The standard naming of these lists is a combination of the detection the list applies to, the alert element that should be allowed/blocked, and the action (allow or block), as demonstrated below:

$Snake_Cased_Detection-$alertElement-$actionList

As far as modifying lists goes, there are three different supported behaviors:

• add, for adding an item to a list
• remove, for removing an item from a list, and
• replace, for replacing a list’s contents entirely (use this when you want to both add and remove

The behavior is specified with the behavior: attribute when modifying lists, as we will show in some examples shortly.

Lists themselves are described in greater detail in the Configuring Policies section. For the purposes of content, lists can be classed as two different types: Shared lists and Local lists.

Shared Lists

Shared lists allow you to allow or block an application running across all enabled detections. These lists should rarely be used, because they can introduce a significant coverage gap and serve as a method for attackers to evade Capsule8.

As shared lists apply to all detections, they take the format Global-$alertElement-$actionList.

As an example, customers commonly want to allowlist actions performed by a user associated with vulnerability management tooling, such as Tenable’s Nessus vulnerability scanner. Nessus regularly connects to vast portions of an organization’s network and executes commands to determine patch levels and identify the presence of known vulnerabilities. This activity could generate a lot of alerts – so it may be desirable to add the nessus operating system user to the shared allowlist to suppress any alerts it might generate. To do so, the following should be added to the host’s configuration file (/etc/capsule8/capsule8-analytics.yaml):

  Global-userName-allowList:
    behavior: add
    list:
    - "nessus"

The shared list is empty by default (meaning nothing is allowlisted), but that list is still used in most detections by default. If an item is added to the shared list, like the userName “nessus” in the example above, then any detection that can filter on userName will automatically ignore alerts from that user.

Another common shared list is SystemUpdatePrograms. By default, this list consists of package management programs (like yum and dpkg) and some related helper programs used by package managers. However, many organizations use configuration management tools such as Puppet to manage fleet configurations. In this case, it would be a good idea to mark the Puppet agent (puppet) as being allowed to perform tasks related to system configuration management. This can be achieved by adding puppet to the SystemUpdatePrograms list, per the following YAML snippet:

  SystemUpdatePrograms:
    behavior: add
    list:
    - "/opt/puppetlabs/bin/puppet"

The snippet above will ensure that any detections focused on system changes will not generate alerts if the program /opt/puppet/puppet-agent was involved.

Detection-local Lists

In addition to shared lists, most detections include their own lists that only apply to a single detection policy. Detection-local lists provide fine-grained control over what each detection considers malicious or benign, and can be very helpful for tuning out false positive alerts.

Detection-local lists are named in a consistent manner to facilitate tweaking. The standard naming of these lists is a combination of the detection name, the element of the event that should be allowed / blocked, and the action (allow or block), as demonstrated below:

$Snake_Cased_Detection_Name-$alertElementName-$actionList

For example, the Process Injection detection has the following lists:

Process_Injection-programName-allowList
Process_Injection-userName-allowList
Process_Injection-imageName-allowList
Process_Injection-parentProgramName-allowList
Process_Injection-ancestorProgramName-allowList

The full list of the detections and predicates that can be modified is in the content file - /var/lib/capsule8/content/capsule8-content.yaml. An upcoming release will introduce an interface for managing lists and detections that will greatly simplify tuning for different environments.

Each of the lists above can be added to so that alerts aren’t generated. These lists enable customization of allowlists for program name, user name, container image name, as well as parent program name and ancestor program name.

As an example, the Process Injection detection monitors for programs using debugging techniques on other processes. Some Application Performance Management (APM) tools use debugging techniques to profile applications and provide information regarding system call usage. This could generate a significant number of alerts for standard system operation. Assuming the APM program’s name is /opt/myAPM/ap-monitor, the following snippet should be added to the host’s configuration file (/etc/capsule8/capsule8-analytics.yaml):

  Process_Injection-programName-allowList:
    behavior: add
    list:
    - "/opt/myAPM/ap-monitor"

Creating Custom Lists

When creating custom detections, it may be useful to define a custom list that will be referred to in the ruleset.

List names must be unique within a configuration file across all strategy and list names (note: unlike strategy names, list names may not contain spaces). Aside from the name, the following table outlines the attributes necessary to define a list:

For example, a custom list of authorized shell programs might look like this:

AuthorizedShellPrograms:
  type: paths
  description: allowlist of authorized programs
  list:
    - "/bin/bash"
    - "/bin/sh"
    - "/usr/sbin/*sh": "this will match all programs beginning with /usr/sbin/" and ending in "sh"

This custom list should be added to the host's /etc/capsule8/capsule8-analytics.yaml configuration file, along with the detection that refers to it.