KubeBolt docs
ENES GitHub

Seguridad

Falco: eventos de runtime

Falco es la única fuente que empuja datos a KubeBolt. Conecta falcosidekick al endpoint de ingesta con un token acotado al clúster: cualquier otra cosa es un 403.

En esta página
  1. Las tres cosas que necesita
  2. Instalar
  3. Cómo lo encuentra KubeBolt
  4. Verificar
  5. Qué se guarda y qué no
  6. Ruido

Falco vigila las syscalls de cada nodo y avisa cuando algo se sale de lo esperado: una shell dentro de un contenedor, la lectura de un archivo sensible, un binario que se deja en disco y se ejecuta. Los eventos llegan a la pestaña Runtime de Security & Compliance.

A diferencia de Trivy y Kyverno, KubeBolt no sale a buscar estos datos: Falco los empuja. Es la única fuente que funciona así, y eso condiciona toda la configuración. falcosidekick, el reenviador que el chart de Falco despliega a su lado, hace un POST de cada evento a la API de KubeBolt; el túnel del agente no lo transporta.

Las tres cosas que necesita

ValorDe dónde saleSin él
URL de ingestaAutoalojado: https://<your-kubebolt>/api/v1/ingest/falco. Cloud: https://api.kubebolt.io/api/v1/ingest/falcofalcosidekick registra un error de conexión y descarta el evento
Token de ingestaAdministration → Agents & Ingest → Agent Tokens, acotado al clúster (un token de ingesta kb_…, no un token de API REST)401: no se acepta nada
cluster_idel UID del namespace kube-systemOpcional. Si se define y no coincide con el token, 403

La URL tiene que ser accesible desde dentro del clúster. En Cloud, eso significa HTTPS saliente hacia api.kubebolt.io, un host distinto del agent.kubebolt.io del agente, así que una lista de salida permitida (egress allowlist) necesita los dos. En autoalojado, cuando Falco se ejecuta en el mismo clúster que KubeBolt, el Service de la API funciona sin salir del clúster: http://<kubebolt-api-service>.<namespace>.svc.cluster.local:8080/api/v1/ingest/falco (el Service es kubebolt-api para una release llamada kubebolt).

El tenant nunca se envía: sale del token. Una instalación autoalojada tiene un único tenant; en Cloud, esto es también lo que impide que un emisor escriba en el feed de otra organización.

En autoalojado, el endpoint necesita la autenticación habilitada (KUBEBOLT_AUTH_ENABLED=true, auth.enabled=true en el chart, el valor por defecto). Sin ella no existen los tokens de ingesta ni el almacén de eventos, y el endpoint responde 503 runtime events are not available (persistence disabled).

El token tiene que estar acotado al clúster, o se rechaza cada evento. Falco no tiene handshake. El agente de KubeBolt anuncia su clúster al conectarse, pero un evento empujado lleva solo el token, así que un token sin acotar produce eventos que no se pueden atribuir a un clúster. La API los rechaza en lugar de registrarlos atribuidos a medias:

403  this ingest token is not scoped to a cluster; issue a cluster-scoped token
     for Falco so its events can be attributed

Emite un token para este clúster concreto: en Issue token, elige el clúster en Cluster scope en lugar de «Any cluster». No reutilices el del agente.

Emitir tokens requiere el rol de admin. En el desplegable Cluster scope solo se puede elegir un clúster que ya haya reportado su id, así que conecta primero el clúster; por defecto aparece el clúster seleccionado en la barra superior. Expires after (days) es opcional: déjalo en blanco para un token que no caduca nunca, y revócalo desde la misma página.

Obtén el id del clúster, la identidad que KubeBolt usa en todas partes:

kubectl get ns kube-system -o jsonpath='{.metadata.uid}'

Instalar

CLUSTER_ID=$(kubectl get ns kube-system -o jsonpath='{.metadata.uid}')
TOKEN=<your cluster-scoped ingest token>

