TeleVoyant/threat-hunting-platform-federated-coordinator

# apt-fl-coordinator 一个独立、安全加固的**联邦聚合服务器**，用于协作式 威胁检测模型。多个威胁狩猎平台在各自的 遥测数据上本地训练 XGBoost，仅共享（差分隐私的）**树结构** —— 绝不 共享原始日志 —— 然后这个中立的协调器将这些矩阵**组合**成一个全局 模型并进行**重新分发**。任何原始安全数据都不会跨越组织的 边界。 它是*用于检测基于凭证的横向移动 APT 的威胁狩猎软件*项目的跨组织部分，被提取到独立的代码仓库中，以便中立的联盟可以独立于任何参与组织的平台运行它。 ## 它的功能 ``` Org A platform ──┐ (1) train locally + DP (4) fetch global model Org B platform ──┤ sign contribution verify coordinator sig Org C platform ──┘ submit over mTLS ──▶ [ apt-fl-coordinator ] ──▶ redistribute (2) verify (nonce, sig, hash, freshness) (3) trust-validate + federated-bagging merge ``` - **接收** — 组织提交带有签名证明的 XGBoost 模型；服务器在 持久化这些字节之前会运行 7 步验证（组织/轮次绑定、SHA-256 完整性、±5 分钟时效性、一次性 nonce、Ed25519 签名）。 - **组合** — 根据需求，服务器会根据公共验证集对每个接受的贡献进行信任验证， 丢弃低信任度/被投毒的模型，并通过 **联邦 bagging** 合并幸存者（树集成按照信任度 × 数据大小的比例进行拼接， 上限为 500 棵树）。 - **提供** — 聚合后的全局模型以**协调器签名**的形式提供，因此组织在加载前可以 证明其真实且未被篡改。 ## 安全模型 | 威胁 | 防御 | |---|---| | **MITM / 篡改** | 双向 mTLS + Ed25519 消息签名 + SHA-256 模型绑定 | | **重放** | 每个组织/轮次的一次性 nonce，原子性消耗，+ ±5 分钟时间戳时效性 | | **伪造全局模型** | 协调器对每个全局模型进行签名；客户端在加载前进行验证 | | **冒充 / 女巫攻击** | CA 门控注册（操作员批准），每个组织一个客户端证书，CRL 吊销 | | **模型投毒** | 信任管理器：在公共验证集上进行结构 + 准确率 + 骤降检查；信任加权聚合；信任度低于 0.3 的组织被排除 | | **否认** | 每个贡献的签名证明都会被持久化；哈希链审计日志 | | **数据暴露** | 只有经过 DP 噪声处理的树结构会离开组织；协调器永远不会看到原始遥测数据 | | **DoS / 滥用** | 最大负载限制，每个（组织，轮次）仅接受一次贡献，容器加固 | 有关确切的通信格式，请参阅 [PROTOCOL.md](PROTOCOL.md)，有关威胁模型和披露政策，请参阅 [SECURITY.md](SECURITY.md)。 ## 快速开始 (Docker) ``` # 1. Operator JWT secret (Docker secret — 永不提交 / 永不放入 env) openssl rand -base64 48 > secrets/fl_jwt_secret # 2. Operator roster — 生成 api_key + hash，并将 hash 放入 config/fl_users.yml cp config/fl_users.example.yml config/fl_users.yml # then edit api_key_hash # 3. (可选) 用于 trust scoring 的 public validation set python examples/gen_validation.py config/validation.svm # 4. 引导 federation CA + coordinator TLS cert (一次性) docker compose run --rm coordinator \ python -m coordinator.init_ca --ca-dir /app/data/ca --hostname fl.example.com # 5. 启动它 (要求 mTLS, read-only, non-root, caps dropped) docker compose up -d ``` 通过带外方式将 `data/ca/ca_cert.pem` 分发给参与的组织（这是它们的信任 锚点）。组织在本地生成 Ed25519 密钥对，然后您使用它们的公钥进行注册； 注册会返回经 CA 签名的客户端证书 + 协调器的公钥。 ## 操作员 + 组织 API (前缀 `/fl`) | 方法 | 路径 | 身份 | 用途 | |---|---|---|---| | POST | `/orgs/enroll` | 操作员 (admin) | 注册组织，签发其客户端证书 | | GET | `/orgs` | 操作员 | 列出组织 + 信任分数 | | POST | `/orgs/{id}/block` · `/unblock` · DELETE `/orgs/{id}` | 操作员/管理员 | 生命周期管理 / 吊销 | | POST | `/rounds/start` | 操作员 | 开启一轮训练 | | GET | `/rounds/{id}/challenge` | 组织 (mTLS) | 一次性 nonce | | POST | `/rounds/{id}/contribute` | 组织 (mTLS) | 提交签名的模型矩阵 | | POST | `/rounds/{id}/aggregate` | 操作员 | 信任验证 + 组合已接受的矩阵 | | GET | `/rounds/{id}/global-model` | 组织 (mTLS) | 下载协调器签名的全局模型 | | GET | `/audit` | 操作员 | 哈希链审计追踪 | 参考参与者客户端位于 [`client_ref/`](client_ref/fl_client.py)。 ## 目录结构 ``` flproto/ vendored, self-contained protocol core (attestation, CA, libsvm) coordinator/ the server: api, store, security/RBAC, mTLS, aggregation, trust, audit client_ref/ reference org client (train -> DP -> sign -> submit -> verify) tests/ unit (crypto/merge/replay) + end-to-end (full round) — runnable scripts examples/ validation-set generator + end-to-end walkthrough ``` ## 开发 / 测试 ``` python -m venv venv && . venv/bin/activate pip install -r requirements.lock.txt PYTHONPATH=. OMP_NUM_THREADS=1 python tests/test_unit.py PYTHONPATH=. OMP_NUM_THREADS=1 python tests/test_e2e.py ``` ## 贡献 欢迎提交 Issues 和 PR —— 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。通信协议是 带版本的（[PROTOCOL.md](PROTOCOL.md)），因此独立的客户端实现可以保持一致。 ## 许可证 [Apache-2.0](LICENSE)。

标签：PE 加载器, XGBoost, 安全协调, 差分隐私, 模型聚合, 联合建模, 联邦学习, 请求拦截, 逆向工具