Manage Threat Detection Rules

Review Understanding Threat Detection Rules to get started.

Access the Rules Library

  1. Select Policies > Threat Detection|Rules > Rules Library.

  2. The Rules Library is displayed.


  • Grouped: Rules are grouped by source and you can collapse or open the groupings as needed.

  • Search: Click the magnifying glass if the Search field is not automatically opened. Search by words in the rule name.

  • Published by: Remember that default (Falco) rules show up as Published by: Sysdig ; user-created rules show as Published by: Secure UI. See also: Edit a Rule.

  • Last Updated: Sort by the date the rule was added/updated. Note that badges highlight rules that were added or changed in the past 7 days.

  • Usage: Shows number of policies where the rule and used, and whether the policies are enabled. Click the rule to see the policy names in the Rule Detail panel.

  • Tags associated with the rule (colored boxes).

Available Filters

Use the various filters to find rules:

  • Usage Type: Choose rules that have been Enabled, Disabled, or Not Used in a policy
  • Rule Source: In addition to being grouped by source, you can also filter down to show only particular sources
  • Managed Type: Choose Managed Rule (from Sysdig) or Custom Rule

Add Rules

You can select existing rules from the Library or create new rules on the fly and add them to a policy.

The Policy Editor interface provides many flexible ways to add rules to or remove rules from a Policy; the instructions below demonstrate one way.

Import from Library

  1. From the New Policy (or Edit Policy) page, click Import from Library.

    The Import from Rules Library page is displayed.

  2. Select the checkboxes by the rules to import.

You can pre-sort a collection of rules by searching for particular keywords or tags, or clicking a colored Tag icon (e.g. ).

  1. Click Mark for Import.

    A blue Import icon

    appears to the right of the selected rules and the Import Rules button is activated.

  2. Click Import Rules.

    The Policy page is displayed with the selected rules listed.

You can remove a rule from a Policy by clicking the X next to the rule in the list.

Create a Falco Rule

  1. From the Rules Library page, click +Add Rule and select Falco from the drop-down.

    The New Rule page for the Falco rule type is displayed.

  2. Enter the parameters:

    Name and Description: create a name and a meaningful description for the rule

    Condition and Output: write the condition code and outputs required. See Supported Fields for more information.

    Priority: This is a required field to meet the Falco rule syntax.

    Source: Define if the rule is detecting events using the Kubernetes Audit data source or using the standard syscall mechanisms

    Tags: Select relevant tags from the drop-down or add your own custom tag

  3. Click Save.

Falco rules with the source k8s_audit need Kubernetes Audit logging enabled for conditions to be met.

Create a List-Matching Rule: Container Type Example

Suppose you want detect whenever someone used a specific container image that has known problems. In this case, a Container rule would be appropriate. (The other list-matching rule types have similar entry fields, as appropriate to their type.)

  1. From the Rules Library page, click +Add Rule and select Container from the drop-down.

    The New Rule page for the Container rule type is displayed.

  2. Enter the parameters:

    Name: Enter a Name, e.g. Problematic Images.

    Description: Enter a Description, e.g. Images that shouldn’t be used

    If Matching/ If Not Matching: Select If Matching. When added to a policy, if the rule conditions match, then the policy action you define (such as “send notification”) will be triggered.

    Containers: Add the container name(s) that are problematic, e.g. cassandra:3.0.23.

    Tags: Select relevant tags from the dropdown, e.g. database and container.

  3. Click Save.

Review a Rule Detail Panel

From the Rules Library list, select a rule to see its details.

From here you can:

  • Review the rule definition, including clicking embedded macros to open their details in a pop-up window
  • Check all policies in which the rule is used and see whether those policies are enabled or disabled.

View Recent Changes to a Rule

When rules are changed, either by the Sysdig Threat Detection team or by users, an Updated badge is displayed next to the rule name. To see the change details:

  1. Go to Policies > Threat Detection|Rules and choose the Rules Library, Falco Lists, or Falco Macros pages.

  2. Open the detail panel of rule with an Updated badge.

  3. Select the +/- icon to compare the two versions of the rule.

Edit a Rule

Any rules published by Sysdig are default and are read-only. You can append to their lists and macros, but cannot change the core parameters. Default rules cannot be deleted.

Self-created rules can be freely edited. You can also override the behavior of default Falco rules and macros using a placeholder mechanism in the Rules Editor.

To display existing rules:

  1. Select Policies > Rules | Rules Library and select a rule.

  2. The Rule Details panel opens on the right. You can review the parameters and append to macros and lists inline if desired.

Append to Falco Macros and Lists

Default Falco rules have a variety of macros and lists embedded in them. While these cannot be deleted from a default rule, you can append additional information onto them.

For example, consider the Policy DB Program Spawned Process in the screenshot above. The embedded rule is used to check that databases have not spawned illicit processes. You can see in the rule condition the Falco list : db_server_binaries.

