The Falco Rules Tuner (Legacy)

This version of the tuner has been updated for Sysdig SaaS; this content is preserved for older on-prem Sysdig environments.

Sysdig policies are built on rules, including Falco rules and macros. (For review: Understanding Sysdig Secure Rules and Using Falco within Sysdig Secure.) Sysdig is always working to improve its out-of-the-box policies based on activity captured about well-known containers and OSS applications. Nevertheless, proprietary software running in unique user environments can require a customized approach.

The Falco Rule Tuner was created to simplify the process of updating the existing ruleset to reduce false positives.

The tool fetches policy events generated during a configurable time window (EVENT_LOOKBACK_MINUTES), and based on occurrence threshold (EVENT_COUNT_THRESHOLD), it suggests updates to rules. It’s up to the user to evaluate the suggestions and selectively apply the changes.

To use the Rule Tuner, you will provide some environment variables, run as a Docker container, review the output in a Slack channel or the terminal window, and then apply the recommended tuning adjustments as desired, in the Sysdig Secure Rules Editor.


  • Sysdig Secure SaaS or On-Prem version 3.5.0+

  • An available Slack channel (optional, for receiving output information)

  • Environment variable values listed in the table below

Set Variables and Run the Container

Gather the values needed for the following environment variables.

Required Environment Variables for Falco Rule Tuner




Optional: Name of the business entity. Default: test


The endpoint for the tuning engine to query.

For SaaS, see SaaS Regions and IP Ranges.

For On-Prem, the endpoint has been user-defined.


The Sysdig Secure API token used to access the Secure backend. See Find Sysdig API Token.


Optional: The Slack webhook URL to receive the events summary and rule tuning recommendations.

For example:


The number of minutes the Falco Rule Tuner should look back to gather the events. Default: 60


The threshold number of events over which a tuning is recommended. Default: 5.

Setting the threshold to 1 would mean that every policy event should be considered a false positive.

Required Environment Variables for Falco Rule Tuner

Run as a Docker container:


The output in the terminal window will show the recommended rules to be adjusted and the recommended/generated macros and their conditions, e.g.:

... <etc.>

# Change for rule: Write below root
- macro: elasticsearch-scripts_python_access_fileshost_exe_access_files
  condition: (container, image, repository endswith locationservices/elasticsearch-scripts and and ( startswith=/root/app/))

Check Output in Slack Channel (Optional)

The output provided in the terminal window includes only the recommended rule changes. If you provide a Slack channel URL in the environment variables, the Tuner gives both an event summary and the recommended rule changes.

For review: How to Use the Rules Editor.

The Tuner detects rules that may be triggering excess alert “noise” and proposes content relevant macros and macro conditions that would reduce the noise.

To implement the suggestions, you can 1) copy the rule contents directly into the left panel of the Rules Editor and edit them, or 2) find the existing placeholder macro that was created for that rule (usual format: user_known_<rule_name> ) and add the suggested macros and conditions there.

Note that editing the definition of a rule directly could cause overwrite issues when upgrading Sysdig versions. Creating custom rules or using the user_known placeholders is a safer procedure.

For example, suppose you decide to implement the Tuner prompt 4 in the image above, which suggests changing the configuration of the rule Write below root. One way to proceed:

  1. Search [CTRL F] the falco_rules.yaml for Write below root.

    You will find both the Rule itself

    and placeholder macros, user_known_write_below_root_activities and user_known_write_below_root_conditions. Either one can be used.

  2. Copy one placeholder to the left-hand Custom Rules panel of the Editor: user_known_write_below_root_activities .

  3. Copy the tuner-generated macro (elasticsearch-scripts_python_access_files in this case), and conditions into the Custom Rules panel, overwriting the never_true default condition. The result is something like:

    # generated by tuner and copied to here (custom panel in the rules editor)
    - macro: elasticsearch-xxx
      condition: (...)
    - macro: user_known_write_below_root_acitivies
      condition: (elasticsearch-xxx) # updated from "never_true" with the generated macro name
  4. Click Save.

    The tuning adjustment will apply when the Write below root rule is invoked in a policy.

These changes will apply anywhere that the edited macro ( user_known_write_below_root) is used. Some macros have been embedded in multiple rules and/or other macros. Edit at your discretion.