python-sbom 0.1.1__py3-none-any.whl

python_sbom/_model/_components.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import re
+from email.utils import getaddresses
+from itertools import starmap
+from typing import TYPE_CHECKING, Final
+
+from packaging.utils import canonicalize_name
+
+from ._graph import walk_components
+from ._iri import iri_reference
+from ._licenses import licenses
+from ._names import purl, pypi_url, reference_type, sbom_property, tool_ref
+from ._types import Dependency
+
+if TYPE_CHECKING:
+    from pathlib import PurePosixPath
+
+    from ._content import BundledWheelInfo
+    from ._inputs import BundledWheel, RecordRow
+    from ._metadata import CoreMetadata
+    from ._types import Component, Contact, ExternalReference, Identity, Property
+
+
+def bundled_wheel_component(wheel: BundledWheel, property_prefix: str, info: BundledWheelInfo) -> Component:
+    component = component_from_metadata(wheel.metadata)
+    mark_bundled(component, wheel.path, property_prefix, info)
+    component["hashes"] = [{"alg": "SHA-256", "content": wheel.sha256}]
+    component["externalReferences"] = [
+        *component["externalReferences"],
+        {"type": "distribution", "url": pypi_url(wheel.metadata.name, wheel.metadata.version)},
+    ]
+    component["evidence"] = {
+        "identity": [
+            _evidence("purl", "manifest-analysis", wheel.metadata_name),
+            _evidence("hash", "hash-comparison", wheel.sha256),
+        ]
+    }
+    vendored: Final[dict[str, Component]] = {}
+    for source, metadata in wheel.vendored:
+        child = component_from_metadata(metadata)
+        child["bom-ref"] = f"{component['bom-ref']}#vendored/{child['bom-ref']}"
+        child["properties"] = [
+            *child["properties"],
+            {"name": sbom_property(property_prefix, "vendored-manifest"), "value": source},
+        ]
+        child["evidence"] = {"identity": [_evidence("purl", "manifest-analysis", source)]}
+        # a vendored .dist-info comes after pip's manifest line naming the same package, so its metadata wins; keyed on
+        # the PEP 503 name, since the manifest and the .dist-info may spell it differently
+        vendored[f"{canonicalize_name(child['name'])}=={child['version']}"] = child
+    component["components"] = [
+        *(file_component(component["bom-ref"], row) for row in wheel.files),
+        *(vendored[key] for key in sorted(vendored)),
+    ]
+    return component
+
+
+def component_from_metadata(metadata: CoreMetadata) -> Component:
+    name, version = metadata.name, metadata.version
+    component: Final[Component] = {"type": "library", "bom-ref": purl(name, version), "name": name, "version": version}
+    component["purl"] = component["bom-ref"]
+    if summary := metadata.first("summary"):
+        component["description"] = summary
+    # maintainers are who users reach today, so they win over the original authors when both are named
+    for names, addresses in (("maintainer", "maintainer_email"), ("author", "author_email")):
+        contacts = [
+            *(_contact(name, "") for name in metadata.values(names)),
+            *starmap(_contact, getaddresses(metadata.values(addresses))),
+        ]
+        if people := [contact for contact in contacts if contact]:
+            component["authors"] = people
+            break
+    if declared := licenses(metadata):
+        component["licenses"] = declared
+    component["externalReferences"], unlinked = _project_references(metadata)
+    # core metadata headers copied verbatim, so a reader sees what the distribution declared
+    headers: Final[list[tuple[str, list[str]]]] = [
+        ("requires-python", metadata.values("requires_python")),
+        ("requires-dist", metadata.values("requires_dist")),
+        ("provides-extra", metadata.values("provides_extra")),
+        ("classifier", metadata.values("classifiers")),
+        ("keywords", metadata.keywords()),
+    ]
+    component["properties"] = []
+    for header, values in headers:
+        component["properties"].extend({"name": f"python:{header}", "value": value} for value in values)
+    component["properties"].extend(unlinked)
+    return component
+
+
+def _contact(name: str, email: str) -> Contact:
+    if email and not re.fullmatch(r"[^@\s]+@[^@\s]+\.[^@\s]+", email):
+        # an address the schema rejects as an email, such as "jane at example.com", is kept as the name
+        return {"name": " ".join(part for part in (name, email) if part)}
+    contact: Final[Contact] = {}
+    if name:
+        contact["name"] = name
+    if email:
+        contact["email"] = email
+    return contact
+
+
+def _project_references(metadata: CoreMetadata) -> tuple[list[ExternalReference], list[Property]]:
+    # a URL CycloneDX would reject is percent-encoded where that keeps what it points at and left out where it cannot
+    # be, as an scp-style git address; either way the header's text is kept verbatim as a property
+    references: Final[list[ExternalReference]] = []
+    unlinked: Final[list[Property]] = []
+    # a home page that is not an http(s) URL, such as UNKNOWN, is left out
+    if (home_page := metadata.first("home_page")) and re.match(r"https?:", home_page, re.IGNORECASE):
+        if (url := iri_reference(home_page)) is not None:
+            references.append({"type": "website", "url": url})
+        if url != home_page:
+            unlinked.append({"name": "python:home-page", "value": home_page})
+    for label, link in metadata.project_urls():
+        if (url := iri_reference(link)) is not None:
+            references.append({"type": reference_type(label), "url": url, "comment": f"Project-URL: {label}"})
+        if url != link:
+            unlinked.append({"name": "python:project-url", "value": f"{label}, {link}"})
+    return references, unlinked
+
+
+def mark_bundled(component: Component, path: str, property_prefix: str, info: BundledWheelInfo) -> None:
+    # the purl names the package; the path, of a .whl or of the directory a wheel is unpacked into, tells apart copies
+    # of one release bundled in two places
+    component["bom-ref"] = f"bundled:{path}"
+    if info.supplier is not None:
+        component["supplier"] = info.supplier
+    component["properties"] = [
+        {"name": sbom_property(property_prefix, "bundled-wheel"), "value": path},
+        *info.properties,
+        *component["properties"],
+    ]
+
+
+def _evidence(field: str, technique: str, value: str) -> Identity:
+    return {"field": field, "confidence": 1, "methods": [{"technique": technique, "confidence": 1, "value": value}]}
+
+
+def file_component(parent_ref: str, row: RecordRow) -> Component:
+    return {
+        "type": "file",
+        "bom-ref": f"{parent_ref}#{row.path}",
+        "name": row.path,
+        "hashes": [{"alg": row.algorithm, "content": row.digest}],
+        "properties": [{"name": "size", "value": row.size}],
+    }
+
+
+def vendored_dependencies(components: list[Component]) -> list[Dependency]:
+    # each bundled wheel depends on the packages it vendors, wherever it sits in the document
+    found: Final[list[Dependency]] = []
+    for component in walk_components(components):
+        if not component["bom-ref"].startswith("bundled:"):
+            continue
+        # a file's ref holds its path, which may itself hold "#vendored/"
+        libraries = (child["bom-ref"] for child in component.get("components", []) if child["type"] == "library")
+        if vendored := [ref for ref in libraries if "#vendored/" in ref]:
+            found.append(Dependency(ref=component["bom-ref"], dependsOn=vendored))
+    return found
+
+
+def script_tool(path: PurePosixPath, sha256: str, version: str, link: str | None) -> Component:
+    tool: Final[Component] = {
+        "type": "application",
+        "bom-ref": tool_ref(str(path)),
+        "name": path.name,
+        "version": version,
+        "hashes": [{"alg": "SHA-256", "content": sha256}],
+    }
+    if link is not None:
+        tool["externalReferences"] = [{"type": "vcs", "url": link}]
+    return tool
+
+
+__all__ = [
+    "bundled_wheel_component",
+    "component_from_metadata",
+    "file_component",
+    "mark_bundled",
+    "script_tool",
+    "vendored_dependencies",
+]