# El token va en un Secret, no en los values de Helm (donde lo lee cualquiera
# que pueda ejecutar `helm get values`). falcosidekick lo carga después de su propio Secret.
kubectl create namespace falco --dry-run=client -o yaml | kubectl apply -f -
kubectl -n falco create secret generic falco-kubebolt \
  --from-literal=WEBHOOK_CUSTOMHEADERS="Authorization:Bearer $TOKEN" \
  --dry-run=client -o yaml | kubectl apply -f -

helm repo add falcosecurity https://falcosecurity.github.io/charts
helm upgrade --install falco falcosecurity/falco -n falco \
  --set driver.kind=modern_ebpf \
  --set falcosidekick.enabled=true \
  --set-string falcosidekick.config.existingSecret=falco-kubebolt \
  --set-string falcosidekick.config.webhook.address=https://<your-kubebolt>/api/v1/ingest/falco \
  --set-string falcosidekick.config.customfields="cluster_id:$CLUSTER_ID"

En Cloud, la dirección es https://api.kubebolt.io/api/v1/ingest/falco.

Usa el chart 9.2.1 o posterior (Falco 0.45.1+); con el kernel 6.18, las versiones anteriores no arrancan (consulta El driver).

ValorQué hace
driver.kindCómo lee Falco las syscalls: modern_ebpf (recomendado), ebpf o kmod
falcosidekick.enabledDespliega falcosidekick, que reenvía cada evento
falcosidekick.config.existingSecretSecret del que falcosidekick carga sus ajustes; aquí, la cabecera Authorization
falcosidekick.config.webhook.addressLa URL de ingesta
falcosidekick.config.customfieldsComprobación opcional cluster_id:<uid>: el token decide el clúster, y un cluster_id que no coincide con él se rechaza
falcosidekick.config.webhook.minimumpriorityOpcional. Reenvía solo los eventos de una prioridad o superior, p. ej. warning

Para rotar el token, vuelve a ejecutar la línea create secret con el nuevo y reinicia falcosidekick (kubectl -n falco rollout restart deploy/falco-falcosidekick): solo lee el Secret al arrancar. Para comprobar lo que envía:

kubectl get secret -n falco falco-kubebolt \
  -o jsonpath='{.data.WEBHOOK_CUSTOMHEADERS}' | base64 -d

Si pasas la cabecera en los values (webhook.customHeaders), el token queda en los values de la release, y la clave tiene que ser customHeaders, con H mayúscula: es la única grafía que lee la plantilla del chart de falcosidekick para el webhook, mientras que otras salidas del mismo values.yaml (Elasticsearch, Loki) la escriben customheaders. La clave en minúsculas deja la cabecera vacía sin ningún aviso, el POST sale sin token y la API responde 401; y el diagnóstico obvio, el equivocado, es que el token está mal.

El driver

modern_ebpf (CO-RE) necesita kernel 5.8 o más reciente con BTF:

uname -r                        # 5.8+
ls /sys/kernel/btf/vmlinux      # debe existir

Si no está disponible, el chart también ofrece ebpf y kmod.

