python-sbom 0.1.1__py3-none-any.whl

python_sbom/__init__.py

@@ -0,0 +1,46 @@
+"""SBOMs for Python distributions: write PEP 770 CycloneDX SBOMs into wheels."""
+
+from __future__ import annotations
+
+from ._errors import SbomError
+from ._model._content import BundledWheelInfo, ContentProvider, Contributions, ProviderContext
+from ._model._identity import ProjectIdentity
+from ._model._inputs import Settings
+from ._model._types import (
+    Component,
+    Contact,
+    Dependency,
+    Evidence,
+    ExternalReference,
+    Hash,
+    Identity,
+    IdentityMethod,
+    License,
+    LicenseInfo,
+    OrganizationalEntity,
+    Property,
+)
+from .version import __version__
+
+__all__ = [
+    "BundledWheelInfo",
+    "Component",
+    "Contact",
+    "ContentProvider",
+    "Contributions",
+    "Dependency",
+    "Evidence",
+    "ExternalReference",
+    "Hash",
+    "Identity",
+    "IdentityMethod",
+    "License",
+    "LicenseInfo",
+    "OrganizationalEntity",
+    "ProjectIdentity",
+    "Property",
+    "ProviderContext",
+    "SbomError",
+    "Settings",
+    "__version__",
+]

python_sbom/__main__.py

