A simple daemon for connecting Falco to your ecosystem. It takes a Falco events and
forward them to different outputs in a fan-out way.
It works as a single endpoint for as many as you want Falco instances :
- Falcosidekick
Falcosidekick manages a large variety of outputs with different purposes.
Note
Follow the links to get the configuration of each output.
- Datadog
- Influxdb
- StatsD (for monitoring of
falcosidekick) - DogStatsD (for monitoring of
falcosidekick) - Prometheus (for both events and monitoring of
falcosidekick) - Wavefront
- Spyderbat
- TimescaleDB
- Dynatrace
- NATS
- STAN (NATS Streaming)
- AWS SQS
- AWS SNS
- AWS Kinesis
- GCP PubSub
- Apache Kafka
- Kafka Rest Proxy
- RabbitMQ
- Azure Event Hubs
- Yandex Data Streams
- MQTT
- Gotify
Run the daemon as any other daemon in your architecture (systemd, k8s deployment, swarm service, ...).
Use the environment variables to set up the outputs:
docker run -d -p 2801:2801 -e SLACK_WEBHOOKURL=XXXX -e DATADOG_APIKEY=XXXX falcosecurity/falcosidekick-
Download the latest release:
VER=$(curl --silent -qI https://github.com/falcosecurity/falcosidekick/releases/latest | awk -F '/' '/^location/ {print substr($NF, 1, length($NF)-1)}') wget -c https://github.com/falcosecurity/falcosidekick/releases/download/${VER}/falcosidekick_${VER}_linux_arm64.tar.gz -O - | tar -xz or wget -c https://github.com/falcosecurity/falcosidekick/releases/download/${VER}/falcosidekick_${VER}_linux_amd64.tar.gz -O - | tar -xz chmod +x falcosidekick sudo mv falcosidekick /usr/local/bin/
-
Create the
/etc/falcosidekick/config.yamlfile, see Configuration. -
Create the systemd unit files
/etc/systemd/system/falcosidekick.service:sudo touch /etc/systemd/system/falcosidekick.service sudo chmod 664 /etc/systemd/system/falcosidekick.service
[Unit] Description=Falcosidekick After=network.target StartLimitIntervalSec=0 [Service] Type=simple Restart=always RestartSec=1 ExecStart=/usr/local/bin/falcosidekick -c /etc/falcosidekick/config.yaml [Install] WantedBy=default.target
-
Reload
systemdand startFalcosidekick:sudo systemctl daemon-reload sudo systemctl enable falcosidekick sudo systemctl start falcosidekick -
Check if
Falcosidekickruns:curl localhost:2801/healthz
See https://github.com/falcosecurity/charts/blob/master/charts/falcosidekick/README.md
helm repo add falcosecurity https://falcosecurity.github.io/charts
helm repo update
helm install falcosidekick --set config.debug=true falcosecurity/falcosidekickNote
You can also deploy falcosidekick as a dependency of the falco chart, the settings for the communication between falco and falcosidekick are automatically set. Just prefix all falcosidekick settings with falcosidekick.:
helm repo add falcosecurity https://falcosecurity.github.io/charts
helm repo update
helm install falco --set falcosidekick.enabled=true falcosecurity/falcoTo connect Falco with Falcosidekick, you need to change it configuration as following:
If managing falco.yaml manually, set this:
json_output: true
json_include_output_property: true
http_output:
enabled: true
url: "http://localhost:2801/"If installing falco with Helm, set this (adapted to your environment) in
your values.yaml :
falcosidekick:
enabled: trueor
jsonOutput: true
jsonIncludeOutputProperty: true
httpOutput:
enabled: true
url: "http://falcosidekick:2801/"or
jsonOutput: true
jsonIncludeOutputProperty: true
programOutput:
enabled: true
keepAlive: false
program: "curl -d @- falcosidekick:2801/"Configuration is made by file (yaml) and env vars, both can be used but env vars override values from file.
See config_example.yaml :
#listenaddress: "" # ip address to bind falcosidekick to (default: "" meaning all addresses)
#listenport: 2801 # port to listen for daemon (default: 2801)
debug: false # if true all outputs will print in stdout the payload they send (default: false)
customfields: # custom fields are added to falco events, if the value starts with % the relative env var is used
# Akey: "AValue"
# Bkey: "BValue"
# Ckey: "CValue"
templatedfields: # templated fields are added to falco events and metrics, it uses Go template + output_fields values
# Dkey: '{{ or (index . "k8s.ns.labels.foo") "bar" }}'
customtags: # custom tags are added to the falco events, if the value starts with % the relative env var is used
# - tagA
# - tagB
# bracketreplacer: "_" # if not empty, replace the brackets in keys of Output Fields
outputFieldFormat: "<timestamp>: <priority> <output> <custom_fields> <templated_fields>" # if not empty, allow to change the format of the output field. (default: "<timestamp>: <priority> <output>")
mutualtlsfilespath: "/etc/certs" # folder which will used to store client.crt, client.key and ca.crt files for mutual tls for outputs, will be deprecated in the future (default: "/etc/certs")
mutualtlsclient: # takes priority over mutualtlsfilespath if not emtpy
certfile: "/etc/certs/client/client.crt" # client certification file
keyfile: "/etc/certs/client/client.key" # client key
cacertfile: "/etc/certs/client/ca.crt" # for server certification
tlsclient:
cacertfile: "/etc/certs/client/ca.crt" # CA certificate file for server certification on TLS connections, appended to the system CA pool if not empty
tlsserver:
deploy: false # if true, TLS server will be deployed instead of HTTP
certfile: "/etc/certs/server/server.crt" # server certification file
keyfile: "/etc/certs/server/server.key" # server key
mutualtls: false # if true, mTLS server will be deployed instead of TLS, deploy also has to be true
cacertfile: "/etc/certs/server/ca.crt" # for client certification if mutualtls is true
notlsport: 2810 # port to serve http server serving selected endpoints (default: 2810)
notlspaths: # if not empty, and tlsserver.deploy is true, a separate http server will be deployed for the specified endpoints
- "/ping"
# - "/metrics"
# - "/healthz"Note
For the confiuration of the outputs, see the docs.
Usage :
usage: falcosidekick [<flags>]
Flags:
--help Show context-sensitive help (also try --help-long and --help-man).
-c, --config-file=CONFIG-FILE config fileDifferent endpoints (handlers) are available :
/: main and default handler, your falco config must be configured to use it/ping: you will get apongas answer, useful to test if falcosidekick is running and its port is opened (for healthcheck purpose for example). This endpoint is deprecated and it will be removed in3.0.0./healthz: you will get a HTTP status code200response as answer, useful to test if falcosidekick is running and its port is opened (for healthcheck or purpose for example)/test: (for debug only) send a test event to all enabled outputs./debug/vars: get statistics from daemon (in JSON format), it uses classicexpvarpackage and some custom values are added/metrics: prometheus endpoint, for scraping metrics about events andfalcosidekick
All logs are sent to stdout.
2019/05/10 14:32:06 [INFO] : Enabled Outputs : Slack DatadogOutputs with mutualtls enabled in their configuration require the client.crt, client.key and ca.crt filepaths to be configured in the mutualtlsclient_certfile, mutualtlsclient_keyfile and mutualtlsclient_cacertfile global parameter.
docker run -d -p 2801:2801 -e MUTUALTLSCLIENT_CERTFILE=/etc/certs/client/client.crt -e MUTUALTLSCLIENT_KEYFILE=/etc/certs/client/client.key -e MUTUALTLSCLIENT_CACERTFILE=/etc/certs/client/ca.crt -e ALERTMANAGER_HOSTPORT=https://XXXX -e ALERTMANAGER_MUTUALTLS=true -e INFLUXDB_HOSTPORT=https://XXXX -e INFLUXDB_MUTUALTLS=true -e WEBHOOK_ADDRESS=XXXX -v /localpath/myclientcert.crt:/etc/certs/client/client.crt -v /localpath/myclientkey.key:/etc/certs/client/client.key -v /localpath/ca.crt:/etc/certs/client/ca.crt falcosecurity/falcosidekickAlternately the path where the client.crt, client.key and ca.crt files are stored can be configured in mutualtlsfilespath global parameter. (Important: file names must be preserved)
docker run -d -p 2801:2801 -e MUTUALTLSFILESPATH=/etc/certs -e ALERTMANAGER_HOSTPORT=https://XXXX -e ALERTMANAGER_MUTUALTLS=true -e INFLUXDB_HOSTPORT=https://XXXX -e INFLUXDB_MUTUALTLS=true -e WEBHOOK_ADDRESS=XXXX -v /localpath/myclientcert.crt:/etc/certs/client.crt -v /localpath/myclientkey.key:/etc/certs/client.key -v /localpath/ca.crt:/etc/certs/ca.crt falcosecurity/falcosidekickIn above example, the same client certificate will be used for both Alertmanager & InfluxDB outputs which have mutualtls flag set to true.
The daemon exposes the common Golang metrics and some custom values in JSON format. It's useful for monitoring purpose.
The daemon exposes a prometheus endpoint on URI /metrics.
See the docs for more info.
The daemon is able to push its metrics to a StatsD/DogstatsD server. See Configuration section for how-to.
See the statsd docs and dogstastd docs for more info.
Run you daemon and try (from Falco's documentation):
curl -XPOST "http://localhost:2801/" -d'{"output":"16:31:56.746609046: Error File below a known binary directory opened for writing (user=root command=touch /bin/hack file=/bin/hack)","hostname": "localhost", "priority":"Error","rule":"Write below binary dir","time":"2019-05-17T15:31:56.746609046Z", "output_fields": {"evt.time":1507591916746609046,"fd.name":"/bin/hack","proc.cmdline":"touch /bin/hack","user.name":"root"}}'make falcosidekickCreate a debug event
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" localhost:2801/testmake testWith Coverage
make test-coverageThomas Labarussias (https://github.com/Issif)
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