To append items in a default list:

  1. Click the blue list text in the rule condition, or go to Policies > Falco Lists and search for it by name.

  2. The list content is displayed. Click Append.

  3. Enter the additional items (i.e. databases) you want to include in the rule and click Save.

    The same process applies to macros.

How to Use the Rules Editor

The Rules Editor allows you can freely create custom Falco rules, lists, and macros and can override the behavior of the defaults.

Understand the Interface

To access the interface, select Policies > Rules Editor:

The Right Panel (Default)

Displays the rules_yamls provided from Sysdig.

  • Contains the default rules and macros

  • Is read-only

The Left Panel (Custom)

Displays the custom rules and overrides you want to add to the selected rules_yaml.

Note that many default Falco rules and macros have a parallel placeholder entry (commented out) in the yaml file. These have the prefix user_known. To change the behavior of a default rule, it is recommended to copy the placeholder equivalent into the custom rules panel and edit it there, rather than editing the default rule directly.

To search the rules YAML files

Click inside the Rules Editor right panel and use CNRL F to open an internal search field .

Rule Exceptions

To reduce false positives, Sysdig uses Falco exceptions, in many of the default rules, including adding exceptions to community rules. Rule exceptions are used in the auto tuning and rules exception features as part of Runtime Policy Tuning.

To understand how exceptions are managed: there are the exception definitions, used to define a set of fields and comps (comparisons) that the values (which are optional) can use to create those exceptions

Define a new exception

You can define a custom exception to configure optional values. This is valuable when the values are not yet known. It also provides the policy tuner with fields to suggest new values for.

- rule: my custom rule
    - name: cmdline_writer
      fields: [proc.cmdline,]
      comps: [startswith, =]

Appending values to an exception

You can append values to the exception, without needing to redefine the entire exception, by specifying the name of the rule and the exception name.

- rule: my custom rule
    - name: cmdline_writer
      values: [httpd, /etc/shadow]
  append: true

Appended to the rule, the rule with the full exception now reads as:

- rule: my custom rule
    - name: cmdline_writer
      fields: [proc.cmdline,]
      comps: [startswith, =]
      values: [httpd, /etc/shadow]

What fields are available in exceptions?

Sysdig SaaS and the Sysdig Agent will enrich events with details that are not available to Falco. The most common classes of fields available are:

Workload/syscall rules

  • proc
  • user
  • group
  • container
    • See below for container fields that are not available from Falco
  • fd To understand each field in those classes, you can find them here.

The k8s fields are not available in the Falco rules. This is due to performance improvements that could affect the Kubernetes API server when collecting those values from Falco. In the event details you may see this information enriched from other parts of Sysdig, with values such as

Kubernetes Audit/k8s_audit rules

All ka fields are available. You can find a comprehensive list here.

However as noted above, Sysdig enriches some additional metadata in the event details. An event may have the field, however that is not available in the rule or rule exceptions.

Common fields that are not available
  • agent.tag.*
  • kubernetes.*
  • host.*
  • container.label.*
  • instead use
    • container.image.repository which outputs sysdig/agent
    • container.image which outputs sysdig/agent:latest

Use Cases: List-Matching Rules

It is more helpful to think of the rules as matching the activity, rather than using concepts of allowing or denying. (The Network types can be a little confusing in this regard; see the last two use cases for more detail on that type). Thus, the use cases are based on answering the question: What do I want to know?


when any process other than web server programs are run:

  • Rule Type: Process

  • If Not Matching

  • Entries: [apache, httpd, nginx]

if any of the following crypto-mining processes are run:

  • Rule Type: Process

  • If Matching

  • Entries: [minerd, ccminer]

if any program reads any file containing password-related information:

  • Rule Type: Filesystem

  • Read Operations: If Matching

  • Entries: /etc/shadow, /etc/sudoers, /etc/pam.conf, /etc/security/pwquality.conf

if any program writes anywhere below binary directories:

  • Rule Type: Filesystem

  • Read/Write Operations: If Matching

  • Entries: /usr, /usr/bin, /bin

if a program writes to anywhere other than /var/tmp:

  • Rule Type: Filesystem

  • Read/Write Operations: If Not Matching

  • Entries: /var/tmp

if any container with an image from is started:

  • Rule Type: Container

  • If Matching

  • Entries: []

if any container runs an Apache web server:

  • Rule Type: Container

  • If Matching

  • Entries: [httpd, amd64/httpd]

I want to know if any container with a non-database image is started:

  • Rule Type: Container

  • If Not Matching

  • Entries [percona/percona-server, mysql, postgres]

if any program accepts an inbound ssh connection:

  • Rule Type: Network

  • Tcp, "If Matching"

  • Entries: [22]

if any program receives a DNS datagram:

  • Rule Type: Network

  • UDP, "If Matching"

  • Entries: [53]

if any program accepts a connection on a port other than http/https

  • Rule Type: Network

  • TCP, "If Not Matching"

  • Entries: [80, 443]

if any program accepts any inbound connection:

  • Rule Type: Network

  • Inbound Connection: Deny

if any program makes any outbound connection

  • Rule Type: Network

  • Outbound Connection: Deny