vin0x00a2/falco-workstation-rules

# falco-workstation-rules 为 Linux 开发者工作站量身定制的 [Falco](https://falco.org) 规则及配套配置。整合了约 3 个月的误报调优经验，让全新安装的 Falco 在桌面环境中真正可用，而不是在第一天就被淹没在海量警报中。 目标环境为 **Lubuntu / XFCE / i3**，搭配 **libvirt 虚拟机**、**VS Code**、**Claude Code** 以及 **Google Chrome**。使用其他桌面环境可能需要自行修改。 ## 功能特性 - 针对用户 Claude Code 安装目录下的任何进程（包括 Bun worker 线程和 VS Code 扩展子进程）读取 `~/.ssh/` 的行为，提供自定义的 CRITICAL 级别检测。 - 针对未授权读取 Claude Code 凭据、配置或设置文件的行为，提供自定义的 WARNING 级别检测。 - 针对真实工作站环境中嘈杂的上游规则，提供定向例外处理： - 针对virtiofsd / vring_worker (libvirt virtio-fs) 的 `Write below root` - 针对Chrome每日 cron 重写 `/etc/default/google-chrome` 的 `Write below etc` - 针对Chrome每日 cron 更新 `sources.list.d` 的 `Update Package Repository` - 针对i3lock、xfce4-screensaver、lightdm、pkexec、systemd-executor 访问 PAM 的 `Read sensitive file untrusted` - 针对gnome-keyring-daemon 和 `systemd-tmpfiles --clean` 的 `Read ssh information` - 针对Chrome、VS Code 和 dpkg postinst chmod 的 `Set Setuid or Setgid bit` - 针对 VS Code 包升级移除 `/usr/bin/code` 的 `Modify binary dirs` - 针对交互式 `dig` 和 `tcpdump` 的 `Launch Suspicious Network Tool on Host` - 针对Chrome、VS Code、opencode、Claude Code、开发工具、fwupd 和 APT 的 `Unexpected UDP Traffic` - ……以及更多内容（详见规则模板中的注释）。 - 在可能的情况下，例外规则均通过 `proc.exepath` 进行限定，以避免攻击者通过重命名二进制文件来利用相同的进程名获得信任。 - 通过 Falcosidekick → Discord 转发 warning 及以上优先级的警报。 - Falco webserver 锁定在 `127.0.0.1`。 - 针对 `/var/log/falco/alerts.json` 的 `logrotate` 配置（每周轮换，保留 12 份，压缩存储）。 ## 不适用的场景 - 不适用于容器或 Kubernetes —— 仅限工作站。 - 不适用于无头 (headless) 服务器 —— 假设存在 X session、屏幕锁定程序和 GUI 认证。 - 不适用于 GNOME/Wayland —— 专门针对 XFCE/i3 编写。 - 没有单文件的 SPDX 头，没有贡献者模型 —— 仅供内部使用，不接收 PR。 ## 目录结构 ``` . ├── LICENSE Apache 2.0 ├── NOTICE attribution ├── README.md this file ├── .gitignore └── falco/ ├── .env.example copy to .env, fill in ├── apply-rules.sh renders + validates + deploys ├── rules.d/ │ ├── 00-trust.yaml.template trustworthy_exe macro │ ├── 10-macro-overrides.yaml.template upstream macro extensions │ ├── 20-claude-detection.yaml.template custom Claude rules │ └── 30-rule-exceptions.yaml.template upstream rule exceptions ├── falcosidekick.yaml.template sidekick config (no secrets) ├── falcosidekick.service.d-override.conf systemd drop-in for secrets ├── falco.workstation.yaml output field overrides ├── falco-alerts.logrotate log rotation ├── falco-healthcheck.sh periodic health check ├── falco-healthcheck.service oneshot systemd unit └── falco-healthcheck.timer runs health check every 6h ``` ### 信任校验机制 `rules.d/` 中的每个例外规则都受 `trustworthy_exe` 宏（`proc.is_exe_from_memfd = false and proc.is_exe_upper_layer = false`）的校验。经过重命名并投放的攻击者二进制文件，不能仅仅因为与受信任的程序共享进程名就进入白名单：内核追踪到的执行源必须是来自底层 (lower layer) 的常规磁盘文件。 这**不是**一个完整的防御体系 —— 在安装时篡改了二进制文件并潜伏等待的攻击者将通过此检查。请将其视为防范简单 drop-and-exec 绕过方式的绊线，而不是完整性保证。 ### 健康检查 `falco-healthcheck.timer` 每 6 小时（以及开机后 5 分钟）运行一次，并验证： - `falco-modern-bpf.service` 处于活动状态 - `falcosidekick.service` 处于活动状态 - `/var/log/falco/alerts.json` 在过去 24 小时内有被写入 - Falco 的 HTTP healthz 端点 `127.0.0.1:8765/healthz` 有响应 失败时，它会向配置的 Discord webhook 发送单条消息并记录到 journald。旨在及时发现 Falco 静默失效的那一天。 ## 安装说明 前置条件： - 已安装并正以 `falco-modern-bpf.service` 运行的 Falco（已在 0.43.x 版本上测试）。 - 已安装在 `/usr/local/bin/falcosidekick` 并配置了 systemd 服务文件的 [Falcosidekick](https://github.com/falcosecurity/falcosidekick)。 - `envsubst`（来自 `gettext-base`）。 - `sudo` 权限。 操作步骤： ``` cp falco/.env.example falco/.env chmod 600 falco/.env $EDITOR falco/.env # fill in USERNAME, HOME_DIR, DISCORD_WEBHOOKURL ./falco/apply-rules.sh ``` `apply-rules.sh`： 1. 加载 `.env`（如果其权限不是 `0600` 或 `0400`，则拒绝运行）。 2. 使用 `envsubst` 将模板渲染至 tmpfs（仅限白名单变量 —— Falco 自身的 `%field.name` 语法保持不变）。 3. 使用 `falco --validate` 验证渲染后的规则。 4. 部署到 `/etc/falco/`、`/etc/falcosidekick/`、`/etc/logrotate.d/`。 5. 通过 `systemctl kill -s HUP` 重新加载 Falco。 6. 重启 Falcosidekick。 7. 验证已部署的规则与渲染的源文件是否一致（漂移检查）。 每次编辑模板或 `.env` 后都可随时重新运行。 ## 密钥管理 Discord webhook URL 是唯一的密钥。它存放在 `.env` 中（已被 gitignore，权限为 `0600`）。在部署时： - `apply-rules.sh` 会将其写入 `/etc/falco-secrets.env`（权限为 `0600`，属主为 `root:root`）。 - 一个 systemd drop-in 文件 (`/etc/systemd/system/falcosidekick.service.d/override.conf`) 会将该文件作为 `EnvironmentFile=` 加载。 - Falcosidekick 从其环境变量中读取 `DISCORD_WEBHOOKURL`。 - 该 webhook URL **绝不会** 出现在 `/etc/falcosidekick/config.yaml` 或任何非 root 用户可读的文件中。 如果你 fork 此项目以适配其他接收端（Slack、Mattermost 等），此模式依然适用 —— Falcosidekick 几乎会从环境变量中读取所有输出的凭据。 ## 变量 在 `.env` 中定义（参见 `.env.example`）： | 变量 | 描述 | |---|---| | `USERNAME` | 受规则保护的 home 目录所属的 Linux 用户 | | `HOME_DIR` | 绝对 home 路径；用于 Claude/SSH 检测规则 | | `DISCORD_WEBHOOKURL` | Discord webhook URL —— 密钥 | 通过 `envsubst` 将变量模板化注入到规则中。其他关于工作站的假设（i3lock、xfce4-screensaver、lightdm、virtiofsd、libvirtd、fwupdmgr 等）均被**硬编码**在规则模板中 —— 如果你的桌面环境不同，请 fork 并进行修改。 ## 开源许可 Apache License 2.0 —— 详见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。

标签：Claude Code, Discord告警, Falco, Google Chrome, HTTP工具, i3, libvirt, Lubuntu, SamuraiWTF, SSH安全, VS Code, XFCE, 主机入侵检测, 云计算, 凭证保护, 安全防护, 应用安全, 开发环境, 敏感文件读取, 敏感词过滤, 日志轮转, 权限管理, 桌面环境, 模型越狱, 端点安全, 补丁管理, 规则引擎, 误报调优