Add Software Bill of Materials guide to the Documentation

lib/elixir/pages/references/sbom.md

@@ -0,0 +1,149 @@
+<!--
+  SPDX-License-Identifier: Apache-2.0
+  SPDX-FileCopyrightText: 2021 The Elixir Team
+-->
+
+# Software Bill of Materials
+
+A Software Bill of Materials (SBoM) is a structured inventory of the components that make up a software system. This guide explains what SBoMs are, why they matter, and how to generate them for Elixir projects.
+
+## What is an SBoM?
+
+An SBoM is a formal, machine-readable record of all components in a piece of software. Think of it as a detailed ingredient list for your application. A typical SBoM includes:
+
+  * **Dependencies**: all libraries and packages your project uses
+  * **Versions**: the exact version of each component
+  * **Source locations**: where each component was obtained (Hex, GitHub, etc.)
+  * **Checksums**: cryptographic hashes to verify integrity
+  * **Licensing information**: the license under which each component is distributed
+
+Two widely adopted standards exist for SBoM formats:
+
+  * [CycloneDX](https://cyclonedx.org/): a lightweight standard designed for security contexts
+  * [SPDX](https://spdx.dev/): a more comprehensive standard originally focused on licensing
+
+Both formats are machine-readable (JSON, XML) and designed to be consumed by automated tooling.
+
+> #### SBoM is an inventory, not a certification {: .info}
+>
+> An SBoM does not claim that software is secure, compliant, or free of vulnerabilities.
+> It simply provides a detailed inventory that enables further analysis. Security and
+> compliance assessments are performed by separate tools that consume the SBoM.
+
+## Why generate SBoMs?
+
+There are three main reasons to generate SBoMs for your projects.
+
+### Vulnerability analysis
+
+When a security vulnerability (CVE) is discovered in a library, you need to quickly determine if your projects are affected. SBoMs make this possible by providing a complete inventory of your dependencies.
+
+Tools like [OWASP Dependency-Track](https://dependencytrack.org/) continuously monitor your SBoMs against vulnerability databases. When a new CVE is published, you get notified if any of your projects use the affected component.
+
+Without an SBoM, answering "are we affected by CVE-2024-XXXXX?" means manually checking each project, which is time-consuming and error-prone.
+
+### Regulatory requirements
+
+SBoMs are required by some regulations and procurement policies:
+
+  * **US Executive Order 14028** (2021) requires SBoMs for certain software supplied to the U.S. federal government, particularly for designated critical software
+  * **EU Cyber Resilience Act** introduces requirements for component inventories (commonly fulfilled using SBoMs) for products with digital elements placed on the EU market
+  * **Safety-critical industries** (medical devices, automotive, aerospace) often require detailed component inventories as part of certification
+
+Customers and partners may also request SBoMs as part of their own compliance efforts.
+
+### License compliance
+
+Every dependency in your project comes with a license. An SBoM provides a starting point for license review by listing the declared license for each package. This helps you:
+
+  * Get an overview of licenses in your dependency tree
+  * Flag packages that may need closer review
+  * Support due diligence for acquisitions, audits, or legal review
+
+Note that package-level license information (as provided by mix_sbom) reflects what the package declares, not necessarily all licenses present in its source files. For thorough license compliance, file-level scanning tools like ORT provide deeper analysis.
+
+## Generating SBoMs with mix_sbom
+
+[mix_sbom](https://github.com/erlef/mix_sbom) is an EEF project that generates CycloneDX SBoMs for Elixir projects.
+
+### Installation
+
+There are several ways to install mix_sbom:
+
+  * **As a project dependency**: add `sbom` to your `mix.exs`
+  * **As a global escript**: run `mix escript.install hex sbom` (requires Elixir 1.19.4+)
+  * **As a standalone binary**: download from the [releases page](https://github.com/erlef/mix_sbom/releases)
+
+The standalone binary is useful for CI environments or when you don't want to modify your project's dependencies. It requires no local Elixir or Erlang installation.
+
+### Basic usage
+
+To generate an SBoM for your project using the standalone binary:
+
+```console
+$ mix_sbom cyclonedx /path/to/your/project
+```
+
+This creates a `bom.cdx.json` file in CycloneDX format containing your project's complete dependency tree.
+
+### Common options
+
+The most useful options are:
+
+  * `-o, --output PATH`: specify the output file (default: `bom.cdx.json`)
+  * `-t, --format FORMAT`: output format (`json`, `xml`, or `protobuf`)
+  * `-s, --schema VERSION`: CycloneDX schema version
+
+For example, to generate an XML format SBoM:
+
+```console
+$ mix_sbom cyclonedx --format xml --output sbom.xml /path/to/project
+```
+
+## CI integration
+
+For automated SBoM generation, mix_sbom provides a GitHub Action:
+
+```yaml
+name: Generate SBoM
+on:
+  release:
+    types: [published]
+
+jobs:
+  sbom:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: erlef/mix_sbom@v0
+        with:
+          path: "."
+          format: "json"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sbom
+          path: bom.cdx.json
+```
+
+This workflow generates an SBoM whenever you publish a release and uploads it as a build artifact. See the [action's documentation](https://github.com/erlef/mix_sbom) for additional options.
+
+## Deeper analysis with ORT
+
+mix_sbom provides package-level license information based on what each dependency declares. However, some compliance workflows require file-level scanning. A package might declare an MIT license but contain individual files under different licenses, or include vendored code with its own licensing terms.
+
+The [OSS Review Toolkit (ORT)](https://oss-review-toolkit.org/) addresses this by scanning actual source files for license headers and copyright notices. ORT supports Mix projects and provides:
+
+  * **File-level license detection**: scans source code for license texts and SPDX identifiers
+  * **Copyright holder identification**: extracts copyright notices from files
+  * **Policy enforcement**: define rules for allowed and denied licenses
+  * **Multi-ecosystem support**: analyze projects that span multiple package managers
+
+For organizations with strict compliance requirements, ORT complements mix_sbom by providing the deeper analysis needed for thorough license audits.
+
+See the [ORT Mix plugin documentation](https://oss-review-toolkit.org/ort/docs/plugins/package-managers/Mix) for details.
+
+## Next steps
+
+  * [CycloneDX Specification](https://cyclonedx.org/specification/overview/): learn more about the SBoM format
+  * [OWASP Dependency-Track](https://dependencytrack.org/): continuous SBoM analysis platform
+  * [mix_sbom documentation](https://hexdocs.pm/sbom): full documentation and advanced options

lib/elixir/scripts/elixir_docs.exs

@@ -61,6 +61,7 @@ canonical = System.fetch_env!("CANONICAL")
     "lib/elixir/pages/references/operators.md",
     "lib/elixir/pages/references/patterns-and-guards.md",
     "lib/elixir/pages/references/syntax-reference.md",
+    "lib/elixir/pages/references/sbom.md",
     "lib/elixir/pages/references/typespecs.md",
     "lib/elixir/pages/references/unicode-syntax.md",
     "lib/elixir/pages/mix-and-otp/introduction-to-mix.md",