Falcoctl: install and manage your rules and plugins
Since the launch of the plugin framework in January 2022, our adopters have requested an out-of-the-box solution to manage the lifecycle of rules (installation, updates). We heard your request and also created a guide to help you smoothly install the plugins.
The Falco maintainers proposed the following solution to help with these issues: falcoctl
. Falcoctl is a CLI tool that performs several useful tasks for Falco.
This blog post describes key concepts around falcoctl
to help you get started.
- Glossary
- Use falcoctl locally
- Use falcoctl in Kubernetes with Helm
- Disable falcoctl in the chart
- Conclusion
Glossary
Before diving into all the details, here's a glossary of the key words to understand how falcoctl
works. An exhaustive list can be found in the README.
Artifact
: An artifact is an elementfalcoctl
can manipulate, right now, onlyrulesfiles
andplugins
are considered.Index
: A .yaml file containing a list of available artifacts with their registries and repositories. The tool's default configuration contains an index file pointing to the officially supported artifacts from thefalcosecurity
organization, see here. Users can also maintain their own index files, pointing to registries and repositories containing custom rulesfiles and plugins.Registry
: A registry stores the artifacts, thatfalcoctl
understands in regards to the OCI standard, any compliant OCI can be used. The official registry uses Github Packages.Repository
: similar to containers, it belongs to a registry and contains one or more versions (tags) of an artifact.
Use falcoctl locally
The following steps explain the basic concepts used to install falcoctl
locally.
Installation
For a Linux amd64 system:
LATEST=$(curl -sI https://github.com/falcosecurity/falcoctl/releases/latest | awk '/location: /{gsub("\r","",$2);split($2,v,"/");print substr(v[8],2)}')
curl --fail -LS "https://github.com/falcosecurity/falcoctl/releases/download/v${LATEST}/falcoctl_${LATEST}_linux_amd64.tar.gz" | tar -xz falcoctl
sudo install -o root -g root -m 0755 falcoctl /usr/local/bin/falcoctl
Other environments are described in the README
Now you are able to confirm that the installation went well. Check the version:
❯ falcoctl version
Client Version: 0.4.0
Print the help:
❯ falcoctl --help
__ _ _ _
/ _| __ _| | ___ ___ ___| |_| |
| |_ / _ | |/ __/ _ \ / __| __| |
| _| (_| | | (_| (_) | (__| |_| |
|_| \__,_|_|\___\___/ \___|\__|_|
The official CLI tool for working with Falco and its ecosystem components.
Usage:
falcoctl [command]
Available Commands:
artifact Interact with Falco artifacts
completion Generate the autocompletion script for the specified shell
help Help with any command
index Interact with index
registry Interact with OCI registries
tls Generate and install TLS material for Falco
version Print the falcoctl version information
Flags:
--config string config file to be used for falcoctl (default "/etc/falcoctl/falcoctl.yaml")
--disable-styling Disable output styling such as spinners, progress bars and colors. Styling is automatically disabled if not attached to a tty (default false)
-h, --help help for falcoctl
-v, --verbose Enable verbose logs (default false)
Use "falcoctl [command] --help" for more information about a command.
Index
Before being able to download and install artifacts, we need to configure an index, we provide one for all official artifacts, plugins and rules:
sudo falcoctl index add falcosecurity https://falcosecurity.github.io/falcoctl/index.yaml
To confirm the installation:
❯ sudo falcoctl index list
NAME URL ADDED UPDATED
falcosecurity https://falcosecurity.github.io/falcoctl/index.yaml 2023-02-14 14:57:33 2023-02-14 15:48:43
The index is not automatically updated, when a new artifact is added to the list, you can refresh your local cache with:
sudo falcoctl index update falcosecurity
Configuration
The default configuration of falcoctl
is /etc/falcoctl/falcoctl.yaml
, as it can store secrets, like credentials to private registries, the file is protected by default.
❯ sudo cat /etc/falcoctl/falcoctl.yaml
indexes:
- name: falcosecurity
url: https://falcosecurity.github.io/falcoctl/index.yaml
To know more about available settings, see the official docs.
Search for artifacts
Everything is set up and ready. We can search for new artifacts:
❯ sudo falcoctl artifact search falco
INDEX ARTIFACT TYPE REGISTRY REPOSITORY
falcosecurity falco-rules rulesfile ghcr.io falcosecurity/rules/falco-rules
❯ sudo falcoctl artifact search kubernetes
INDEX ARTIFACT TYPE REGISTRY REPOSITORY
falcosecurity k8saudit plugin ghcr.io falcosecurity/plugins/plugin/k8saudit
falcosecurity k8saudit-rules rulesfile ghcr.io falcosecurity/plugins/ruleset/k8saudit
Note the
TYPE
column to determine the kind of artifact.
The search is made through names and keywords as we can find them in the index.yaml
:
- name: k8saudit
type: plugin
registry: ghcr.io
repository: falcosecurity/plugins/plugin/k8saudit
description: Read Kubernetes Audit Events and monitor Kubernetes Clusters
home: https://github.com/falcosecurity/plugins/tree/master/plugins/k8saudit
keywords:
- audit
- audit-log
- audit-events
- kubernetes
license: Apache-2.0
maintainers:
- email: cncf-falco-dev@lists.cncf.io
name: The Falco Authors
sources:
- https://github.com/falcosecurity/plugins/tree/master/plugins/k8saudit
Installation of artifacts
Installation of Rules
It's time to install our first artifact, the beloved falco default rules.
❯ sudo falcoctl artifact install falco-rules
INFO Reading all configured index files from "/root/.config/falcoctl/indexes.yaml"
INFO Resolving dependencies ...
INFO Installing the following artifacts: [ghcr.io/falcosecurity/rules/falco-rules:latest]
INFO Preparing to pull "ghcr.io/falcosecurity/rules/falco-rules:latest"
INFO Pulling ad24f8acf278: ############################################# 100%
INFO Pulling 0d3705a4650f: ############################################# 100%
INFO Pulling 0957c1ef3fe4: ############################################# 100%
INFO Artifact successfully installed in "/etc/falco"
By default, the latest
version is used, but you can specify a targeted tag sudo falcoctl artifact install falco-rules:0.5.0
.
All official artifacts come with floating tags, for example:
0
for the last0.x.x
0.5
for the last0.5.x
- etc
You can find the available versions (tags) with:
❯ sudo falcoctl artifact info falco-rules
REF TAGS
ghcr.io/falcosecurity/rules/falco-rules 0.0.0 0.1.0-rc1 0.1.0 0.1.0 latest
You can also directly check in Github: https://github.com/falcosecurity/rules/pkgs/container/rules%2Ffalco-rules
When you install a ruleset requiring specific plugins, the relative plugins are also installed!
❯ sudo falcoctl artifact install k8saudit-rules:0.5
INFO Reading all configured index files from "/root/.config/falcoctl/indexes.yaml"
INFO Resolving dependencies ...
INFO Installing the following artifacts: [ghcr.io/falcosecurity/plugins/ruleset/k8saudit:0.5 json:0.6.0 k8saudit:0.5.0]
INFO Preparing to pull "ghcr.io/falcosecurity/plugins/ruleset/k8saudit:0.5"
INFO Pulling cb5233c876c3: ############################################# 100%
INFO Pulling 4383c69ba0ad: ############################################# 100%
INFO Pulling 2c6ca9f7dac5: ############################################# 100%
INFO Artifact successfully installed in "/etc/falco"
INFO Preparing to pull "ghcr.io/falcosecurity/plugins/plugin/json:0.6.0"
INFO Pulling 65a28b294bff: ############################################# 100%
INFO Pulling 15fb7eddd978: ############################################# 100%
INFO Pulling f4ca8f34ad16: ############################################# 100%
INFO Artifact successfully installed in "/usr/share/falco/plugins"
INFO Preparing to pull "ghcr.io/falcosecurity/plugins/plugin/k8saudit:0.5.0"
INFO Pulling 3e249d372a35: ############################################# 100%
INFO Pulling c4abb288df01: ############################################# 100%
INFO Pulling 5e5cfe270518: ############################################# 100%
INFO Artifact successfully installed in "/usr/share/falco/plugins"
Installation of Plugins
Like rules, plugins can be installed with one simple command:
❯ sudo falcoctl artifact install github
INFO Reading all configured index files from "/root/.config/falcoctl/indexes.yaml"
INFO Resolving dependencies ...
INFO Installing the following artifacts: [ghcr.io/falcosecurity/plugins/plugin/github:latest]
INFO Preparing to pull "ghcr.io/falcosecurity/plugins/plugin/github:latest"
INFO Pulling 19dc1c0f62a0: ############################################# 100%
INFO Pulling d97aadfc1199: ############################################# 100%
INFO Pulling 5b9143db2a1d: ############################################# 100%
INFO Artifact successfully installed in "/usr/share/falco/plugins"
Easy!
Follow artifacts
A great feature of falcoctl
is its ability to run as a daemon to periodically check the artifacts' repositories and automatically install new versions.
The configuration of the behavior is also in /etc/falcoctl/falcoctl.yaml
.
indexes:
- name: falcosecurity
url: https://falcosecurity.github.io/falcoctl/index.yaml
artifact:
install:
refs:
- k8saudit:0.5.0
follow:
every: 6h0m0s
falcoVersions: http://localhost:8765/versions
refs:
- k8saudit:-rules:0.5
The install
section lists the references of the artifacts we want to install at deployment of falcoctl
.
The follow
section lists those we want to automatically update and check every
for frequency.
Some plugins and rules versions depend on the falco
version, falcoctl
request, and the falco
type of /versions
and API endpoint that gather intel, this is why we have the falcoVersions
field in the configuration.
We do not advise to disable the plugins, as they are binaries, and could lead to security breaks.
Systemd service
To help you set falcoctl
as a daemon, here's a systemd service template /etc/systemd/system/falcoctl.service
:
[Unit]
Description=Falcoctl
After=network.target
StartLimitIntervalSec=0
[Service]
Type=simple
Restart=always
RestartSec=1
ExecStart=/usr/local/bin/falcoctl artifact follow
To enable/start the new service:
❯ systemctl enable falcoctl
❯ systemctl start falcoctl
❯ systemctl status falcoctl
● falcoctl.service - Falcoctl
Loaded: loaded (/etc/systemd/system/falcoctl.service; static)
Active: active (running) since Thu 2023-02-16 16:46:32 CET; 1h ago
Main PID: 567876 (falcoctl)
Tasks: 9 (limit: 38132)
Memory: 6.8M
CPU: 15ms
CGroup: /system.slice/falcoctl.service
└─567876 /usr/local/bin/falcoctl artifact follow
Use falcoctl in Kubernetes with Helm
The last version of the falco
helm
chart, v3.0.0
includes falcoctl
as an init container and sidecar, to accordingly install and follow artifacts.
Add the official Helm repo
Nothing new under the sun, a classic helm
command:
helm repo add falcosecurity https://falcosecurity.github.io/charts
helm repo update
Configure the installation and followed by the artifacts
Like any other values, we can set the values.yaml
field to choose the artifacts to install and follow the index we use for.
...
falcoctl:
artifact:
install:
enabled: true
follow:
enabled: true
config:
indexes:
- name: falcosecurity
url: https://falcosecurity.github.io/falcoctl/index.yaml
artifact:
allowedTypes:
- rulesfile
- plugin
install:
resolveDeps: true
refs: [k8saudit-rules:0.5, falco-rules:0]
follow:
refs: [k8saudit-rules:0.5, falco-rules:0]
every: 6h
...
The
resolveDeps: true
avoids listing the plugin at install, and will be automatically installed with the rules.
Here's the final command to bootstrap a very basic installation with these settings:
helm install falco -n falco -f values.yaml falcosecurity/falco --create-namespace
Disable falcoctl in the chart
If for some reason you don't want to use falcoctl
to manage artifacts, you can disable its installation by following these steps:
helm install falco \
--set falcoctl.artifact.install.enabled=false \
--set falcoctl.artifact.follow.enabled=false
Conclusion
In this blog post we learned some of the basic falcoctl
usages that we can run locally and in our Kubernetes clusters with helm
. It helps to manage the lifecycle of the rules and the plugins with an out of the box solution like falcoctl`. Stay tuned as the plugin ecosystem is growing and we are seeing the development of more features and enhancements.
More posts will also be out soon to detail more advanced usages, such as using private registries and creating your own artifacts. See you soon!
Per usual, if you have any feedback or need help, you can find us at any of the following locations.
- Get started in Falco.org
- Check out the Falcoctl project on GitHub.
- Check out the Falco Rules on GitHub.
- Check out the Falco Plugins on GitHub.
- Get involved in the Falco community.
- Meet the maintainers on the Falco Slack.
- Follow @falco_org on Twitter.