ParzivalHack/PySpector

# 高性能 Python/Rust 基于图的 SAST 框架 [](https://www.securitycert.it/) [](https://pepy.tech/project/pyspector) [](https://pepy.tech/projects/pyspector) [](https://github.com/ParzivalHack/PySpector/releases/tag/v0.1.6-beta) [](https://pypi.org/project/pyspector/) [](https://www.python.org/) [](https://www.rust-lang.org/) [](https://satori.ci/) PySpector 是一个最先进的静态分析安全测试 (SAST) 框架，采用 Rust 构建以实现下一代性能，专为现代 Python 项目和大型代码库打造。与传统的 linter 不同，PySpector 利用 **流敏感、过程间污点引擎** 来跟踪跨复杂函数边界和控制流结构的不可信数据。 通过将核心分析引擎编译为原生二进制文件，PySpector 避免了传统纯 Python 工具的性能限制。这使其非常适合对速度和可扩展性有要求的 CI/CD 流水线和本地开发环境。 PySpector 的设计既全面又直观，提供多层分析方法，超越了简单的模式匹配，能够理解 Python 应用程序的结构和数据流。 ## 目录 - [快速演示](#quick-demo) - [入门指南](#getting-started) - [关键特性](#key-features) - [核心引擎架构](#core-engine-architecture) - [工作原理](#how-it-works) - [性能基准测试](#performance-benchmarks) - [使用方法](#usage) - [插件系统](#plugin-system-new-feature) - [分流与基线管理](#triaging-and-baselining-findings) - [自动化与集成](#automation-and-integration) ## 快速演示 https://github.com/user-attachments/assets/0fe03961-0b62-4964-83ba-849f2357efba ## 入门指南 ### 前置条件 - **Python**: 支持 Python 3.9 – 3.12（Python 3.9 或更高版本，最高至 3.12）。 - **Rust**: 需要 Rust 编译器 (`rustc`) 和 Cargo 包管理器。您可以通过 [rustup](https://rustup.rs/) 轻松安装 **Rust 工具链**，并通过运行 `cargo --version` 验证安装。 ### 安装 **强烈建议**在专用的 Python 3.12 venv 中安装 PySpector。 #### 创建虚拟环境: - **Linux (Bash)**: # 下载 Python 3.12 python3.12 -m venv venv source venv/bin/activate - **Windows (PowerShell)**: # 从 Microsoft Store 下载 Python 3.12 并运行: python3.12 -m venv venv .\venv\Scripts\Activate.ps1 # 或者，取决于 Python 3.12 的安装来源: .\venv\bin\Activate.ps1 随着 PySpector 现已正式登陆 PyPI🎉，安装变得非常简单，只需运行： ``` pip install pyspector ``` ## 关键特性 * **流敏感分析:** 利用控制流图 (CFG) 按顺序跟踪变量状态，准确区分安全代码路径和易受攻击的代码路径。 * **过程间污点跟踪:** 使用全局不动点迭代和函数摘要，跨函数边界传播不可信数据。 * **上下文感知摘要:** 复杂映射哪些函数参数流向返回值，允许通过复杂的实用函数进行高精度跟踪。 * **多引擎混合扫描:** * **正则引擎:** 高速扫描秘密、硬编码凭证和配置错误。 * **AST 引擎:** 深度结构模式匹配，查找 Python 特有的反模式。 * **图引擎:** 基于 CFG 和调用图的先进数据流分析，用于复杂的漏洞链。 * **市场最快性能:** 核心分析引擎使用 Rust 实现，并利用 `Rayon` 进行多线程并行化（使 PySpector 的扫描速度比 Bandit 快 71%，比 Semgrep 快 16.6 倍）。 * **AI 代理安全:** 专用规则集，旨在识别 LLM 集成 Python 应用程序中的提示注入、不安全工具使用和数据泄露。 ## 核心引擎架构 PySpector v0.1.5 代表了从部分静态模式匹配到完整基于图的分析引擎的转变： 1. **AST 解析:** Python 源代码被转换为结构化的 JSON AST，用于语义分析。 2. **调用图构建:** PySpector 构建项目范围的函数定义和调用点映射，以实现跨文件分析。 3. **CFG 生成:** 每个函数被分解为控制流图 (CFG)，使引擎能够理解操作顺序和条件 Python 逻辑。 4. **不动点污点传播:** 使用工作列表算法，引擎将“污点”从定义的 **源** 传播到 **汇聚点**，同时遵守沿途清理数据的 **净化器**。 ## 工作原理 PySpector 的混合架构是其性能和效率的关键。 * **Python CLI 编排:** 流程始于基于 Python 的 CLI。它处理命令行参数，加载配置和规则，并准备要分析的目标文件。对于每个 Python 文件，它使用原生 ast 模块生成抽象语法树，然后将其序列化为 JSON。 * **调用 Rust 核心:** 序列化的 AST 以及规则集和配置被传递给编译后的 Rust 核心。从 Python 到 Rust 的交接由 pyo3 库管理。 * **Rust 中的并行分析:** Rust 引擎接管并执行繁重的工作。它利用 rayon crate 并行执行文件扫描和分析，最大限度地利用可用的 CPU 核心。它构建应用程序的完整调用图以理解文件间函数调用，这对污点分析模块至关重要。 * **结果与报告:** 分析完成后，Rust 核心将结构化的发现列表返回给 Python CLI。然后，Python 包装器处理最后步骤，根据严重性阈值和基线文件过滤结果，并以用户指定的格式生成报告。 这种架构结合了两全其美：Python 中灵活、用户友好的界面，以及 Rust 中高性能、内存安全的分析引擎 :) ## 性能基准测试 性能基准测试展示了 PySpector 在 SAST 扫描速度方面的竞争优势，同时保持了全面的安全分析。 ### 基准测试结果 #### 跨主要 Python 代码库（Django, Flask, Pandas, Scikit-learn, Requests）的对比分析显示： | 指标 | PySpector | Bandit | Semgrep | |--------|-----------|---------|---------| | **吞吐量** | 25,607 行/秒 | 14,927 行/秒 | 1,538 行/秒 | | **性能优势** | 比 Bandit **快 71%** | 基准 | 慢 16.6 倍 | | **内存使用** | 平均 1.4 GB | 平均 111 MB | 平均 277 MB | | **CPU 利用率** | 120% (多核) | 100% (单核) | 40% | ### 关键性能特征 - **速度**: 通过 Rust 驱动的并行分析，比传统工具提供快 71% 的扫描速度 - **可扩展性**: 在大型代码库（50 万行以上代码）上保持高吞吐量 - **资源概况**: 针对具有足够内存分配的现代多核环境进行了优化 - **一致性**: 在不同项目类型和规模下保持稳定的性能 ### 最佳性能的系统要求 - **最低**: 2 个 CPU 核心，2 GB RAM - **推荐**: 4+ 个 CPU 核心，4+ GB RAM（用于大型代码库） - **存储**: 建议使用 SSD 进行大型仓库扫描 ### 基准测试方法 性能测试在以下环境进行： - **测试环境**: 基于 Debian 的 Linux VM（2 核心，4GB RAM） - **测试项目**: 5 个主要 Python 仓库（1.3k-53万行代码） - **测量**: 多次运行的平均值，包含 CPU 稳定期 - **比较**: 使用相同配置与 Bandit 和 Semgrep 进行正面比较 *基准数据可在项目仓库中获取，以确保透明度和可重复性。* ## 使用方法 PySpector 通过简单的命令行界面进行操作。 ### 运行扫描 主要命令是 `scan`，它可以针对本地文件、目录，甚至远程 Git 仓库。 ``` pyspector scan [PATH or --url REPO_URL] [OPTIONS] ``` ### 示例: * **扫描单个文件** ``` pyspector scan /path/to/your/project ``` * **扫描本地目录并将报告保存为 HTML:** ``` pyspector scan /path/to/your/project -o report.html -f html ``` * **扫描公共 GitHub 仓库:** ``` pyspector scan --url https://github.com/username/repo.git ``` ### 面向初学者的向导模式 (新功能🚀) * **使用 `--wizard` 标志进入引导扫描模式，非常适合首次用户、初学者或学生：** ``` pyspector scan --wizard ``` ### 扫描 AI 和 LLM 漏洞 * **使用 `--ai` 标志为使用大语言模型的项目启用专用规则集：** ``` pyspector scan /path/to/your/project --ai ``` ### 扫描依赖项中的供应链 CVE * **使用 `--supply-chain` 标志检查您的项目依赖项是否存在已知 CVE：** ``` pyspector scan /path/to/your/project --supply-chain ``` ## 插件系统 PySpector ships with an extensible plugin architecture that lets you post-process findings, generate custom artefacts, or orchestrate follow-up actions after every scan. Plugins run in-process once the Rust core returns the final issue list, so they see exactly the same normalized data that drives the built-in reports. ### 生命周期概述 1. **发现** - 插件文件位于仓库的 `plugins` 目录（`PySpector/plugins`）中，并被自动发现。 2. **注册** - 受信任的插件与其校验和和元数据一起记录在 `PySpector/plugins/plugin_registry.json` 中。 3. **验证** - 在执行之前，PySpector 会验证插件配置，静态检查源代码中是否存在危险的 API，并检查磁盘上的校验和。 4. **执行** - 插件被初始化，接收完整的发现列表，并可以发出额外的文件或数据。最后总会调用 `cleanup()`。 ### 从 CLI 管理插件 CLI 提供了用于维护本地目录的辅助命令： ``` pyspector plugin list # Show discovered plugins, trust status, version, author pyspector plugin trust plugin_name # Validate, checksum, and mark a plugin as trusted pyspector plugin info plugin_name # Display stored metadata and checksum verification pyspector plugin install path/to/plugin.py --trust pyspector plugin remove legacy_plugin ``` 只有受信任的插件才会自动执行。当您信任一个插件时，PySpector 会计算其 SHA256 校验和，并存储该插件通过 `PluginMetadata` 声明的版本、作者和描述。如果文件后来被修改，您将在它再次运行之前收到警告。要信任插件： ``` pyspector plugin install ./PySpector/plugins/aipocgen.py --trust ``` ### 在扫描期间运行插件 在 `pyspector scan` 期间使用一个或多个 `--plugin` 标志，如果插件需要自定义设置，请提供 JSON 配置文件： ``` pyspector scan vulnerableapp.py --plugin aipocgen --plugin-config ./PySpector/pluginconfig/aipocgen.json ``` 配置文件必须是一个 JSON 对象，其键与插件名称匹配，例如： ``` { "aipocgen": { "api_key": "YOUR-GROQ-KEY", "model": "llama-3.3-70b", "severity_filter": ["HIGH", "CRITICAL"], "max_pocs": 5, "output_dir": "pocs", "dry_run": false } } ``` 每个插件仅接收其自己的配置块。结果将打印在 CLI 中，并且在 `output_files` 列表中返回的任何路径都会显示在“Generated files”下。 ### 编写插件 在 `~/.pyspector/plugins/.py` 中创建一个新的 Python 文件，并继承 `PySpectorPlugin` 子类： ``` from pathlib import Path from typing import Any, Dict, List from pyspector.plugin_system import PySpectorPlugin, PluginMetadata class MyPlugin(PySpectorPlugin): @property def metadata(self) -> PluginMetadata: return PluginMetadata( name="my_plugin", version="0.1.0", author="Your Name", description="Summarises HIGH severity findings", category="reporting", ) def validate_config(self, config: Dict[str, Any]) -> tuple[bool, str]: if "output_file" not in config: return False, "output_file is required" return True, "" def initialize(self, config: Dict[str, Any]) -> bool: self.output = Path(config["output_file"]).resolve() return True def process_findings( self, findings: List[Dict[str, Any]], scan_path: Path, **kwargs, ) -> Dict[str, Any]: highs = [f for f in findings if f.get("severity") == "HIGH"] self.output.write_text(f"{len(highs)} HIGH findings\n", encoding="utf-8") return { "success": True, "message": f"Summarised {len(highs)} HIGH findings", "output_files": [str(self.output)], } ``` 您的插件必须实现以下内容： - **`metadata`** – 返回一个描述插件的 `PluginMetadata` 实例。 - **`validate_config(config)`** *(可选但推荐)* – 当缺少所需设置时，通过返回 `(False, "reason")` 优雅地中止。 - **`initialize(config)`** – 准备状态或依赖项；返回 `False` 以跳过执行。 - **`process_findings(findings, scan_path, **kwargs)`** – 以字典形式接收每个发现，并返回包含以下内容的结果对象： - `success`: 布尔状态 - `message`: CLI 的简短摘要 - `data`: 可选的可序列化负载 - `output_files`: 可选的生成文件路径列表 - **`cleanup()`** *(可选)* – 释放资源；即使发生异常也会调用。 提示：插件是普通的 Python 模块，因此您可以在开发时运行 `python my_plugin.py` 进行快速检查，然后再通过 CLI 信任它们。 ### 配置提示和最佳实践 - 将 API 密钥或长期存在的机密存储在环境变量中，并在 `initialize` 期间读取它们。当凭据缺失时提供有用的错误消息。 - 将副作用保留在扫描目录内。当 PySpector 扫描单个文件时，`scan_path` 就是该文件，因此参考插件在写入输出之前会切换到 `scan_path.parent`。 - 使用 `validate_config` 尽早验证配置；PySpector 会在 CLI 中显示错误消息，而无需执行插件。 - 返回有意义的 `message` 值并填充 `output_files`，以便自动化可以提取生成的工件。 - 记录可选开关，例如 `dry_run`（参见捆绑的 `aipocgen` 插件示例），以支持离线测试。 ### 安全模型 插件管理器强制执行多项保障措施： - **基于 AST 的静态检查** 阻止危险结构（eval`, `exec`, `subprocess.*` 等），并在使用敏感但可接受的调用（例如 `open`）时打印警告。 - **信任工作流** – 您必须显式信任插件才能运行它；CLI 会通知您验证期间产生的任何警告。 - **校验和验证** – 每个受信任的插件都有一个存储的 SHA256 哈希；在执行之前会标记更改。 - **参数隔离** – 运行器将 `sys.argv` 重置为最小值，因此基于 Click 的插件不会意外消耗父 CLI 参数。 - **结构化错误处理** – 异常被捕获、跟踪和报告，而不会中止主扫描，并且 `cleanup()` 仍然会运行。 这些措施共同让您自信地扩展 PySpector，同时为第三方自动化维护安全的供应链。 ## 分流与基线管理 PySpector 包含一个交互式分流模式，以帮助管理和建立发现基线。这允许您审查问题并将其标记为“忽略”，以便它们不会出现在未来的扫描中。 * **生成 JSON 报告:** ``` pyspector scan /path/to/your/project -o report.json -f json ``` * **启动分流 TUI:** ``` pyspector triage report.json ``` 在 TUI 内部，您可以使用箭头键导航，按 i 切换问题的“忽略”状态，按 s 将您的更改保存到 .pyspector_baseline.json 文件。该基线文件将在后续扫描中自动加载。 ## 自动化与集成 PySpector 包含 Shell 辅助脚本，可将安全扫描直接集成到您的开发和运营工作流程中。 ### Git Pre-Commit 钩子 为了确保不会将新的高严重性问题引入代码库，您可以设置一个 Git pre-commit hook。此 hook 将在每次提交之前自动扫描暂存的 Python 文件，如果发现任何 HIGH 或 CRITICAL 问题，则阻止提交。 **要设置 hook，请从 Git 仓库的根目录运行以下脚本：** ``` ./scripts/setup_hooks.sh ``` 此脚本创建一个可执行的 .git/hooks/pre-commit 文件来执行检查。您可以通过在 git commit 命令中使用 --no-verify 标志来绕过特定提交的 hook。 ## 使用 Cron 进行定时扫描 为了进行持续监控，您可以使用 cron 作业安排项目的定期扫描。PySpector 提供了一个交互式脚本来帮助您生成正确的 crontab 条目。 **要生成您的 cron 作业命令，请运行：** ``` ./scripts/setup_cron.sh ``` 该脚本将提示您输入项目路径、所需的扫描频率（每日、每周、每月）以及存储 JSON 报告的位置。然后它将输出要添加到 crontab 的命令，从而自动化您的安全扫描和报告过程。

标签：CI/CD安全, DevSecOps, DNS 反向解析, Llama, Python, Rust, SAST, XSS注入, 上游代理, 代码安全, 可视化界面, 图分析, 安全专业人员, 安全测试, 开发安全, 攻击性安全, 无后门, 漏洞枚举, 盲注攻击, 结构化查询, 网络流量审计, 自动化payload嵌入, 自动化安全, 调试插件, 逆向工具, 错误基检测, 静态代码分析