Repository files navigation

This repository has been created upon thisProposal and contains the officially managedFalco Rules by The Falco Project, along with theFalco Rules Files Registry.

Rules tellFalco what to do. These rules are pre-defined detections for various security threats, abnormal behaviors, and compliance-related monitoring.

   Explore theOfficial Documentation for a starting point and better understanding of rule concepts. Users can modify the community-contributed Falco rules to fit their needs or use them as examples. In most cases, users also create their own custom rules. Keep in mind that the rules in this repository are related to Falco's primary monitoring functions, specifically for syscalls and container events. Meanwhile, Falco plugin rules are stored within the respective subfolders of thePlugins repository.

   Because Falco rules, especially Sandbox and Incubating rules, are dynamic, it's crucial to stay updated. As threats and systems evolve, Falco evolves with each release. Therefore, regularly check theRules Overview Document, Falco'sSupported Fields, and Falco's release notes with every new release. It is recommended to consistently use the most recentFalco Release to avoid compatibility issues.

   Important: The Falco Project only guarantees that the most recent rules releases are compatible with the latest Falco release. Discover all rule files in therules/ folder. Refer to ourRelease Process andRules Maturity Framework for rule categorization, release procedures, and usage guidelines. Published upon tagging a new release, thematurity_stable rules in thefalco_rules.yaml file are included in the Falco release package. Other maturity-level rules are released separately, requiring explicit installation and possible customization for effectiveAdoption.

   Beginning with rules version 3.0.0, therequired_engine_version followsSemantic Versioning and requires Falco version 0.37.0 or higher. Since rules version2.0.0, we've modified our rules' shipping and distribution process. With Falco >= 0.37.0,Selective Rules Overrides aim to further streamline the customization of rules. Since Falco 0.36.0, you can use therule_matching config to resolve issues with rules overlapping, which is caused by the default "first match wins" principle. Starting from Falco 0.35.0, you have precise control over the syscalls that are being monitored, seebase_syscalls. Lastly, keep in mind that theRules Maturity Framework is a best effort on the part of the community, and ultimately, you have to decide if any rules are useful for your use cases.

   Be cautious: Themain branch has the latest development. Before using rules from themain branch, check for compatibility. Changes like new output fields might cause incompatibilities with the latest stable Falco release. The Falco Project recommends using rules only from the release branches. Lastly, we'd like to highlight the importance of regular engineering effort to effectively adopt Falco rules. Considering that each adopter's system and monitoring needs are unique, it's advisable to view the rules as examples.

   Debugging: Historically, we've noted that issues often arise either from incorrect configurations or genuine bugs, acknowledging that no software is entirely bug-free. The Falco Project continually updates itsInstall and Operate andTroubleshooting guides. We kindly suggest reviewing these guides. In the context of Falco rules, missing fields, such as container images, may be anticipated within our imperfection tolerances under certain circumstances. We are committed to addressing and resolving issues within our control.

The Falco Rules Files Registry contains metadata and information about rules files distributed by The Falco Project. 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 thePlugins repository.

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 theruleset 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 toSemantic Versioning. SeeRELEASE document for more details about our release process.

For instance, thefalco ruleset is stored under/rules/falco_rules.yaml, and its version1.0.0 was released using thefalco-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.

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 theContributing 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:

If you are using the official Helm chart, you can add the incubating and/or sandbox repository in yourfalcoctl config and by enabling them in the correspondingfalco.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 optionfalcoctl.config.artifact.install.refs governs which rules are downloaded at startup,falcoctl.config.artifact.follow.refs identifies which rules are automatically updated andfalco.rules_file indicates which rules are loaded by the engine.

If you are managing your Falco installation you should be aware of which directories contain the rules. Those are governed by therules_file configuration option in yourfalco.yaml. Normally, there is also arules.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 therules repository, uncompress and copy the file there.

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

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