Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update docker images usage for Falco 0.40 #1411

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
+57 −64
Open

update docker images usage for Falco 0.40 #1411

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e44f6a9
update(docs/download): update container images table for Falco 0.40
leogr Nov 6, 2024
49bbe08
update(docs/setup): update container images instructions for Falco 0.40
leogr Nov 6, 2024
c483545
fix(content/en/docs): container setup paths in examples
leogr Nov 19, 2024
b7705c2
chore(content/en/docs): reorder container setup paths in examples
leogr Nov 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 46 additions & 55 deletions content/en/docs/setup/container.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,70 +31,58 @@ To run Falco in a container using Docker with full privileges, use the following

#### Modern eBPF {#docker-privileged-modern-ebpf}

The {{< glossary_tooltip text="Modern eBPF" term_id="modern-ebpf-probe" >}} is bundled into the Falco binary. Therefore, the `falcosecurity/falco-no-driver` image is enough to run Falco. This allows you to run Falco without dependencies by using the following command:
The {{< glossary_tooltip text="Modern eBPF" term_id="modern-ebpf-probe" >}} is bundled into the Falco binary. This allows you to run Falco without dependencies by using the following command:

```shell
docker pull falcosecurity/falco-no-driver:latest
docker pull falcosecurity/falco:latest
docker run --rm -it \
--privileged \
-v /var/run/docker.sock:/host/var/run/docker.sock \
-v /proc:/host/proc:ro \
-v /etc:/host/etc:ro \
falcosecurity/falco-no-driver:latest
falcosecurity/falco:latest
```

#### Kernel Module {#docker-privileged-kernel-module}

To use Falco with the {{< glossary_tooltip text="Kernel Module" term_id="kernel-module" >}} driver, run:
For the {{< glossary_tooltip text="Kernel Module" term_id="kernel-module-driver" >}} driver, Falco requires the driver to be installed on the host system first.