python_sbom/_model/_content.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path, PurePosixPath
+
+    from ._identity import ProjectIdentity
+    from ._inputs import Settings
+    from ._types import Component, Dependency, OrganizationalEntity, Property
+
+
+class ProviderContext:
+    """
+    What a content provider may use about the build it contributes to.
+
+    :param root: the project directory
+    :param settings: the project's options
+    :param identity: how the project's SBOMs name it, including the prefix of its properties
+    :param read: reads a member of the artifact being described, for :meth:`read`
+
+    """
+
+    def __init__(
+        self, *, root: Path, settings: Settings, identity: ProjectIdentity, read: Callable[[PurePosixPath], bytes]
+    ) -> None:
+        self.root = root
+        self.settings = settings
+        self.identity = identity
+        self._read = read
+
+    def read(self, path: PurePosixPath) -> bytes:
+        """
+        Read a file of the artifact being described: a member of the built wheel or of the archive.
+
+        :param path: the file's path inside the artifact, as a bundled wheel's path is given
+        :returns: the file's bytes
+        :raises KeyError: when the artifact holds no such file
+
+        """
+        return self._read(path)
+
+
+class ContentProvider:
+    """
+    Adds what a project knows beyond its metadata to its SBOM; subclass it and override what the project needs.
+
+    Name a subclass in the ``content-provider`` option, which the hook, ``python-sbom embed`` and ``python-sbom
+    archive`` load, or return an instance from :meth:`python_sbom.hatch.SbomBuildHook.content_provider`. When the class
+    lives in the project, the SBOM lists its module among the build tools.
+
+    """
+
+    # ruff: disable[unused-method-argument, no-self-use] # the defaults add nothing, whatever they are given
+    def bundled_wheel(self, context: ProviderContext, wheel: PurePosixPath) -> BundledWheelInfo:
+        """
+        Describe what the project does with a wheel it bundles, as a file or unpacked into a directory.
+
+        :param context: the project and the artifact being described
+        :param wheel: the wheel's path inside the artifact
+        :returns: its extra properties, and whether the project's supplier supplies it; neither by default
+
+        """
+        return BundledWheelInfo()
+
+    def contributions(self, context: ProviderContext) -> Contributions:
+        """
+        Add components, their dependencies, root properties and build tools, before references and the serial derive.
+
+        :param context: the project and the artifact being described
+        :returns: the contributions; none by default
+
+        """
+        return Contributions()
+
+    # ruff: enable[unused-method-argument, no-self-use]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BundledWheelInfo:
+    """
+    What a project adds to the component of one bundled wheel.
+
+    Both fields default to empty, so a provider names only what it adds.
+
+    :param properties: properties after ``<prefix>:bundled-wheel``, before those from the wheel's metadata
+    :param supplier: the wheel's supplier, or ``None`` to name none; only the project decides a bundled wheel's
+        supplier, never the wheel's own metadata
+
+    """
+
+    properties: list[Property] = field(default_factory=list)
+    supplier: OrganizationalEntity | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Contributions:
+    """
+    What a project adds to the document beyond its bundled wheels, merged before references and the serial are derived.
+
+    Each field defaults to empty, so a provider names only what it adds. The build fails when a component or tool lacks
+    ``type``, ``bom-ref`` or ``name``, a ``bom-ref`` repeats, the ``formula:`` and ``workflow:`` refs of the build's
+    formulation included, a dependency names one that does not exist, or a ``bom-ref`` gets a second dependency entry,
+    as the root does if a provider adds one, since python-sbom writes the root's.
+
+    :param components: extra top-level components, such as vendored C libraries; the root depends on each, and a
+        component's own parts nest under its ``components``
+    :param dependencies: extra dependency entries, such as the dependencies of those components
+    :param root_properties: extra properties of the root component; their names must not start with the project's
+        prefix, which python-sbom's own properties use
+    :param tools: extra build tools
+
+    """
+
+    components: list[Component] = field(default_factory=list)
+    dependencies: list[Dependency] = field(default_factory=list)
+    root_properties: list[Property] = field(default_factory=list)
+    tools: list[Component] = field(default_factory=list)
+
+
+__all__ = [
+    "BundledWheelInfo",
+    "ContentProvider",
+    "Contributions",
+    "ProviderContext",
+]

