bact/pitloom

# Pitloom [](https://pypi.org/project/pitloom/) [](https://doi.org/10.5281/zenodo.19246283)  自动化的透明度，从根本上编织而成。 **开发中** -- **不可用于生产环境** ## 概述 **Pitloom** 自动为 Python 项目生成符合 SPDX 3 标准的 SBOM， 记录软件系统的构成和来源。 通过直接从 Python 包和 AI 模型（GGUF, ONNX, PyTorch, Safetensors）读取元数据，它创建标准化的 SPDX 3 JSON 工件。 它还提供原生的 Hatchling 集成，允许用户挂钩到构建过程以自动生成 SBOM。 ## 功能特性 - **SPDX 3 支持**: 以 SPDX 3 JSON-LD 格式生成 SBOM - **Hatchling 集成**: 使用 Hatchling 从 Python 项目中提取元数据 - **依赖追踪**: 自动将项目依赖包含在 SBOM 中 - **AI/ML 模型元数据**: 从模型文件（GGUF, ONNX, PyTorch, Safetensors）提取元数据 用于 SPDX AI 配置文件 - **元数据来源**： 追踪每个元数据字段的来源，以实现透明度和可审计性 - **符合标准**： 遵循 SPDX 3 规范和现代 Python 打包标准 ## 安装说明 使用 pip 安装 Pitloom： ``` pip install pitloom ``` 用于开发（lint + test），使用 pip >= 25： ``` pip install --group dev -e . ``` 或者使用 uv： ``` uv sync --group dev ``` ### 可选模型格式支持 安装扩展以启用从模型文件提取元数据的功能： ``` pip install -e ".[fasttext]" # fastText models pip install -e ".[gguf]" # GGUF models pip install -e ".[onnx]" # ONNX models pip install -e ".[safetensors]" # Safetensors models pip install -e ".[aimodel]" # all of the above ``` ## 使用方法 ### 命令行 为当前目录中的 Python 项目生成 SBOM： ``` loom . ``` 指定输出文件： ``` loom /path/to/project -o sbom.spdx3.json ``` 显示帮助： ``` loom -h ``` ### Python API SBOM 生成器可以通过编程方式使用： ``` from pathlib import Path from pitloom.core.creation import CreationMetadata from pitloom.assemble import generate_sbom # 为项目生成 SBOM generate_sbom( project_dir=Path("/path/to/project"), output_path=Path("sbom.spdx3.json"), creation_info=CreationMetadata( creator_name="Your Name", creator_email="your@example.com", ), pretty=False, ) ``` ### Hatchling 构建钩子 Pitloom 可以通过充当 Hatchling 构建钩子，自动将 SBOM 嵌入到您构建的每个 wheel 中 SBOM 位于 wheel 内部的 `.dist-info/sboms/sbom.spdx3.json`，遵循 [PEP 770](https://peps.python.org/pep-0770/)。 #### 将 Pitloom 添加到您的构建要求中 将 `loom` 添加到项目的构建要求中： ``` [build-system] requires = ["hatchling", "pitloom"] build-backend = "hatchling.build" ``` #### 注册钩子 通过向您的 `pyproject.toml` 添加部分来启用钩子： ``` [tool.hatch.build.hooks.pitloom] # 所有字段均为可选。显示的是默认值。 enabled = true sbom-basename = "package-name" # name part only (no extension); default "sbom" creator-name = "SBOM Creator" # defaults to "Pitloom" creator-email = "mail@example.com" # defaults to None creation-datetime = "2026-04-01T00:00:00Z" # Date and time in ISO 8601 UTC format fragments = [] # extra SPDX fragment paths (relative to project root) ``` 完整的 SBOM 文件名为 `{sbom-basename}.spdx3.json` — 例如，默认设置 生成 `sbom.spdx3.json`。设置 `sbom-basename = "mypackage-1.0"` 将 生成 `mypackage-1.0.spdx3.json`。 就是这样。运行 `hatch build` 或 `python -m build` 现在将自动生成并 嵌入 SBOM — 无需额外命令。 #### 合并 AI/ML 片段 对于 AI 驱动的软件，您可以使用 `pitloom.bom` 在训练期间追踪模型和数据集的来源， 然后将这些片段包含在 wheel SBOM 中： ``` [tool.hatch.build.hooks.pitloom] fragments = [ "fragments/train_run.spdx3.json", "fragments/eval_run.spdx3.json", ] ``` 在 `[tool.hatch.build.hooks.pitloom]` 下列出的片段将与 已在 `[tool.pitloom]` 下列出的任何片段合并在一起。 #### 生成的 wheel 结构 ``` mypackage-1.0-py3-none-any.whl └── mypackage-1.0.dist-info/ └── sboms/ └── sbom.spdx3.json ← PEP 770 ``` ### Python 追踪装饰器 开发人员可以轻松地注解脚本或 Jupyter notebook，以生成外部 SBOM 片段， Pitloom 将在构建过程中合并这些片段： ``` from pitloom import bom # 作为函数装饰器使用... @bom.track(output_file="fragments/sentiment_model.json") def train_model(): bom.set_model("sentiment-clf") bom.add_dataset("imdb-reviews", dataset_type="text") # ... training logic ... # ...或作为上下文管理器使用 with bom.track(output_file="fragments/sentiment_model.json"): bom.set_model("sentiment-clf") bom.add_dataset("imdb-reviews", dataset_type="text") ``` ## 示例 为 sentimentdemo 项目生成 SBOM： ``` # 克隆 sentimentdemo 仓库 git clone https://github.com/bact/sentimentdemo.git # 生成 SBOM loom sentimentdemo ``` 生成的 SBOM 将包括： - 项目元数据（名称、版本、描述） - 带有版本约束的项目依赖 - 组件之间的 SPDX 关系 - 创建者和创建时间戳信息 - **元数据来源**追踪以实现透明度 ## 元数据来源 Pitloom 使用 SPDX 3 的 `comment` 属性在 SBOM 中追踪每个元数据字段的来源。这有助于回答如下问题： ### 来源示例 对于从各种来源提取元数据的包： ``` { "type": "software_Package", "name": "mypackage", "software_packageVersion": "1.2.3", "comment": "Metadata provenance: name: Source: pyproject.toml | Field: project.name; version: Source: src/mypackage/__about__.py | Method: dynamic_extraction; dependencies: Source: pyproject.toml | Field: project.dependencies" } ``` 来源信息显示： - **包名称**：从 `pyproject.toml` → `project.name` 提取 - **版本**：从 `src/mypackage/__about__.py` 动态提取 - **依赖**：在 `pyproject.toml` → `project.dependencies` 中列出 这种透明度对于以下方面至关重要： - **可审计性**：了解 SBOM 数据的来源 - **信任**：验证元数据的准确性 - **机器消费**：自动化工具可以解析来源 - **人工审查**：手动检查数据源 ## 项目结构 ``` pitloom/ ├── docs/ │ ├── design/ │ │ ├── architecture-overview.md │ │ ├── format-neutral-representation.md │ │ └── metadata-provenance.md │ └── implementation/ │ ├── demo.md │ ├── demo-provenance.md │ └── summary.md ├── src/ │ └── pitloom/ │ ├── assemble/ │ │ ├── spdx3/ # SPDX 3 specific (future: spdx23, cyclonedx) │ │ │ ├── document.py # SPDX 3 document assembly — build(DocumentModel) │ │ │ ├── deps.py # Dependency element assembly │ │ │ ├── ai.py # AI model element assembly │ │ │ └── fragments.py # Fragment merging │ │ └── __init__.py # generate_sbom() orchestrator │ ├── core/ │ │ ├── ai_metadata.py # Format-neutral AI model metadata │ │ ├── config.py # [tool.pitloom] settings (PitloomConfig) │ │ ├── creation.py # SBOM creation metadata (CreationMetadata) │ │ ├── document.py # Format-neutral document model (DocumentModel) │ │ ├── models.py # SPDX ID generation utilities │ │ └── project.py # Python project metadata (ProjectMetadata) │ ├── export/ │ │ └── spdx3_json.py # SPDX 3 JSON-LD serialiser │ ├── extract/ │ │ ├── ai_model.py # AI model file extractor (GGUF, ONNX, Safetensors) │ │ └── pyproject.py # pyproject.toml extractor │ ├── plugins/ │ │ ├── __init__.py │ │ └── hatch.py # Hatchling build hook (PEP 770) │ ├── __about__.py │ ├── __init__.py │ ├── __main__.py # CLI entry point │ └── bom.py # ML tracking SDK ├── tests/ │ ├── fixtures/ │ │ └── sampleproject/ # minimal wheel-build fixture │ ├── test_ai_model_extractor.py │ ├── test_bom.py │ ├── test_generator.py │ ├── test_hatch_hook.py │ ├── test_metadata.py │ ├── test_models.py │ ├── test_provenance.py │ └── test_spdx3_compliance.py ├── LICENSE ├── README.md └── pyproject.toml ``` ## 开发 ### 运行测试 ``` pytest ``` ### 运行 linter ``` ruff check src/ tests/ ``` ### 构建包 ``` pip install build python -m build ``` ## 路线图 - [x] 基础 SPDX 3.0 SBOM 生成 - [x] Hatchling 元数据提取 - [x] 依赖追踪 - [ ] 支持 setuptools - [x] 格式中立的内部表示（`DocumentModel` — 参见 [设计文档](docs/design/format-neutral-representation.md)) - [ ] 构建日志提取（用于编译型依赖） - [x] AI/ML 包配置文件 - [x] PEP 770 支持（通过 `build_data["sbom_files"]` 实现 .dist-info/sboms） - [ ] PEP 740 证明支持 - [ ] Rust 后端性能优化 ## 参考 - [SPDX 3.0 规范](https://spdx.dev/wp-content/uploads/sites/31/2024/12/SPDX-3.0.1-1.pdf) - [PEP 770 – Python 包中的 SBOM 元数据](https://peps.python.org/pep-0770/) - [设计文档](docs/design/architecture-overview.md) ## 许可证 - 源代码：Apache License 2.0。 - 文档：Creative Commons Attribution 4.0 International。 - 测试固件 AI 模型： 单个文件根据 Apache-2.0, CC0-1.0 或 MIT 授权。 详见 [tests/fixtures/README.md](tests/fixtures/README.md)。 请注意，这些仅在源代码仓库中可用， 不包含在分发包中。 ## 名称 一个[坑机](https://en.wikipedia.org/wiki/Loom#Treadle_loom) 是一种传统的手工织机，建在地面的坑中， 用于容纳其内部机构和织布者的双腿。 这种“接地”的设计在织造过程中提供了稳定性和精度。 我们用织机作为工具功能的隐喻： 它将散落的元数据线编织成紧密结合的 SBOM， 为软件构建创建了一张透明、结构化的“织物”。

标签：AI 模型安全, DevSecOps, fastText, GGUF, Hatchling 构建钩子, JSON-LD, ONNX, Python 包管理, Python 安全工具, PyTorch, Safetensors, SBOM 生成, SPDX 3, 上游代理, 元数据提取, 合规性自动化, 工件溯源, 文档安全, 机器学习运维, 跌倒检测, 软件物料清单, 进程保护, 逆向工具, 透明度日志