Manage Threat Detection Rules

The Rules Library

The the Rules Library is the main interface for managing Threat Detection rules. The library includes all created rules that can be referenced in policies. Out of the box, it provides a comprehensive runtime security library with specific rules developed by the Sysdig Threat Research team, Falco open source community rules, and international security benchmarks such as CIS or MITRE ATT&CK.

To access the Rules Library:

1. Log in to Sysdig Secure.
2. Select Policies > Rules > Rules Library.

Explore the Rules Library

The Rules Library displays all available rules in a table, grouped by rule type. You can:

• Filter them using the available filters.
• Change the order by interacting with the columns.
• Expand or collapse the different groups.
• Open the rule details by clicking on a table row.

You can also add custom rules using the Add Rule button in the top right. To learn more, see Add a Rule.

Filter Rules

You can use various filters to find rules in the Rules Library.

The first set of fields on the left allows you to search based on one or more values:

• Rule name

• Type

• Usage: Define whether a rule is Enabled in at least one policy, Disabled in all policies, or Not Used in any policy at all.

• Managed Type

• MITRE Tags

• Tags

  You can also use different operators by clicking on them (=, !=, in, !in).

Using the second set, you can also filter by:

• New: Find newly created rules.
• Updated: Find rules changed in the last 7 days.
• Modified: Find only rules that have exceptions or appends.

These attributes are all part of the rule detail. For explanations, see Review the Rule Detail.

Sorting

Use the Type column dropdown to change the order of the groups. By interacting with the other headers, you can reorder the rules within each group. By default, rules are sorted alphabetically by name.

Review the Rule Detail

From the Rules Library list, select a rule to see its details, displayed in a panel on the right.

From this panel, you can see 4 sections:

• The Rule summary contains the main rule information. It contains:

  • The name of the rule.
  • Type: The policy type. For example, Linux Workload or Kubernetes Audit.
  • Rule ID: Used when managing the rule using APIs or Terraform.
  • An indication of whether the rule was created by Sysdig (Managed) or by a user in the UI (Custom).
  • If the rule has been changed in the last 7 days, an Updated badge appears.

• What, which contains:

  • Last update, showing when the rule was last updated
  • The View as Diff action, explained in the dedicated section
  • A main body with the rule content, displayed as YAML and explained in the dedicated section
  • The author, on the right:
    • Secure UI, when the rule is custom or has been customized by a user
    • Sysdig stateful, when it’s part of Sysdig’s managed behavioral analytics rules. These are managed by the Threat Research Team. In this case, an authoring version is also included, referencing a rule version as in the Behavioral Analytics changelog.
    • Sysdig, when it’s part of Sysdig’s managed Falco rules. These are managed by the Threat Research Team. In this case, an authoring version is also included, referencing a rule version as in the Falco rules changelog.
    • Tuner, shown as Tuner 0.0.0, when the rule was customized by the Sysdig Runtime Policy Tuner. See more in the dedicated page.

  If a rule has been extended, multiple sections will be displayed to differentiate the content managed by different authors.

• Usage, showing whether and in which policies the rule is used, and whether it’s enabled in any of them. The overall status is:

  • Enabled: The rule is actively used, as it is enabled in one or more policies that are enabled.
  • Disabled: The rule is not active. It is referenced in one or more policies, but none are active, or the rule isn’t active in any of them.
  • Not Used: The rule is not included in any policy.

  You can see the details of the policies that include the rule and their status in the table below.

• Tags, attached to this rule.

You can also find actions available in the Rule Detail:

• Edit, to review the rule content. Refer to the dedicated paragraph to understand what can be edited and how.
• Duplicate, to clone a rule and customize it. This copies the rule content to a new rule and is available for all rule types that can be customized. Refer to Add Rule to learn more. This is a useful action for customizing a managed rule to your needs. However, once you do this, you will need to maintain it like any other custom rule.
• Delete, available for custom rules. This cannot be completed if the rule is used by any policy.

View rule history

To view the rule changelog:

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

2. The Rule Details panel opens on the right.

3. If the rule has changed, you will see a “View as Diff” button on the top right of the “What” section.

   

4. By default, you will see the current definition on the right and the previous on the left. Use the dropdowns to select different versions and compare the differences.

5. Select View Default to return to the default view.

Add a Rule

To add a rule, you have two options:

• Start from scratch by clicking the Add Rule button in the top right of the Rules Library.
• Clone an existing rule using the Duplicate function from the Rule Detail. See Review the Rule Detail.

You can create custom Falco rules of the following types:

• AWS CloudTrail
• AWS GuardDuty
• Azure Platform Log
• GCP Audit Log
• GitHub
• Kubernetes Audit
• Microsoft Entra
• Okta
• Linux Workload

Regardless of the selected type, you will need to provide the following details:

