Sbom generate

Generate an SBOM with Pitloom

Pitloom is a command-line tool that generates SPDX 3 JSON SBOMs for Python projects, sdist archives, wheels, AI/ML model files, and Python environments. This skill drives Pitloom's existing CLI (loom / pitloom).

Triggers automatically on natural-language requests (see the trigger phrasings above), or invoke it explicitly with /sbom-generate [target] (/pitloom:sbom-generate [target] when installed via the Claude Code plugin). target is optional -- a project directory, an sdist/wheel path, a local model file, or a Hugging Face model ID; omit it to default to the current directory.

See references/examples.md for copy-paste recipes.

Run without installing anything persistent

Prefer an ephemeral run so the user's environment is not polluted:

uvx pitloom generate <target> -o sbom.spdx3.json       # Smart auto-detection entrypoint

or

pipx run pitloom generate <target> -o sbom.spdx3.json  # pipx's ephemeral runner

Fall back to a normal install only if neither uv nor pipx is available:

pip install pitloom
loom generate <target> -o sbom.spdx3.json

-o/--output is required for generate -- unlike project/wheel/ model/env below, which each know their target type and so have an obvious default filename, generate dispatches across several target types with no single natural default.

loom and pitloom are two names for the same console-script entry point.

Smart Entrypoint: loom generate

Use loom generate for automatic target detection:

loom generate . -o sbom.spdx3.json                              # project directory -> Source SBOM
loom generate mypackage-1.0.0.tar.gz -o sbom.spdx3.json         # sdist archive     -> Source SBOM
loom generate dist/pkg-1.0-py3-none-any.whl -o sbom.spdx3.json  # wheel package     -> Analyzed SBOM
loom generate models/model.gguf -o sbom.spdx3.json              # local model file  -> AI Model SBOM
loom generate mistralai/Mistral-7B-v0.1 -o sbom.spdx3.json      # Hugging Face URL  -> AI Model SBOM
loom generate env -o sbom.spdx3.json                            # installed venv    -> Deployed SBOM

Explicit Target Subcommands

For deterministic execution in CI/CD and sandboxed runners:

# 1. Project Directory or Sdist Archive (Source SBOM)
loom project .
loom project /path/to/project -o sbom.spdx3.json
loom project dist/mypackage-1.0.0.tar.gz

# 2. Built Wheel Package (Analyzed SBOM)
loom wheel dist/mypackage-1.0.0-py3-none-any.whl -o wheel.spdx3.json

# 3. AI Model Asset (AIBOM)
loom model models/model.safetensors
loom model models/model.gguf --offline      # --offline forbids network calls
loom model mistralai/Mistral-7B-v0.1        # Hugging Face model ID

# 4. Deployed Environment (Installed venv)
loom env -o env.spdx3.json

# 5. Fragment Merging
loom merge .spdx3-fragments/ -o combined.spdx3.json

Embed an SBOM into a wheel (PEP 770)

For a request to embed an SBOM into a built wheel rather than write it as a standalone file -- PEP 770's .dist-info/sboms/ convention -- use embed-wheel instead of wheel:

