I read your Falco: Zero to Intermediate – Gold-Standard Hands-on Master Tutorial. It uses Ubuntu Server 24.04 LTS as its reference lab and covers Falco installation, runtime detection, alerts, and integrations.
Tutorials
Let’s extend that tutorial with a practical, end-to-end lab: install Falcosidekick on Ubuntu, connect it to Falco, generate test security events, and investigate the alerts.
1. Understand what we are building
Ubuntu 24.04 — Falco
Detects suspicious runtime activity
HTTP POST — JSON events
Falcosidekick — port 2801
Receives, enriches and forwards alerts
HTTP forwarding
Falcosidekick UI — optional
Visual alert investigation, normally port 2802
Falco is the detection engine. Falcosidekick is the alert-routing component; it is not itself the security detector. The UI is a separate component. On a standalone Ubuntu host, we can install Falcosidekick as a systemd service and configure Falco to send it JSON events over HTTP.
GitHub
+1
Our lab goals
- Confirm that Falco is working.
- Install and start Falcosidekick.
- Connect Falco to Falcosidekick.
- Generate safe, controlled test activity.
- View the alerts and investigate the process, command, user, and event priority.
- Troubleshoot events that do not arrive.
2. Step 1 — Check your Ubuntu and Falco installation
Run these commands on your Ubuntu server or VM.
# Check Ubuntu version
lsb_release -a
# Check CPU architecture
uname -m
# Check Linux kernel
uname -r
# Check whether Falco is installed
falco --version
# Find installed Falco services
systemctl list-unit-files | grep -i falco
# Check the Falco service status
sudo systemctl status falco-modern-bpf.service --no-pagerThe tutorial uses the service falco-modern-bpf.service for its modern eBPF lab. Your installation might use a different service name, so check the service list if the last command reports that the unit does not exist.
Tutorials
If Falco is already running, continue to Step 2. If it is not installed, use the official Falco Linux installation guide to install it and configure a supported driver before proceeding.
3. Step 2 — Install Falcosidekick on Ubuntu
We will install Falcosidekick as a native Linux service rather than using Kubernetes or Docker. This is suitable for a standalone Ubuntu lab.
3.1 Install the required utilities
sudo apt-get update
sudo apt-get install -y curl wget ca-certificates tar3.2 Download the latest Falcosidekick release
The following commands discover the latest GitHub release and download the correct archive for an x86-64 or ARM64 machine.
# Detect the machine architecture
ARCH="$(dpkg --print-architecture)"
case "$ARCH" in
amd64) SIDekICK_ARCH="amd64" ;;
arm64) SIDekICK_ARCH="arm64" ;;
*)
echo "Unsupported architecture: $ARCH"
exit 1
;;
esac
# Get the latest release tag from GitHub
VERSION="$(curl -fsSL \
https://api.github.com/repos/falcosecurity/falcosidekick/releases/latest \
| grep '"tag_name":' \
| head -n 1 \
| cut -d '"' -f 4)"
echo "Architecture: $ARCH"
echo "Release: $VERSION"
# Download the matching release archive
curl -fL \
"https://github.com/falcosecurity/falcosidekick/releases/download/${VERSION}/falcosidekick_${VERSION}_linux_${SIDekICK_ARCH}.tar.gz" \
-o /tmp/falcosidekick.tar.gzCheck the release and archive before extracting:
# Inspect the downloaded archive
tar -tzf /tmp/falcosidekick.tar.gz | head -n 20
# Extract into a temporary directory
mkdir -p /tmp/falcosidekick-install
tar -xzf /tmp/falcosidekick.tar.gz \
-C /tmp/falcosidekick-install
# Locate the binary
find /tmp/falcosidekick-install -type f -name falcosidekickIf the archive contains the binary at the expected path, install it:
# Install the executable
sudo install -m 0755 \
/tmp/falcosidekick-install/falcosidekick \
/usr/local/bin/falcosidekick
# Verify the binary
/usr/local/bin/falcosidekick --helpThese steps follow the project’s documented native-host installation approach.
GitHub
If the download returns 404: inspect the current release assets at Falcosidekick releases and adjust the archive filename to match the published asset.
4. Step 3 — Create the Falcosidekick configuration
Create the configuration directory:
sudo mkdir -p /etc/falcosidekickCreate the configuration file:
sudo tee /etc/falcosidekick/config.yaml > /dev/null <<'EOF'
# Falcosidekick listener configuration
listenaddress: "127.0.0.1"
listenport: 2801
# Keep debug disabled unless troubleshooting
debug: false
EOFThis configuration binds Falcosidekick to the local loopback interface on port 2801. That is appropriate when Falco and Falcosidekick run on the same Ubuntu machine.
Check the configuration:
sudo cat /etc/falcosidekick/config.yamlFor this first lab, we are not configuring Slack, email, a SIEM, or any other external destination. Falcosidekick can receive alerts without an external forwarding integration. For additional configuration options, see the official Falcosidekick project documentation.
GitHub
5. Step 4 — Create a systemd service
Create the service file:
sudo tee /etc/systemd/system/falcosidekick.service > /dev/null <<'EOF'
[Unit]
Description=Falcosidekick Alert Forwarder
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/falcosidekick -c /etc/falcosidekick/config.yaml
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
EOFReload systemd and start Falcosidekick:
# Tell systemd to load the new service
sudo systemctl daemon-reload
# Enable startup after reboot and start now
sudo systemctl enable --now falcosidekick
# Check the service
sudo systemctl status falcosidekick --no-pager
# Read recent logs
sudo journalctl -u falcosidekick -n 50 --no-pagerTest its health endpoint:
curl -i http://127.0.0.1:2801/healthzExpected result: an HTTP 200 status. If the service is not running, check its journal for configuration errors or port conflicts before moving on.
GitHub
6. Step 5 — Connect Falco to Falcosidekick
This is the most important step. Installing Falcosidekick alone does not automatically connect it to Falco.
6.1 Back up the existing Falco configuration
# Back up the main configuration before editing
sudo cp -a /etc/falco/falco.yaml \
/etc/falco/falco.yaml.before-falcosidekick
# Find the relevant existing settings
sudo grep -nE \
'^(json_output:|json_include_output_property:|http_output:| enabled:| url:)' \
/etc/falco/falco.yaml6.2 Edit the Falco configuration
sudo nano /etc/falco/falco.yamlFind the existing top-level JSON and HTTP output settings. Enable JSON output and HTTP forwarding, using the following values:
# Emit structured JSON alerts
json_output: true
# Include the human-readable alert output in the JSON
json_include_output_property: true
# Forward Falco alerts to Falcosidekick
http_output:
enabled: true
url: "http://127.0.0.1:2801/"Important: merge these values into the existing configuration. Do not append duplicate top-level keys or replace the entire file. Keep any other settings that your Falco installation needs.
The HTTP output URL must point to the address where Falcosidekick is listening. For a single-host lab, both services can use 127.0.0.1.
GitHub
+1
6.3 Validate and restart Falco
First, check the configuration and rules:
# Validate Falco's configuration before restarting
sudo falco --dry-run -c /etc/falco/falco.yamlIf validation succeeds, restart the service that is actually running on your machine. For the tutorial’s modern eBPF service:
sudo systemctl restart falco-modern-bpf.service
# Confirm Falco is running
sudo systemctl is-active falco-modern-bpf.service
# Review startup messages and errors
sudo journalctl -u falco-modern-bpf.service \
-n 60 --no-pagerIf your system uses another Falco unit, replace falco-modern-bpf.service with that unit’s name.
Check Falcosidekick again:
sudo systemctl is-active falcosidekick
curl -sS -i http://127.0.0.1:2801/healthzAt this point, Falco should be configured to forward its alerts to Falcosidekick.
7. Step 6 — Generate a controlled security event
Let’s generate an attempted read of a sensitive Linux file without changing or deleting anything.
Run this command as your normal, non-root user — do not prefix it with sudo:
# Attempt to read the protected shadow file
cat /etc/shadow > /dev/nullOn a normally configured Ubuntu host, this should fail with a permission-denied message. That is expected.
Now inspect Falco’s logs:
# Look for recent Falco detections
sudo journalctl -u falco-modern-bpf.service \
--since "5 minutes ago" --no-pagerLook for an alert related to sensitive-file access, if a matching rule is loaded and the event is captured. The exact rule name depends on your installed ruleset.
Next, inspect Falcosidekick:
# Check whether the receiver reports errors
sudo journalctl -u falcosidekick \
--since "5 minutes ago" --no-pagerFalcosidekick does not necessarily print every received alert to its service log when debug mode is disabled. Therefore, an empty log does not prove that no alert arrived.
8. Step 7 — View Falco alerts in a web dashboard
One important distinction: Falcosidekick alone is not an event-history dashboard. To browse alerts in a UI, use Falcosidekick-UI with Redis. Redis stores the events, and the UI displays them.
GitHub
+1
The following is an optional dashboard setup using Docker on the same Ubuntu host.
8.1 Install Docker if it is not already installed
If Docker is already working, skip this step. Otherwise, follow the official Docker Engine installation guide for Ubuntu.
Verify:
docker --version
sudo docker info8.2 Start Redis with the required search module
Falcosidekick-UI requires Redis with the RediSearch module. For this learning lab, start the documented Redis Stack-compatible image:
sudo docker network create falco-net
sudo docker run -d \
--name falco-redis \
--restart unless-stopped \
--network falco-net \
-p 127.0.0.1:6379:6379 \
redislabs/redisearch:2.2.4Check Redis:
sudo docker ps
sudo docker logs --tail 30 falco-redis8.3 Start Falcosidekick-UI
sudo docker run -d \
--name falcosidekick-ui \
--restart unless-stopped \
--network falco-net \
-p 2802:2802 \
-e FALCOSIDEKICK_UI_REDIS_URL=falco-redis:6379 \
-e 'FALCOSIDEKICK_UI_USER=labadmin:ChangeThisPassword123!' \
falcosecurity/falcosidekick-uiThe official UI supports a configurable Redis address and login credentials.
GitHub
Check the UI container:
sudo docker ps
sudo docker logs --tail 50 falcosidekick-ui
# Test the UI health endpoint
curl -i http://127.0.0.1:2802/healthzIf the container cannot connect to Redis, remember that 127.0.0.1 inside a container refers to that container itself. In that case, configure both containers on a shared Docker network and set the UI’s Redis address to falco-redis:6379 instead.
8.4 Connect Falcosidekick to the UI
Edit the Falcosidekick configuration:
sudo nano /etc/falcosidekick/config.yamlAdd the UI output settings to the existing configuration:
# Falcosidekick listener
listenaddress: "127.0.0.1"
listenport: 2801
debug: false
# Forward received alerts to Falcosidekick-UI
webui:
enabled: true
url: "http://127.0.0.1:2802"The UI output configuration uses the webui output. Check the exact keys supported by your installed Falcosidekick release in its official configuration reference.
Restart the receiver:
sudo systemctl restart falcosidekick
sudo systemctl status falcosidekick --no-pager
sudo journalctl -u falcosidekick -n 50 --no-pagerOpen the dashboard on the Ubuntu machine:
Dashboard URL
Log in using the username and password configured for the UI container.
If Ubuntu is a remote server, use SSH port forwarding from your local computer:
ssh -L 2802:127.0.0.1:2802 YOUR_USER@YOUR_SERVER_IPThen open http://127.0.0.1:2802 in your local browser. Do not expose the dashboard or Redis ports publicly for this lab.
9. Step 8 — Trigger an alert and investigate it
Repeat the controlled test:
# Run as a normal, non-root user
cat /etc/shadow > /dev/nullOpen the dashboard and select the events view. If the loaded ruleset detects this attempt, inspect the event details.
Look for the following fields:
| Field | What it tells you |
|---|---|
rule | Which Falco detection matched |
priority | Severity assigned by the rule |
output | Human-readable description of the event |
time | When the event occurred |
hostname | Which host generated it |
proc.name | Process name |
user.name | User associated with the event |
fd.name | File or descriptor involved, when available |
container.id | Container context, if applicable |
Not every event will include every field. The available details depend on the matching rule and event source. An alert is evidence to investigate, not automatic proof of a compromise.
Tutorials
+1
10. Step 9 — Troubleshoot when no alerts appear
Work through this checklist in order.
Troubleshooting checklist
0 of 7Falco is active
sudo systemctl is-active falco-modern-bpf.service
Copy commandFalcosidekick is active
sudo systemctl is-active falcosidekick
Copy commandReceiver health check passes
curl -i http://127.0.0.1:2801/healthz
Copy commandFalco HTTP output is enabled
sudo grep -nA3 ‘^http_output:’ /etc/falco/falco.yaml
Copy commandFalco logs contain detections or errors
sudo journalctl -u falco-modern-bpf.service –since ’10 minutes ago’ –no-pager
Copy commandFalcosidekick logs show errors
sudo journalctl -u falcosidekick –since ’10 minutes ago’ –no-pager
Copy commandReceiver metrics are available
curl -fsS http://127.0.0.1:2801/metrics | head -n 40
Copy command
How to interpret the results:
- Falco is active, but no detection appears: verify that the ruleset is loaded and the test actually matches a rule.
- Falco logs show an alert, but the UI is empty: investigate HTTP forwarding, the Falcosidekick
webuioutput, Redis connectivity, and UI logs. - The receiver health check fails: check the systemd service and whether port
2801is already occupied. - No HTTP output is configured: correct
http_outputin Falco’s configuration, validate it, and restart the correct service. - Events arrive but are too noisy: review rule priorities, exclusions, and the expected behavior of the workload before tuning rules.
11. Final verification
Your lab is complete when all of these are true:
- Falco is running and loading rules.
- Falcosidekick responds on port
2801. - Falco’s HTTP output points to Falcosidekick.
- A controlled test generates an alert when a matching rule is loaded.
- The event reaches the UI and is visible with its rule, priority, timestamp, and available process details.
- You can diagnose a missing event by checking Falco, the receiver, and the UI separately.
Official references
- Falco installation and configuration tutorial
- Falcosidekick installation and configuration
- Falcosidekick-UI documentation
- Falco output forwarding