• Name
• Description
• Tags

Then, depending on the rule type, you will complete the rule definition. To learn more, see Rule Definition.

Edit & Customize a Rule

To edit a rule:

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

2. The Rule Details panel opens on the right.

From there, you can:

• Edit the rule definition by clicking the Edit button:

  • For a managed Falco rule, you can append a condition, append the output, create custom exceptions, or add values to existing exceptions.
  • For a custom rule, you can edit its entire definition.

  In both cases, you can do this using a form that shows all the parameters in the rule definition or using the YAML format.

• For Falco rules, edit the Lists and Macros included in the rule, which are highlighted by a grey, rounded background, by clicking on them:

  • You can append to Lists and Macros provided by Sysdig, as explained in Append to Rules Macros and Lists.
  • You can edit custom Lists and Macros. See more in the dedicated section.

For more information about the content that can be modified and how, see Rule definition.

Managed Rules and Releases

Sysdig’s Threat Research Team maintains the managed rules and publishes updates as releases. Each release lists the rules that were added, changed, or removed:

• Falco Rules Changelog, for the managed Falco rules.
• Behavioral Analytics Changelog, for the managed behavioral analytics rules.

A managed rule shows its author and the release it comes from in the rule detail. See Review the Rule Detail. To see what changed in a rule between releases, see View rule history.

Update Managed Rules on SaaS

Sysdig Secure SaaS always uses the most up-to-date managed rules. You do not need to manually update managed rules.

Update Managed Rules On-Prem

On-premises installations receive the managed rules with the rules installer. The managed Falco rules, the behavioral analytics rules, and the managed policies are updated daily at midnight UTC, unless you disable it. To change or disable the schedule, see Managed Policy Updates.

In airgapped installations, the installer can’t pull its image from the internet. You mirror the image to your own registry and control when the update runs. See Update Managed Rules in Airgapped On-Prem.

The Falco Rules Changelog shows, for each release, the version of the Falco rules installer that includes it.

Understand Threat Detection Rules

Rules define what types of activity an enterprise wants to detect in its environment. They are the fundamental building blocks of your security policies.

Policies define where the rules apply and with which consequences, such as the severity, the notifications, and the policy actions. See Manage Threat Detection Policies.

Most rules are written in the Falco rules syntax, which can be complex and layered. Sysdig delivers Falco rules by default, and you can also create your own. Other rule types, such as behavioral analytics, drift, malware (which includes YARA rules provided by Sysdig), FIM, and machine learning, are defined by Sysdig or inside their policy. To learn what you can do with each type, see Rule Types Capabilities.

Using Falco within Sysdig Secure

Falco is an open-source intrusion detection and activity monitoring project. Designed by Sysdig, the project has been donated to the Cloud Native Computing Foundation, where it continues to be developed and enhanced by the community. Sysdig Secure incorporates the Falco Rules Engine as part of its Policy and Compliance modules.

Falco rules consist of a condition under which an alert should be generated and an output to send with the alert. In Sysdig Secure, you will primarily interact with Falco through writing or customizing the rules deployed in the policies for your environment.

Anatomy of a Falco Rule

A Falco rule is made of the following parts:

Name: Uniquely identifies a rule. You can’t change it after the rule is created, because other elements can refer to it. Description: Describes what the rule aims to detect and how. Condition: A boolean expression that Sysdig evaluates for each event. When it’s true, the rule triggers. Its syntax is described in Write a Condition. Conditions can reuse macros and lists:

• Macros are rule condition snippets that can be re-used inside rules and other macros, providing a way to factor out and name common patterns.
• Lists are lists of items that can be included in rules, macros, or other lists. Unlike rules and macros, they are not expressions: they are sets of values. Output: The message shown in the What section of the event. See Write the Output. Priority: Defines the importance of a detection (that is, the gravity of the condition being met). Don’t confuse it with the policy’s severity, which applies to a specific context. Tags: Categorize the event, usually by attack phase or according to a framework like MITRE ATT&CK. You can also use them to search and sort rules. Exceptions: Define when the event should not trigger, suppressing false positives and reducing noise. See Work with Exceptions.

Select a rule from Rules > Rules Library to see or edit its underlying structure. The same structure applies when creating a new Falco rule and adding it to the library.

Falco Macros

Macros make rules easier to write. They name common scenarios, so you can use them in any rule instead of repeating the same condition. The default rule set defines many of them. You can browse them, examine a macro’s condition, or create your own. See Falco Lists and Macros.

Falco Lists

Lists make rules easier to adapt to your environment. They name sets of values, so you can customize them once and reference them from any rule. For example, you can customize the default list allow.inbound.source.domains and use it in your own rules.

Rule Exceptions

To reduce false positives, Sysdig uses 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.

