SemClone/src2purl

# SRC2PURL - 源代码到 Package URL 的发现工具 [](https://opensource.org/licenses/AGPL-3.0) [](https://www.python.org/downloads/) [](https://pypi.org/project/src2purl/) 一款 Python 工具，通过结合使用 manifest 解析、代码指纹识别、仓库搜索和 Software Heritage 归档集成的混合发现策略，从源代码目录中识别包坐标（名称、版本、许可证、PURL）。 ## 特性 - **两阶段发现策略**：基于 hash 的识别，辅以 manifest 解析增强 - **多生态系统支持**：PyPI、NPM、Maven、Go、Ruby Gems、PHP、.NET 等 - **高性能**：典型项目仅需 5-15 秒（使用 SWH 则需 90 秒以上） - **SEMCL.ONE 集成**：与 upmex、osslili 及其他生态系统工具无缝协作 ## 安装 ``` pip install src2purl ``` 用于开发环境： ``` git clone https://github.com/SemClone/src2purl.git cd src2purl pip install -e . ``` ## 快速入门 ``` # 从源代码识别 package src2purl /path/to/source/code # 使用 Software Heritage archive（全面但较慢） src2purl /path/to/source --use-swh ``` ## 用法 ### CLI 用法 ``` # 快速发现（默认） - 使用 manifest 解析 + SCANOSS + GitHub（5-15 秒） src2purl /path/to/source/code # 全面发现 - 包含 Software Heritage archive（90+ 秒） src2purl /path/to/source --use-swh # 仅高置信度匹配 src2purl /path/to/source --confidence-threshold 0.85 # 用于集成的 JSON 输出格式 src2purl /path/to/source --output-format json # 检测 monorepo 中的子组件 src2purl /path/to/source --detect-subcomponents ``` ### Python API ``` from src2purl import identify_package # 基本识别 result = identify_package("/path/to/source") print(f"Package: {result.name}@{result.version}") print(f"PURL: {result.purl}") # 带选项 result = identify_package( path="/path/to/source", use_swh=True, confidence_threshold=0.85 ) ``` ### 发现策略示例 ``` # 默认：2-Phase 混合方法（5-15 秒） # Phase 1：基于 Hash 的发现 + Phase 2：UPMEX manifest 解析 # 适用于：大多数用例，平衡了速度和准确性 src2purl /path/to/project # 全面：包含 Software Heritage archive（90+ 秒） # Phase 1 包含深度来源发现 + Phase 2：UPMEX 增强 # 适用于：安全审计、研究、历史分析 export SWH_API_TOKEN=your_token # Optional but recommended src2purl /path/to/project --use-swh # 高置信度：仅报告置信度高的匹配 # 将结果筛选为两个阶段中置信度最高的发现 src2purl /path/to/project --confidence-threshold 0.85 ``` ### API 认证 **无需 API 密钥！** 本工具可直接使用免费的公共 API。API 密钥仅用于提升速率限制和启用附加功能。 #### 推荐的 API 密钥（可选） **1. GitHub API** - **最有价值**（免费，2 分钟即可完成设置） ``` export GITHUB_TOKEN=your_github_personal_access_token ``` - **获取令牌**：https://github.com/settings/tokens（无需特殊权限） - **优势**： - **速率限制**：10 → 5000 次请求/小时 - **更佳搜索**：更准确的仓库识别 - **完全免费**：无任何成本 - **影响**：显著提升仓库发现能力 **2. SCANOSS API** - **锦上添花**（免费，可选） ``` export SCANOSS_API_KEY=your_scanoss_key ``` - **获取令牌**：在 https://www.scanoss.com 注册 - **优势**： - **完全免费**：提供免费套餐 - **提升速率限制**：高级 API 端点 - **附加功能**：可能获取额外的元数据 - **影响**：轻微提升（即使没有密钥，SCANOSS 也表现出色） **3. Software Heritage API** - **适用于重度使用**（免费，仅在启用 `--use-swh` 时需要） ``` export SWH_API_TOKEN=your_swh_token ``` - **获取令牌**：在 https://archive.softwareheritage.org/api/ 注册 - **优势**： - **绕过速率限制**：无需等待 60 秒 - **更快的全面扫描**：在使用 `--use-swh` 时 - **影响**：对 `--use-swh` 标志至关重要，默认的快速模式不需要 #### 性能对比 | 配置 | 典型耗时 | API 调用 | 适用场景 | |---------------|-------------|-----------|----------| | **无 API 密钥** | 5-15 秒 | 最少 | 大多数用户 | | **+ GitHub token** | 5-15 秒 | 增强 | 推荐配置 | | **+ 所有 token** | 5-15 秒 | 高级 | 生产环境使用 | | **+ SWH 模式** | 90+ 秒 | 繁重 | 安全审计 | **建议**：从**仅使用 GitHub token** 开始——它不仅免费、设置快，而且能提供最大的改善。 ### SWHID 验证 ``` # 为目录生成并验证 SWHID src2purl-validate /path/to/directory # 与预期的 SWHID 进行比较 src2purl-validate /path/to/directory --expected-swhid swh:1:dir:abc123... # 使用 fallback 实现 src2purl-validate /path/to/directory --use-fallback --verbose ``` ### 命令行选项 #### **核心选项** - `path`：要分析的目录路径（必填） - `--confidence-threshold`：报告匹配结果的最低置信度（默认值：0.3） - `--output-format`：输出格式：'json' 或 'table'（默认值：table） - `--verbose`：用于调试的详细输出 #### **发现控制** - `--use-swh`：包含 Software Heritage 归档检查（可选，会增加 90 秒以上的耗时） - `--no-license-detection`：跳过从本地源代码自动检测许可证（速度更快） - `--detect-subcomponents`：检测并识别 monorepo 中的子组件 - `--max-depth`：扫描的最大目录深度（默认值：2） #### **性能与缓存** - `--no-cache`：禁用 API 响应缓存 - `--clear-cache`：清除所有已缓存的 API 响应并退出 #### **认证** - `--api-token`：Software Heritage API 令牌（仅在使用 --use-swh 时有效） - 环境变量：`GITHUB_TOKEN`、`SCANOSS_API_KEY`、`SWH_API_TOKEN` #### **发现方法详解** ``` # 默认：2-Phase 发现（基于 Hash + UPMEX manifest 解析） src2purl /path/to/project # Phase 1：SWHID 生成 → GitHub/SCANOSS 搜索 # Phase 2：UPMEX manifest 提取 → 交叉验证与增强 # 添加 Software Heritage 以实现全面的来源发现 src2purl /path/to/project --use-swh # Phase 1：SWHID 生成 → Software Heritage archive → Fallback 搜索 # Phase 2：UPMEX manifest 提取 → 交叉验证与增强 # 性能优化选项 src2purl /path/to/project --no-license-detection # Skip license enhancement src2purl /path/to/project --use-swh --verbose # Full discovery with details ``` ## 与 SEMCL.ONE 集成 SRC2PURL 是 SEMCL.ONE 生态系统的核心组件： - 使用 **upmex** 进行 manifest 解析和包元数据提取 - 集成 **osslili** 以增强许可证检测 - 为 **purl2src** 提供 PURL 以下载源代码包 - 支持 **purl2notices** 生成归属说明文档 - 支持使用已识别的包启用 **ospac** 策略评估 ## 配置 通过环境变量进行配置： ``` # API token（可选，但推荐） export GITHUB_TOKEN=your_github_token export SCANOSS_API_KEY=your_scanoss_key export SWH_API_TOKEN=your_swh_token # 性能设置 export SRC2PURL_CACHE_DIR=~/.cache/src2purl export SRC2PURL_MAX_DEPTH=2 ``` ## 文档 - [用户指南](docs/user-guide.md) - 全面的用法示例 - [API 参考](docs/api.md) - Python API 文档 - [发现方法](docs/discovery-methods.md) - 识别策略的详细说明 - [示例](docs/examples.md) - 常见用例与工作流 ## 贡献 我们欢迎各种贡献！有关以下内容的详细信息，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)： - 行为准则 - 开发环境设置 - 提交 Pull Request - 报告问题 ## 支持 获取支持与提问： - [GitHub Issues](https://github.com/SemClone/src2purl/issues) - Bug 报告和功能请求 - [文档](https://github.com/SemClone/src2purl) - 完整的项目文档 - [SEMCL.ONE 社区](https://semcl.one) - 生态系统支持与讨论 ## 许可证 GNU Affero General Public License v3.0 (AGPL-3.0) - 详见 [LICENSE](LICENSE) 文件。 ## 作者 贡献者列表请见 [AUTHORS.md](AUTHORS.md)。 *全面 OSS 合规与代码分析 [SEMCL.ONE](https://semcl.one) 生态系统的一部分。*

标签：API安全, API集成, Cilium, Go模块, JSON输出, Maven, NPM, OpenVAS, Package URL, PHP, PURL, PyPI, Python, Ruby Gems, SCANOSS, Software Heritage, 仓库搜索, 代码指纹, 代码溯源, 依赖识别, 包管理, 可观测性, 哈希识别, 开源许可证, 文档结构分析, 无后门, 混合发现策略, 清单解析, 源代码分析, 漏洞验证, 组件发现, 软件资产管理, 逆向工具