Capsule8 Docs
Capsule8 Docs

Adjusting Default Detections

Once you’re familiar with Capsule8’s Detections and have successfully added default detections to your environment, you can consider adjusting Capsule8’s default detections to suit your environment. This guide will help you understand the adjustment “levers” you can use to do so.

Content Groups

As outlined in the article on Types of Detections, Capsule8 Protect content is grouped to support high-level management of detection groups (Detection Analytics and Smart Policy). To manage the content groups that can be enabled, the enabled_content_groups configuration directive can be used in the host’s configuration file (/etc/capsule8/capsule8-analytics.yaml).

The default configuration for enabled_content_groups is shown below:

  - Detection Analytics
  - Smart Policy

The above configuration enabled all detections that are associated with the Detection Analytics and Smart Policy content groups.

The grouping of detections is hierarchical, so that all or a subset of detections can be enabled. In the example configuration below, all Smart Policy detections are marked enabled, but only “System Exploitation” is enabled for Detection Analytics:

  - Detection Analytics.System Exploitation
  - Smart Policy

Applying the above configuration would effectively disable all Detection Analytics detections that were not related to System Exploitation.

Note for advanced users: Some detections shipped with the Capsule8 content package may be disabled by default at the individual detection level, either due to the potential for the detection to impact performance, or because the detection may carry an increased risk of generating false-positive alerts. If an enabled content group includes one of these detections, that detection will not be enabled by default – it would need to be manually enabled. Further detail regarding configuring individual detections is covered in the next section (Tweak Individual Detections).

Tweaking Individual Detections

While Content Groups provide an easy way to enable or disable a group of detections, sometimes a finer-grained approach is needed. Capsule8 supports tuning the attributes of individual detection mechanisms in order to provide granular enable/disable controls, altering the priority of an alert, changing the response action, and more. Common attribute overrides and examples are included below, and the full list of customizable attributes is here.

Enabling a default-disabled detection

For a list of default-disabled detections, please refer to the List of Detection Classes and their Individual Detections. As one example, the New File Executed in Container detection is included in Capsule8 content packages, but is disabled by default. The tracking of the file telemetry that supports this detection can have an adverse effect on performance for some systems, hence why you must opt-in to using it.

To enable this detection, the following snippet should be added to the host’s configuration file (/etc/capsule8/capsule8-analytics.yaml):

New File Executed in Container:
	enabled: true

The above snippet overrides the enabled attribute of the New File Executed in Container detection. Restarting the sensor after having applied the above snippet will enable the New File Executed in Container detection.

Setting a detection to have a “kill” response

All detections provided by Capsule8 are configured to alert by default, but most detections support additional response actions. A common use case for Capsule8 is to set certain detections to an “enforcing” mode that will kill any processes that violate the detection rules.

For example, the Kernel Exploit detection is a good candidate for enforcement, as the detection has a very strong degree of certainty (i.e. very low false positive rate). To enable the “enforcing” mode for Kernel Exploit and kill offending processes in their tracks, override the responseAction attribute for this detection by placing the following override snippet in the host’s configuration file:

Kernel Exploit:
	responseAction: kill

Restarting the sensor with the above configuration will ensure that any processes that violate the Kernel Exploit detection will be killed if the process generating the detection is still present.

Customizable Attributes

Note that not all properties are customizable, as modification of some attributes would fundamentally change the nature of a detection. If the attributes in this list are insufficient for configuring detections, Configuring Custom Policies describes how to create customized detections for your environment. Custom policy creation and management is a Capsule8 Enterprise feature.

Detection Attribute Customizable? Comments
policy no Fundamentally changes the type of detection
enabled yes
alertMessage yes
comments yes
priority yes
responseAction yes
dryRun yes
rules no Fundamentally changes detection operation and could result in unexpected behavior
alertLabels yes
additionalCategories yes
alertDetail yes
contentGroups yes
List Attribute Customizable? Comments
type no Fundamentally changes the type of list
description yes
list yes

Where are detections located?

The Capsule8 packaged content is installed in /var/lib/capsule8/content/capsule8-content.yaml, a single content file containing all detections with their default configurations. All of the detections and lists within this file can be overridden with customizations in the host’s configuration file - /etc/capsule8/capsule8-analytics.yaml. While the content file will be updated whenever the Capsule8 content package is upgraded, the host’s configuration file will not be modified by a Capsule8 package and will retain any overrides and customizations across Capsule8 content releases.

The location of the content file is controlled with the content_path configuration directive, which can be applied in the host’s configuration file. By default, the value of content_path is set to /var/lib/capsule8/content/capsule8-content.yaml. Setting a custom content_path will direct the sensor to read content from the specified location.

When a sensor starts up, reads the packed content, and then applies any overrides, the sensor writes a “reference” copy of the merger of the capsule8-content.yaml with the capsule8-analytics.yaml to this location: /var/run/capsule8/cache_analytics.yaml. This cache yaml file represents the result of the merger, which you can inspect or save for debugging or auditing purposes.

Attention: Users of Version 4.0 or Earlier

If you are running a sensor version before version 4.1, Capsule8 strongly recommends that you adopt the model outlined above. You will get regularly updated Detections from Capsule8 that you can decide to enable in your environment. Capsule8 will do the work for you to break apart your existing policies from the single capsule8-anaytics.yaml into the two file approach detailed above. If you would rather not take this step, the 4.1 and later sensor is backward compatible with your existing capsule8-analytics.yaml policies.

Warning: Advanced Users Only Ahead

The following section is only recommended for advanced users.

!Advanced! 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:


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):

    behavior: add
    - "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:

    behavior: add
    - "/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:


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


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):

    behavior: add
    - "/opt/myAPM/ap-monitor"