davidborzek/suho

# suho **适用于原生 Docker / Compose 的基于标签驱动的 L3/L4 network-policy 控制器。** *“suho”（수호）在韩语中意为“保护 / 守护”——该守护进程负责监管哪些容器可以相互通信。* [](https://github.com/davidborzek/suho/actions/workflows/ci.yaml) [](LICENSE) suho 在单个 Docker 宿主机上重现了 Kubernetes 的 `NetworkPolicy` / `CiliumClusterwideNetworkPolicy` 语义：容器标签（以及全局的 `policies/suho.yaml`）声明了哪些容器可以相互通信以及访问互联网，随后 suho 使用 nftables 强制执行这些规则。它是一个宿主机级别的守护进程，专为希望在不使用 Kubernetes 的情况下获得 Kubernetes 风格 network-policy 的单节点 Docker / Compose 环境而设计。 ## 工作原理 容器 IP 会不断变化，因此策略引用的是**身份**——容器的标签、Docker 网络、CIDR 或容器名称——而不是 IP。每次调和都会根据当前的 Docker 快照和 `policies/suho.yaml` 重建 suho 唯一的 `inet suho` nftables 表，并原子地替换它，因此停止的容器不会留下孤立的规则。强制执行机制与 Kubernetes 类似：只有当策略针对某个方向选择了某个容器时，该方向才会默认拒绝流量；并且只有当源端的出口和目的端的入口**同时**允许时，才会放行流量。 完整设计请参阅 [`docs/architecture.md`](docs/architecture.md)。 ## 快速开始 在宿主机 network 命名空间中运行 suho，赋予其 `CAP_NET_ADMIN` 权限，将 Docker socket 设为只读，并挂载你的全局策略： ``` docker run --network host --cap-drop ALL --cap-add NET_ADMIN --read-only \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -v ./policies:/etc/suho/policies:ro -e SUHO_POLICIES_PATH=/etc/suho/policies \ suho # build from source — see examples/docker-compose.yml ``` 然后使用策略为容器添加标签（该方向将默认拒绝，仅允许你列出的内容）： ``` labels: suho.networkpolicy.default: | policyTypes: [Ingress, Egress] ingress: - from: [{selector: {com.docker.compose.service: proxy}}] ports: ["8080/tcp"] egress: - to: [{cidr: 0.0.0.0/0, except: [10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16]}] ports: ["443/tcp"] ``` `examples/` 中包含一个可运行的 Compose 设置，支持内联、同位以及基于文件的全局策略。为了强制执行容器间和入口流量，网桥数据包必须穿过 forward hook——请启用 `br_netfilter`：`sysctl -w net.bridge.bridge-nf-call-iptables=1`（如果关闭此项，suho 在启动时会发出警告）。 ## 文档 - [`docs/network-policies.md`](docs/network-policies.md) — 策略指南：隔离模型、networkpolicy 标签、选择器、peers、端口、默认策略以及全宿主机范围的全局配置（参照 Kubernetes NetworkPolicy 文档建模）。 - [`docs/architecture.md`](docs/architecture.md) — 架构、强制执行模型、技术栈以及待解决的问题。 - [`docs/deployment.md`](docs/deployment.md) — 生产环境部署、socket 加固、可观测性与故障排除。 - [`docs/metrics.md`](docs/metrics.md) — Prometheus metrics、健康检查 endpoint 以及示例抓取配置与告警。 - [`examples/`](examples/) — 一个可运行的 Compose 示例。 ## 开发 ``` cargo fmt --all cargo clippy --all-targets -- -D warnings cargo build cargo test ``` 编译时会构建 `rustables`，这会运行 `bindgen`：请安装 `clang` 以及内核 UAPI 头文件（Arch 上为 `linux-api-headers`，Debian/Ubuntu 上为 `linux-libc-dev`）。针对内核进行强制执行需要 root 权限（`CAP_NET_ADMIN`）；如果没有该权限，请使用 `--dry-run`。一项无 root、沙盒化的端到端测试会将具有代表性的双栈规则集写入一个一次性的 user+network 命名空间中——使用 `cargo test -- --ignored` 运行它。 运行时配置通过环境变量进行——`SUHO_LABEL_PREFIX`、`SUHO_POLICIES_PATH`、`SUHO_RESYNC_INTERVAL`（周期性执行完全调和的安全网）、`SUHO_DEBOUNCE_MS`（Docker 事件后的静默窗口）以及 `SUHO_METRICS_ADDR`（暴露 Prometheus 的 `/metrics`、`/healthz` 和 `/readyz` 的 `host:port`）——此外还有 `--dry-run` 标志，它会记录解析出的规则集而不应用任何更改。 `suho schema` 会打印 `policies/suho.yaml` 的 JSON Schema (v1alpha1)（已提交至 `schemas/network-policies.v1alpha1.json`，用于编辑器的 `$schema` 验证）。`suho validate [path]` 可离线检查策略文件，`suho status` 会显示受管辖的容器以及解析出的规则集。 ## 贡献与安全 欢迎贡献力量——请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md) 和 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。请通过 Security 标签页私下报告漏洞，不要提交公开 issue（详见 [`SECURITY.md`](SECURITY.md)）。 ## 许可证 [GPL-3.0-or-later](LICENSE) — suho 链接了基于 GPL 许可的 `rustables` nftables 库，因此其二进制文件采用 GPL-3.0-or-later 许可证。版权所有 (C) 2026 David Borzek。

标签：Docker, nftables, 可视化界面, 安全防御评估, 容器网络, 网络策略控制, 自定义请求头, 请求拦截, 通知系统, 防火墙