Deploy Detections from the Console

Monitoring your systems for unwanted activity requires defining it first. Capsule8’s detection policies provide you with deep insight into your systems’ behaviors, from program monitoring detecting exploitation attempts to granular policy enforcement based on program, user, network, or file activity.

Learn how to configure and deploy your detection policies to one or more sensors from the console.

Requirements

• Console 4.5.0 or later with remote policy configuration enabled
• Sensor 4.5.0 or later

Notes

Some features are not available when configuring detections from the Capsule8 Console:

• Automated Responses like kill, quarantine, and stop are not available.
• kprobe and uprobe strategies are not available.

Customizing Default Detection versions

Keep Capsule8's defaults:

Each Console version includes a recent version of Default Detections requiring no user configuration. This is the best choice for typical users.

Specify a version:

Users who need to deploy a specific version of Default Detections to their sensors may do so by installing that version of the capsule8-content package on the Console's host machine. Use the same commands that would be used to install Default Detections on a Sensor's host machine, but run them on the Console's host machine. Those commands may be found in the "Default Detections" section of the distribution-specific instructions.

Specify multiple versions (Console 4.7+):

Users who need to simultaneously deploy multiple different versions of Default Detections to different sensors may use this workaround:

1. Create a folder on your Console's host machine and note the name, for example:

   mkdir -p /usr/local/capsule8detections

2. Install the first of the required Detection versions as per the distribution-specific instructions.
3. Copy the yaml file containing the detections into the folder, making sure the new name is unique:

   cp /var/lib/capsule8/content/capsule8-content.yaml \
   /usr/local/capsule8detections/content-9.9.9.yaml

4. Repeat steps 2 and 3 for each required Detections version, until all yaml files are copied and renamed.
5. Set permissions to prevent tampering with the Detection files:

   chown -R capsule8:capsule8 /usr/local/capsule8detections
   chmod -R ug=rX /usr/local/capsule8detections

6. Update the Console configuration file, setting

   console:
     content_path: "/usr/local/capsule8detections"

7. Restart the Console.
8. When creating a new Policy Set in the browser, choose the desired Detection version from the dropdown.

Configure and Deploy Detection Policy Set

You can create and configure your detection policies under the "Detection" page. Under "Detection," you will find a list of policy sets that you may deploy to one or more sensors to implement Capsule8's detection. A policy set is composed of individual policies comprised of rules and any policy-specific parameters. This policy determines how the data collected and analyzed should be acted upon.

Once a policy set is deployed, it will begin generating alerts when it encounters system activity matching its specified configuration. You can configure integration with third party services so that common operations systems – SIEMs, Slack, PagerDuty – or other custom endpoints via Webhooks will be aware of detected alerts.

 If there are multiple policy sets assigned to a particular sensor, the policy set that was most recently applied will be applied to that sensor.

 

How to create a policy set

Under the "Detection" page, click "New Policy Set."

 

You will then see the visual editor to configure Capsule8's default detection policies and create a new policy set from them.

For the 4.6 release, custom policies can only be added and configured in an already-existing policy set using the YAML editor.

For more context on these categories, click on the blue question mark () next to each category, or visit our list of detection categories and their individual policies.

 

Each category or subcategory may be expanded or collapsed by clicking on any empty portion of the section. The blue switch () indicates whether a category, subcategory, or policy is enabled or disabled. The "partially-enabled" state () indicates that a category or subcategory contains some enabled and some disabled policies.

These switches can be clicked to toggle them on and off, enabling individual policies, or entire categories or subcategories.

For more context on each policy, hover over the abbreviated description, or visit our list of detection categories and their individual policies.

 

Certain policies may be disabled by default: 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. These policies have a blue flag icon () next to them. Click on this flag in the console to read documentation regarding deployment considerations. This information is also available here.

 

How to deploy a policy set

"Assigned Resources" is used to specify which sensors a policy set will be deployed on. One or more parameters may be chosen, and each must have a single value. The policy set will be applied to every sensor that matches all parameters when those sensors requests a configuration.

Note that if you create another configuration that also matches the sensor, the most recent configuration will be applied, overwriting this one.

Parameters include:

Environment: Determines on which environment the policy will be executed. For example Production.

Hostname: Determines on which host the policy will be executed. This parameter is used when we are applying the policy to a single sensor.

In Container: Determines whether the policy will be used inside a container or not. It takes the values True or False.