For how exceptions are defined and managed, see Work with Exceptions.

Available Fields

The fields you can use in conditions and outputs depend on the rule type. For the complete list, see the Falco reference library.

Work with Exceptions

Exceptions let a rule skip behavior that is expected or temporarily accepted, to reduce false positives. They are tied to a rule: each exception defines the fields and operators an event is checked against, and the values that are allowed.

You can add values to the exceptions of a managed Falco rule, or define new exceptions on custom rules, from the rule’s Edit page or the Rules Editor. To learn how exceptions work, how to create them, and how to apply them from an event, see Work with Exceptions in Tune Runtime Threat Detection Policies.

Falco Lists and Macros

The default Falco rules have a variety of Macros and Lists embedded in them. These types of elements are useful for defining sets of values (lists) and common conditions (macros) that you can use in multiple rules, such as a list of trusted images or an outbound TCP connection macro.

The managed rules contain these elements for you to add well-known items in your environment. These elements all start with user_known, such as the user_known_ips list and the user_known_cron_jobs macro.

A List is a named set of values that you reference within a comparison, such as fd.cip.name in (allowed_inbound_source_domains). A Macro is a named piece of condition, so you combine it with logical operators, such as not user_known_cron_jobs.

From the Lists and Macros pages (Policies > Rules > Falco Lists and Falco Macros), you can see all defined elements. Like the rules, elements published by Sysdig are provided, and you can only append to them. If an element is published by both Sysdig and Secure UI, it means that it has already been customized with an append, and the append can be edited. Elements published by Secure UI are custom and can be edited. Using the Add action at the top, you can add additional custom elements.

Customize Lists and Macros

You can customize Lists and Macros in two ways:

• Directly from the respective pages (Policies > Rules > Falco Lists and Falco Macros) by opening an element.
• From a rule detail by opening it directly (Policies > Rules > Rules Library, then select a rule) or from the events detail. You can visually identify rules using Lists and Macros by looking for elements in the condition with a grey background. Click on the element to customize it.

The element content appears. Macros and lists can reference other macros and lists, which you can open in turn.

For custom elements, you can Edit the definition, excluding the name.

For managed elements, you can Append content if it hasn’t been done already, or Edit Append if it has.

Add Custom Lists and Macros

From the Lists and Macros pages (Policies > Rules > Falco Lists and Falco Macros), click Add in the top right.

From there, define a name and content.

Remember that Lists are comma-separated sets of elements, while Macros are complete logical operations, similar to rule conditions.

Append to Rules, Macros, and Lists

Rules, macros, and lists published by Sysdig are managed: their definition is updated by the Threat Research team and you can’t edit it. To adapt one to your environment without losing those updates, append your own content to it. Sysdig keeps your append separate and applies it on top of the managed definition each time the definition is updated.

An append adds to the original definition. It never replaces or removes anything from it.

An append of any kind:

• Must match an existing element with the same name.
• Can’t change the append setting of an element after it’s created.
• Is not available for behavioral analytics rules, except for adding values to their predefined exceptions.

How the content is combined:

• Rule condition: the appended text is added to the end of the original condition, so start it with and or or. For example, appending and not container.image.repository = "my-registry/tool" excludes that image. To exclude behavior, prefer an exception, which is easier to maintain.
• Rule output: the appended text is added after the original output. You can use any field available for the rule type.
• Macro: the appended condition is added to the macro condition, which changes everywhere the macro is used.
• List: the appended items are added to the end of the list.

In YAML, an append references the element by name, adds append: true, and sets only the part you want to add:

- list: user_known_ips
  items: [203.0.113.10]
  append: true

- macro: user_known_cron_jobs
  condition: or (proc.cmdline startswith "/opt/my-tool/run")
  append: true

- rule: Terminal shell in container
  condition: and not container.image.repository = "my-registry/tool"
  output: image=%container.image.repository
  append: true

Your appends appear in the What section of the element as a separate block, identified by the Secure UI author. See Review the Rule Detail.

Rule Definition

The first attribute of the rule definition is its type. It is defined by a combination of the engine the rule operates in and the raw event it applies to. It uniquely identifies a language, meaning a set of fields, conditions, and outputs that are available, either statically defined or customizable.

The main body content depends on the rule type and is explained in the following sections:

• Behavioral Analytics: All rules marked as Observation type, or published by Sysdig stateful (top right corner of the rule definition).
• Falco-based rules: All other rules.

Rule Types Capabilities

The following table summarizes what actions can be performed on each rule type:

Notes:

• View content - From policy: The rule is embedded in the policy. Refer to the policies to manage these rules.
• Custom - Edit only: You can only customize the existing ones, cannot create new ones.
• Exceptions - Add values only: It’s only possible to add values to predefined exceptions.

