python-sbom 0.1.1__py3-none-any.whl

python_sbom/_formats/_spdx.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Final, NotRequired, TypedDict
+
+from python_sbom._model._graph import walk_components
+from python_sbom._model._names import SBOM_FILE, SBOM_REPOSITORY, property_prefix, sbom_property
+from python_sbom.version import __version__
+
+if TYPE_CHECKING:
+    from python_sbom._model._types import (
+        Component,
+        Document,
+        ExternalReference,
+        License,
+        Metadata,
+        OrganizationalEntity,
+        Tools,
+    )
+
+# SPDX 2.3 JSON names every CycloneDX 1.6 hash algorithm, but by names of its own
+_HASH_ALGORITHMS: Final[dict[str, str]] = {
+    "MD5": "MD5",
+    "SHA-1": "SHA1",
+    "SHA-256": "SHA256",
+    "SHA-384": "SHA384",
+    "SHA-512": "SHA512",
+    "SHA3-256": "SHA3-256",
+    "SHA3-384": "SHA3-384",
+    "SHA3-512": "SHA3-512",
+    "BLAKE2b-256": "BLAKE2b-256",
+    "BLAKE2b-384": "BLAKE2b-384",
+    "BLAKE2b-512": "BLAKE2b-512",
+    "BLAKE3": "BLAKE3",
+}
+_LICENSE_REF: Final[re.Pattern[str]] = re.compile(r"LicenseRef-[A-Za-z0-9.-]+")
+
+
+class _LegacyTool(TypedDict):
+    vendor: NotRequired[str]
+    name: NotRequired[str]
+    version: NotRequired[str]
+
+
+class _Checksum(TypedDict):
+    algorithm: str
+    checksumValue: str
+
+
+class _ExternalRef(TypedDict):
+    referenceCategory: str
+    referenceType: str
+    referenceLocator: str
+
+
+class _Package(TypedDict):
+    SPDXID: str
+    name: str
+    downloadLocation: str
+    filesAnalyzed: bool
+    licenseConcluded: str
+    licenseDeclared: str
+    primaryPackagePurpose: str
+    versionInfo: NotRequired[str]
+    supplier: NotRequired[str]
+    checksums: NotRequired[list[_Checksum]]
+    homepage: NotRequired[str]
+    copyrightText: NotRequired[str]
+    summary: NotRequired[str]
+    comment: NotRequired[str]
+    externalRefs: NotRequired[list[_ExternalRef]]
+    licenseComments: NotRequired[str]
+
+
+class _Relationship(TypedDict):
+    spdxElementId: str
+    relationshipType: str
+    relatedSpdxElement: str
+
+
+class _CreationInfo(TypedDict):
+    created: str
+    creators: list[str]
+
+
+class _ExtractedLicense(TypedDict):
+    licenseId: str
+    extractedText: str
+    name: str
+
+
+class Spdx(TypedDict):
+    spdxVersion: str
+    dataLicense: str
+    SPDXID: str
+    name: str
+    documentNamespace: str
+    comment: str
+    creationInfo: _CreationInfo
+    packages: list[_Package]
+    relationships: list[_Relationship]
+    hasExtractedLicensingInfos: NotRequired[list[_ExtractedLicense]]
+
+
+def render_spdx(document: Document) -> Spdx:
+    metadata: Final[Metadata] = document["metadata"]
+    root: Final[Component] = metadata["component"]
+    project: Final[str] = property_prefix(root["name"])
+    recorded: Final[dict[str, str]] = {prop["name"]: prop.get("value", "") for prop in metadata.get("properties", [])}
+    name: Final[str] = f"{root['name']}-{root['version']}" if "version" in root else root["name"]
+    # without a serial number the content names the document, so rendering it twice gives the same namespace
+    source: Final[str] = (
+        document["serialNumber"]
+        if "serialNumber" in document
+        else f"sha256:{hashlib.sha256(json.dumps(document, sort_keys=True).encode()).hexdigest()}"
+    )
+    repository: Final[str] = recorded.get(sbom_property(project, SBOM_REPOSITORY), "https://spdx.org/spdxdocs")
+    sbom_file: Final[str] = recorded.get(sbom_property(project, SBOM_FILE), "CycloneDX JSON")
+    tools, tool_creators = _tools(metadata)
+    # file components mirror wheel RECORD entries, which carry no SHA-1 and so cannot become SPDX files
+    components: Final[list[Component]] = [
+        component
+        for component in walk_components([root, *document.get("components", []), *tools])
+        if component["type"] != "file"
+    ]
+    packages: Final[list[_Package]] = [_package(component, project) for component in components]
+    spdx: Final[Spdx] = {
+        "spdxVersion": "SPDX-2.3",
+        "dataLicense": "CC0-1.0",
+        "SPDXID": "SPDXRef-DOCUMENT",
+        "name": name,
+        "documentNamespace": f"{repository}/sboms/{name}-{source.removeprefix('urn:uuid:')}",
+        "comment": f"Rendered from the CycloneDX SBOM {source} ({sbom_file}), which also carries per-file hashes and"
+        " the build formulation.",
+        "creationInfo": _creation_info(metadata, tool_creators),
+        "packages": packages,
+        "relationships": _relationships(document, components, tools),
+    }
+    # SPDX requires the text of every LicenseRef a package declares; the metadata names them, it holds no text
+    references: Final[set[str]] = set()
+    for package in packages:
+        references.update(_LICENSE_REF.findall(package["licenseDeclared"]))
+    if references:
+        spdx["hasExtractedLicensingInfos"] = [
+            {"licenseId": token, "extractedText": f"{token}, as named in package metadata", "name": token}
+            for token in sorted(references)
+        ]
+    return spdx
+
+
+def _tools(metadata: Metadata) -> tuple[list[Component], list[str]]:
+    # CycloneDX 1.5 lists the tools as components; earlier versions as a bare array, whose entries carry no bom-ref, so
+    # they become creators alone
+    tools: Final[Tools | list[_LegacyTool] | None] = metadata.get("tools")
+    if isinstance(tools, list):
+        return [], [_creator(name, tool.get("version")) for tool in tools if (name := tool.get("name"))]
+    components: Final[list[Component]] = [] if tools is None else tools.get("components", [])
+    return components, [
+        _creator(tool["name"], tool.get("version")) for tool in components if tool["type"] == "application"
+    ]
+
+
+def _creator(name: str, version: str | None) -> str:
+    return f"Tool: {name}" if version is None else f"Tool: {name}-{version}"
+
+
+def _package(component: Component, project: str) -> _Package:
+    # a component carries either one SPDX expression, or the free-form names from License/classifier metadata plus the
+    # SPDX ids concluded from them
+    licenses: Final[list[License]] = component.get("licenses", [])
+    concluded: Final[list[str]] = [
+        entry["license"]["id"] for entry in licenses if "license" in entry and "id" in entry["license"]
+    ]
+    package: Final[_Package] = {
+        "SPDXID": _spdx_id(component["bom-ref"]),
+        "name": component["name"],
+        "downloadLocation": "NOASSERTION",
+        "filesAnalyzed": False,
+        "licenseConcluded": " AND ".join(concluded) or "NOASSERTION",
+        "licenseDeclared": next((entry["expression"] for entry in licenses if "expression" in entry), "NOASSERTION"),
+        "primaryPackagePurpose": {"application": "APPLICATION", "library": "LIBRARY"}.get(component["type"], "OTHER"),
+    }
+    if version := component.get("version"):
+        package["versionInfo"] = version
+    if (supplier := component.get("supplier")) and (organization := supplier.get("name")):
+        package["supplier"] = f"Organization: {organization}"
+    checksums: Final[list[_Checksum]] = [
+        {"algorithm": _HASH_ALGORITHMS[entry["alg"]], "checksumValue": entry["content"]}
+        for entry in component.get("hashes", [])
+        if entry["alg"] in _HASH_ALGORITHMS
+    ]
+    if checksums:
+        package["checksums"] = checksums
+    references: Final[list[ExternalReference]] = component.get("externalReferences", [])
+    if homepage := next((reference["url"] for reference in references if reference["type"] == "website"), None):
+        package["homepage"] = homepage
+    if copyright_text := component.get("copyright"):
+        package["copyrightText"] = copyright_text
+    if description := component.get("description"):
+        package["summary"] = description
+    if comment := "\n".join(
+        f"{prop['name']}: {prop.get('value', '')}"
+        for prop in component.get("properties", [])
+        if prop["name"].startswith(f"{project}:")
+    ):
+        package["comment"] = comment
+    if purl := component.get("purl"):
+        package["externalRefs"] = [
+            {"referenceCategory": "PACKAGE-MANAGER", "referenceType": "purl", "referenceLocator": purl}
+        ]
+    if package["licenseDeclared"] == "NOASSERTION" and (
+        names := [entry["license"]["name"] for entry in licenses if "license" in entry and "name" in entry["license"]]
+    ):
+        package["licenseComments"] = f"Declared in package metadata as: {'; '.join(names)}"
+    return package
+
+
+def _spdx_id(bom_ref: str) -> str:
+    # the readable part drops every other character, so refs that differ only in those share it; only the full digest,
+    # not a prefix of it, keeps their ids apart
+    readable: Final[str] = re.sub(r"[^A-Za-z0-9.]+", "-", bom_ref).strip("-")
+    return f"SPDXRef-{readable}-{hashlib.sha256(bom_ref.encode()).hexdigest()}"
+
+
+def _creation_info(metadata: Metadata, tool_creators: list[str]) -> _CreationInfo:
+    timestamp: Final[str | None] = metadata.get("timestamp")
+    # SPDX requires a creation time; without the CycloneDX one, the time of this rendering is the true one
+    created: Final[datetime] = datetime.now(UTC) if timestamp is None else datetime.fromisoformat(timestamp)
+    supplier: Final[OrganizationalEntity | None] = metadata.get("supplier")
+    organization: Final[str] = "" if supplier is None else supplier.get("name", "")
+    creators: Final[list[str]] = [f"Organization: {organization}"] if organization else []
+    creators.extend(tool_creators)
+    creators.append(f"Tool: python-sbom-{__version__}")
+    return {"created": created.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"), "creators": creators}
+
+
+def _relationships(document: Document, components: list[Component], tools: list[Component]) -> list[_Relationship]:
+    root_id: Final[str] = _spdx_id(document["metadata"]["component"]["bom-ref"])
+    relationships: Final[list[_Relationship]] = [_relationship("SPDXRef-DOCUMENT", "DESCRIBES", root_id)]
+    for parent in components:
+        parent_id = _spdx_id(parent["bom-ref"])
+        children = (child for child in parent.get("components", []) if child["type"] != "file")
+        relationships.extend(_relationship(parent_id, "CONTAINS", _spdx_id(child["bom-ref"])) for child in children)
+    for entry in document.get("dependencies", []):
+        dependent_id = _spdx_id(entry["ref"])
+        relationships.extend(
+            _relationship(dependent_id, "DEPENDS_ON", _spdx_id(dependency)) for dependency in entry.get("dependsOn", [])
+        )
+    relationships.extend(_relationship(_spdx_id(tool["bom-ref"]), "BUILD_TOOL_OF", root_id) for tool in tools)
+    return relationships
+
+
+def _relationship(element: str, kind: str, related: str) -> _Relationship:
+    return {"spdxElementId": element, "relationshipType": kind, "relatedSpdxElement": related}
+
+
+__all__ = [
+    "Spdx",
+    "render_spdx",
+]

python_sbom/_generate/__init__.py

@@ -0,0 +1 @@
+"""The pipelines that build a wheel's and an archive's SBOM from what _collect gathers, and write it."""

python_sbom/_generate/_archive.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from python_sbom._collect._archive import read_archive
+from python_sbom._collect._content import resolve_provider
+from python_sbom._collect._facts import collect_facts
+from python_sbom._collect._revision import revision_reader
+from python_sbom._collect._settings import settings_from_pyproject
+from python_sbom._collect._source import copyright_notice, hash_build_scripts
+from python_sbom._errors import SbomError
+from python_sbom._formats._json import dumps
+from python_sbom._model._archive import archive_artifact, bundled_paths
+from python_sbom._model._bom import assemble
+from python_sbom._model._content import ProviderContext
+from python_sbom._model._document import checked_contributions
+from python_sbom._model._identity import project_identity
+from python_sbom._model._names import archive_sbom_file_name
+from python_sbom._wheel._reader import open_artifact
+from python_sbom._wheel._write import append_member
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path, PurePosixPath
+
+    from python_sbom._model._content import ContentProvider
+    from python_sbom._model._inputs import BuildFacts
+    from python_sbom._model._types import Document
+
+
+def archive_sbom(  # ruff: ignore[too-many-arguments] # every command-line option reaches the build
+    root: Path,
+    archive: Path,
+    *,
+    provider: ContentProvider | str | None,
+    commit: str | None,
+    build_env: Sequence[str] | None,
+    build_scripts: Sequence[PurePosixPath],
+    output: Path | None,
+    embed: bool,
+) -> tuple[Path, str | None]:
+    name = archive_sbom_file_name(archive.name)
+    if (target := output or archive.with_name(name)).exists() and target.samefile(archive):
+        msg = f"{target} is the archive {archive} itself, refusing to overwrite it with the SBOM"
+        raise SbomError(msg)
+    facts = collect_facts(root, revision_reader(commit), path=build_env)
+    document = describe_archive(root, archive, facts=facts, provider=provider, build_scripts=build_scripts)
+    target.write_bytes(content := dumps(document))
+    if not embed:
+        return target, None
+    append_member(archive, name, content, facts.epoch)
+    return target, name
+
+
+def describe_archive(
+    root: Path,
+    archive: Path,
+    *,
+    facts: BuildFacts,
+    provider: ContentProvider | str | None,
+    build_scripts: Sequence[PurePosixPath],
+) -> Document:
+    settings = settings_from_pyproject(root)
+    content, provider_scripts = resolve_provider(provider, settings, root)
+    with open_artifact(archive) as artifact:
+        tree = read_archive(artifact)
+        project = project_identity(tree.metadata[""], settings)
+        context = ProviderContext(root=root, settings=settings, identity=project, read=artifact.provider_read)
+        built = archive_artifact(
+            archive.name,
+            tree,
+            project=project,
+            bundled_info={str(path): content.bundled_wheel(context, path) for path in bundled_paths(tree)},
+            build_scripts=hash_build_scripts(root, [*build_scripts, *provider_scripts]),
+            copyright_line=copyright_notice(root, tree.metadata[""].values("license_files")),
+        )
+        contributions = checked_contributions(content.contributions(context), content)
+    return assemble(built, project, settings, facts, contributions)
+
+
+__all__ = [
+    "archive_sbom",
+    "describe_archive",
+]

python_sbom/_generate/_embed.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING
+
+from python_sbom._collect._content import resolve_provider
+from python_sbom._collect._facts import collect_facts
+from python_sbom._collect._revision import revision_reader
+from python_sbom._collect._settings import settings_from_pyproject
+from python_sbom._collect._wheel import read_wheel
+from python_sbom._formats._json import dumps
+from python_sbom._model._bom import assemble
+from python_sbom._model._content import ProviderContext
+from python_sbom._model._document import checked_contributions
+from python_sbom._model._identity import project_identity
+from python_sbom._model._wheel import wheel_artifact
+from python_sbom._wheel._reader import open_artifact
+from python_sbom._wheel._write import write_sbom
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from python_sbom._model._content import ContentProvider
+    from python_sbom._model._inputs import BuildFacts, Settings
+
+
+def embed_sbom(
+    wheel: Path,
+    root: Path,
+    *,
+    provider: ContentProvider | str | None,
+    commit: str | None,
+    build_env: Sequence[str] | None,
+) -> str:
+    settings = settings_from_pyproject(root)
+    content, scripts = resolve_provider(provider, settings, root)
+    facts = collect_facts(root, revision_reader(commit), path=build_env)
+    return embed_into(wheel, root, settings=settings, content=content, build_scripts=scripts, facts=facts)
+
+
+def embed_into(  # ruff: ignore[too-many-arguments] # what the hook and the command line each gather their own way
+    wheel: Path,
+    root: Path,
+    *,
+    settings: Settings,
+    content: ContentProvider,
+    build_scripts: Sequence[PurePosixPath],
+    facts: BuildFacts,
+) -> str:
+    # the wheel stays open while its document is built, for its metadata, its bundled wheels and the provider to read,
+    # and is closed before it is rewritten
+    with open_artifact(wheel) as artifact:
+        tree = read_wheel(artifact, root, settings, build_scripts)
+        project = project_identity(tree.metadata, settings)
+        context = ProviderContext(root=root, settings=settings, identity=project, read=artifact.provider_read)
+        built = wheel_artifact(
+            tree,
+            project=project,
+            settings=settings,
+            bundled_info={
+                bundled.path: content.bundled_wheel(context, PurePosixPath(bundled.path)) for bundled in tree.bundled
+            },
+        )
+        contributions = checked_contributions(content.contributions(context), content)
+    return write_sbom(
+        wheel, built.sbom_file, dumps(assemble(built, project, settings, facts, contributions)), facts.epoch
+    )
+
+
+__all__ = [
+    "embed_into",
+    "embed_sbom",
+]

python_sbom/_model/__init__.py

@@ -0,0 +1 @@
+"""The CycloneDX document model: its types, its inputs and the pure functions that build it."""

python_sbom/_model/_archive.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, Final
+
+from packageurl import PackageURL
+
+from ._components import (
+    bundled_wheel_component,
+    component_from_metadata,
+    file_component,
+    mark_bundled,
+    vendored_dependencies,
+)
+from ._graph import artifact_contents
+from ._inputs import Artifact
+from ._names import archive_sbom_file_name
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from ._content import BundledWheelInfo
+    from ._identity import ProjectIdentity
+    from ._inputs import ArchiveTree, BuildScript
+    from ._types import Component
+
+
+def archive_artifact(  # ruff: ignore[too-many-arguments] # keyword-only, each a separate fact the edge read
+    name: str,
+    tree: ArchiveTree,
+    *,
+    project: ProjectIdentity,
+    bundled_info: Mapping[str, BundledWheelInfo],
+    build_scripts: list[BuildScript],
+    copyright_line: str | None,
+) -> Artifact:
+    # the archive's top-level .dist-info names the project; every other .dist-info marks a wheel bundled unpacked into
+    # its parent directory and every .whl member a bundled wheel; other files belong to the deepest distribution that
+    # holds them, or, at the top level, to the archive
+    version: Final[str] = tree.metadata[""].version
+    ref: Final[str] = PackageURL(type="generic", name=name, version=version).to_string()
+    distributions = _Distributions(tree=tree, project=project, bundled_info=bundled_info)
+    root: Final[Component] = {
+        "type": "application",
+        "bom-ref": ref,
+        "name": name,
+        "version": version,
+        "purl": ref,
+        "components": [
+            distributions.wheel(member) if member.endswith(".whl") else file_component(ref, tree.files[member])
+            for member in tree.loose
+        ],
+    }
+    components: Final[list[Component]] = [distributions.component(prefix) for prefix in sorted(tree.metadata)]
+    return Artifact(
+        root=root,
+        components=components,
+        dependencies=vendored_dependencies(artifact_contents(root, components)),
+        build_scripts=build_scripts,
+        version=version,
+        sbom_file=archive_sbom_file_name(name),
+        scope=(
+            "Components are the distributions the archive holds, as wheels or unpacked, each with its files; the"
+            " archive's own top-level files sit under the root component."
+        ),
+        workflow=("archive-build", f"build {name} and this SBOM"),
+        license_file=next(iter(tree.metadata[""].values("license_files")), None),
+        copyright=copyright_line,
+    )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _Distributions:
+    tree: ArchiveTree
+    project: ProjectIdentity
+    bundled_info: Mapping[str, BundledWheelInfo]
+
+    def component(self, prefix: str) -> Component:
+        component = component_from_metadata(self.tree.metadata[prefix])
+        if prefix:
+            # a wheel bundled unpacked, named by its directory as a .whl is by its path
+            directory = prefix.removesuffix("/")
+            mark_bundled(component, directory, self.project.property_prefix, self.bundled_info[directory])
+        component["components"] = [
+            self.wheel(name) if name.endswith(".whl") else file_component(component["bom-ref"], self.tree.files[name])
+            for name in self.tree.owned[prefix]
+        ]
+        return component
+
+    def wheel(self, name: str) -> Component:
+        return bundled_wheel_component(self.tree.bundled[name], self.project.property_prefix, self.bundled_info[name])
+
+
+def bundled_paths(tree: ArchiveTree) -> list[PurePosixPath]:
+    return [PurePosixPath(member.removesuffix("/")) for member in bundled_members(tree.loose, tree.owned)]
+
+
+def bundled_members(loose: list[str], owned: Mapping[str, list[str]]) -> list[str]:
+    # the bundled wheels in the order the components list them, which is the order they are read and a provider is asked
+    # about them: the archive's own top-level .whl members, then each wheel bundled unpacked, by its directory ending in
+    # "/", followed by the .whl members it holds
+    return [
+        *(name for name in loose if name.endswith(".whl")),
+        *(
+            member
+            for prefix in sorted(owned)
+            for member in ([prefix] if prefix else []) + [name for name in owned[prefix] if name.endswith(".whl")]
+        ),
+    ]
+
+
+__all__ = [
+    "archive_artifact",
+    "bundled_members",
+    "bundled_paths",
+]

python_sbom/_model/_bom.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, Final
+from urllib.parse import urlsplit
+
+from ._components import script_tool
+from ._document import check_refs, contributed_properties, formulation, timestamp, with_header
+from ._names import SBOM_FILE, SBOM_REPOSITORY, sbom_property
+from ._tools import tool_components
+
+if TYPE_CHECKING:
+    from ._content import Contributions
+    from ._identity import ProjectIdentity
+    from ._inputs import Artifact, BuildFacts, Settings
+    from ._types import Body, Component, Document, ExternalReference, Metadata, Property
+
+
+def assemble(
+    artifact: Artifact, project: ProjectIdentity, settings: Settings, facts: BuildFacts, contributions: Contributions
+) -> Document:
+    # what every artifact of the project carries alike: who supplies it, where its source lives and at which revision,
+    # the tools that built it and what the project contributes
+    root = _provenance(artifact, project, settings, facts, contributions)
+    components: Final[list[Component]] = [*artifact.components, *contributions.components]
+    environment, tool_dependencies = tool_components(facts)
+    tools: Final[list[Component]] = [
+        *(
+            script_tool(script.path, script.sha256, artifact.version, _file_link(project, settings, facts, script.path))
+            for script in artifact.build_scripts
+        ),
+        *environment,
+        *contributions.tools,
+    ]
+    uid, name = artifact.workflow
+    body: Final[Body] = {
+        "metadata": _metadata(tools, artifact, project, settings, facts),
+        "components": components,
+        "dependencies": [
+            {"ref": root["bom-ref"], "dependsOn": [component["bom-ref"] for component in components]},
+            *artifact.dependencies,
+            *tool_dependencies,
+            *contributions.dependencies,
+        ],
+        # what the artifact needs at run time beyond what it ships, an interpreter and the dependencies an installer
+        # resolves, is not listed
+        "compositions": [{"aggregate": "incomplete", "dependencies": [root["bom-ref"]]}],
+        "formulation": [formulation(uid, name, tools, root["bom-ref"], facts)],
+    }
+    check_refs(body)
+    return with_header(body, project.serial_namespace)
+
+
+def _provenance(
+    artifact: Artifact, project: ProjectIdentity, settings: Settings, facts: BuildFacts, contributions: Contributions
+) -> Component:
+    root = artifact.root
+    if settings.supplier is not None:
+        root["supplier"] = settings.supplier
+    if artifact.copyright is not None:
+        root["copyright"] = artifact.copyright
+    references: Final[list[ExternalReference]] = [*root.get("externalReferences", [])]
+    if project.repository and urlsplit(project.repository).netloc == "github.com":
+        references.extend([
+            {"type": "security-contact", "url": f"{project.repository}/security/policy"},
+            {"type": "advisories", "url": f"{project.repository}/security/advisories"},
+        ])
+    if artifact.license_file is not None and (
+        link := _file_link(project, settings, facts, PurePosixPath(artifact.license_file))
+    ):
+        references.append({"type": "license", "url": link})
+    properties: Final[list[Property]] = [
+        *root.get("properties", []),
+        *contributed_properties(contributions.root_properties, project.property_prefix),
+    ]
+    if (revision := facts.revision) is not None:
+        if project.repository:
+            comment = "source revision, with uncommitted changes" if revision.dirty else "exact source revision"
+            references.append({
+                "type": "vcs",
+                "url": f"{project.repository}/tree/{revision.commit}",
+                "comment": comment,
+            })
+        properties.append({"name": sbom_property(project.property_prefix, "vcs-commit"), "value": revision.commit})
+        if revision.dirty:
+            properties.append({"name": sbom_property(project.property_prefix, "vcs-dirty"), "value": "true"})
+    root["externalReferences"] = references
+    root["properties"] = properties
+    return root
+
+
+def _file_link(project: ProjectIdentity, settings: Settings, facts: BuildFacts, path: PurePosixPath) -> str | None:
+    if project.repository is None:
+        return None
+    # the commit of a clean checkout holds the file as it was built; with no commit, or uncommitted changes, the default
+    # branch is where the file most likely still lives
+    revision = facts.revision
+    tree = settings.default_branch if revision is None or revision.dirty else revision.commit
+    return f"{project.repository}/blob/{tree}/{path}"
+
+
+def _metadata(
+    tools: list[Component],
+    artifact: Artifact,
+    project: ProjectIdentity,
+    settings: Settings,
+    facts: BuildFacts,
+) -> Metadata:
+    metadata: Final[Metadata] = {
+        "timestamp": timestamp(facts),
+        "lifecycles": [{"phase": "build"}],
+        "tools": {"components": tools},
+        "component": (root := artifact.root),
+    }
+    if settings.supplier is not None:
+        metadata["manufacturer"] = metadata["supplier"] = settings.supplier
+    if "authors" in root:
+        metadata["authors"] = root["authors"]
+    if "licenses" in root:
+        metadata["licenses"] = root["licenses"]
+    properties: Final[list[Property]] = [
+        {"name": sbom_property(project.property_prefix, "sbom:scope"), "value": artifact.scope},
+        # names the document's file, which marks it as one python-sbom built, so validation checks it in full
+        {"name": sbom_property(project.property_prefix, SBOM_FILE), "value": artifact.sbom_file},
+    ]
+    if project.repository is not None:
+        properties.append({
+            "name": sbom_property(project.property_prefix, SBOM_REPOSITORY),
+            "value": project.repository,
+        })
+    metadata["properties"] = properties
+    return metadata
+
+
+__all__ = [
+    "assemble",
+]