python_sbom/_model/_document.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Final
+
+from python_sbom._errors import SbomError
+
+from ._graph import reference_problems, walk_components
+
+if TYPE_CHECKING:
+    from ._content import ContentProvider, Contributions
+    from ._inputs import BuildFacts
+    from ._types import Body, Component, Document, Formula, Property
+
+
+def check_refs(body: Body) -> None:
+    # a provider contributes refs of its own, so the document is checked before it is written rather than by validate
+    components: Final[list[Component]] = [
+        *walk_components([
+            body["metadata"]["component"],
+            *body["components"],
+            *body["metadata"]["tools"]["components"],
+        ])
+    ]
+    # formulas and workflows share the bom-ref namespace, so a component cannot take theirs
+    formulas: Final[list[str]] = [
+        ref
+        for formula in body.get("formulation", [])
+        for ref in (formula["bom-ref"], *(workflow["bom-ref"] for workflow in formula["workflows"]))
+    ]
+    if problems := reference_problems(
+        [*(component["bom-ref"] for component in components), *formulas], body["dependencies"]
+    ):
+        raise SbomError(problems[0])
+
+
+def with_header(body: Body, serial_namespace: uuid.UUID) -> Document:
+    return {
+        "$schema": "http://cyclonedx.org/schema/bom-1.6.schema.json",
+        "bomFormat": "CycloneDX",
+        "specVersion": "1.6",
+        "serialNumber": f"urn:uuid:{uuid.uuid5(serial_namespace, json.dumps(body, sort_keys=True))}",
+        "version": 1,
+        **body,
+    }
+
+
+def checked_contributions(contributions: Contributions, provider: ContentProvider) -> Contributions:
+    # what a provider adds is checked for the fields everything else here reads, so a mistake names the provider rather
+    # than surfacing as a KeyError deep in the build
+    for component in walk_components([*contributions.components, *contributions.tools]):
+        if missing := [key for key in ("type", "bom-ref", "name") if key not in component]:
+            name = type(provider).__qualname__
+            msg = f"content provider {name} added a component without {', '.join(missing)}: {component!r:.200}"
+            raise SbomError(msg)
+    return contributions
+
+
+def contributed_properties(properties: list[Property], prefix: str) -> list[Property]:
+    if claimed := sorted(prop["name"] for prop in properties if prop["name"].startswith(f"{prefix}:")):
+        msg = f"contributed root properties {', '.join(claimed)} use the {prefix}: prefix python-sbom writes"
+        raise SbomError(msg)
+    return properties
+
+
+def formulation(uid: str, name: str, tools: list[Component], output_ref: str, facts: BuildFacts) -> Formula:
+    formula: Formula = {
+        "bom-ref": f"formula:{uid}",
+        "workflows": [
+            {
+                "bom-ref": f"workflow:{uid}",
+                "uid": uid,
+                "name": name,
+                "taskTypes": ["build"],
+                "resourceReferences": [{"ref": tool["bom-ref"]} for tool in tools],
+                "outputs": [{"type": "artifact", "resource": {"ref": output_ref}}],
+            }
+        ],
+    }
+    if facts.epoch_from_environment:
+        formula["workflows"][0]["inputs"] = [
+            {"environmentVars": [{"name": "SOURCE_DATE_EPOCH", "value": str(facts.epoch)}]}
+        ]
+    return formula
+
+
+def timestamp(facts: BuildFacts) -> str:
+    return datetime.fromtimestamp(facts.epoch, tz=UTC).isoformat()
+
+
+__all__ = [
+    "check_refs",
+    "checked_contributions",
+    "contributed_properties",
+    "formulation",
+    "timestamp",
+    "with_header",
+]

