Rule Format Version

Last modified November 29, 2022
Understand how Falco Rules support explicit versioning

From time to time, we make changes to the rules file format that are not backwards-compatible with older versions of Falco. Similarly, libsinsp and libscap may define new filtercheck fields, operators, etc. We want to denote that a given set of rules depends on the fields/operators from those libraries.

As of Falco version 0.14.0, the Falco rules support explicit versioning of both the Falco engine and the Falco rules file.

There are currently two optional fields in the falco rules file related to versioning:

ElementDescription
required_engine_versionUsed to track compatibility between rules content and the falco engine version.
required_plugin_versionsUsed to track compatibility between rules content and plugin versions.

Falco Engine Versioning

The falco executable and the falco_engine C++ object now support returning a version number. The initial version is 2 (implying that prior versions were 1). We will increment this version any time we make an incompatible change to the rules file format or add new filtercheck fields/operators to Falco.

Falco Rules File Versioning

The Falco rules files included with Falco include a new top-level object, required_engine_version: N, that specifies the minimum engine version required to read this rules file. If not included, no version check is performed when reading the rules file. Here's an example:

# This rules file requires a falco with falco engine version 7.
- required_engine_version: 7

If a rules file has an engine_version greater than the Falco engine version, the rules file is loaded and an error is returned.


Last modified November 29, 2022: add descriptions to sections (714da20)