El kernel 6.18 necesita Falco 0.45.1 o posterior (chart 9.2.1+). Las versiones anteriores con modern_ebpf entran en crash-loop con ese kernel: el verificador de BPF rechaza el programa signal_deliver (R9 invalid mem access 'scalar'). Las imágenes de nodo AL2023 de Amazon EKS ejecutan 6.18 desde noviembre de 2026. Corregido en falcosecurity/libs (#3119); verificado con el chart 9.2.2 / Falco 0.45.2.

Un sensor por kernel

Falco es un DaemonSet: un pod por nodo, y cada uno ve su propio kernel. Correcto en cualquier clúster real.

En kind o k3d no lo es. Los «nodos» son contenedores que comparten un único kernel de Docker, así que cada Falco ve las syscalls de toda la máquina y el mismo evento llega dos veces: una copia con la identidad de Kubernetes resuelta y otra sin ella, desde el nodo que no aloja el pod. Para un laboratorio, ánclalo a un solo nodo:

helm upgrade falco falcosecurity/falco -n falco --reuse-values \
  --set-string nodeSelector."kubernetes\.io/hostname"=<your-node>

No se pierde ninguna detección: el sensor que queda ya ve esas syscalls.

Cómo lo encuentra KubeBolt

Por la etiqueta app.kubernetes.io/name=falco y, si no, por pods llamados falco* en los namespaces falco o falco-system. El resultado es la tarjeta Falco en Administration → Agents & Ingest → Integrations, para el clúster seleccionado en la barra superior. La tarjeta cuenta los pods de Falco y si están listos; si de verdad llegan eventos, solo se ve en la pestaña Runtime y en el log de falcosidekick.

Verificar

# 1. Dispara una regla a propósito
kubectl exec -n <ns> deploy/<something> -- cat /etc/shadow

# 2. La entrega tiene que reportar 202
kubectl logs -n falco -l app.kubernetes.io/name=falcosidekick --tail=5
#   → Webhook - POST OK (202)

El evento llega a la pestaña Runtime en menos de un minuto.

SíntomaCausa
401 missing Bearer tokenexistingSecret se quedó fuera de la instalación, o la clave del Secret no es exactamente WEBHOOK_CUSTOMHEADERS; con la cabecera en los values, customheaders en minúsculas
falcosidekick atascado en CreateContainerConfigErrorEl Secret falco-kubebolt no existe en el namespace falco. Créalo y el pod arranca solo
401 invalid ingest tokenEl token está revocado, ha caducado o pertenece a otra instalación u organización
503 runtime events are not available (persistence disabled)Autoalojado con la autenticación desactivada
403 not scoped to a clusterEl token se emitió sin clúster
403 cluster_id does not matchEl token pertenece a un clúster distinto del de customfields
400 unrecognized falco payloadEl cuerpo no es un evento de webhook de falcosidekick: no es JSON, o no contiene ni rule ni output
connection refused o un tiempo de espera agotadoLa URL no es accesible desde el clúster (reglas de egress, host equivocado o el nombre del Service dentro del clúster)
Nada en el propio log de FalcoEl driver nunca se cargó: revisa el kernel y BTF
Falco en CrashLoopBackOff, con R9 invalid mem access 'scalar' en su logFalco anterior a 0.45.1 en el kernel 6.18: actualiza el chart a 9.2.1+

Qué se guarda y qué no

Un evento guarda lo que envía falcosidekick y nada más: la regla, la prioridad, la hora, la línea de salida de Falco, el hostname, cada campo de los output_fields del evento (namespace y pod, el proceso y su línea de comandos, el usuario, el archivo) y las etiquetas de la regla, incluida la técnica de MITRE ATT&CK, que dice qué se intentaba hacer y no solo qué syscall se disparó.

No se guarda contenido. Las reglas de Falco imprimen metadatos, no el contenido de archivos ni cuerpos de peticiones: el evento dice qué se tocó, nunca qué había dentro. Desde la 2.6.4, una credencial en la línea de salida o en los campos de Falco (una contraseña o un token pasados como argumento, por ejemplo) se oculta al guardar el evento y otra vez al leerlo, con el mismo filtro que usa Kobi; los ids y los digests siguen siendo legibles.

falcosidekick reintenta un POST fallido con el mismo cuerpo. KubeBolt deriva el id del evento a partir del payload, así que un reintento nunca llega como un segundo evento.

Los eventos forman un flujo de sucesos puntuales: salen del feed a las 24 horas en lugar de resolverse. No hay ningún estado que cerrar, y por eso la vista de detalle no ofrece un botón de «resuelto»: mentiría sobre lo que el sistema puede hacer. Siguen guardados, y Kobi puede leerlos, hasta el horizonte de retención de hallazgos, que se explica en Seguridad y cumplimiento.

Ruido

El perfil por defecto de Falco es conservador y bastante hablador. Antes de silenciar una regla, mira el panel Top 5 rules by hits de la pestaña: una sola regla que acapara la mayor parte del feed suele ser una regla ruidosa, no un incidente. El ajuste se hace en Falco (customRules), no en KubeBolt: la fuente es la autoridad. Para recortar volumen en el emisor, sube falcosidekick.config.webhook.minimumpriority.