Capsule8 Docs
Capsule8 Docs



Monitoring your systems for unwanted activity requires defining the unwanted activity. 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.

Once a policy is created, it will begin generating alerts when it encounters system activity violating its specified configuration. You can also output alerts for your team to digest into third party services (e.g. SIEMs, Slack, or PagerDuty), or other custom endpoints via Webhooks.

Triggered policies can also take automated response actions, which can shut down unwanted activity as soon as it is detected. These actions will also appear in the alert details for a triggered policy.

Get started with Capsule8 policies:


Term Definition
Policy An “engine” that monitors for a subset of system behavior. These can be thought of as core detection and analysis mechanisms - the system behavior you want to monitor.
Policy Type The name of an underlying policy, for use when configuring policy instances.
Policy Instance An instance of a policy comprised of rules and any policy-specific parameters. Instances determine how the data collected and analyzed should be acted upon. Multiple instances can exist for a given policy type, each with differing matching and output configuration.
Policy Category The high-level category/categories, based on MITRE’s ATT&CK framework, in which a policies alert should fall. This helps inform detection coverage across the attack lifecycle.
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 event.
Alert Label Alert labels are user-defined labels for a policy that will be emitted in any alerts generated by the policy. An alert label is a key-value pair and policies may define any number of labels.

Understanding policies

Capsule8 provides monitoring capabilities through modular components called policies. We call them policies because they work towards specific detection goals rather than detecting specific vulnerabilities or exploits—covering attack categories and entire vulnerability classes by detecting the low-level behaviors required to carry out an exploit or other security violation.

Policies are designed to provide diverse, overlapping layers of system security monitoring to cover the many facets of an attack. Use our default detection policies to begin your monitoring journey, or configure policies to meet your specific needs, such as for file integrity monitoring (FIM), access control, or other custom behaviours to preserve the health of your Linux production environment.

How policies work

  1. Define a policy category and set of rules for the policy (in a YAML configuration file)
  2. Monitoring begins on a certain set of behaviors based on the policy configuration
  3. Alerts are generated if any behaviors violate the configured rules (one alert per violation)

Let’s walk through an example of creating a policy to detect any interactive shell started by sshd (the OpenSSH daemon).

  1. Pick a name for your policy instance. Let’s call this one SSH Audit Trail. This will be the top-level element for the YAML snippet we’re creating.

  2. Define the policy type. In this case, we want to configure an interactive shell policy, so we would use the directive policy: interactiveShell.

  3. Policy instances can be toggled off-and-on with the enabled boolean keyword - so lets set enabled: true to ensure that our new policy will be used.

  4. Create the rules for the pollcy instance. Because we want to alert on shells started by sshd, we need to specify sshd as the parent program. We also want to ensure that only shells spawned by sshd generate alerts, meaning we want to ignore shells generated by any other programs. This is what such a rule set would look like:

  - match parentProgramName == "/usr/sbin/sshd"
  - default ignore
  1. Specify the priority level of the alert. In this case, we will define it as priority: Low - administrators log into hosts regularly, so we don’t want to cause huge alarm every time they do so.

  2. Create a message to describe the alert that would be generated, such as alertMessage: SSH Session Started.

  3. Finally, there’s a field for you to leave comments about the policy instance. These comments will be sent with every alert by default, and they can provide some context for the team or process consuming alerts. For our example, lets go with comments: Alerts whenever a new interactive shell is started by SSH, for audit purposes.

All together, our brand new policy instance appears as follows:

SSH Audit Trail:
  policy: interactiveShell
  enabled: true
  alertMessage: SSH Session Started
  priority: Low
  - match parentProgramName == "/usr/sbin/sshd"
  - default ignore
  comments: Alerts whenever a new interactive shell is started by SSHD, for audit purposes

Create multiple policies of the same type to get granular control of alerts – ensuring all potential system contexts are covered. For example, an unexpected outbound connection to an internal subnet could raise a lower-priority alert than an outbound connection to an unknown host on the internet. You could also create a different version of the SSH Audit Trail policy that raises a high-priority alert if a privileged user (e.g. root) logs in via SSH - a bad practice that often violates an organization’s security directives.