Capsule8 Sensor Version: Determines on which sensor versions the policy will be applied to. This can be used when we need to assign a policy to multiple sensors.

Kernel Release: Determines on which versions of Linux this policy applies to.

 

Finishing creating a policy set

Once your policy set is configured and the appropriate resources have been assigned, click "Save and Apply" (don't worry: you can return to edit this policy set and its assigned resources at any time). Clicking "Save and Apply" will create a new policy set and return you to the main detection page with a list of all policy sets.

 

How to delete a policy set

Click the "Detection" section in the top menu bar. Available policy sets will be displayed as shown below.

Click on the checkbox next to the policy set(s) that need to be deleted. Please note the the Delete button will be disabled until one policy is selected.

Once the required policies are selected, click on the Delete button. Confirm on the pop up message by selecting "Yes, Delete" to delete the selected policy set(s).

If any changes have to be made, please click on No to go back to the Policy sets table.

 

How to edit a policy set

Under the "Detection" page, select the policy set you would like to configure. Below is an example of a policy set detail page.

There are four attributes you can edit on the policy set page – make sure to click "Save and Apply" after making any changes to the following:

• Name of policy set
• Default detection content
• Custom policies- This feature is not available by default. Talk to your Capsule8 representative if you need it.
• Assigned Resources

Please note that for the Console 4.6 release, you cannot create policies and lists using the visual editor. For the time being, you can switch to the YAML editor for these capabilities.

How to edit policies

Individual policies can be viewed and edited, both in the "Default Detection" content section, and the "Custom Policies" section.

For default detection, you can reach individual policies by expanding detection content categories and subcategories:

 

For custom policies, you can edit the YAML directly (at your own risk), or click "Switch to UI Editor" to edit policies graphically.

Select a policy for editing by clicking on a non-interactable part of any policy row (that is, not the 'enabled/disabled' switch, or any other control). You can configure the rules and any policy-specific parameters in the modal form.

An example detection content policy form:

The available fields in each policy's form may vary depending on relevance.

Detection content policies have the following fields available for editing:

• Enabled: Toggle to enable or disable
• Alert Message: Description of this policy that will be emitted when triggered
• Priority
• Response Actions: Specify which automated actions to take when triggered. Learn more here.
  • Not all policy types can support all response actions as each policy type detects different behaviors that require different responses.
• Lists (see below for more information)

 

An example custom policy form:

Custom policies have the following fields available for editing:

• Enabled: Toggle to enable or disable
• Comments: Description of this policy that will be emitted when triggered
• Alert labels: user-defined labels for a policy that will be emitted when triggered
  • Alert Message
  • Priority
• Response Action: Specify which automated actions to take when triggered. Learn more here.
  • Not all policy types can support all response actions as each policy type detects different behaviors that require different responses.
• Rules: Each policy exposes a set of valid fields that can be used for the construction of higher-level rules in policy instances. In each policy instance definition, the rules define how an alert will be generated upon the receipt of an alert.
  • Click "+" to add an AND statement to the existing rule
  • Click "+ Add Rule" to add an additional statement
  • You can point to a list here using $ListName (i.e. $BLKMapps in the above example)

Make sure to click "OK" to apply any changes you've made in a policy edit form.

How to edit 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. Capsule8 supports four data types for lists: names, hosts, paths, and numbers (along with an experimental lineage type). For more detail, look at creating custom detection policies.

Lists are only relevant to certain policies. Currently, only lists relevant to detection content policies can be edited graphically. Here's an example of the "Lists" section of the modal policy form (see above) of a detection content policy:

 

In the image above, several lists have been expanded by clicking on them already. Lists have three parts:

• Name of list
• Type of list
• Entries
  • Add, remove, and edit the rules within the list
  • Click the "–" preceding an entry to remove it
  • Click "+ Add an entry" to add an entry

Lists in the "Global Lists" sidebar generally apply to multiple policies. Editing a global list in the context of a single policy will change the list everywhere, no matter what policy you view it under. Learn more here.

Known Limitations

• The Console 4.6.0 release limits the available resource 'key' criteria to Environment, Architecture, Hostname, In Container, uname, Sensor Version, and Kernel Release.
• When assigning resources, only "AND" logic is supported. For instance, selecting both "env:production" (Environment is the key, and Production is the value) and "uname_os:linux" (uname is the key, and Linux is the value) will not apply the policy set to a Windows machine in a production environment, nor to a Linux machine in a staging environment.