neuregex/nodesafe

# nodesafe [](https://pypi.org/project/nodesafe/) [](https://pypi.org/project/nodesafe/) [](https://pypi.org/project/nodesafe/) [](https://opensource.org/licenses/Apache-2.0) [](https://github.com/neuregex/nodesafe/actions/workflows/ci.yml) `nodesafe` 会在您将第三方插件/节点安装到基于节点的工作流工具之前对其进行扫描，它通过一个级联 pipeline 检测恶意代码，该 pipeline 结合了静态分析、签名匹配、机器学习，以及可选的 LLM 语义分析。起点：ComfyUI 生态系统。 ## 为什么会有这个项目 在 **2024 年 6 月**，ComfyUI_LLMVISION 窃取了数百名用户的浏览器凭证和加密货币钱包。在 **2026 年 4 月**，一个僵尸网络通过 Manager 自动安装恶意节点，攻破了 1000 多个 ComfyUI 实例。custom_nodes 生态系统庞大、发展迅速，且很大程度上未经审查。 `nodesafe` 会在您安装前进行扫描。 ## 快速开始 ``` pip install nodesafe nodesafe scan /path/to/custom_node ``` 或者无需安装直接运行： ``` uvx nodesafe scan /path/to/custom_node ``` ## 工作原理 一个 9 层级联 pipeline。每一层都比前一层开销更大。大多数干净的节点在 100ms 内即可通过；只有模糊不清的情况才会逐级上报。 | 层级 | 技术 | 开销 | |-------|-----------|------| | 0 | 针对恶意软件数据库的哈希匹配 | 微秒 (μs) | | 1 | 恶意 URL 的布隆过滤器 | 微秒 (μs) | | 2 | 基于危险模式的 Aho-Corasick 算法 | 毫秒 | | 3 | AST 分析 + 混淆检测器（字符链、分割拼接、香农熵、可疑标识符、Unicode 同形字、嵌套解码器链、文件级代码压缩） | 毫秒 | | 4 | 域名抢注 + OSV 漏洞检查 | 毫秒 | | 5 | 启发式综合风险评分（手动校准；ML 模型正等待数据集） | 数十毫秒 | | 6 | 异常检测（Isolation Forest + Autoencoder） | 数十毫秒 | | 7 | 语义相似度（CodeBERT embeddings + FAISS） | 数百毫秒 | | 8 | LLM 审查（可选，通过 Ollama 优先本地运行） | 秒 | **当前状态 (v0.5.1)：** 第 0-5 层已实现功能并在 PyPI 上发布。在 Python 3.10–3.12 × Linux/macOS/Windows 上通过了 87 项测试。第 3 层包含 7 个混淆检测器，可捕获字符代码关键字构造、分割拼接、高熵字面量、可疑标识符形状、Unicode 同形字攻击、嵌套解码器链和压缩文件。CLI 支持 `--batch`，可一次性扫描包含多个节点的父目录。第 6-8 层在 M3-M4 路线图中。 ## 功能特性 - ✓ **纯静态分析** — 绝不执行被扫描的代码 - ✓ **默认零遥测** — 此策略不可变 - ✓ **离线可用**（在首次签名更新之后） - ✓ **多种输出格式**：JSON、Markdown（v0.6 将支持 SARIF，以集成 GitHub Code Scanning） - ✓ **适配 GitHub Action** — 参见示例工作流 - ✓ **适配 Pre-commit hook** — 用于 custom_nodes 仓库的 CI/CD - ✓ **优先本地的 LLM 分析** — 默认使用 Ollama，可使用自带密钥选择开启云端分析 - ✓ **开源协议 Apache 2.0** — 没有免费增值模式，没有隐藏的 SaaS，没有付费白名单 ## 用法 ### 扫描目录 ``` nodesafe scan /path/to/custom_node ``` ### JSON 输出 ``` nodesafe scan /path/to/custom_node --format json ``` ### 仅运行低开销层级（快速，无综合评分） ``` nodesafe scan /path/to/custom_node --layers 0,1,2,3 ``` ### 批处理模式（一次扫描整个 `custom_nodes/` 文件夹） ``` nodesafe scan ComfyUI/custom_nodes --batch ``` 输出每个节点的判定结果以及一行综合的“最坏判定”。使用 `--format json` 可获取一组节点摘要信息，以便用于工具集成。 ### 更新签名 ``` nodesafe update ``` ### 验证安装 ``` nodesafe doctor ``` ## 回顾性分析 nodesafe 能否检测到历史上的安全事件？我们在脑海中对每个案例应用了该 pipeline： | 事件 | 检测层级 | 耗时 | 判定结果 | |----------|-----------------|------|---------| | LLMVISION (2024 年 6 月) | 第 2-3 层 | ~30-50ms | 恶意 0.98 | | Pickai (2025 年 3-6 月) | 第 2-3 + 5-7 层 | ~100ms | 恶意 0.92 | | 挖矿僵尸网络 (2026 年 4 月) | 第 2-3 层 + Manager 拦截 | <50ms | 恶意 0.95 | 完整分析见 [`docs/retrospective-analysis.md`](docs/retrospective-analysis.md)。 ## 诚实的局限性 `nodesafe` 是**静态分析**，而不是沙盒。它的局限性在于： - **它无法防止上游供应链攻击**（合法提供商被攻破的情况）。它检测的是分发在节点中的恶意软件，而不是最初的入侵。 - **它不能替代 Manager** — 它是互补的；理想情况下应整合在一起。 - **它不监控运行时行为** — 那是 IDS/EDR 的工作。 - **会出现误报** — 策略是保守的，但每个标记都会准确显示触发警报的原因，以便您做出决定。 ## 配置 `~/.config/nodesafe/config.toml`（可选 — 具有合理的默认值）： ``` [scanner] default_layers = "0,1,2,3,4,5,6" # Layer 8 NOT included by default fail_on = "suspicious" [llm] enabled = false # OFF by default. Conscious opt-in. provider = "local" # local-first if enabled [llm.local] endpoint = "http://localhost:11434" # Ollama model = "qwen2.5-coder:7b-instruct" [telemetry] enabled = false # ALWAYS false. Immutable policy. ``` ## 路线图 - **v0.5.x（已发布）：** 包含混淆检测器和批处理模式的第 0-5 层。现可通过 `pip install nodesafe` 使用。 - **v0.6（下一步）：** 运行时安装检测器（捕获在运行时执行 pip-install 或 git-clone 代码的节点，即 2026 年 4 月僵尸网络的传播途径）+ 用于 GitHub Code Scanning 的 SARIF 输出。 - **v0.7 (M3)：** 第 6 层异常检测（基于特征提取器的 Isolation Forest + autoencoder），一旦收集到足够的标记样本以建立基线即会推出。 - **v0.9 (M3)：** 第 7 层语义相似度（CodeBERT embeddings + FAISS），用于多态变体匹配。 - **v1.0：** 第 8 层 LLM 上下文审查（通过 Ollama 优先本地运行，可选用云端）+ 首次向 ComfyUI-Manager 提交 PR，以便默认在任何安装之前运行扫描。 - **v1.5：** 公开威胁报告 + 整合社区签名贡献。 - **v2+（第 2 年）：** `.nodesafe` 标准可移植到其他基于节点的生态系统（LangFlow、n8n、Flowise）。 完整计划见 [`ARCHITECTURE.md`](ARCHITECTURE.md)。 ## 许可证 Apache 2.0。参见 [LICENSE](LICENSE)。 ## 长期愿景 ComfyUI 是最迫切的情况，但不是唯一的情况。所有带有可执行插件的基于节点的工具类别（LangFlow、Flowise、Node-RED、n8n 等）都存在相同的结构性问题。从长远来看，`.nodesafe` 渴望成为一种**可移植的清单工件**，供任何生态系统采用——类似于 `.safetensors` 成为 ML 模型权重标准的方式。 该项目的 V2-V3 版本将使标准规范化，并与其他生态系统的维护者合作。今天，我们将集中精力死磕 ComfyUI。

标签：AI风险缓解, Apex, CLI应用, ComfyUI, DNS 反向解析, GraphQL安全矩阵, Python, 安全扫描器, 无后门, 无服务器架构, 机器学习, 网络信息收集, 自动化payload嵌入, 逆向工具, 错误基检测, 静态代码分析