alonsoir/test-zeromq-c-

# ML Defender (aRGus EDR) **开源、企业级网络安全系统，保护关键基础设施免受勒索软件和 DDoS 攻击。** [](https://en.wikipedia.org/wiki/Appian_Way) [](LICENSE) []() https://alonsoir-test-zeromq-c-.mintlify.app/introduction ## 🎯 使命 为医院、学校和小型组织普及企业级网络安全，这些机构通常无力承担商业解决方案。以科学的诚实和系统化的开发为基础，旨在构建能持续运行数十年的系统。 **理念**：*Via Appia Quality* —— 像罗马道路一样构建系统，设计旨在持久。 ### 三大基础能力 **Shield** —— 运维防护。通过启发式 Fast Detector 和嵌入式 C++20 ML 集成，实时检测并阻断勒索软件和 DDoS。在 CTU-13 Neris 数据集上 F1=1.0000 验证通过。 **Microscope** —— 流量测量仪器。流经 Pipeline 的每个数据报文都被解析为 40 个维度，通过 `trace_id` 关联，并存储为 Pipeline 原生数据 —— 消除了导致基于学术数据集训练的模型失效的特征漂移。 **Research Platform** —— 具有可配置比例的受控数据集生成、可复现的实验基础架构，以及作为基于生成数据的对话式分析接口的 RAG-security。 所有代码、所有分析脚本、所有实验和所有失败都记录在代码库中。没有花招，没有捷径。 ## 🏗️ 架构 ``` ┌──────────────────────────────────────────────────────────────────┐ │ ML Defender Pipeline │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ Network Traffic (eBPF/XDP) │ │ ↓ │ │ ┌──────────────────┐ │ │ │ sniffer (C++20) │ eBPF/XDP packet capture │ │ │ │ - ShardedFlowManager (16 shards) │ │ │ │ - Fast Detector (heuristics) │ │ │ │ - 4x embedded ML feature extraction │ │ │ │ - ChaCha20-Poly1305 + LZ4 transport │ │ │ │ - Thresholds desde JSON ✅ DAY 80 │ │ └──────────────────┘ │ │ ↓ ZeroMQ (encrypted) │ │ ┌──────────────────┐ │ │ │ ml-detector │ 4x Embedded RandomForest Models │ │ │ (C++20) │ - DDoS Detection (<50μs) │ │ │ │ - Ransomware Detection (<55μs) │ │ │ │ - Traffic Classification (<50μs) │ │ │ │ - Internal Anomaly Detection (<48μs) │ │ └──────────────────┘ │ │ ↓ ChaCha20-Poly1305 + LZ4 │ │ ┌──────────────────┐ │ │ │ etcd-server │ Distributed Config + Key Management │ │ │ (C++20) │ - Automatic crypto seed exchange │ │ │ │ - HMAC secrets management ✅ │ │ └──────────────────┘ │ │ ↓ │ │ ┌──────────────────┐ │ │ │ firewall-acl │ Autonomous Blocking │ │ │ agent (C++20) │ - IPSet/IPTables integration │ │ │ │ - Sub-microsecond latency │ │ └──────────────────┘ │ │ ↓ │ │ ┌──────────────────┐ │ │ │ rag-ingester │ Log Parsing + Vector Ingestion │ │ │ (C++20) │ - ml-detector CSV logs ✅ │ │ └──────────────────┘ │ │ ↓ │ │ ┌──────────────────┐ │ │ │ rag (TinyLlama) │ Natural Language Intelligence │ │ │ + FAISS │ - Forensic queries │ │ │ (C++20) │ - ML retraining data │ │ └──────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────┘ ``` ## 📊 当前状态 (第 83 天 — 2026年3月12日) ### ✅ 已验证结果 | 指标 | 数值 | |---|---| | **F1-score (CTU-13 Neris, 阈值 0.85/0.90)** | **1.0000** | | **F1-score (CTU-13 Neris, 阈值 0.70/0.75)** | **0.9976** | | Recall | 1.0000 (零漏报，上限) | | Precision | 1.0000 / 0.9951 | | 数据集 | 492K 包, 19,135 流, 两种条件使用相同 PCAP | | Ground truth | 147.32.84.165 (此抓包中唯一的恶意 IP) | | 激活特征 | 28/40 实际 (11 个哨兵 Phase 2, 1 个语义) | | Pipeline 组件 | 6/6 RUNNING | | 阈值 | 来自 JSON ✅ (Phase1-Day4-CRITICAL 于第 80 天关闭) | | **ML 最高分数 (smallFlows 正常流量, 1209 流)** | **0.3818** (0 攻击 ✅) | | **ML 最高分数 (bigFlows 混合, 40467 流)** | **0.6897** (2 次攻击 conf≥0.65) | | Fast Detector FPR (正常 Windows 流量) | 高 — DEBT-FD-001 (ADR-006) | | **bigFlows ground truth** | **纯正常流量** (网络 172.16.133.x, 无 binetflow) | | **FPR ML (bigFlows, 40467 流)** | **0.0049%** (2 FP / 40,467) | | **FPR Fast Detector (bigFlows)** | 76.8% — DEBT-FD-001 | | **ML vs Fast Detector FP 降低** | **~15,500x** | | pipeline_health.sh | ✅ 第 83 天修复 (pgrep → vagrant ssh defender) | ### 阈值比较 (第 81 天 — 相同 PCAP，受控) | 条件 | DDoS | Ransom | Traffic | Internal | F1 | FP 实际 | |---|---|---|---|---|---|---| | 生产环境 (JSON) | 0.85 | 0.90 | 0.80 | 0.85 | **1.0000** | 0 | | 旧版低阈值 | 0.70 | 0.75 | 0.70 | 0.70 | **0.9976** | 1 | 保守阈值在不牺牲召回率的情况下消除了唯一的假阳性。 ### 诚实的局限性 - FN=0 是上限 —— 需要完整的事件级 IP 表来确认 - CTU-13 Neris 是 98% 的恶意流量 —— 平衡数据集验证待定 (P0) - ML RandomForest 最高分 = 0.6607 (低于阈值) —— Fast Detector 处理 Neris 中的所有检测 - 11/40 ML 特征使用哨兵值 —— Phase 2 待定 - Fast Detector Path A 使用硬编码阈值 (第 13 天债务) —— 在 Windows CDN/更新流量上 FPR 较高 (DEBT-FD-001, ADR-006, 修复 PHASE2) - bigFlows.pcap 确认为良性 (172.16.133.x 网络，无僵尸网络 ground truth 可用)。ML FPR = 0.0049%。 - ml-detector 中有三个不同的攻击计数器 —— 语义正确但直到第 82 天才记录 ### Fast Detector 双路径架构 (第 82 天发现) `ring_consumer.cpp` 中共存两条独立的告警路径： **Path A** (`is_suspicious()`, 第 13 天): 逐包评估，使用 `fast_detector.hpp` 中的编译常量 (`THRESHOLD_EXTERNAL_IPS=10`, `WINDOW_NS=10s`)。 忽略 `sniffer.json`。Windows CDN 流量上 FP 的来源。**DEBT-FD-001.** **Path B** (`send_ransomware_features()`, 第 80 天): 基于时间聚合评估， 读取 `sniffer.json` (`external_ips_30s=15`)。正确的 JSON 驱动行为。 修复 (PHASE2): 将 `FastDetectorConfig` 注入到 `FastDetector` 构造函数中。 完整分析: `docs/adr/ADR-006-fast-detector-hardcoded-thresholds.md` ### ML Detector: 三个攻击计数器 | 信号 | 条件 | 语义 | |---|---|---| | log `🚨 ATTACK` | `label_l1 == 1` | RandomForest 二分类投票 | | `stats_.attacks_detected` | `label_l1==1 AND conf >= 0.65` | 置信度足够 | | `final_classification=MALICIOUS` | `final_score >= malicious_threshold` | 最终决定 | `level1_attack=0.65` 位于 `ml-detector/config/ml_detector_config.json`。 ## 🚀 快速开始 ### 前置条件 ``` vagrant --version # 2.3+ vboxmanage --version # 7.x ``` ### 构建与部署 ``` git clone https://github.com/yourusername/ml-defender.git cd ml-defender vagrant up defender make all make pipeline-start make pipeline-status ``` ### 运行 CTU-13 Neris 验证 ``` # 先检查 VM 状态 — 切勿重复启动 client vagrant status make pipeline-stop && make logs-lab-clean && make pipeline-start && sleep 15 vagrant ssh -c "grep 'Thresholds (JSON)' /vagrant/logs/lab/sniffer.log" vagrant up client # only if client is not already running make test-replay-neris # 计算 F1 vagrant ssh -c "cat /vagrant/logs/lab/sniffer.log" > /tmp/sniffer.log vagrant ssh -c "grep 'Stats:' /vagrant/logs/lab/ml-detector.log | tail -1" python3 scripts/calculate_f1_neris.py /tmp/sniffer.log --total-events N --day 82 ``` ### 调整阈值 (无需重新编译) 编辑**源**文件 `sniffer/config/sniffer.json` (而非构建产物): ``` "ml_defender": { "thresholds": { "ddos": 0.85, "ransomware": 0.90, "traffic": 0.80, "internal": 0.85 } } ``` 重启 Pipeline 以应用。启动日志确认: ``` [ML Defender] Thresholds (JSON): DDoS=0.85 Ransomware=0.9 Traffic=0.8 Internal=0.85 ``` ## 🔬 工程决策 ### 哨兵值分类 (第 79 天) ML 特征提取中三类特殊值： 1. **域有效哨兵** (`-9999.0f`) —— 数学上不可达。确定性，可审计。 2. **语义值** (例如 `0.5f` TCP established-not-closed) —— 有效的域值，通过保护性注释保留。 3. **域内占位符** —— 严格来说比第 1 类差。在 RandomForest 集成中引入虚假方差。 完整分析: [`docs/engineering_decisions/DAY79_sentinel_analysis.md`](docs/engineering_decisions/) ### JSON 即法律 (第 80 天) 所有配置值 —— 包括 ML 阈值 —— 均来自 JSON。 生产代码中无硬编码常量。回退必须显式并记录日志。 注意: `sniffer/build-debug/config/sniffer.json` 是生成的产物。 始终编辑 `sniffer/config/sniffer.json` (事实来源)。 ### ML 训练数据 —— 三个类别 (第 81 天) 项目正式区分三种类型的训练数据： - **类别 A —— 学术** (CTU-13, CIC-IDS2017): 离线 F1≈0.99，生产环境 F1≈0.006。特征漂移使模型完全失效。 - **类别 B —— 合成统计** (自生成器): 生产环境最高分 0.6607。优于 A，但不足以作为阈值。 - **类别 C —— Pipeline 原生**: 由 C++20 提取器自身生成的特征，通过 `trace_id` 关联。构造上零特征漂移。**假设验证中。** 完整分析: [`docs/engineering_decisions/DAY81_ml_training_data_analysis.md`](docs/engineering_decisions/) ### Fast Detector 设计 (第 12 天 —— 未在 CTU-13 上训练) Fast Detector 启发式规则是基于勒索软件和 C&C 行为的第一性原理设计的 —— 而非来自 CTU-13 数据。CTU-13 仅作为理论验证引用。启发式规则： - `external_ips_30s > 15` —— 勒索软件必须联系 C&C (不可避免) - `smb_connection_diversity > 10` —— WannaCry/Petya 横向移动特征 - `dns_entropy > 2.5` —— DGA 检测 - `upload_download_ratio > 3.0` —— 双重勒索数据窃取 - `burst_connections > 50` —— 蠕虫行为 因此，在 CTU-13 Neris 上 F1=1.0000 是泛化结果，而非过拟合。 ### FlowStatistics Phase 2 (第 81 天) 四个特征在 `FlowStatistics` 层级受阻，而非 protobuf： - `tcp_udp_ratio` —— 需要 FlowStatistics 中的 `uint8_t protocol` 字段 - `flow_duration_std`, `protocol_variety`, `connection_duration_std` —— 需要多流 TimeWindowAggregator Protobuf 契约是正确的。这些特征返回 `MISSING_FEATURE_SENTINEL` (-9999.0f) 直到 Phase 2。在代码注释中记录为 `DEBT-PHASE2`。 ### 标准化日志 (第 79 天 + ADR-005 第 81 天) ``` /vagrant/logs/lab/ ├── etcd-server.log ├── rag-security.log ├── rag-ingester.log ├── ml-detector.log ← stdout (Makefile redirect, startup only) ├── detector.log ← spdlog internal (operational source of truth) ├── firewall-agent.log └── sniffer.log ``` ADR-005: 在论文完成后通过 ENT-4 热重载统一两个 ml-detector 日志。 ## 🧪 实验跟踪 所有 F1 重放结果跟踪在 `docs/experiments/f1_replay_log.csv` 中。 协议定义在 `docs/experiments/f1_replay_log.md`。 | replay_id | day | thresholds | F1 | Precision | Recall | notes | |---|---|---|---|---|---|---| | UNKNOWN_DAY79 ⚠️ | 79 | 0.70/0.75 hardcoded | 0.9921 | 0.9844 | 1.0000 | Replay unknown ⚠️ | | UNKNOWN_DAY80 ⚠️ | 80 | 0.85/0.90 JSON | 0.9934 | 0.9869 | 1.0000 | Replay unknown ⚠️ | | DAY81_thresholds_085090 | 81 | 0.85/0.90 JSON | 1.0000 | 1.0000 | 1.0000 | First clean replay ✅ | | DAY81_condicionB | 81 | 0.70/0.75 legacy | 0.9976 | 0.9951 | 1.0000 | Controlled comparison ✅ | | DAY82-001 | 82 | 0.85/0.90 JSON | — | — | — | smallFlows benign Windows: ML attacks=0 ✅, FD 3741 FPs (DEBT-FD-001) | | DAY82-002 | 82 | 0.85/0.90 JSON | — | — | — | bigFlows: ML 7 label=1, 2 attacks (conf≥0.65), max_score=0.6897, GT unknown | ## 📋 路线图 ### ~~紧急 (第 82-83 天)~~ - ✅ 平衡数据集验证 —— smallFlows + bigFlows 确认为良性 - ✅ bigFlows ground truth 已解决 —— 良性，FPR ML=0.0049% - ✅ 修复 pipeline_health.sh (pgrep → vagrant ssh defender) - ✅ CSV Pipeline E2E 验证通过 (ml-detector: 71K 行, 0 HMAC 错误) - ✅ F1=1.0000 第 83 天重新验证 ### 短期 (第 84-86 天) - arXiv 论文准备 - 修复 2 个预先存在的 trace_id 测试失败 (第 72 天) DNS payload 解析实战 ### 紧急 (第 82 天) - 平衡数据集验证 (P0 论文 —— CTU-13 Neris 是 98% 恶意) - 调查 ML RandomForest 最高分 0.6607 (从未达到阈值) - 修复 pipeline_health.sh (pgrep 在 macOS 上运行，而非 VM 内) ### 短期 (第 83-85 天) - CSV Pipeline E2E 验证与真实流量 - 修复 2 个预先存在的 trace_id 测试失败 (第 72 天) - arXiv 论文准备 ### 企业版 - 联邦威胁情报 (ENT-1) - 攻击图谱生成 — GraphML + STIX 2.1 (ENT-2) - P2P Seed 分发 — 消除 etcd 作为加密权威 (ENT-3) - 热重载配置 — 无停机阈值调优 (ENT-4) ## 🎓 设计理念 **Via Appia Quality** —— 科学诚实，系统化开发，透明 AI 协作。 **Consejo de Sabios** —— 多智能体同行评审：Claude, DeepSeek, Grok, ChatGPT, Qwen。 所有 AI 贡献均明确署名为共同作者。 ## 🔐 安全 ### 保障 - ✅ ChaCha20-Poly1305 认证加密 (AEAD) - ✅ HMAC-SHA256 日志完整性 - ✅ 自主阻断 (无人工干预) - ✅ JSON 驱动阈值 (无硬编码安全参数) - ✅ 故障关闭设计 ### 已知局限 - 11/40 ML 特征使用哨兵值 (Phase 2 待定) - 平衡数据集验证待定 (CTU-13 Neris 98% 恶意) - ML RandomForest 未检测到 Neris —— Fast Detector 处理所有检测 - 单节点部署 (无 HA/故障转移) ## 📈 性能 **sniffer**: 亚微秒级 eBPF/XDP, ShardedFlowManager 16 分片, 0 加密错误 **ml-detector**: 每次检测 0.24μs–1.06μs, CTU-13 Neris 上 F1=1.0000 (第 81 天) **firewall-acl-agent**: <10ms 检测→阻断, 364 ev/s, 54% CPU, 127MB RAM, 36K 事件下 0 加密错误 ## 📄 许可证 MIT License — 详见 [LICENSE](LICENSE) ## 🙏 致谢 **人类**: Alonso Isidoro Roman — 创始人, ML 架构师 **AI 共同作者 (Consejo de Sabios)**: Claude (Anthropic), DeepSeek, Grok, Gemini, ChatGPT, Qwen, Parallel.ai **数据集**: CTU-13 (Czech Technical University), CIC-IDS2017 (UNB), UNSW-NB15 ## 🗺️ 项目状态 **当前阶段**: 第 81 天 — F1=1.0000 受控比较验证通过 **近期里程碑**: - ✅ 第 76 天: SIGSEGV 消除 — pipeline 6/6 稳定 - ✅ 第 79 天: F1=0.9921 — 哨兵修复 + 日志标准化 - ✅ 第 80 天: F1=0.9934 — **JSON is the LAW** 🦅 - ✅ 第 81 天: F1 comparativa limpia — 阈值经验证合理 ✅ - ✅ 第 82 天: DEBT-FD-001 发现 — FastDetector Path A 自第 13 天起硬编码 (ADR-006) - ✅ 第 82 天: 平衡数据集重放 (smallFlows + bigFlows) — ML 对正常流量判断正确 - ✅ 第 83 天: bigFlows ground truth 已解决 — 40K 正常流上 FPR ML=0.0049% - ✅ 第 83 天: CSV E2E 验证通过 — 71K 行, 0 HMAC 错误 - ✅ 第 83 天: pipeline_health.sh 修复 — 6/6 PID 正确 - ✅ 第 83 天: **MERGE TO MAIN** — 所有标准验证通过 ✅ **Via Appia Quality** 🏛️ — 旨在持续数十年 *"通往安全的道路漫长，但我们建造它是为了持久。"*

标签：Apex, Beacon Object File, C++20, CIDR输入, Cloudflare, DDoS检测, DNS 反向解析, EDR, FAISS, IP 地址批量处理, MITRE ATT&CK, ML集成, RAG安全, Red Canary, ZeroMQ, 企业级安全, 分布式系统, 勒索软件防护, 响应大小分析, 威胁情报, 实时检测, 幂等性, 开发者工具, 微服务架构, 数据流水线, 机器学习, 特征工程, 确定性计算, 网络安全, 脆弱性评估, 语义索引, 配置错误, 隐私保护