python_sbom/_model/_graph.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from collections import Counter
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+    from ._types import Component, Dependency
+
+
+def artifact_contents(root: Component, components: list[Component]) -> list[Component]:
+    # what the artifact holds or declares, wherever the document places it: the files and wheels nested under the root,
+    # which sit in an archive's top level, and the components; not the root itself, nor the tools that built it, so
+    # generation, the license policy and validation all judge the same set
+    return [*root.get("components", []), *components]
+
+
+def shipped_libraries(contents: list[Component]) -> list[Component]:
+    # what the artifact carries bytes for: a declared requirement resolves at install time, and a library a bundled
+    # wheel vendors ships under that wheel's terms
+    return [
+        component
+        for component in walk_components(contents)
+        if component["type"] == "library"
+        and ("hashes" in component or any(child["type"] == "file" for child in component.get("components", [])))
+    ]
+
+
+def walk_components(components: Iterable[Component]) -> Iterator[Component]:
+    # depth first, each component before the ones it nests, in document order; iterative, so a deeply nested document
+    # cannot exhaust the stack
+    pending: Final[list[Component]] = list(reversed(list(components)))
+    while pending:
+        component = pending.pop()
+        yield component
+        pending.extend(reversed(component.get("components", [])))
+
+
+def reference_problems(refs: list[str], dependencies: list[Dependency]) -> list[str]:
+    # what generation refuses and validation reports alike: a bom-ref given twice, which formulas and workflows share
+    # with components; a second dependency entry for one ref, which a reader taking them as a mapping would let a valid
+    # entry hide an invalid one with, while the SPDX rendering keeps the edges of both; and an entry naming no component
+    if twice := repeated(refs):
+        return [f"bom-ref values repeat: {', '.join(twice)}"]
+    if twice := repeated(entry["ref"] for entry in dependencies):
+        return [f"dependencies list more than one entry for: {', '.join(twice)}"]
+    named: Final[set[str]] = {ref for entry in dependencies for ref in (entry["ref"], *entry.get("dependsOn", []))}
+    if unknown := sorted(named - set(refs)):
+        return [f"dependencies name bom-refs no component has: {', '.join(unknown)}"]
+    return []
+
+
+def repeated(values: Iterable[str]) -> list[str]:
+    return sorted(value for value, count in Counter(values).items() if count > 1)
+
+
+__all__ = [
+    "artifact_contents",
+    "reference_problems",
+    "repeated",
+    "shipped_libraries",
+    "walk_components",
+]