```shell
docker pull falcosecurity/falco:latest
docker run --rm -it \
--privileged \
-e FALCO_DRIVER_LOADER_OPTIONS="kmod" \
-v /var/run/docker.sock:/host/var/run/docker.sock \
-v /dev:/host/dev \
-v /proc:/host/proc:ro \
-v /boot:/host/boot:ro \
-v /lib/modules:/host/lib/modules:ro \
-v /usr:/host/usr:ro \
-v /etc:/host/etc:ro \
falcosecurity/falco:latest falco
```
1. Install the driver on the host system using the `falcosecurity/falco-driver-loader` image, as described in the [Driver Installation](#driver-installation-kernel-module) section.

{{% pageinfo color="primary" %}}
Alternatively, you can install the driver on the host system first, then run Falco in a separate container. In such cases:
2. Run Falco:

```shell
docker pull falcosecurity/falco:latest
docker run --rm -it \
--privileged \
-v /var/run/docker.sock:/host/var/run/docker.sock \
-v /dev:/host/dev \
-v /proc:/host/proc:ro \
-v /etc:/host/etc:ro \
falcosecurity/falco:latest falco -o engine.kind=kmod
```

1. Install the driver on the host system using the `falcosecurity/falco-driver-loader` image, as described in the [Driver Installation](#driver-installation-kernel-module) section.
2. Replace `falcosecurity/falco:latest` with `falcosecurity/falco-no-driver:latest` in the above command.
{{% /pageinfo %}}

#### eBPF Probe {#docker-privileged-ebpf}

To use Falco with the {{< glossary_tooltip text="eBPF probe" term_id="ebpf-probe" >}} driver, run:
For the {{< glossary_tooltip text="eBPF probe" term_id="ebpf-probe" >}} driver, Falco requires the probe to be prepared and stored on the host system first (under `/root/.falco`).

```shell
docker pull falcosecurity/falco:latest
docker run --rm -it \
--privileged \
-e FALCO_DRIVER_LOADER_OPTIONS="ebpf" \
-v /var/run/docker.sock:/host/var/run/docker.sock \
-v /proc:/host/proc:ro \
-v /boot:/host/boot:ro \
-v /lib/modules:/host/lib/modules:ro \
-v /usr:/host/usr:ro \
-v /etc:/host/etc:ro \
falcosecurity/falco:latest falco
1. Install the driver on the host system using the `falcosecurity/falco-driver-loader` image, as described in the [Driver Installation](#driver-installation-ebpf-probe) section.

# If running a kernel version < 4.14, add '-v /sys/kernel/debug:/sys/kernel/debug:ro \' to the above docker command.
```
2. Run Falco:

{{% pageinfo color="primary" %}}
Alternatively, you can install the driver on the host system first, then run Falco in a separate container. In such cases:
```shell
docker pull falcosecurity/falco:latest
docker run --rm -it \
--privileged \
-v /var/run/docker.sock:/host/var/run/docker.sock \
-v /proc:/host/proc:ro \
-v /boot:/host/boot:ro \
leogr marked this conversation as resolved.
Show resolved Hide resolved
-v /etc:/host/etc:ro \
leogr marked this conversation as resolved.
Show resolved Hide resolved
falcosecurity/falco:latest falco -o engine.kind=ebpf

1. Install the driver on the host system using the `falcosecurity/falco-driver-loader` image, as described in the [Driver Installation](#driver-installation-ebpf-probe) section.
2. Replace `falcosecurity/falco:latest` with `falcosecurity/falco-no-driver:latest` in the above command.
{{% /pageinfo %}}
# If running a kernel version < 4.14, add '-v /sys/kernel/debug:/sys/kernel/debug:ro \' to the above docker command.
```

### Least Privileged (Recommended) {#docker-least-privileged}

Expand All @@ -103,6 +91,7 @@ To run Falco in a container using Docker with the [principle of least privilege]
#### Modern eBPF {#docker-least-privileged-modern-ebpf}

```shell
docker pull falcosecurity/falco:latest
docker run --rm -it \
--cap-drop all \
--cap-add sys_admin \
Expand All @@ -111,7 +100,7 @@ docker run --rm -it \
-v /var/run/docker.sock:/host/var/run/docker.sock \
-v /proc:/host/proc:ro \
-v /etc:/host/etc:ro \
falcosecurity/falco-no-driver:latest
falcosecurity/falco:latest
```

{{% pageinfo color="primary" %}}
Expand All @@ -133,16 +122,16 @@ For the {{< glossary_tooltip text="Kernel Module" term_id="kernel-module-driver"

1. Install the driver on the host system using the `falcosecurity/falco-driver-loader` image, as described in the [Driver Installation](#driver-installation-kernel-module) section.

2. Run Falco using the `falcosecurity/falco-no-driver` image with the least privileges:
2. Run Falco using the `falcosecurity/falco` image with the least privileges:

```shell
docker pull falcosecurity/falco-no-driver:latest
docker pull falcosecurity/falco:latest
docker run --rm -it \
-e HOST_ROOT=/ \
--cap-add SYS_PTRACE --pid=host $(ls /dev/falco* | xargs -I {} echo --device {}) \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /etc:/host/etc:ro \
falcosecurity/falco-no-driver:latest falco -o engine.kind=kmod
falcosecurity/falco:latest falco -o engine.kind=kmod
```

{{% pageinfo color="primary" %}}
Expand All @@ -166,10 +155,10 @@ For the {{< glossary_tooltip text="eBPF probe" term_id="ebpf-probe" >}} driver,

1. Install the driver on the host system using the `falcosecurity/falco-driver-loader` image, as described in the [Driver Installation](#driver-installation-ebpf-probe) section.

2. Run Falco using the `falcosecurity/falco-no-driver` image with the least privileges:
2. Run Falco using the `falcosecurity/falco` image with the least privileges:

```shell
docker pull falcosecurity/falco-no-driver:latest
docker pull falcosecurity/falco:latest
docker run --rm -it \
--cap-drop all \
--cap-add sys_admin \
Expand All @@ -179,7 +168,7 @@ For the {{< glossary_tooltip text="eBPF probe" term_id="ebpf-probe" >}} driver,
-v /root/.falco:/root/.falco \
-v /etc:/host/etc \
-v /proc:/host/proc:ro \
falcosecurity/falco-no-driver:latest falco -o engine.kind=ebpf
falcosecurity/falco:latest falco -o engine.kind=ebpf

# If running a kernel version < 4.14, add '-v /sys/kernel/debug:/sys/kernel/debug:ro \' to the above Docker command.
```
Expand Down Expand Up @@ -210,18 +199,20 @@ To run Falco with the least privileges using the eBPF probe, the following capab

This section provides instructions for installing the driver on the host system using the `falcosecurity/falco-driver-loader` image. This approach is helpful if you prefer to install the driver on the host first and then run Falco in a container later.

Driver installation on the host is only required for the {{< glossary_tooltip text="Kernel Module" term_id="kernel-module-driver" >}} and {{< glossary_tooltip text="eBPF probe" term_id="ebpf-probe" >}} drivers when these drivers are installed in separate stages.
Driver installation on the host is only required for the {{< glossary_tooltip text="Kernel Module" term_id="kernel-module-driver" >}} and {{< glossary_tooltip text="eBPF probe" term_id="ebpf-probe" >}} drivers.

You can **skip this section** if you plan to use:
- The {{< glossary_tooltip text="Modern eBPF" term_id="modern-ebpf-probe" >}} driver; or
- The fully privileged method with the `falcosecurity/falco` image.
You can **skip this section** if you plan to use the {{< glossary_tooltip text="Modern eBPF" term_id="modern-ebpf-probe" >}}.

{{% pageinfo color="primary" %}}
When using the eBPF probe or kernel module drivers, the driver loader attempts to either download a prebuilt driver or build it on the fly as a fallback. Starting with Falco 0.38, the driver loader has improved functionality to automatically retrieve the required kernel headers for distributions supported by [driverkit](https://github.com/falcosecurity/driverkit). This enhancement ensures that the necessary kernel headers are available to dynamically build the appropriate driver—whether it is the {{< glossary_tooltip text="Kernel Module" term_id="kernel-module-driver" >}} or the {{< glossary_tooltip text="eBPF probe" term_id="ebpf-probe" >}}.

However, if the driver loader cannot automatically fetch the required kernel headers, you may need to install them manually on the host as a prerequisite. For detailed instructions on manual installation, refer to the [Installation section](/docs/getting-started/installation).
{{% /pageinfo %}}

{{% pageinfo color="primary" %}}
The `falcosecurity/falco-driver-loader:latest` is based on a recent Debian image. For ancient kernel versions, this might not work. The alternative `falcosecurity/falco-driver-loader:latest-buster` (based on an older Debian image) may work in such a case.
{{% /pageinfo %}}

### Kernel Module {#driver-installation-kernel-module}

To install the kernel module driver on the host system, you can use the following command:
Expand Down Expand Up @@ -267,7 +258,7 @@ cosign verify docker.io/falcosecurity/falco:{{< latest >}} \
--certificate-github-workflow-ref=refs/tags/{{< latest >}}
```

Replace `docker.io/falcosecurity/falco` with any official Falco image (`falco`, `falco-no-driver`, `falco-driver-loader`) from any official container registry to verify other images.
Replace `docker.io/falcosecurity/falco` with any official Falco image (`falco`, `falco-driver-loader`) from any official container registry to verify other images.

If you have your own container registry and wish to retain the signature while copying Falco images, you can simply use the cosign copy command:

Expand Down
14 changes: 8 additions & 6 deletions content/en/docs/setup/download.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,12 +42,14 @@ The tables below provide quick pull commands for Falco container images hosted a

|tag | pull command | description |
|----|----------|-----------------|
|[latest](https://hub.docker.com/r/falcosecurity/falco-no-driver/tags)| `docker pull falcosecurity/falco-no-driver:latest` | The most recent version |
|[*version*](https://hub.docker.com/r/falcosecurity/falco-no-driver/tags)| `docker pull falcosecurity/falco-no-driver:<version>` | A specific version of Falco such as `{{< latest >}}` |
|[latest](https://hub.docker.com/r/falcosecurity/falco-driver-loader/tags)| `docker pull falcosecurity/falco-driver-loader:latest` | The most recent version of `falco-driver-loader` with the building toolchain |
|[*version*](https://hub.docker.com/r/falcosecurity/falco-driver-loader/tags)| `docker pull falcosecurity/falco-driver-loader:<version>` | A specific version of `falco-driver-loader` such as `{{< latest >}}` with the building toolchain |
|[latest](https://hub.docker.com/r/falcosecurity/falco/tags)| `docker pull falcosecurity/falco:latest` | The most recent version with the `falcoctl driver` tool included |
|[*version*](https://hub.docker.com/r/falcosecurity/falco/tags)| `docker pull falcosecurity/falco:<version>` | A specific version of Falco such as `{{< latest >}}` with `falcoctl driver` tool included |
|[latest](https://hub.docker.com/r/falcosecurity/falco/tags)| `docker pull falcosecurity/falco:latest` | Distroless image with the latest released of Falco. No tools are included in the image. |
|[*version*](https://hub.docker.com/r/falcosecurity/falco/tags)| `docker pull falcosecurity/falco:<version>` | Distroless image with a specific version of Falco such as `{{< latest >}}`. No tools are included in the image. |
|[latest-debian](https://hub.docker.com/r/falcosecurity/falco/tags)| `docker pull falcosecurity/falco:latest-debian` | Debian-based image with the latest released of Falco. Available since Falco 0.40. |
|[*version*-debian](https://hub.docker.com/r/falcosecurity/falco/tags)| `docker pull falcosecurity/falco:<version>-debian` | Debian-based image with a specific version of Falco such as `{{< latest >}}`. Available since Falco 0.40. |
|[latest](https://hub.docker.com/r/falcosecurity/falco-driver-loader/tags)| `docker pull falcosecurity/falco-driver-loader:latest` | Debian-based image with the most recent Falco driver loader and the building toolchain. |
|[*version*](https://hub.docker.com/r/falcosecurity/falco-driver-loader/tags)| `docker pull falcosecurity/falco-driver-loader:<version>` | Debian-based image with specific version of `falco-driver-loader` such as `{{< latest >}}` and the building toolchain. |
|[latest-buster](https://hub.docker.com/r/falcosecurity/falco-driver-loader/tags)| `docker pull falcosecurity/falco-driver-loader:latest` | Same as `falco-driver-loader:latest` but based on Debian `buster`. Available since Falco 0.40. |
|[*version*-buster](https://hub.docker.com/r/falcosecurity/falco-driver-loader/tags)| `docker pull falcosecurity/falco-driver-loader:<version>` | Same as `falco-driver-loader:<version>` but based on Debian `buster`. Available since Falco 0.40. |

### Rules {#rules}

Expand Down