JoeRu/federloom

# FederLoom 一个**去中心化、联邦式、基于信誉的 IP 黑名单**——威胁情报在自托管服务器之间点对点共享，并以**本地主权**为核心。它最初是作为一个非侵入式的 **Mailcow** 插件构建的，旨在补充 Fail2Ban 和 CrowdSec 等现有工具，而非取代它们。 CrowdSec 通过*中心化*的社区网络共享情报，而 FederLoom 则是其*去中心化*的对应方案：信任是**联邦化**的（类似 Mastodon 的信任域），黑/白名单仅仅是**辅助**，运维者始终可以对其进行覆盖，并且 IP 信誉会随着时间的推移而**衰减**——这也同时作为 GDPR 的存储限制机制。 ## 核心理念（一屏概览） - **基于每个 IP 的信誉评分**，而非硬性的全局列表。你的本地阈值会将其转化为黑名单。三个输出级别：评分 / 可直接替换的 blocklist / 原始事件。 - **通过结构防毒化，而非盲目信任**（规范 §4）：真值锚点（honeypot 或真实系统上的 spamtrap 语义）、多样性加权交叉验证（N 个*独立*的 ASN/国家，而不是 N 个节点），以及不对称的信誉衰减（信任上升缓慢，下降迅速）。 - **联邦信任**（规范 §5）：一个可管理的已签名信任锚点列表，加上你自己的子网，它们可以进行联邦（带有信任折扣）或保持隔离。断开联邦是对不良子网的应对之策。 - **通过查询而非复制进行扩展**（规范 §11）：DNSBL 风格的按需查找 + 紧凑的本地布隆过滤器；`ipset`/`nftables` (O(1))，绝不逐个 IP 生成规则。守护进程是一个良好的“邻居”——有资源预算，在遭受攻击时会自动减轻负载。 - **设计上遵循 GDPR**（规范 §9）：IP *属于*个人数据；合法利益基于网络安全中的正当权益（Art. 6(1)(f), Recital 49），将衰减作为自动删除机制，本地管理员作为数据控制者。 ## 运营联邦？请先阅读本文。 查阅 `docs/getting-started.md` 获取分步说明。使用 `federloomctl setup` 初始化身份，然后使用 `federloomctl federation invite`（面向现有运维者）或 `federloomctl federation join`（面向加入的运维者）来交换信任包。 如果你运营（而不仅仅是加入）一个信任域，你必须事先建立三件事。**这是必读内容**，记录在 [`docs/onboarding/`](docs/onboarding/) 中： 1. **[真值锚点](docs/onboarding/01-ground-truth.md)** — 注册你的 honeypot / spamtrap 系统的签名。 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/` 存放开发者技能。 ## 扩展：插件 FederLoom 围绕两个小型插件接口构建，因此它可以封装现有的工具（参见 [`docs/plugins.md`](docs/plugins.md)）： - **`ingest.Source`** — 攻击信号生产者：Mailcow 日志、spamtrap、honeypot (Cowrie/Dionaea/OpenCanary/T-Pot)、CrowdSec、Fail2Ban。 - **`enforce.Sink`** — 执行后端：`ipset`、`nftables`，或生成一个兼容 CrowdSec 的 blocklist，交由现有的 bouncer 来执行拦截。 ## 安装与首次运行 ``` make build ./bin/federloomd -config config.yaml # first run generates the node key ./bin/federloomctl setup # initialise identity and self-certify ``` 查看 **[docs/getting-started.md](docs/getting-started.md)** 获取完整指南（单节点、创建联邦或加入联邦）。 ``` make test # runs tests make adversarial # poisoning/sybil suite — the security CI gate ``` Mailcow 插件安装：参见 [`deploy/mailcow/README.md`](deploy/mailcow/README.md)。 ## 路线图（分阶段，参见 project-structure §6） 1. **MVP 单节点**：ingest (Mailcow + spamtrap) → reputation → ipset。 2. **P2P 核心**：gossip + bloom + 多样性交叉验证（约 80% 的核心价值）。 3. **信任锚点** + 密钥生命周期。 4. **联邦**：带折扣的导入、断开联邦、DHT 按需查找。 5. **扩展/强化**：中继角色、资源预算、可选的可观测性。 ## 开放性问题的状态 在规范的风险表中进行了追踪（规范 §12）：投毒行为只能被*缓解，永远无法彻底“解决”*；报告者隐私和衰减半衰期的调整是目前值得关注的未决事项。 ## 许可证 MIT — 参见 [`LICENSE`](LICENSE)。 ## 相关项目 - [JoeRu/Mailcow-Crowdsec-Override](https://github.com/JoeRu/Mailcow-Crowdsec-Override) — 本项目与之进行联邦的互补型中心化情报 CrowdSec 集成。

标签：GDPR合规, IP黑名单, 去中心化, 后端开发, 威胁情报, 开发者工具, 日志审计, 网络安全, 联邦学习, 请求拦截, 邮件防护, 隐私保护