python_sbom/_model/_identity.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ._iri import iri_reference
+from ._names import property_prefix, reference_type
+
+if TYPE_CHECKING:
+    from ._inputs import Settings
+    from ._metadata import CoreMetadata
+
+
+def project_identity(metadata: CoreMetadata, settings: Settings) -> ProjectIdentity:
+    project = property_prefix(metadata.name)
+    repository = settings.repository
+    # links into the repository extend its URL, so one that cannot be an IRI reference, as an scp-style git address, is
+    # passed over for the next
+    for label, url in [] if repository else metadata.project_urls():
+        if reference_type(label) == "vcs" and (link := iri_reference(url)) is not None:
+            repository = link.rstrip("/")
+            break
+    base = repository or f"https://pypi.org/project/{project}"
+    return ProjectIdentity(
+        property_prefix=project,
+        repository=repository,
+        serial_namespace=uuid.uuid5(uuid.NAMESPACE_URL, f"{base}/sboms"),
+    )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ProjectIdentity:
+    """
+    How every SBOM of a project names it.
+
+    :param property_prefix: the project's normalized name, which starts the names of the properties python-sbom writes,
+        such as ``virtualenv`` in ``virtualenv:bundled-wheel``
+    :param repository: the repository URL, from the options or the first ``Source``, ``Repository`` or ``GitHub``
+        project URL, or ``None``
+    :param serial_namespace: the UUID namespace of the serial numbers of the project's SBOMs
+
+    """
+
+    property_prefix: str
+    repository: str | None
+    serial_namespace: uuid.UUID
+
+
+__all__ = [
+    "ProjectIdentity",
+    "project_identity",
+]

