snchakri/FluxShield

# Flux Shield — 开源 AI 驱动的 Web 应用防火墙 Flux Shield 是一个面向生产环境的开源 AI 辅助 Web 应用防火墙和流量防御平台。它结合了确定性的前置门启发式检测、高性能的 ML 推理运行时以及异步学习流水线，提供一个具备防御性、可审计且可部署的 WAF，并可与现代云和容器平台进行集成。 Flux Shield 专为安全工程师、SecOps 团队和平台运营商设计，他们在为 Web 服务需要强大且低延迟的保护，同时希望为模型驱动的决策保留安全、可审查的反馈循环。 **核心原则** - 防御性：支持人工审查的门控、只追加的审计跟踪以及保守的信任门控，以避免模型发生静默失败。 - 低延迟：前置门启发式检测 + 快速的模型运行时，使热路径延迟保持在严格的预算之内。 - 可观测性优先：丰富的指标、JSONL 审计日志，以及用于 SIEM 和 Prometheus 的集成钩子。 - 开放且可扩展：清晰的数据流、模块化的运行时组件，以及为研究人员和运营商提供的宽松贡献路径。 **目录** - **项目概述** - **能力与特性** - **架构与组件** - **安装与快速入门** - **运维指南** - **开发与贡献** - **安全、隐私与信任** - **路线图与治理** - **许可与致谢** - **联系与社区** ## 独特价值主张 Flux Shield 在开源生态系统中被设计并定位为最先进的 AI 驱动 Web 应用防火墙架构。它结合了可防御的教师/学生学习模型、只追加的可审计数据流、受约束的 AutoML 实践以及生产级的运维控制，旨在提供一种实用且可验证的安全态势，这在其他开源 WAF 项目中是难以匹敌的。 我们鼓励独立验证：该项目提供可复现的检查点、评估指标（F1、ROC、漂移）以及基准测试工具，以便运营商和研究人员能够在代表性工作负载上测量延迟、吞吐量和检测性能。这种公开且可测试的透明度是 Flux Shield 声称处于领先地位的核心——这不是营销炒作，而是一个经验上可验证的设计目标。 **项目概述** Flux Shield 提供了一个多路径流量检测流水线：轻量级的确定性前置门检查、主要的 ML 推理路径（低延迟），以及一个记录人类反馈以用于异步学习的教师/学生仲裁层。它可以部署在集群内部（Docker Compose 或 Kubernetes），与后端共存，或者作为独立的运行时运行以供测试。 Flux Shield 的目标： - 使用前置门启发式检测以极小的代价阻止已知的、基于规则的攻击。 - 在保持清晰的审计跟踪的同时，使用 ML 运行时对模糊流量进行分类。 - 捕获运营商反馈，并以旁路方式安全地更新在线学习器。 **能力与特性** - 前置门启发式检测：正则表达式、签名检查、头部异常——目标延迟在 3ms 以内。 - ML 推理运行时：模型加载、向量化 `predictSingle()`、置信度评分以及备用传输选项（ZeroMQ 为主，HTTP 为备）。 - 教师/学生仲裁：执行教师标记并允许运营商覆盖，以防止投毒。 - 异步学习器：批量重放、部分拟合流、检查点与回滚支持。 - 只追加的 file-db 日志：用于 `security_audit.jsonl` 和 `traffic_records.jsonl` 的 JSONL 审计通道，适用于离线分析和 SIEM 接入。 - 可观测性：Prometheus 指标、漂移分数、队列深度、p50/p95 延迟以及健康检查。 - 负载与混沌测试支持：Locust 场景和带有种子的加密流量，用于真实环境验证。 **架构与组件** 高级组件（详见 [docs/system_diagrams.md](docs/system_diagrams.md) 中的详细图表）： - Backend API (Node/Express)：解密负载，执行前置门检查，并协调推理/回退。 - 前置门过滤器：确定性规则和启发式方法，用于快速阻止明显的攻击。 - ZeroMQ 桥接：通往 AI 运行时的低延迟传输，具有可配置的超时和重试机制。 - AI-WAF 运行时 (Python)：强大的推理引擎、教师/学生仲裁、模型检查点和审计日志。 - 异步学习器：处理来自运行时的反馈事件，并执行安全的离线更新。 - file-db：用于可审计性和数据交换的只追加 JSONL 通道。 设计保证与指标： - 延迟预算：前置门 ≤3ms，ML 路径平均 ≤10ms，最坏情况 ≤40ms。 - 吞吐量：水平可扩展的 AI 运行时；在典型模型下，目标是每个运行时实例 >200 req/s。 - 准确度门控：在推广到生产环境之前，推荐的模型验证阈值在 holdout 数据集上 ≥85%。 **安装与快速入门** 最低前提条件： - Python 3.11+（用于 AI 运行时组件） - Node.js 16+（用于 Backend API 和 Web UI） - Docker & Docker Compose 或 Kubernetes 集群 快速本地运行（开发者测试）： 1. 克隆仓库并切换到项目根目录： ``` git clone cd twilight_exp ``` 2. 创建 Python 虚拟环境并安装运行时依赖： ``` python -m venv .venv source .venv/bin/activate # or .venv\\Scripts\\Activate.ps1 on Windows PowerShell pip install -r backup_model/v1/requirements.txt ``` 3. 启动 file-db 和后端（快速 compose 示例）： ``` docker-compose up file-db backend ``` 4. 在本地启动 AI 运行时（开发模式）： ``` cd backup_model/v1 python api_service.py # development entrypoint for inference runtime ``` 5. 发送测试加密负载（示例参见 `livepage/demo/generate-encrypted-traffic-samples.js`）或运行 `loadtest/` 中的 Locust 场景。 **运维指南** 推荐部署： - 使用容器编排 (Kubernetes) 并为 AI 运行时配置存活/就绪探针和 HPA。 - 保持异步学习器与热路径隔离，并限制重放窗口以避免不稳定。 - 导出 Prometheus 指标，并为漂移阈值和高队列深度配置 Alertmanager 规则。 审计与保留： - Flux Shield 将只追加的 JSONL 写入 `file-db/data/`（或挂载卷）。定期将这些文件轮换并归档到对象存储中，以实现长期保留和合规性。 故障转移与传输策略： - 将 ZeroMQ 配置为主传输；设置较短的请求超时（例如 15ms），并启用 HTTP 备用以保证可靠性。 **开发与贡献** 我们欢迎贡献者。对首次贡献的关键建议： - 查阅 [docs/system_diagrams.md](docs/system_diagrams.md) 中的架构。 - 运行您打算更改的组件的单元测试。仓库在 `backup_model/` 和 `loadtest/` 下包含组件级别的需求和测试。 - 在提出模型更改时，请将评估产物（F1、ROC、漂移分数）连同数据集或合成测试工具一起提供。 建议的本地工作流： ``` # 运行 backend 测试 cd backup_model/v1 pytest -q # 运行基础 locust profile cd loadtest locust -f locustfile.py --headless -u 50 -r 5 --run-time 2m ``` 贡献流程： - Fork 仓库，创建一个功能分支，并打开一个包含清晰描述和适用测试的 PR。 - 对于影响生产行为的模型或策略更改，请提供回滚计划和测试产物。 **安全、隐私与信任** Flux Shield 围绕强大的可审计性和安全学习原则构建： - 只追加日志：审计轨迹保留在 JSONL 中，适合用于取证审查。 - 信任账本与门控：来源和反馈会被评分；低信任度的来源会被隔离以供人工审查，然后才能用于重新训练模型。 - 人工教师标记：运营商提供的教师信号可以覆盖自动决策并防止不安全的更新。 - 数据隐私：系统支持传输中加密（TLS + AES-GCM 信封），并建议限制日志中的个人身份信息字段。 在报告安全问题时，请遵循标准的安全漏洞披露流程。如果您发现严重漏洞，请私下联系维护者（见下方的联系与社区）。 **路线图与治理** 计划中的短期和中期项目： - 强化教师-学生仲裁，以便在检测到学习器不稳定时包含自动回滚功能。 - 提供官方的 Helm chart 和带有合理默认值的生产级 Compose 堆栈，用于持久化和监控。 - 添加模型打包和可复现的训练流水线（容器化 GPU 训练 + CI 门控）。 我们打算让 Flux Shield 实行社区治理。改变运行时行为或信任策略的重大更改需要经过维护者的审查和明确批准。 **许可与致谢** Flux Shield 旨在成为开源项目。如果您希望我们采用宽松的许可证（推荐用于广泛的社区采用），请考虑 Apache-2.0 或 MIT 许可证。我们可以在请求时添加 LICENSE 文件，并在项目需要时帮助准备贡献者许可协议。 **联系与社区** 要讨论 Flux Shield，请在本仓库中开启 issues 或 PRs。对于私密或敏感的安全报告，请发送电子邮件至仓库元数据中列出的维护者联系方式。 **附录：实用路径** - 系统图表和 MERMAID 流程：[docs/system_diagrams.md](docs/system_diagrams.md) - AI 运行时和训练代码：[backup_model/](backup_model/) - 负载测试与 locust 场景：[loadtest/locustfile.py](loadtest/locustfile.py) - File-db（只追加 JSONL 存储）：[file-db/](file-db/) 如果您愿意，我还可以： - 为仓库页眉撰写简短的项目标语和电梯演讲 - 生成初始的 `LICENSE` 文件（Apache-2.0 或 MIT） - 更新 `sample_readme.md` 和附加文档，使其统一使用 `Flux Shield` 名称 告诉我您接下来希望我做其中的哪些事项。 ## 理论与设计（哲学、模型、数据与性能） 本节描述了指导 Flux Shield 架构和运维行为的理论基础和设计选择。它适用于希望了解安全模型、数据拓扑、AutoML 权衡以及预期性能特征的研究人员、平台架构师和 SecOps 工程师。 ### 设计哲学 - 关注点分离：在可能的情况下（前置门），使热路径推理保持最小和确定性，同时将学习和模型更新置于旁路进行，以避免性能退化。 - 设计时即考虑故障安全：置信度不足的决策会回退到保守的操作（人工审查、隔离或 HTTP 备用）；教师信号和审计日志支持人工干预的修复。 - 可观测性与可验证性：每个决策路径都会生成只追加的审计记录，适用于回顾性分析和合规性检查。 - 最小侵入式学习：在线更新需要带有漂移检测和回滚支持的门控接受机制，以防止模型投毒。 ### 教师 ⇄ 学生（安全的在线学习） Flux Shield 采用了带有明确信任控制的教师/学生式架构： - 教师：可以是人类分析师、强大的基于规则的分类器（前置门），或者在离线训练期间使用的集成预言机。教师生成高质量的标签，并可能将样本标记为权威的（教师标记）。 - 学生：部署在推理路径中的轻量级模型。学生通过异步学习器从教师标记的样本中学习，该学习器执行批量增量更新或定期重新训练。 核心安全机制： - 信任账本：每个反馈来源（人类、自动化）都有一个信任分数 ∈ [0,1]。只有高于可配置信任阈值的反馈才能在无需人工审查的情况下用于训练。 - 门控接受：模型更新需要通过验证门控（holdout 指标、漂移约束），然后才能推广到生产环境。 - 回滚与检查点：每个推广的检查点都有版本控制；当部署后的指标降至预定义的阈值以下时，将触发自动回滚。 数学草图（非正式）： - 设 D_t 为当前的生产数据集快照，θ 为学生模型参数。来自可信反馈的新批次 B 通过部分拟合或 SGD 步骤更新 θ： $$\theta_{t+1} = \theta_t - \eta \nabla L(\theta_t; B)$$ - 接受条件：如果 Eval(\theta_{t+1}, V) ≥ Eval(\theta_t, V) - \epsilon 并且 drift(\theta_{t+1}) ≤ \delta，则推广；否则保留 \theta_t 并排队等待离线分析。 其中 Eval 是评估指标（F1、AUC），V 是验证集，\epsilon 是一个小容差，\delta 是漂移分数阈值。 ### 数据拓扑：分布式摄取，集中式训练 实际部署在只追加的分片存储 中收集反馈和流量日志。系统区分两种角色： - 分布式热路径收集器：与运行时节点共存并追加 JSONL 记录的轻量级写入器（处理量极小）。这保持了每个节点的 I/O 成本低廉，并减少了跨节点延迟。 - 集中聚合与训练：周期性作业（或控制平面服务）将分片聚合为经过清洗的训练数据集，应用特征提取和去重，并运行 AutoML/训练流水线。 优势： - 本地只追加存储避免了热路径上的同步跨节点协调。 - 集中聚合实现了特征计算的一致性、数据集版本控制和可复现的运行。 隐私与治理： - 存储最少的 PII，尽可能匿名化，并在只追加通道强制执行保留/轮换策略。对归因于分析师的反馈使用元数据和假名化。 ### AutoML 与模型选择（以 auto-sklearn 为例） 对于表格或工程化的特征集（文本流量特征的 TF-IDF，数字头部/统计数据），可以使用诸如 `auto-sklearn` 之类的 AutoML 系统，在受约束条件下自动搜索模型族、预处理流水线和超参数： - 成本/延迟约束：将候选模型限制在推理延迟 ≤ L_max（由操作员设定）的范围内，并在代表性硬件上进行测量。 - 资源感知搜索：在搜索预算中包括 CPU/GPU 的可用性；对于低延迟要求，首选轻量级集成或单模型部署。 典型的 AutoML 工作流： 1. 从中央数据集准备带版本的特征和 holdout 拆分。 2. 定义优化目标：主要目标（F1 / 召回率），次要目标（推理延迟、模型大小）。 3. 运行受约束的 AutoML 搜索（时间预算 + 延迟约束）。 4. 在校准、鲁棒性（通过对抗/合成测试）和漂移敏感性方面评估候选模型。 5. 打包选定的模型（例如 `.joblib`），生成可复现的训练产物，并存储带有元数据的检查点。 关于集成的注意事项：集成可能会提高准确性，但通常会增加推理延迟和内存占用——通过延迟门控并将其可能蒸馏为更小的学生模型来进行平衡。 ### 理论延迟、吞吐量与性能估算 这些是帮助容量规划的工程估算。实际结果取决于模型选择、特征流水线、硬件和序列化。 假设（示例基线）： - 前置门确定性检查：0.3–3.0 ms（单线程正则/头部检查）。 - 序列化与反序列化 (msgpack/json)：0.2–1.0 ms。 - ZeroMQ 网络传输（集群内）：0.5–10 ms（中位数取决于节点拓扑和消息大小）。 - 模型推理（学生）每次请求：在现代 CPU 上，小型/优化模型为 1–10 ms；在优化的向量化推理或小型 GPU 上为 0.5–2 ms。 端到端中位延迟（典型的低延迟路径）： ``` pre-gate (1 ms) + transport (5 ms) + model inference (3 ms) + serialization (0.5 ms) = ~9.5 ms ``` 简单的吞吐量估算（每个运行时实例）： ``` throughput ≈ 1000 / latency_ms (requests/sec per single worker core) ``` 因此，在 10 ms 的延迟下，每个工作线程的近似吞吐量 ≈ 100 req/s。如果有 4 个工作线程和优化的 I/O，单个容器通常可以处理数百个 req/s。通过调整模型和并发性，实现每个运行时 >200 req/s 是现实的。 批处理权衡： - 批处理增加了吞吐量，但也增加了尾部延迟和抖动——除非应用程序能够容忍略高的延迟，否则这对于严格的热路径预算是不可接受的。 扩展策略： - 水平扩展（复制 AI 运行时 Pod），并在 ZeroMQ/HTTP 桥接器上进行负载均衡。 - 模型量化/蒸馏以降低推理成本。 - 当 GPU 资源可用时，为重型模型使用专用的推理运行时（ONNX、TensorRT）。 ### 评估与监控策略 - 持续跟踪的指标：p50/p95 延迟、队列深度、漂移分数、采样标记流量的召回率/精确率、每分钟的教师覆盖次数以及审计日志写入延迟。 - 门控：要求模型在推广到生产环境之前通过离线准确率（≥85% F1 或由操作员定义）、校准检查和漂移容忍度。 - 金丝雀/推广式发布：先部署到一小部分流量，并比较 24–72 小时的指标，然后再进行全面推广。

标签：AIOps, AI辅助安全, API集成, AppImage, AutoML, CISA项目, MITM代理, PB级数据处理, Prometheus监控, SecOps, SIEM集成, WAF, Web安全, Web应用防火墙, Web截图, 云安全架构, 人机回环, 低延迟安全, 可观测性, 启发式检测, 威胁防御, 子域名突变, 安全运维, 容器安全, 平台工程, 开源WAF, 异常流量检测, 异步学习管道, 时序数据库, 机器学习推理, 模型驱动安全, 流量防御平台, 网络安全, 自定义请求头, 蓝队分析, 请求拦截, 逆向工具, 隐私保护