falcosecurity/falcosidekick-ui

Falco WebUI 镜像文档

1. 镜像概述

1.1 主要用途

falco-webui 是一个轻量级 Web 用户界面，旨在实时展示 Falco 生成的最新安全事件。Falco 作为运行时安全监控工具，可检测容器、主机及 Kubernetes 环境中的异常行为（如文件篡改、权限提升等）。本镜像通过提供直观的可视化界面，帮助用户便捷地查看、监控和分析 Falco 事件，简化安全事件响应流程。

2. 核心功能与特性

2.1 核心功能

• 实时事件展示：动态加载并展示 Falco 最新生成的安全事件，支持按时间倒序排列（最新事件优先）。
• 事件信息呈现：显示事件关键信息，包括发生时间、事件类型、严重级别（如 Emergency、Critical、Warning 等）、涉及资源（容器 ID、进程名等）及事件描述。
• 基础事件过滤：支持按严重级别、事件类型等条件快速筛选事件。

2.2 特性

• 轻量级设计：镜像体积小，资源占用低，适合在资源受限环境部署。
• 易于集成：与 Falco 原生事件源无缝对接，无需额外插件或中间件。
• 快速部署：基于 Docker 容器化，支持单命令启动，部署流程简化。
• 简洁界面：聚焦核心事件信息，无冗余功能，降低学习成本。

3. 使用场景与适用范围

3.1 使用场景

• 开发/测试环境：实时监控应用运行时行为，辅助排查安全配置问题。
• 生产环境轻量监控：作为 Falco 事件的可视化补充工具，适合中小规模集群或单机环境。
• 安全事件审计：快速回溯近期异常行为，支持初步事件分类与筛选。

3.2 适用范围

• 目标用户：系统管理员、安全运维工程师、DevSecOps 团队。
• 环境要求：已部署 Falco 的容器化环境（Docker、Kubernetes）或物理/虚拟机环境。

4. 使用方法与配置说明

4.1 前置条件

• 已部署并运行 Falco（版本需支持事件输出接口，如 HTTP 或 gRPC，具体取决于 WebUI 适配的事件源类型）。
• WebUI 容器需与 Falco 事件源网络互通（如同一 Docker 网络、Kubernetes 集群内或跨主机网络可达）。

4.2 快速启动（Docker Run）

通过以下命令快速启动 WebUI 容器，默认监听本地 8080 端口：

bash
docker run -d \
  --name falco-webui \
  -p 8080:8080 \
  -e FALCO_ENDPOINT="http://falco:8080" \  # Falco 事件源地址（必填）
  -e LOG_LEVEL="info" \                     # 日志级别（可选，默认 info）
  falco-webui:latest

说明：

• -p 8080:8080：将容器内 WebUI 服务端口（默认 8080）映射到主机 8080 端口，可根据需求修改主机端口（如 -p 9000:8080）。
• FALCO_ENDPOINT：指定 Falco 事件源地址（如 Falco 暴露的 HTTP 事件接口地址，格式为 http://<falco-ip>:<port>），需确保该地址可被 WebUI 容器访问。

4.3 Docker Compose 配置示例

若需与 Falco 联动部署，可使用以下 docker-compose.yml 配置（假设 Falco 以容器形式运行）：

yaml
version: '3.8'

services:
  falco:
    image: falcosecurity/falco:latest
    container_name: falco
    privileged: true  # Falco 需特权模式运行以监控系统调用
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /proc:/host/proc:ro
      - /boot:/host/boot:ro
      - /lib/modules:/host/lib/modules:ro
      - /usr:/host/usr:ro
    environment:
      - FALCO_OUTPUT_FORMAT=json  # 确保 Falco 输出 JSON 格式事件（WebUI 依赖）
      - FALCO_LISTEN_PORT=8080    # Falco 事件 HTTP 接口端口

  falco-webui:
    image: falco-webui:latest
    container_name: falco-webui
    ports:
      - "8080:8080"
    environment:
      - FALCO_ENDPOINT="http://falco:8080"  # 指向同一网络中的 falco 服务
      - WEBUI_PORT=8080                     # WebUI 监听端口（默认 8080）
      - LOG_LEVEL=warn                      # 日志级别（可选，支持 debug/info/warn/error）
    depends_on:
      - falco  # 确保 Falco 启动后再启动 WebUI

启动命令：

bash
docker-compose up -d

4.4 环境变量配置

WebUI 支持通过环境变量自定义配置，具体参数如下：

5. 注意事项

• Falco 事件格式兼容性：需确保 Falco 输出事件格式为 WebUI 支持的类型（如 JSON），可通过配置 Falco 的 output_format 参数（如 json）实现。
• 网络连通性：WebUI 容器必须能够访问 FALCO_ENDPOINT 配置的地址，建议通过 Docker 网络或 Kubernetes Service 确保通信正常。
• 资源限制：若事件量较大，可适当调整容器 CPU/内存限制（如 --cpus=0.5 -m=256m），避免影响 WebUI 响应速度。
• 版本匹配：建议使用与 Falco 版本兼容的 WebUI 镜像，具体兼容性信息可参考镜像标签或官方文档。