Skip to content

About

Connect Falco to your ecosystem

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

704 stars

Watchers

12 watching

Forks

Falcosidekick

Falco Ecosystem Repository Stable Last Release Docker Pulls

License

falcosidekick

Falcosidekick connects Falco to your ecosystem. Falco posts its events over HTTP, and Falcosidekick forwards each one to the chat, alerting, logging, streaming and storage systems you configure, with retries, metrics and a web UI.

Note

This branch is Falcosidekick v3, in beta. v2 is on the 2.x branch and its images keep the latest and 2.* tags. v2 configuration is not compatible with v3: see Migrate from v2.

How it works

flowchart LR
  F1[Falco] -->|HTTP :2801| S
  F2[Falco] -->|HTTP :2801| S
  S[Falcosidekick] --> O1[Slack, Teams, Discord]
  S --> O2[Alertmanager, PagerDuty, Opsgenie]
  S --> O3[Loki, Elasticsearch, Syslog]
  S --> O4[Kafka, SQS, SNS, Pub/Sub]
  S --> O5[S3, Redis, OTLP, Webhook, ...]
Loading

One Falcosidekick serves any number of Falco instances. Each output has its own queue, so a slow or failing destination does not delay the others.

Features

  • Reliable delivery. Per output: a queue, retries with backoff, a circuit breaker and optional batching. Permanent rejections are not retried, and after a partial batch failure only the events that can still be delivered are retried.
  • Configuration as files. A core file (-c) and one or more output files (-o), with snake_case keys. Output files reload on change, on SIGHUP or by polling, without a restart.
  • Secrets from files. Every secret field has a <field>_file variant, read from a mounted Secret.
  • Web UI and API. Dashboard, pipeline, configuration and events pages, on a separate management listener (127.0.0.1:2802 by default). Read-only unless api.allow_writes is set.
  • Persistence. Outputs created through the API are kept in memory, sqlite or postgres, never with secret values. Postgres replicas stay in step.
  • Observability. Prometheus metrics for every delivery outcome, /livez and /readyz probes, JSON logs.
  • Secure defaults. Distroless image running as uid/gid 65532, signed with cosign; releases carry SLSA provenance.

Web UI

Falcosidekick dashboard: events of the last hour, outputs that need attention, events over time and by severity

The dashboard shows what needs attention now: outputs that do not deliver and critical events. The pipeline page shows each output with its queue, circuit breaker and last error; the events page searches and filters the events the UI stores.

Falcosidekick pipeline: Falco, the event pipeline and each output with its status Falcosidekick events: search, filters by priority, source, rule, hostname and tags

The UI is off by default. Install shows how to turn it on.

Quick start

Helm

The v3 chart is a pre-release, so Helm installs it only with --devel:

helm repo add falcosecurity https://falcosecurity.github.io/charts
helm repo update
helm install falcosidekick falcosecurity/falcosidekick --devel \
  --namespace falco --create-namespace \
  --set outputs.webhook.host=http://receiver.example:8080

Docker

# outputs.yaml
outputs:
  webhook:
    host: "http://receiver.example:8080"
    endpoint: /falco
docker run -d --name falcosidekick -p 2801:2801 \
  -v "$PWD/outputs.yaml:/etc/falcosidekick/outputs.yaml:ro" \
  falcosecurity/falcosidekick:3.0.0-beta.1 \
  -o /etc/falcosidekick/outputs.yaml
curl -s localhost:2801/readyz

Connect Falco

In falco.yaml:

json_output: true
json_include_output_property: true
http_output:
  enabled: true
  url: "http://falcosidekick:2801/"

Install covers the core file, Kubernetes manifests, the web UI, persistence and image verification.

Outputs

Category Outputs
Chat Slack, Microsoft Teams, Discord
Alerting and on-call Alertmanager, PagerDuty, Opsgenie, Grafana OnCall, Datadog
Logs Loki, Elasticsearch, Syslog
Queues and streams Apache Kafka, Amazon SQS, Amazon SNS, Google Pub/Sub
Storage Amazon S3, Redis, In-memory store
Observability OpenTelemetry (OTLP)
Email SMTP
Webhooks Webhook, CloudEvents
Response Falco Talon
Other Policy Report

Each page has the settings, an example and the tested versions. Settings shared by several outputs are in common settings.

Ports and endpoints

Port Default address Serves
2801 all interfaces, IPv4 and IPv6 Falco events (POST /), /livez, /readyz, /metrics
2802 127.0.0.1 API and web UI. The API has no authentication: expose it only to trusted clients.

Versions and images

Version Branch Status Image tags
v3 master Beta 3.* releases, v3-main builds of master; -slim variants without the UI
v2 2.x Maintenance, security and critical fixes only latest, 2.*

Images are published to Docker Hub. Install lists every tag and how to verify the signatures.

Documentation

Build from source

Requires Go and Bun.

make falcosidekick       # binary with the web UI
make falcosidekick-slim  # binary without the web UI
make image               # local image falcosidekick:local
make verify              # the checks CI runs

Contributing

Issues and pull requests are welcome; see the Falco contributing guidelines. v2 fixes go to the 2.x branch. Talk to the community in the #falco channel of the Kubernetes Slack.

License

Apache License 2.0

About

Connect Falco to your ecosystem

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

704 stars

Watchers

12 watching

Forks

Releases

Used by

Contributors

Languages