python_sbom/_model/_inputs.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import PurePosixPath
+
+    from ._metadata import CoreMetadata
+    from ._types import Component, Dependency, OrganizationalEntity
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RecordRow:
+    path: str
+    algorithm: str
+    digest: str
+    size: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Interpreter:
+    name: str
+    version: str
+    implementation: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InstalledDistribution:
+    name: str
+    metadata: CoreMetadata
+    files: list[RecordRow]
+    depends_on: list[str]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Revision:
+    commit: str
+    dirty: bool
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BuildFacts:
+    epoch: int
+    epoch_from_environment: bool
+    revision: Revision | None
+    interpreter: Interpreter
+    distributions: list[InstalledDistribution]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Settings:
+    """
+    The project's options, from ``[tool.python-sbom]``.
+
+    :param supplier: the organization that supplies the project, or ``None`` to name none
+    :param repository: the repository URL, or ``None`` to take the first ``Source``, ``Repository`` or ``GitHub``
+        project URL
+    :param default_branch: the branch in links to files in the repository when the build's commit is unknown or has
+        uncommitted changes
+    :param bundled_wheels: glob patterns, relative to the project directory, of wheels the project ships as data files
+    :param content_provider: ``module:attribute`` of the content provider, or ``None``
+
+    """
+
+    supplier: OrganizationalEntity | None
+    repository: str | None
+    default_branch: str
+    bundled_wheels: tuple[str, ...]
+    content_provider: str | None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BundledWheel:
+    path: str
+    sha256: str
+    metadata_name: str
+    metadata: CoreMetadata
+    files: list[RecordRow]
+    vendored: list[tuple[str, CoreMetadata]]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BuildScript:
+    path: PurePosixPath
+    sha256: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ArchiveTree:
+    # what an archive holds, read from the zip without unpacking it: each distribution's metadata and members by the
+    # directory that holds its .dist-info, "" for the project's own, the archive's own top-level files, the digest of
+    # every member but the bundled wheels, and those wheels
+    metadata: dict[str, CoreMetadata]
+    owned: dict[str, list[str]]
+    loose: list[str]
+    files: dict[str, RecordRow]
+    bundled: dict[str, BundledWheel]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Artifact:
+    # what one artifact, a wheel or an archive, puts in its SBOM; the provenance every artifact of the project shares is
+    # added around it
+    root: Component
+    components: list[Component]
+    dependencies: list[Dependency]
+    build_scripts: list[BuildScript]
+    version: str
+    sbom_file: str
+    scope: str
+    workflow: tuple[str, str]
+    license_file: str | None
+    copyright: str | None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class WheelTree:
+    # what a built wheel holds, read from the wheel without unpacking it: its file name, its core metadata and the
+    # wheels it bundles; and what the project adds: the copyright line of its license files and the scripts that built
+    # it
+    name: str
+    metadata: CoreMetadata
+    copyright: str | None
+    bundled: list[BundledWheel]
+    build_scripts: list[BuildScript]
+
+
+__all__ = [
+    "ArchiveTree",
+    "Artifact",
+    "BuildFacts",
+    "BuildScript",
+    "BundledWheel",
+    "InstalledDistribution",
+    "Interpreter",
+    "RecordRow",
+    "Revision",
+    "Settings",
+    "WheelTree",
+]