JoeRu/swarmguard

# SwarmGuard 一个**去中心化、联邦式、基于信誉的 IP 黑名单** —— 威胁 情报在自托管服务器之间点对点共享，以**本地主权**为核心。 它最初是作为一个非侵入式的 **Mailcow** 插件构建的，旨在 补充 Fail2Ban 和 CrowdSec 等现有工具，而不是 取代它们。 CrowdSec 通过*中心化*的社区网络共享情报，而 SwarmGuard 是 其*去中心化*的对应物：信任是**联邦式**的（类似 Mastodon 的信任 域），黑/白名单只是**辅助**，运维人员始终可以对其进行覆盖， 并且 IP 信誉会随着时间的推移而**衰减** —— 这同时也作为 GDPR 的 存储限制机制。 ## 核心理念（一屏概览） - **每个 IP 的信誉分数**，而不是死板的全局列表。你本地的阈值会将其变成 一个黑名单。三个输出级别：分数 / 直接可用的黑名单 / 原始事件。 - **通过结构防投毒，而非盲目信任**（规范 §4）：基准真相锚点 （真实系统上的蜜罐或垃圾邮件陷阱语义）、多样性加权佐证（N 个*独立*的 ASN/国家，而不是 N 个节点），以及非对称的 信誉衰减（信任上升缓慢，下降迅速）。 - **联邦式信任**（规范 §5）：一个可筛选的已签名信任锚点列表，加上 你自己进行联邦（带有信任折扣）或保持隔离的子网。 解除联邦是对不良子网的应对手段。 - **通过查询而非复制来扩展**（规范 §11）：DNSBL 式的按需查找 + 紧凑的本地布隆过滤器；使用 `ipset`/`nftables` (O(1))，绝不使用每个 IP 对应一条规则。 该守护进程是一个好邻居 —— 拥有资源预算，在受到攻击时会减轻负载。 - **设计上符合 GDPR**（规范 §9）：IP*属于*个人数据；法律依据是 网络安全方面的正当利益（第 6(1)(f) 条，第 49 条说明），其中衰减作为自动 删除机制，本地管理员作为控制者。 ## 运营联邦？请先阅读此内容。 如果你运行（而不仅仅是加入）一个信任域，你必须预先建立三件事。 **这是必读内容**，记录在 [`docs/onboarding/`](docs/onboarding/)： 1. **[基准真相锚点](docs/onboarding/01-ground-truth.md)** —— 注册 你的蜜罐/垃圾邮件陷阱系统的签名。 2. **[大规模白名单 + 本地真相](docs/onboarding/02-whitelist.md)** —— 维护 联邦白名单；每次安装都会通过脚本添加其自己的本地真相。 3. **[密钥管理](docs/onboarding/03-key-management.md)** —— 锚点密钥的颁发、轮换、 撤销。 ……以及将这一切联系在一起的原则： **[列表是辅助，而非法律](docs/onboarding/04-override.md)** —— 用户可以 覆盖任何参数。 ## 仓库结构 有关完整的树状结构和原理，请参阅 [`docs/project-structure.md`](docs/project-structure.md)。 简而言之：`cmd/` 存放二进制文件，`internal/` 存放逻辑（三个平面：数据 = `enforce`，控制 = `reputation`/`transport`/`store`，可观测性 = `observability`），`pkg/proto` 存放网络协议，`deploy/` 存放 Docker + Mailcow， `docs/` 存放设计文档，`.claude/skills/` 存放开发者技能。 ## 扩展：插件 SwarmGuard 围绕两个小型插件接口构建，因此它可以封装现有的 工具（见 [`docs/plugins.md`](docs/plugins.md)）： - **`ingest.Source`** —— 攻击信号生产者：Mailcow 日志、垃圾邮件陷阱、 蜜罐（Cowrie/Dionaea/OpenCanary/T-Pot）、CrowdSec、Fail2Ban。 - **`enforce.Sink`** —— 执行后端：`ipset`、`nftables`，或者输出一个 兼容 CrowdSec 的黑名单，让现有的 bouncer 来执行拦截。 ## 快速开始（脚手架） ``` make build # builds bin/swarmd and bin/swarmctl (currently stubs) make test # runs tests (none yet) make adversarial # poisoning/sybil suite — the security CI gate ``` Mailcow 插件安装：请参阅 [`deploy/mailcow/README.md`](deploy/mailcow/README.md)。 ## 路线图（分阶段，见 project-structure §6） 1. **MVP 单节点**：摄取（Mailcow + 垃圾邮件陷阱） → 信誉 → ipset。 2. **P2P 核心**：gossip + 布隆过滤器 + 多样性佐证（约 80% 的价值）。 3. **信任锚点** + 密钥生命周期。 4. **联邦**：折扣导入、解除联邦、DHT 按需查找。 5. **扩展/强化**：中继角色、资源预算、可选择加入的可观测性。 ## 开放问题的状态 在规范的风险表（规范 §12）中进行了跟踪：投毒是*已缓解，从未被“解决”*；报告者隐私和衰减半衰期调整是值得注意的待办事项。 ## 许可证 MIT —— 请参阅 [`LICENSE`](LICENSE)。 ## 相关内容 - [JoeRu/Mailcow-Crowdsec-Override](https://github.com/JoeRu/Mailcow-Crowdsec-Override) — 本项目与之进行联邦的互补型中心化情报 CrowdSec 集成。

标签：IP黑名单, 去中心化, 后端开发, 威胁情报, 开发者工具, 日志审计, 联邦学习, 请求拦截, 运维工具