Thomas Labarussias Feb 24, 2023

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
- Add the official Helm repo
- Configure the installation and followed by the artifacts
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 element falcoctl can manipulate, right now, only rulesfiles and plugins 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 the falcosecurity 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, that falcoctl 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
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 last 0.x.x
0.5 for the last 0.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.

←Previous

You are viewing documentation for Falco version: v0.34.1