Falco-Based Rules

The parts of a Falco rule are described in Anatomy of a Falco Rule. The following sections explain how to write the condition and the output.

Write a Condition

The condition is a boolean expression that Sysdig evaluates for each event. When it’s true, the rule triggers and produces an event. When it’s false, nothing happens. A condition combines comparisons with logical operators, and each comparison has a field, an operator, and a value:

container.id != host and proc.name in (bash, sh) and not proc.pname = "sshd"

This condition is true for the bash or sh processes that run inside a container, unless their parent process is sshd.

Operators at a glance

Fields

A field is a property of the event, such as proc.name, user.name or container.image.repository. Each field has a type, such as string, number, or list, and the type decides which operators you can use. Each rule type has its own fields. See Available Fields and the Falco reference library.

Values

The value on the right of a comparison is a string, a number, or a set of values in parentheses, such as (bash, sh). You can also use the name of a list, or another field with val().

Write strings that contain spaces or special characters in quotes, for example proc.name = "my tool". Using quotes is always allowed, so quote when in doubt.

Comparison operators

Fields of type list support only in, exists, and intersects.

Logical operators

Use and, or, and not to build a condition from simple comparisons. and and or join two expressions, and not negates the expression that follows it. Use parentheses to control the order of evaluation and to keep long conditions readable:

(proc.name = "curl" or proc.name = "wget") and not proc.pname = "my_updater"

Check that a field has a value

exists is true when the field has a value for the event. For example, proc.pname exists is true for events where the process has a parent. Use not to check for the opposite: not proc.pname exists.

Transform a field

Transformers change a field before the comparison. Write them as a function around the field:

For example, tolower(proc.name) = "curl" matches curl, Curl, and CURL. You can apply transformers on either side of the comparison.

Compare two fields

To compare a field to another field instead of to a fixed value, wrap the right-hand field in val(). For example, proc.name = val(proc.pname) matches the processes that have the same name as their parent.

Compare to several values at once

Where available, you write the values in parentheses after the operator, for example proc.cmdline contains anyof (curl, wget). anyof is true if at least one of the values matches, allof if every value matches, and oneof if exactly one value matches. They work with the equality and string operators, such as =, !=, contains, startswith, endswith, glob, and regex, but not with in, intersects, pmatch, exists, or the numeric operators. To exclude several values, use allof with !=: anyof would match a value that differs from only one of them. An empty set of values makes all three false.

Reuse parts of a condition

Macros and lists let you name and reuse parts of a condition. Reference a macro by its name as if it were a comparison, and a list inside in (...):

spawned_process and not user_known_cron_jobs and proc.name in (shell_binaries)

See Falco Lists and Macros.

Write the Output

The output is a text template. Add % before a field name to insert its value from the event, for example:

Shell started in container (user=%user.name command=%proc.cmdline image=%container.image.repository)

You can use any field available for the rule type.

The event collects the fields you reference in the output, in addition to its other fields. The What section of the event shows the output text with each %field replaced by its value, and the rule description below it. If the output has the format first part (second part), the What section shows only the first part. Use the part in parentheses to collect the fields you want in the event without making the visible message long. In the example, the What section shows Shell started in container, and the user, command, and image are still available as event fields.

A field you include in the output shows as <NA> in the event when it’s absent or has no value for that event. For example, %container.image.repository is <NA> for activity on a host, outside any container. <NA> doesn’t mean an error.

You can also compare a field to <NA> in a condition, for example proc.pname != "<NA>", but this isn’t the usual approach. To check that a field has a value, use the exists operator instead, for example proc.pname exists.

Behavioral Analytics

Behavioral Analytics rules are more complex rules that match against multiple events with common attributes happening in a well-defined period of time and/or order. These rules are defined and managed by the Sysdig Threat Research team. They’re currently available for AWS CloudTrail and Linux Workloads.

As with Falco rules, the description explains what is matched and how, so you can understand the detection. In Linux Workload Behavioral Analytics, there is also a Falco-compatible output.

Unlike Falco rules, the only customization available in AWS Behavioral Analytics rules is appending exception values.

Rules Editor

The Rules Editor lets you freely create custom Falco elements like rules, lists, and macros, modify them and create appends, as you would do when using Falco directly, through a YAML ruleset.

To access the Rules Editor interface, select Policies > Rules > Rules Editor:

The right panel displays the various rulesets provided by Sysdig, in read-only mode. You can select them by using the dropdown.

On the left side, under Custom Rules, you can see the custom elements you created. Use Save to apply your changes, or Discard Changes to undo them.

The editor supports basic capabilities, like a find and replace function, accessible with Ctrl + F/Cmd + F or code completion upon writing.

Exceptions defined in YAML use the same structure as in the form. See Manage Rule Exceptions in YAML.