@@ -0,0 +1,10 @@
+"""Main entry point."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli._main import main
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

python_sbom/_cli/__init__.py

@@ -0,0 +1 @@
+"""The command line: parsing options and running one command per subcommand."""

python_sbom/_cli/_archive.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path, PurePosixPath
+from typing import Protocol
+
+from python_sbom._generate._archive import archive_sbom
+
+from ._parser import BuildOptions
+
+
+class _Options(BuildOptions, Protocol):
+    archive: Path
+    build_scripts: list[str] | None
+    output: Path | None
+    embed: bool
+
+
+def run(options: _Options) -> bool:
+    target, embedded = archive_sbom(
+        Path.cwd() if options.root is None else options.root,
+        options.archive,
+        provider=options.content_provider,
+        commit=options.commit,
+        build_env=options.build_env,
+        build_scripts=tuple(PurePosixPath(script) for script in options.build_scripts or []),
+        output=options.output,
+        embed=options.embed,
+    )
+    sys.stdout.write(f"wrote {target}\n")
+    if embedded is not None:
+        sys.stdout.write(f"wrote {embedded} into {options.archive.name}\n")
+    return True
+
+
+__all__ = [
+    "run",  # simplint: ignore[SMP402] # the parser names it for pkgutil.resolve_name
+]

python_sbom/_cli/_embed.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Protocol
+
+from python_sbom._generate._embed import embed_sbom
+
+from ._parser import BuildOptions
+
+
+class _Options(BuildOptions, Protocol):
+    wheels: list[Path]
+
+
+def run(options: _Options) -> bool:
+    root = Path.cwd() if options.root is None else options.root
+    for wheel in options.wheels:
+        written = embed_sbom(
+            wheel, root, provider=options.content_provider, commit=options.commit, build_env=options.build_env
+        )
+        sys.stdout.write(f"wrote {written} into {wheel.name}\n")
+    return True
+
+
+__all__ = [
+    "run",  # simplint: ignore[SMP402] # the parser names it for pkgutil.resolve_name
+]

python_sbom/_cli/_main.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import pkgutil
+import sys
+from typing import TYPE_CHECKING
+
+from python_sbom._errors import SbomError
+
+from ._parser import build_parser
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def main(args: Sequence[str] | None = None) -> None:
+    options = build_parser().parse_args(args)
+    try:
+        succeeded = pkgutil.resolve_name(options.handler)(options)
+    except SbomError as error:
+        sys.stderr.write(f"python-sbom: {error}\n")
+        succeeded = False
+    if not succeeded:
+        raise SystemExit(1)
+
+
+__all__ = [
+    "main",
+]

python_sbom/_cli/_parser.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, ArgumentTypeError, _SubParsersAction
+from pathlib import Path
+from typing import Protocol
+
+# the limits module imports nothing, so --help and --version load none of validation
+from python_sbom._validate._limits import MAX_COMPONENTS
+from python_sbom.version import __version__
+
+
+def build_parser() -> ArgumentParser:
+    parser = ArgumentParser(prog="python-sbom", description="Write, convert and check the CycloneDX SBOMs of wheels.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    commands = parser.add_subparsers(required=True)
+    _add_embed(commands)
+    _add_archive(commands)
+    _add_spdx(commands)
+    _add_validate(commands)
+    return parser
+
+
+def _add_embed(commands: _SubParsersAction[ArgumentParser]) -> None:
+    parser = commands.add_parser(
+        "embed",
+        help="write the SBOM into wheels another build backend built",
+        description="Write the SBOM the hatchling hook writes into wheels another build backend built, such as"
+        " meson-python. Options come from the [tool.python-sbom] table of the project's pyproject.toml.",
+    )
+    # a name, not the function, so each command imports only what it runs and --help imports none of it
+    parser.set_defaults(handler="python_sbom._cli._embed:run")
+    parser.add_argument("wheels", type=Path, nargs="+", metavar="WHEEL", help="wheel to rewrite in place")
+    _add_build_options(parser)
+
+
+def _add_build_options(parser: ArgumentParser) -> None:
+    parser.add_argument(
+        "--root", type=Path, metavar="DIR", help="project directory of the artifact (default: current directory)"
+    )
+    parser.add_argument(
+        "--commit", metavar="SHA", help="source revision to record, for an artifact built from an sdist"
+    )
+    parser.add_argument(
+        "--build-env",
+        action="append",
+        metavar="DIR",
+        help="site-packages directory of the environment that built the artifact; repeat it per directory"
+        " (default: this interpreter's)",
+    )
+    parser.add_argument(
+        "--content-provider",
+        metavar="MODULE:ATTRIBUTE",
+        help="content provider, overriding the content-provider option",
+    )
+
+
+def _add_archive(commands: _SubParsersAction[ArgumentParser]) -> None:
+    parser = commands.add_parser(
+        "archive",
+        help="write the SBOM of a zip archive that is not a wheel, such as a zipapp",
+        description="Describe a zip archive that holds the project's .dist-info at its top level, such as a zipapp:"
+        " the archive's own files, the project's distribution, and every wheel it bundles, as a file or unpacked,"
+        " described as the wheel's SBOM describes them. Options come from [tool.python-sbom].",
+    )
+    parser.set_defaults(handler="python_sbom._cli._archive:run")
+    parser.add_argument("archive", type=Path, metavar="ARCHIVE", help="archive to describe")
+    _add_build_options(parser)
+    parser.add_argument(
+        "--build-script",
+        dest="build_scripts",
+        action="append",
+        metavar="PATH",
+        help="script, relative to the project, that built the archive; repeat it per script",
+    )
+    parser.add_argument(
+        "--output", type=Path, metavar="FILE", help="SBOM file to write (default: <archive>.cdx.json next to it)"
+    )
+    parser.add_argument(
+        "--embed", action="store_true", help="also add the SBOM to the archive, at its top level as <archive>.cdx.json"
+    )
+
+
+def _add_spdx(commands: _SubParsersAction[ArgumentParser]) -> None:
+    parser = commands.add_parser(
+        "spdx",
+        help="render a CycloneDX SBOM as SPDX 2.3 JSON",
+        description="Render a CycloneDX JSON SBOM, such as one python-sbom wrote, as an SPDX 2.3 JSON document. It"
+        " checks only the fields the rendering reads, so it needs no extra; python-sbom validate checks the whole"
+        " document.",
+    )
+    parser.set_defaults(handler="python_sbom._cli._spdx:run")
+    parser.add_argument("source", type=Path, metavar="SOURCE", help="CycloneDX JSON file to read")
+    parser.add_argument("target", type=Path, metavar="TARGET", help="SPDX JSON file to write")
+
+
+def _add_validate(commands: _SubParsersAction[ArgumentParser]) -> None:
+    parser = commands.add_parser(
+        "validate",
+        help="validate the SBOMs in wheels and archives",
+        description="Check every CycloneDX SBOM a wheel or archive holds against the CycloneDX 1.6 schema; for one"
+        " python-sbom wrote, also its serial number, references, SPDX rendering and, with --allow-license, the licenses"
+        " of what it ships. Needs the validate extra: python-sbom[validate].",
+    )
+    parser.set_defaults(handler="python_sbom._cli._validate:run")
+    parser.add_argument(
+        "paths", type=Path, nargs="+", metavar="PATH", help="wheel, archive, or directory holding wheels"
+    )
+    parser.add_argument(
+        "--allow-license",
+        dest="allowed_licenses",
+        action="append",
+        metavar="SPDX-ID",
+        help="SPDX license id shipped components may use; repeat it per id, leave it out to skip the license policy",
+    )
+    parser.add_argument(
+        "--max-components",
+        type=_positive_int,
+        default=MAX_COMPONENTS,
+        metavar="N",
+        help="reject an SBOM listing more than N components, nested ones included, or larger than 1 MiB plus 1 KiB per"
+        " component, without checking it further, which bounds the work an untrusted SBOM can ask for (default:"
+        f" {MAX_COMPONENTS})",
+    )
+
+
+def _positive_int(text: str) -> int:
+    # argparse reports the error through parser.error, with the usage, like any other bad argument
+    if text.isdecimal() and (number := int(text)) > 0:
+        return number
+    msg = f"must be a positive integer, got {text!r}"
+    raise ArgumentTypeError(msg)
+
+
+class BuildOptions(Protocol):
+    root: Path | None
+    commit: str | None
+    build_env: list[str] | None
+    content_provider: str | None
+
+
+__all__ = [
+    "BuildOptions",
+    "build_parser",
+]

python_sbom/_cli/_spdx.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from python_sbom._errors import SbomError
+from python_sbom._formats._json import dumps
+from python_sbom._formats._spdx import render_spdx
+from python_sbom._validate._document import is_document, load_json
+from python_sbom._validate._limits import MAX_COMPONENTS, byte_limit
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from python_sbom._model._types import Document
+
+
+class _Options(Protocol):
+    source: Path
+    target: Path
+
+
+def run(options: _Options) -> bool:
+    document = _read(options.source)
+    try:
+        rendered = dumps(render_spdx(document))
+    # ValueError: a timestamp fromisoformat rejects; AttributeError: a tools value that is neither an array nor an
+    # object; RecursionError: nesting json.dumps, a few frames deeper than json.loads, gives up on
+    except (AttributeError, KeyError, TypeError, ValueError, RecursionError) as error:
+        # the CLI renders without the schema check, which needs the validate extra
+        msg = f"{options.source} is not a CycloneDX document python-sbom can render: {error!r}"
+        raise SbomError(msg) from error
+    # bytes, so the line endings are the same on every operating system
+    options.target.write_bytes(rendered)
+    return True
+
+
+def _read(source: Path) -> Document:
+    # the size validate accepts at its default component cap, so the parser never holds more than validate lets it
+    limit = byte_limit(MAX_COMPONENTS)
+    try:
+        with source.open("rb") as handle:
+            raw = handle.read(limit + 1)
+    except OSError as error:
+        raise SbomError(str(error)) from error
+    if len(raw) > limit:
+        msg = f"{source} is over {limit} bytes, the size limit of an SBOM python-sbom reads"
+        raise SbomError(msg)
+    try:
+        loaded = load_json(raw)
+    except SbomError as error:
+        msg = f"{source} {error}"
+        raise SbomError(msg) from error
+    if not is_document(loaded):
+        msg = f"{source} is not a CycloneDX document python-sbom can render"
+        raise SbomError(msg)
+    return loaded
+
+
+__all__ = [
+    "run",  # simplint: ignore[SMP402] # the parser names it for pkgutil.resolve_name
+]

python_sbom/_cli/_validate.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Protocol
+
+from python_sbom._validate._artifact import validate
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class _Options(Protocol):
+    paths: list[Path]
+    allowed_licenses: list[str] | None
+    max_components: int
+
+
+def run(options: _Options) -> bool:
+    allowed = None if options.allowed_licenses is None else frozenset(options.allowed_licenses)
+    if not (
+        artifacts := sorted(
+            artifact for path in options.paths for artifact in (path.glob("*.whl") if path.is_dir() else [path])
+        )
+    ):
+        sys.stderr.write(f"no wheel found in {', '.join(map(str, options.paths))}\n")
+        return False
+    valid = True
+    for artifact in artifacts:
+        for problem in (problems := validate(artifact, allowed, options.max_components)):
+            sys.stderr.write(f"SBOM invalid: {artifact.name}: {problem}\n")
+        if problems:
+            valid = False
+        else:
+            sys.stdout.write(f"SBOM in {artifact.name} is valid\n")
+    return valid
+
+
+__all__ = [
+    "run",  # simplint: ignore[SMP402] # the parser names it for pkgutil.resolve_name
+]

python_sbom/_collect/__init__.py

@@ -0,0 +1 @@
+"""What the edge reads: settings, build facts, the source revision, the project tree, the artifact and the provider."""

python_sbom/_collect/_archive.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+from python_sbom._errors import SbomError
+from python_sbom._model._archive import bundled_members
+from python_sbom._model._inputs import ArchiveTree, RecordRow
+from python_sbom._model._metadata import parse_metadata
+from python_sbom._model._names import archive_sbom_file_name
+
+if TYPE_CHECKING:
+    from collections.abc import Container
+
+    from python_sbom._model._metadata import CoreMetadata
+    from python_sbom._wheel._reader import ArtifactReader
+
+
+def read_archive(artifact: ArtifactReader) -> ArchiveTree:
+    # every member is read from the zip by its name, never from a file system path, so a name such as /etc/hostname or
+    # ../outside names a member, not a file of the host
+    where: Final[str] = artifact.path.name
+    members: Final[list[str]] = sorted(
+        info.filename
+        for info in artifact.archive.infolist()
+        if not info.is_dir() and info.filename != archive_sbom_file_name(where)
+    )
+    metadata: Final[dict[str, CoreMetadata]] = {}
+    for name in members:
+        if not name.endswith(".dist-info/METADATA"):
+            continue
+        # files belong to a distribution by the directory that holds its .dist-info, which two cannot share
+        if (directory := _distribution_prefix(name)) in metadata:
+            msg = (
+                f"{where} holds more than one .dist-info in {directory or 'its top level'}, so their files cannot"
+                " be told apart"
+            )
+            raise SbomError(msg)
+        metadata[directory] = parse_metadata(artifact.read(name).decode("utf-8"))
+    if "" not in metadata:
+        msg = f"{where} holds no top-level .dist-info/METADATA naming the project"
+        raise SbomError(msg)
+    files: Final[dict[str, RecordRow]] = {
+        name: RecordRow(
+            path=name,
+            algorithm="SHA-256",
+            digest=artifact.digest(name),
+            size=str(artifact.archive.getinfo(name).file_size),
+        )
+        for name in members
+        if not name.endswith(".whl")
+    }
+    owned: Final[dict[str, list[str]]] = {prefix: [] for prefix in metadata}
+    loose: Final[list[str]] = []
+    for name in members:
+        # the project's own distribution holds every subdirectory no other one does
+        if owner := _owner(name, metadata):
+            owned[owner].append(name)
+        elif "/" in name:
+            owned[""].append(name)
+        else:
+            loose.append(name)
+    # in the order the components list them, so the first broken wheel is the one reported
+    wheels: Final[list[str]] = [member for member in bundled_members(loose, owned) if not member.endswith("/")]
+    return ArchiveTree(
+        metadata=metadata,
+        owned=owned,
+        loose=loose,
+        files=files,
+        bundled=dict(zip(wheels, artifact.bundled_wheels(wheels), strict=True)),
+    )
+
+
+def _distribution_prefix(name: str) -> str:
+    # each distribution by the directory that holds its .dist-info, the project's own at the top level
+    return f"{name.rsplit('/', 2)[0]}/" if name.count("/") > 1 else ""
+
+
+def _owner(name: str, distributions: Container[str]) -> str | None:
+    # the deepest distribution directory that holds the member, found by looking up each of its ancestor directories,
+    # deepest first, so the work grows with the member's depth rather than the number of distributions
+    parents: Final[list[str]] = name.split("/")[:-1]
+    return next(
+        (
+            prefix
+            for depth in range(len(parents), 0, -1)
+            if (prefix := f"{'/'.join(parents[:depth])}/") in distributions
+        ),
+        None,
+    )
+
+
+__all__ = [
+    "read_archive",
+]

python_sbom/_collect/_content.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import inspect
+import pkgutil
+import sys
+from importlib.machinery import PathFinder
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING, Final
+
+from python_sbom._errors import SbomError
+from python_sbom._model._content import ContentProvider
+
+if TYPE_CHECKING:
+    from python_sbom._model._inputs import Settings
+
+
+def resolve_provider(
+    given: ContentProvider | str | None, settings: Settings, root: Path
+) -> tuple[ContentProvider, tuple[PurePosixPath, ...]]:
+    # an instance wins, as a hook subclass builds one; a module:attribute string overrides the option, as the CLI's flag
+    # does; otherwise the content-provider option, or the provider that adds nothing
+    if isinstance(given, ContentProvider):
+        provider = given
+    elif (spec := settings.content_provider if given is None else given) is None:
+        provider = ContentProvider()
+    else:
+        provider = _load(spec, root)
+    return provider, _provider_scripts(provider, root)
+
+
+def _load(spec: str, root: Path) -> ContentProvider:
+    # resolve_name also takes a bare module, which is no provider
+    module_name, _, attribute = spec.partition(":")
+    if not (module_name and attribute):
+        msg = f"content provider {spec!r} must be `module:attribute`"
+        raise SbomError(msg)
+    if (imported := _imported_elsewhere(module_name, root)) is not None:
+        msg = (
+            f"content provider {spec!r} cannot load from {root}: this process already imported {imported}, a module of"
+            " the same name, and would run that instead; build each such project in a process of its own"
+        )
+        raise SbomError(msg)
+    sys.path.insert(0, str(root))
+    try:
+        provider = pkgutil.resolve_name(spec)
+    # ValueError: a name resolve_name cannot parse, such as a second colon
+    except (ImportError, AttributeError, ValueError) as error:
+        msg = f"content provider {spec!r} does not load from {root}: {error}"
+        raise SbomError(msg) from error
+    finally:
+        sys.path.remove(str(root))
+    if isinstance(provider, type) and issubclass(provider, ContentProvider):
+        provider = provider()
+    if not isinstance(provider, ContentProvider):
+        msg = f"content provider {spec!r} is not a ContentProvider subclass or instance"
+        raise SbomError(msg)
+    return provider
+
+
+def _imported_elsewhere(module_name: str, root: Path) -> str | None:
+    # the import cache is per process, so a hatch build of a second project with a provider module of the same name
+    # would run the first project's; each package on the way down to the module, and the module itself, that the project
+    # provides is compared with what is already imported under its name; namespace packages merge, so only modules and
+    # regular packages can clash
+    search: list[str] | None = [str(root)]
+    parts: Final[list[str]] = module_name.split(".")
+    for depth in range(1, len(parts) + 1):
+        if search is None or (found := PathFinder.find_spec(".".join(parts[:depth]), search)) is None:
+            return None
+        imported = getattr(sys.modules.get(found.name), "__file__", None)
+        if (
+            found.origin is not None
+            and imported is not None
+            and Path(imported).resolve() != Path(found.origin).resolve()
+        ):
+            return imported
+        search = None if found.submodule_search_locations is None else list(found.submodule_search_locations)
+    return None
+
+
+def _provider_scripts(provider: ContentProvider, root: Path) -> tuple[PurePosixPath, ...]:
+    # each class of the provider defined in the project shapes the document, a base class or mixin as much as the class
+    # itself, so the SBOM lists their modules among the build tools; python-sbom's own ContentProvider adds nothing
+    found: Final[dict[PurePosixPath, None]] = {}
+    for cls in type(provider).__mro__:
+        if cls in {ContentProvider, object}:
+            continue
+        if (source := _source(cls)) is None:
+            continue
+        resolved, base = Path(source).resolve(), root.resolve()
+        if resolved.is_relative_to(base):
+            found[PurePosixPath(resolved.relative_to(base).as_posix())] = None
+    return tuple(found)
+
+
+def _source(cls: type) -> str | None:
+    # a method's code names the file even for a module hatchling loaded outside the import system, such as a custom
+    # hook script
+    methods = (
+        function.__code__.co_filename
+        for _, function in inspect.getmembers(cls, inspect.isfunction)
+        if function.__qualname__.startswith(f"{cls.__qualname__}.")
+    )
+    return next(methods, getattr(sys.modules.get(cls.__module__), "__file__", None))
+
+
+__all__ = [
+    "resolve_provider",
+]