Skip to content

falcosecurity/rules

Folders and files

NameName
Last commit message
Last commit date
Jan 16, 2024
Oct 11, 2023
Nov 7, 2023
Sep 4, 2023
Jan 16, 2024
Sep 4, 2023
Dec 21, 2022
Jun 19, 2023
Sep 25, 2023
Jun 7, 2023
Jul 26, 2023
Oct 11, 2023

Repository files navigation

Falco Rules

Falco Core Repository Stable License

Note: This repository has been created upon this proposal.

This repository maintains the default rules files officially owned by the Falcosecurity organization as well as the Falco Rules Files Registry.

Please note: since version 2.0.0 we changed how we ship and distribute the rules. Read more below.

Falco Rules

Rules tell Falco what to do. These rules are pre-defined detections for various security threats, abnormal behaviors, and compliance-related monitoring. Adopters can customize these rules to their specific needs or use them as examples. Please refer to the official documentation to better understand the rules' concepts.

The main branch contains the most up-to-date state of development. All rules files are located under the rules folder. Please refer to our Release Process to understand how rules are released. Stable rules are released and published only when a new release gets tagged. This means that rules in the main branch can become incompatible with the latest stable Falco release if, for example, new output fields are introduced.

Links:

Default Rules

The falco_rules.yaml file includes community-contributed Falco rules for syscalls and container events. These rules are part of the default Falco release package and are categorized by maturity level as maturity_stable, following the Rules Maturity Framework. Rules at the remaining maturity levels can be found within the Falco rules file according to their level. Rules at a maturity level lower than maturity_stable may need extra customization to ensure effective adoption.

For an up-to-date overview table linking to the respective Mitre Attack resources and more, please refer to the rules overview document. Lastly, you can find Falco plugins rules in the respective plugins repos' subfolder.

Interested in contributing your custom rules? Visit the contributing section below and join the Falco community now.

Falco Rules Files Registry

The Falco Rules Files Registry contains metadata and information about rules files distributed by the Falcosecurity organization. The registry serves as an additional method of making the rules files available to the community, complementing the process of retrieving the rules files from this repository.

Note: Currently, the registry includes only rules for the syscall call data source; for other data sources see the plugins repository.

Naming Convention

Rule files must be located in the /rules folder of this repository and are named according to the following convention: <ruleset>_rules.yaml.

The <ruleset> portion represents the ruleset name, which must be an alphanumeric string, separated by -, entirely in lowercase, and beginning with a letter.

Rule files are subsequently released using Git tags. The tag name should follow the pattern <ruleset>-rules-<version>, where <version> adheres to Semantic Versioning. See RELEASE.md for more details about our release process.

For instance, the falco ruleset is stored under /rules/falco_rules.yaml, and its version 1.0.0 was released using the falco-rules-1.0.0 tag.

Note: This convention applies to this repository only. Falco application does not impose any naming convention for naming rule files.

Falco Rules 2.x

Since version 2.0.0, the rules distributed from this repository have been split into three parts:

  • Stable Falco rules. Those are the only ones that are bundled in the Falco by default. It is very important to have a set of stable rules vetted by the community. To learn more about the criterias that are required for a rule to become stable, see the contributing guide.
  • Incubating rules, which provide a certain level of robustness guarantee but have been identified by experts as catering to more specific use cases, which may or may not be relevant for each adopter.
  • Sandbox rules, which are more experimental.

Previously, Falco used to bundle all the community rules in its default distribution. Today you can choose which set of rules you want to load in your distribution, depending on your preferred installation method:

Helm Chart

If you are using the official Helm chart, you can add the incubating and/or sandbox repository in your falcoctl config and by enabling them in the corresponding falco.yaml file.

For instance, in order to install the Helm chart and load all the available Falco rules with automatic update on all of them, you can run

helm install falco falcosecurity/falco --set "falcoctl.config.artifact.install.refs={falco-rules:2,falco-incubating-rules:2,falco-sandbox-rules:2}" --set "falcoctl.config.artifact.follow.refs={falco-rules:2,falco-incubating-rules:2,falco-sandbox-rules:2}" --set "falco.rules_file={/etc/falco/k8s_audit_rules.yaml,/etc/falco/rules.d,/etc/falco/falco_rules.yaml,/etc/falco/falco-incubating_rules.yaml,/etc/falco/falco-sandbox_rules.yaml}"

Where the option falcoctl.config.artifact.install.refs governs which rules are downloaded at startup, falcoctl.config.artifact.follow.refs identifies which rules are automatically updated and falco.rules_file indicates which rules are loaded by the engine.

Host installation

If you are managing your Falco installation you should be aware of which directories contain the rules. Those are governed by the rules_file configuration option in your falco.yaml. Normally, there is also a rules.d directory that you can use to upload extra rules or you can add your custom files.

Now you can simply download incubating or sandbox rules from the repository, uncompress and copy the file there.

Contributing

If you are interested in helping and wish to contribute, we kindly request that you review our general contribution guidelines and, more specifically, the dedicated rules contributing guide hosted in this repository. Please be aware that our reviewers will ensure compliance with the rules' acceptance criteria.

License

This project is licensed to you under the Apache 2.0 Open Source License.