loom embed-wheel dist/mypackage-1.0.0-py3-none-any.whl
loom embed-wheel dist/*.whl --project-dir .   # multiple wheels, Build SBOM

Or embed an already-generated SBOM file directly:

loom embed-wheel dist/*.whl --sbom sbom.spdx3.json

Or embed directly on loom wheel for a single wheel's own Analyzed SBOM (no project-directory scanning):

loom wheel dist/mypackage-1.0.0-py3-none-any.whl --embed

embed-wheel mutates the .whl archive in place (RECORD is updated to match); it works on any wheel regardless of build backend, since a wheel is just a ZIP archive -- unlike the Hatchling-specific build hook. See docs/cli.md for the full flag reference, including --output (rejected when more than one wheel matches, since a single standalone copy would be ambiguous) and --sbom-basename.

Useful flags

• -o FILE / --output FILE -- explicit output path.
• --pretty -- indent the JSON for human reading (default: compact).
• --offline -- enforce offline execution for loom model / loom generate.
• -v / --verbose -- print effective options and where each came from.
• --creator-name NAME, --creator-email EMAIL -- name who created the SBOM.
• --enrich / --no-enrich -- opt in to (or force off) Pitloom's own deterministic, local, frontmatter-only enrichment pass as part of the same generate call. See "Combine with enrichment" below for when to use this versus the fuller sbom-enrich skill.
• --extract-file-header / --no-extract-file-header -- per-file SPDX header tag scanning (copyright, contributor, license, file type). On by default; cheap, no need to pass it explicitly.
• --content-type / --no-content-type -- per-file content-type detection via magika/a filename-extension guess. Off by default and opt-in only -- only add this flag when the user's request specifically implies wanting per-file content-type/MIME data, not reflexively on every SBOM request, since it costs real time per file (~5ms/file with magika) across potentially thousands of files.
• --content-type-method {auto,magika,extension} -- which detector --content-type uses; defaults to auto (try magika, fall back to the extension guess). Only needed to force a specific detector.

Combine with enrichment

Some requests ask for generation and enrichment in one breath -- "generate SBOM and enrich it", "give me a complete SBOM", "create an SBOM and fill in information as much as possible", "help me get a full SBOM". Two different depths answer these, and the request's own language is the signal for which one:

• Light ask ("...and enrich it", "with enrichment") -- add --enrich to the generate command:

  loom generate <target> --enrich -o sbom.spdx3.json
  

  This runs Pitloom's own deterministic, local, frontmatter-only pass (enrich/readme.py) as part of the same command -- no prose reading, no network, no separate skill invocation.

• Strong ask ("complete", "as much detail/information as possible", "full SBOM") -- generate with --enrich too (it's free), then invoke the sbom-enrich skill on the result for the agentic pass: reading README/model-card prose and inferring license/dataset relationships that neither frontmatter nor static extraction can see. This costs more (agent reasoning, and possibly network for Hugging Face/PyPI lookups some of sbom-enrich's steps make) -- reasonable for an explicit "as much as possible", not for a bare "generate an SBOM".

Plain "generate an SBOM" with no enrichment language in the request skips both -- just run the base generate command.

Verify the result

A quick @graph-presence sanity check is enough for most runs (see references/examples.md), but for a schema/shape-level conformance check, use the sbom-validate skill on the output.

Known limitations -- say so, don't paper over it

Pitloom's dependency/supplier/license extraction is Python-packaging-native: it reads pyproject.toml/setup.cfg/setup.py, installed importlib.metadata, and the PyPI JSON API. Outside that world, coverage drops, and the honest move is to tell the user plainly rather than hand back a JSON file that looks complete but isn't:

• No Python packaging markers at all (a directory with only package.json, Cargo.toml, go.mod, pom.xml/build.gradle, Gemfile, composer.json, or a .csproj/.sln -- no pyproject.toml/setup.cfg/setup.py anywhere) -- loom project/ loom generate already refuses outright ("No project configuration found ... Expected pyproject.toml, setup.cfg, or setup.py"). Don't try to work around this (e.g. by hand-authoring a fragment to fake coverage) -- tell the user this ecosystem isn't supported yet.

• Mixed-ecosystem repos (a pyproject.toml sitting alongside package.json/Cargo.toml/etc., e.g. a Python backend with a JS frontend in the same repo) -- generation succeeds here, silently. The resulting SBOM only inventories the Python side ([project.dependencies] and what's importable); every non-Python dependency is invisible to Pitloom and simply won't appear -- no error, no NOASSERTION placeholder, nothing marking the gap. If you see non-Python ecosystem files during generation, say explicitly that the SBOM covers only the Python packaging surface, not the whole repo.

• Non-PyPI dependencies (a git+https://... URL, a local path requirement, or a private-index-only package) -- these get a package entry, but supplier/license/hash enrichment (both the deterministic local pass and the PyPI JSON API fallback) has nothing to look up, so those fields land on NOASSERTION. That's the correct, honest output for "genuinely unknown" -- not a bug -- but worth naming when a user asks why a dependency's entry looks sparse.

• AI model formats: broad but not universal coverage (GGUF, ONNX, PyTorch, Safetensors, Keras, HDF5, NumPy, fastText, plus Hugging Face Hub models). A model in some other serialization format isn't recognized at all -- same "say so" rule applies rather than silently skipping it.

• Non-Hatchling build backend for loom project/loom generate against a project directory -- check pyproject.toml's [build-system] build-backend before generating, not after. If it isn't hatchling.build (setuptools.build_meta, poetry.core.masonry.api, pdm.backend, flit_core.buildapi, uv_build, etc. -- or there's no pyproject.toml build-backend declared at all, just a bare setup.py/setup.cfg), say so upfront, don't wait for the user to ask why the SBOM looks off:

  Limitation notes: While Pitloom can work with any Python project, it currently gathers more information from Hatchling project. More complete support for setuptools is planned for version 0.17.0. uv_build, Poetry Core, PDM-Backend, and Flit-Core are also in the plan. See full limitation notes.

  Project-level metadata (name, version, dependencies, license, authors) is unaffected by this -- it's read correctly regardless of backend. What's affected is the file-level inventory: which files are listed, their hashes, and the package's Merkle-root integrity hash, which currently rely on Hatchling's own file-discovery heuristics regardless of the declared backend.

See also

• references/examples.md -- copy-paste recipes for every target type.
• The sibling sbom-enrich skill -- the agentic, prose-reading enrichment pass; see "Combine with enrichment" above for when a request calls for it.
• The sibling sbom-validate skill -- schema/shape-level conformance check for any SBOM this skill produces.
• docs/resources.md in the Pitloom repository -- SPDX 3 spec, ontology, JSON-LD, and JSON Schema links (including the per-minor-version URL pattern) for looking up the exact schema/spec a generated SBOM should conform to.