alonsoir/argus

# ML Defender (aRGus NDR) **开源、内嵌机器学习的网络检测与响应系统，旨在保护关键基础设施免受勒索软件和 DDoS 攻击。** [](https://en.wikipedia.org/wiki/Appian_Way) [](#-consejo-de-sabios--multi-model-peer-review) [](LICENSE) []() []() []() [](docs/adr/ADR-025-plugin-integrity-ed25519.md) [](contrib/safe-path/) []() []() []() []() []() []() []() []() [](https://arxiv.org/abs/2604.04952) [](https://github.com/alonsoir/test-driven-hardening) 📜 活跃契约：[Protobuf schema](docs/contracts/Protobuf%20contracts.md) · [流水线配置](docs/contracts/JSON%20contracts.md) · [RAG API](docs/contracts/Rag%20security%20commands.md) ✅ `main` 分支已打上 `v0.5.2-hardened` 标签 —— 第 128 天文档编写与系统加固已完成。关闭 4 项技术债务，5 项属性测试全部通过 (GREEN)，Snyk 扫描发现的 18 个问题已分类处理。 **预生产：在 ACRL (DEBT-PENTESTER-LOOP-001) 完成之前，请勿在医院部署。** ## 当前状态 —— 第 128 天 (2026-04-24) **活跃标签：** `v0.5.2-hardened` | **活跃分支：** `main` (干净) ### 流水线 - 6/6 组件正在运行 —— 已在销毁并从零重建的虚拟机中得到验证 - `make test-all`：所有测试完成 - TEST-PROVISION-1：8/8 正常 ### 第 128 天里程碑 - **从零创建的新虚拟机** —— vagrant destroy + up + bootstrap。流水线 6/6 运行中。 - **技术发现：** `resolve_seed()` 使用 `std::terminate()` 强制执行 `0400` 权限。包含 seeds 的组件必须使用 `sudo` 启动。已作为永久模式记录在文档中。 - **关闭 4 项技术债务：** DEBT-SAFE-PATH-TAXONOMY-DOC-001, DEBT-PROPERTY-TESTING-PATTERN-001, DEBT-PROVISION-PORTABILITY-001, DEBT-SNYK-WEB-VERIFICATION-001 - **5 项属性测试通过 (GREEN)** 位于 `contrib/safe-path/tests/test_safe_path_property.cpp` —— 已集成到 `make test-libs` 中 - **18 个 Snyk 发现已分类** —— 1 个新增的高危级别：DEBT-IPTABLES-INJECTION-001 (CWE-78，第 129 天) - **第 128 天委员会 8/8 决议：** iptables 使用不带 shell 的 execve()（全票通过），FEDER 采用独立 NDR（全票通过），在执行 ADR-024 之前清理 EtcdClient (5/3 票通过) ### 待处理技术债务 详情请参阅 [docs/BACKLOG.md](docs/BACKLOG.md)。 | 债务 | 优先级 | 目标 | |-------|-----------|--------| | DEBT-IPTABLES-INJECTION-001 | 🔴 阻塞 | DAY 129 | | DEBT-FEDER-SCOPE-DOC-001 | 🟡 中等 | DAY 129 | | DEBT-FIREWALL-CONFIG-PATH-001 | 🔍 待验证 | DAY 129 | | DEBT-ETCDCLIENT-LEGACY-SEED-001 | ⏳ P2P 前期 | feature/etcdclient-p2p-cleanup | ### 下一个前沿领域（债务清理后） - **DEBT-PENTESTER-LOOP-001** —— ACRL：Caldera → eBPF 捕获 → XGBoost 重训练 → Ed25519 签名 → 热更新 ### ⚠️ 在以下事项完成前，切勿部署到生产环境 - DEBT-PENTESTER-LOOP-001 已完成（真实的 ACRL 数据） - ADR-036（形式化验证基线） ## 🏗️ 三种流水线变体 | 变体 | 状态 | 描述 | |----------|--------|-------------| | **aRGus-dev** | ✅ 活跃 (`main`) | x86-debug，完整的 Vagrant 镜像，build-debug。用于日常研究和开发。 | | **aRGus-production** | 🟡 待定 | x86-apparmor + arm64-apparmor。优化后的 Debian 镜像。面向医院、学校和市政部门。 | | **aRGus-seL4** | ⏳ 未来设计 | 科学附录。seL4 内核，libpcap（非 eBPF/XDP），单线程嗅探器。独立分支。 | ## 📄 预印本 **ML Defender (aRGus NDR)** 的详细说明记录在一份经过同行评审的预印本中，该预印本发表于 **arXiv cs.CR**（2026 年 4 月）。 **arXiv:** [arXiv:2604.04952 \[cs.CR\]](https://arxiv.org/abs/2604.04952) **DOI:** https://doi.org/10.48550/arXiv.2604.04952 **发布日期：** 2026 年 4 月 3 日 · **草稿 v16**（2026 年 4 月 19 日更新） · MIT 许可证 **代码库：** https://github.com/alonsoir/argus ## 🎯 使命 为负担不起商业解决方案的医院、学校和小型组织普及企业级网络安全。以科学的诚实和严谨的开发方式构建，旨在服务数十年。 **理念**: *Via Appia Quality* —— 系统的构建如同罗马大道，经久不衰。 ## 🛡️ 威胁模型范围 ML Defender 是一个**网络检测与响应 (NDR)** 系统。其指导原则是**网络监控**：每个组件都针对网络流量进行运作。 **物理和可移动介质载体经过深思熟虑后被明确排除在范围之外。** 建议与 [Wazuh](https://wazuh.com) 互补使用以进行文件完整性监控。 ## 📊 验证结果（第 122 天 —— 2026 年 4 月 19 日） | 指标 | 数值 | 备注 | |---|---|---| | **F1分数 (CTU-13 Neris)** | **0.9985** | 在 4 次重放运行中保持稳定 | | **精确率** | **0.9969** | | | **召回率** | **1.0000** | 零漏报攻击 (FN=0) | | **XGBoost 精确率 (CIC-IDS-2017 验证集)** | **0.9945** | 分布内，阈值=0.8211 | | **XGBoost 召回率 (CIC-IDS-2017 验证集)** | **0.9818** | 分布内 | | **XGBoost F1 (CIC-IDS-2017 验证集)** | **0.9881** | 验证集 AUCPR=0.99846 | | **XGBoost 周三 OOD** | **已记录的不可能性** | 结构性协变量偏移 —— 详见论文第 8 节 | | **推理延迟** | **1.986 µs/样本** | 门控 <2µs ✅ | | **推理延迟** | **0.24–1.06 µs** | 按类别计算，内嵌 C++20 | | **吞吐量上限 (虚拟化)** | **~33–38 Mbps** | VirtualBox 网卡限制，非流水线瓶颈 | | **压力测试** | **2,374,845 个数据包 — 0 丢包** | 请求 100 Mbps，循环 3 次 | | **内存 (完整流水线)** | **~1.28 GB** | 负载下保持稳定 | | **流水线组件** | **6/6 正在运行** | 可通过 `make bootstrap` 复现 | | **插件完整性** | **ADR-025 已合并** | Ed25519 + TOCTOU 安全的 dlopen | | **AppArmor** | **6/6 强制模式** | 0 次拒绝 | | **路径遍历防御** | **ADR-037 已合并** | `safe_path` 仅头文件库 —— 3 个基元 + 16+ 项 RED→GREEN 测试 | | **开发/生产一致性** | **第 127 天已合并** | `resolve_config()` —— 可信前缀下的合法符号链接 | | **CI 门控** | **TEST-PROVISION-1 8/8** | | ## 🔬 第 122 天科学发现 在第 122 天，针对 CIC-IDS-2017 的严格时间保留评估揭示了一种结构性协变量偏移：星期三包含的应用层 DoS 攻击（Hulk, GoldenEye, Slowloris）是所有训练日中都不存在的。**没有任何阈值能够同时满足周三数据中精确率 ≥0.99 和召回率 ≥0.95 的要求。** 这不是 XGBoost 的失败 —— 这是一个由数据集特有的按天攻击隔离设计所导致的经验上不可能的结果。 **这一发现印证了 Sommer & Paxson (2010) 的研究**，并提供了新的量化证据，表明基于学术基准训练的静态分类器在结构上不足以应对生产环境的 NDR。 **架构响应** —— 对抗性捕获-重训练循环 (ACRL) —— 在论文的第 11.18 节中提出。 ## 🔒 第 124-127 天安全加固 ### ADR-037 —— safe_path (第 124 天) `contrib/safe-path/` 是一个零依赖的 C++20 仅头文件库，可防止所有生产组件中的路径遍历攻击。包含三个具有不同安全语义的活跃基元： ``` // General paths — prefix verified post-canonical resolution const auto safe = argus::safe_path::resolve(path, "/etc/ml-defender/"); // Cryptographic seed material — lstat() PRE-resolution, symlinks strictly rejected // (fs::is_symlink(resolved) arrives too late — weakly_canonical() already resolved it) const int fd = argus::safe_path::resolve_seed(seed_path, keys_dir_); // Config files with legitimate symlinks — lexically_normal() verifies prefix // BEFORE following symlinks (enables /etc/ml-defender/ → /vagrant/ dev/prod parity) const auto cfg = argus::safe_path::resolve_config(config_path, "/etc/ml-defender/"); ``` **分类法（委员会 8/8 · 第 127 天）：** | 基元 | 用例 | 符号链接 | 验证 | |-----------|----------|----------|-------------| | `resolve()` | 通用路径 | 检查后允许 | 解析后使用 `weakly_canonical()` | | `resolve_seed()` | 加密材料 | ❌ 严格拒绝 | 解析前使用 `lstat()` | | `resolve_config()` | 配置文件 | ✅ 前缀内允许 | 解析前使用 `lexically_normal()` | | `resolve_model()` | ML 模型 (未来) | 待定 | Ed25519 签名验证 —— 待办 ADR-038 | ### 测试驱动加固 —— 属性测试 (第 125-127 天) 第 125-127 天通过经验证据验证了关键的 TDH（测试驱动加固）原则： ``` // memory_utils.hpp — header-only, independently testable [[nodiscard]] inline double compute_memory_mb(long pages, long page_size) noexcept { return (static_cast(pages) * static_cast(page_size)) / (1024.0 * 1024.0); } // Note: double chosen over int64_t — LONG_MAX/4096 * 8192 overflows int64_t. // Property test PropertyNeverNegative caught this latent bug in the int64_t version. ``` **测试层级（委员会 8/8 · 第 127 天）：** | 层级 | 验证内容 | 时机 | |-------|-----------------|------| | 单元测试 | 特定已知用例 (RED→GREEN) | 每次安全修复 | | 属性测试 | 数学不变量 | 每次安全修复 | | 模糊测试 | 解析器和外部接口 | 属性测试之后 | | 变异测试 | 测试套件质量 | 主要版本发布前 | **永久规则（委员会 8/8）：** - 每次安全修复必须包含：(1) 单元测试 RED→GREEN，(2) 用于验证不变量的属性测试，(3) 真实组件中的集成测试。 - 在实现之前，必须使用 PathPolicy 对每个新文件处理接口进行分类。 ## 🏗️ 架构 ``` ┌──────────────────────────────────────────────────────────────────┐ │ ML Defender Pipeline │ ├──────────────────────────────────────────────────────────────────┤ │ Network Traffic │ │ ↓ │ │ ┌──────────────────┐ │ │ │ sniffer (C++20) │ eBPF/XDP zero-copy packet capture │ │ │ │ ShardedFlowManager (16 shards) │ │ └──────────────────┘ │ │ ↓ ZeroMQ (ChaCha20-Poly1305 encrypted) │ │ ┌──────────────────┐ │ │ │ ml-detector │ 4× Embedded RandomForest classifiers │ │ │ (C++20) │ XGBoost plugin ADR-026 ✅ Prec=0.9945 │ │ └──────────────────┘ │ │ ↓ ZeroMQ (encrypted) │ │ ┌──────────────────┐ │ │ │ etcd-server │ Component registration + seed distrib. │ │ └──────────────────┘ │ │ ↓ │ │ ┌──────────────────┐ │ │ │ firewall-acl │ Autonomous blocking via ipset/iptables │ │ │ agent (C++20) │ safe_path::resolve_config() DAY 127 ✅ │ │ └──────────────────┘ │ │ ↓ │ │ ┌──────────────────┐ │ │ │ rag-ingester │ FAISS + SQLite event ingestion │ │ │ (C++20) │ safe_path::resolve_config() DAY 127 ✅ │ │ └──────────────────┘ │ │ ↓ │ │ ┌──────────────────┐ │ │ │ rag-security │ TinyLlama natural language interface │ │ │ (C++20+LLM) │ Local inference — no cloud exfiltration │ │ └──────────────────┘ │ └──────────────────────────────────────────────────────────────────┘ ``` ## 🚀 快速入门 ### 👶 首次使用 —— 全新克隆 ``` git clone https://github.com/alonsoir/argus.git cd argus make up # vagrant up — full provisioning ~20-30 min make bootstrap # all 8 steps in one command ``` ### 🔄 日常工作流 ``` make up make pipeline-stop make pipeline-build make sign-plugins && make sign-models make pipeline-start && make pipeline-status make test-all ``` ### ✅ CI 门控 ``` make test-all # 运行：libs + components + TEST-PROVISION-1 (8/8) # TEST-INVARIANT-SEED + plugin-integ-test (6/6，含 TEST-INTEG-SIGN) ``` ## 🗺️ 路线图 ###✅ 已完成 —— 第 127 天 (2026 年 4 月 23 日) —— DEBT-DEV-PROD-SYMLINK-001 🎉 - [x] **resolve_config()** ✅ —— 新的 safe_path 基元，用于处理带有合法符号链接的配置 - [x] **Makefile 绝对路径** ✅ —— 终结了组件启动时的相对路径问题 - [x] **委员会 8/8** ✅ —— safe_path 分类法正式确立 + FEDER 关键问题提出 ### ✅ 已完成 —— 第 126 天 (2026 年 4 月 23 日) —— v0.5.2-hardened 🎉 - [x] **DEBT-SAFE-PATH-SEED-SYMLINK-001** ✅ —— 解析前使用 lstat()，11/11 项测试通过 - [x] **DEBT-CONFIG-PARSER-FIXED-PREFIX-001** ✅ —— 固定前缀，4/4 + 3/3 项测试通过 - [x] **DEBT-PRODUCTION-TESTS-REMAINING-001** ✅ —— seed-client + firewall 3/3 + 3/3 项测试通过 - [x] **DEBT-MEMORY-UTILS-BOUNDS-001** ✅ —— MAX_REALISTIC_MEMORY_MB，5/5 项测试通过 - [x] **标签: v0.5.2-hardened** ✅ ### ✅ 已完成 —— 第 125 天 (2026 年 4 月 22 日) —— 债务清理 🎉 - [x] **DEBT-GITIGNORE-TEST-SOURCES-001** ✅ - [x] **DEBT-INTEGER-OVERFLOW-TEST-001** ✅ —— 属性测试发现其自身修复中的一个潜在 bug - [x] **DEBT-SAFE-PATH-TEST-RELATIVE-001** ✅ - [x] **DEBT-SAFE-PATH-TEST-PRODUCTION-001** ✅ (rag-ingester) - [x] **DEBT-CRYPTO-TRANSPORT-CTEST-001** ✅ ### ✅ 已完成 —— 第 124 天 (2026 年 4 月 21 日) —— ADR-037 加固 🎉 - [x] **ADR-037** —— `contrib/safe-path/` 仅头文件 C++20 · 9 项 RED→GREEN 测试 ✅ - [x] **标签: v0.5.1-hardened** ✅ ### ✅ 已完成 —— 第 128 天 (2026 年 4 月 24 日) —— 文档编写与加固 🎉 - [x] **DEBT-SAFE-PATH-TAXONOMY-DOC-001** ✅ —— docs/SECURITY-PATH-PRIMITIVES.md - [x] **DEBT-PROPERTY-TESTING-PATTERN-001** ✅ —— safe_path 的 5 项属性测试通过 (GREEN) - [x] **DEBT-PROVISION-PORTABILITY-001** ✅ —— ARGUS_SERVICE_USER + 对 seeds 使用 sudo - [x] **DEBT-SNYK-WEB-VERIFICATION-001** ✅ —— 18 个发现已分类，DEBT-IPTABLES-INJECTION-001 已识别 - [x] **发现：** resolve_seed() 使用 std::terminate() 强制执行 0400 权限 —— sudo 是正确的机制 - [x] **委员会 8/8** ✅ —— 5 项约束性决议已记录在文档中 ### 🔜 下一步 —— 第 129 天：CWE-78 修复 + EtcdClient 清理 | 优先级 | 任务 | |---|---| | 🔴 P0 阻塞 | DEBT-IPTABLES-INJECTION-001 —— 在 IPTablesWrapper 中使用不带 shell 的 execve() | | 🟡 P1 | DEBT-ETCDCLIENT-LEGACY-SEED-001 —— P2P 前期清理，[[deprecated]] + 移除 | | 🟡 P1 | DEBT-FEDER-SCOPE-DOC-001 —— docs/FEDER-SCOPE.md | | 🟡 P1 | 属性测试 compute_memory_mb (F17) RED→GREEN | | 🟡 P2 | 属性测试 HKDF 密钥派生 | ### 🔜 随后 —— 阶段 5：对抗性捕获-重训练循环 | 优先级 | 任务 | |---|---| | P0 | **DEBT-PENTESTER-LOOP-001** —— MITRE Caldera → 真实对抗流量 → XGBoost 重训练 | | P0 | **ADR-038** —— ACRL 正式设计 | | P0 | **BACKLOG-FEDER-001** —— 与 Andrés Caro Lindo 明确范围（独立 NDR vs 联邦） | | P1 | aRGus-production 镜像 (x86 + ARM64 apparmor) | | P2 | aRGus-seL4 研究分支 | ## 🧠 智者委员会 —— 多模型同行评审 八个大型语言模型作为知识联合评审员： **Claude** (Anthropic) · **Grok** (xAI) · **ChatGPT** (OpenAI) · **DeepSeek** · **Qwen** (Alibaba) · **Gemini** (Google) · **Kimi** (Moonshot) · **Mistral** 方法论：结构化分歧。在提出修复建议之前，必须通过可编译的测试或数学公式来证明问题存在。详见预印本第 6 节。 ## 🗺️ 里程碑 - ✅ 第 111 天: **arXiv:2604.04952 已发布** 🎉 - ✅ 第 113 天: **ADR-025 已合并 —— v0.3.0-plugin-integrity** 🎉 - ✅ 第 118 天: **阶段 3 完成 —— v0.4.0** 🎉 - ✅ 第 120 天: **make bootstrap + XGBoost F1=0.9978** 🎉 - ✅ 第 122 天: **阶段 4 完成 —— v0.5.0-preproduction** 🎉 - ✅ 第 124 天: **ADR-037 已合并 —— v0.5.1-hardened** 🎉 - ✅ 第 125 天: **关闭 5 项债务 · 属性测试验证 TDH · 恢复 47 个测试源** 🎉 - ✅ 第 126 天: **关闭 4 项债务 · 解析前使用 lstat() · 固定前缀 · v0.5.2-hardened** 🎉 - ✅ 第 127 天: **resolve_config() · 开发/生产一致性 · 委员会 8/8 safe_path 分类法** 🎉 - ✅ 第 128 天: **新虚拟机 6/6 · 关闭 4 项债务 · 5 项属性测试 · Snyk 发现 18 个问题 · 委员会 8/8** 🎉 - 🔜 第 129 天: **DEBT-IPTABLES-INJECTION-001 (CWE-78) · EtcdClient 清理 · FEDER 范围文档** ## 📄 许可证 MIT 许可证 —— 详见 [LICENSE](LICENSE) **Via Appia Quality** 🏛️ —— *为服务数十年而构建。*

标签：Apex, AppArmor, C++20, ChaCha20, DDoS防护, DNS解析, Docker镜像, FAISS, GitHub Advanced Security, HKDF, IP 地址批量处理, ML, NDR, Poly1305, XGBoost, 事件关联, 人工智能, 入侵检测与响应系统, 分布式架构, 勒索软件防护, 后端开发, 基础设施保护, 安全加固, 实时检测, 密码学, 幂等重放, 开源项目, 异常检测, 手动系统调用, 数据加密, 机器学习, 模型审查, 测试驱动安全, 用户模式Hook绕过, 确定性处理, 端点安全, 网络安全, 网络安全防御, 网络流量分析, 补丁管理, 语义索引, 遥测数据, 隐私保护, 零协调, 高级威胁防护