Waariss/whitebox-secure-scan

# whitebox-secure-scan [](https://pypi.org/project/whitebox-secure-scan/) [](https://pypi.org/project/whitebox-secure-scan/) [](https://github.com/Waariss/whitebox-secure-scan/actions/workflows/test.yml) [](https://github.com/Waariss/whitebox-secure-scan/blob/main/LICENSE)  `whitebox-secure-scan` 是一款专为渗透测试人员设计的本地、离线白盒安全代码分诊工具。它能帮助您将庞大的代码库过滤为可解释的审查线索、精确的文件与代码行证据、分组的根本原因，以及审查者指导。 它是一个分诊辅助工具——不是最终的渗透测试报告，也不是自动漏洞确认器。每一个候选项都必须由授权的安全工程师独立验证。 分析过程完全在本地进行：源码进入有界的审查 pipeline，证据被分组以供人类审查者查阅，且不会有任何源码被发送到外部服务。  ## 快速开始 无需全局安装即可运行最新发布的 package： ``` uvx whitebox-secure-scan@latest version uvx whitebox-secure-scan@latest review /path/to/repository \ --output ./whitebox-results ``` 请将输出目录保留在目标 repository 之外。扫描器会在本地读取目标源码，不会执行它，也不会对其进行修改。 ## 安装 ### 使用 `uvx` 运行 — 推荐 `uvx` 会在隔离的环境中运行已发布的 package，不需要进行永久性安装。 ``` uvx whitebox-secure-scan@latest version uvx whitebox-secure-scan@latest --help uvx whitebox-secure-scan@latest review /path/to/repository \ --output ./whitebox-results uvx whitebox-secure-scan@1.0.1 version ``` ### 使用 `pip` 安装 ``` python3 -m venv .venv source .venv/bin/activate python3 -m pip install whitebox-secure-scan whitebox-secure-scan version whitebox-secure-scan review /path/to/repository \ --output ./whitebox-results ``` 使用以下命令升级现有安装： ``` python -m pip install --upgrade whitebox-secure-scan ``` 该 package 支持 Python 3.11 及以上版本。`uvx` 和 `pip` 使用已发布的 PyPI package；正常使用无需 checkout repository。 ### 可选解析依赖 核心扫描器无需可选 parser 即可工作。当您需要额外的 parser 支持时，请安装本地解析扩展： ``` python -m pip install "whitebox-secure-scan[parsing]" ``` ## 产出内容 常规的 `review` 命令会生成一套以审查者为优先的简洁结果集： | 文件 | 用途 | | --- | --- | | `SUMMARY.md` | 快速概览根本原因、位置和范围 | | `report.md` | 详细的证据和验证指导 | | `findings.json` | 用于自动化的标准化发现实例 | | `root-causes.json` | 将相关实例分组以进行高效审查 | | `review-points.json` | 需要上下文的低置信度项目 | 高级兼容性命令还可以生成清单、路由、元数据、SARIF 以及有界的内部 AI 交接 package。 无需执行，即可导入来自受支持工具的本地结果文件： ``` whitebox-secure-scan review /path/to/repository \ --import-result semgrep=/path/to/semgrep.json \ --output ./whitebox-results ``` 受支持的导入格式包括 Semgrep、Gitleaks、Bandit、gosec 和 FindSecBugs。导入的结果会保留外部工具和规则 ID，并且依然作为审查候选项。  ## 功能与限制 | 它能做 | 它不能做 | | --- | --- | | 在本地扫描 Python、JavaScript/TypeScript、Java 和 Go 源码 | 执行应用代码、测试、构建、迁移或 package 脚本 | | 识别安全审查线索和审查点 | 断言某个发现是可利用的或已确认的 | | 保留文件、代码行、source、sink 和证明缺失的上下文 | 取代人工代码审查或渗透测试人员 | | 将相关证据分组为根本原因 | 上传源码、发现、遥测或分析数据 | | 默认离线工作 | 在扫描期间调用外部 AI 服务或下载规则 | ## 安全边界 扫描器专为受控的白盒审查而设计： - 默认启用离线操作。 - 目标 repository 被视为只读。 - Repository 代码和命令永远不会被执行。 - 除非明确启用并已在本地安装，否则外部 scanner 将被禁用。 - 输出路径会经过安全检查，且应位于目标 repository 之外。 - 不跟随脱离目标的符号链接。 - 默认会对敏感信息进行脱敏处理，且代码片段是有界的。 - 不会将任何源代码或扫描结果发送到云服务。 请仅扫描您已获授权审查的 repository。 ## 支持的语言 - Python - JavaScript 和 TypeScript，包括常见的 Node.js 和前端模式 - Java，包括常见的 Spring 相关模式 - Go 只有在 repository 中可观察到框架证据时，才会进行报告。静态分析有意设计得较为保守：不完整的流程会保留为审查线索或审查点。 安装可选的解析扩展后，parser 层可以使用本地的 Tree-sitter 语法来解析 JavaScript、TypeScript、Java 和 Go。若未安装，扫描器将使用结构化的词法回退方案。代码图局限于可观察到的声明、路由和调用；它并不是完整的全程序过程间污点分析。 ## 典型工作流 ``` Scan locally ↓ Read SUMMARY.md and grouped root causes ↓ Inspect the referenced file and line ↓ Verify the complete flow manually ↓ Write the approved security finding, if confirmed ``` ## 开发安装 仅在为项目贡献代码或运行其合成测试套件时使用本部分： ``` git clone https://github.com/Waariss/whitebox-secure-scan.git cd whitebox-secure-scan python3 -m venv .venv source .venv/bin/activate python -m pip install -e ".[dev]" pytest -q ruff check . ruff format --check . mypy src ``` 测试使用合成 fixtures。请勿将测试套件或示例指向您不拥有或无权审查的 repository。请参阅 [CONTRIBUTING.md](https://github.com/Waariss/whitebox-secure-scan/blob/main/CONTRIBUTING.md) 和[技术参考](https://github.com/Waariss/whitebox-secure-scan/blob/main/docs/REFERENCE.md)。 ## 文档与支持 - [技术参考](https://github.com/Waariss/whitebox-secure-scan/blob/main/docs/REFERENCE.md) - [安全边界](https://github.com/Waariss/whitebox-secure-scan/blob/main/SECURITY.md) - [贡献指南](https://github.com/Waariss/whitebox-secure-scan/blob/main/CONTRIBUTING.md) - [报告安全问题](https://github.com/Waariss/whitebox-secure-scan/blob/main/SECURITY.md) - [GitHub issues](https://github.com/Waariss/whitebox-secure-scan/issues) ## 许可证 Apache License 2.0。详见 [LICENSE](https://github.com/Waariss/whitebox-secure-scan/blob/main/LICENSE)。

标签：Python, 云安全监控, 无后门, 白盒测试, 逆向工具, 静态分析