# sbom

**Repository Path**: cncf/sbom

## Basic Information

- **Project Name**: sbom
- **Description**: House of SBOMs (and tooling)
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-19
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CNCF Projects Supply Chain & SBOM Generator

## ⚠️ DISCLAIMER

**IMPORTANT NOTICE:**

The Software Bill of Materials (SBOM) files generated by this project are **automatically generated** by the CNCF and are **NOT official SBOMs** provided by the individual CNCF projects themselves.

1. **No Warranty**: These SBOMs are provided "AS IS" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement.

2. **No Guarantee of Completeness or Accuracy**: We make no representations or guarantees regarding the completeness, accuracy, reliability, or currentness of the information contained in these SBOMs. The automated generation process may miss dependencies, include incorrect versions, or contain other errors.

3. **Use at Your Own Risk**: Any use of these SBOMs is entirely at your own risk. This project, its contributors, and maintainers shall not be liable for any claims, damages, or other liability arising from the use of these SBOMs.

4. **Not a Substitute for Official SBOMs**: For production use, compliance requirements, or security audits, please refer to the official documentation and releases of each individual CNCF project.

5. **Automated Generation**: These SBOMs are generated using [Waybill](https://github.com/kusari-oss/waybill) (formerly Mikebom) with deps.dev enrichment for license and dependency resolution. The generation process runs weekly and supports **all ecosystems** that Waybill can detect (Go, Rust, npm, Python, Java/Maven, Ruby, and more).

---

## Overview

This tool generates Software Bill of Materials (SBOM) in SPDX JSON format for CNCF projects and uploads them to OCI-compatible S3 storage.

The SBOM generator:
- Automatically syncs the list of CNCF projects from the [CNCF Landscape](https://landscape.cncf.io)
- Discovers additional subproject repositories within CNCF GitHub organizations
- Fetches stable releases (major, minor, patch) from CNCF project repositories
- Supports **all ecosystems** with lockfile-aware dependency graph extraction (Go, Rust, npm, Python, Maven, Ruby, etc.)
- Skips alpha, beta, RC, and other pre-release versions
- Generates SPDX 2.3-compliant SBOM files using [Waybill](https://github.com/kusari-oss/waybill) (v0.2.0)
- Automatically enriches SBOMs with license information via [deps.dev](https://deps.dev) and [ClearlyDefined](https://clearlydefined.io)
- Extracts real dependency graph edges (not a flat fan-out) from lockfiles
- **Uploads SBOMs directly to OCI S3-compatible buckets** (no SBOM files are stored in this repository)

## Storage

Generated SBOMs are stored in two OCI S3-compatible buckets:

| Bucket | Content |
|--------|---------|
| `cncf-project-sboms` | Official CNCF project SBOMs |
| `cncf-subproject-sboms` | Subproject / discovered repo SBOMs |

### S3 Object Naming Convention

**Projects:**
```
<project>/<version>/<project>_<version>_spdx.json
```
Example: `coredns/1.12.0/coredns_1_12_0_spdx.json`

**Subprojects:**
```
<parent-project>/<repo>/<version>/<parent-project>_<repo>_<version>_spdx.json
```
Example: `higress/IOC-golang/1.0.0/higress_ioc-golang_1_0_0_spdx.json`

> **Note:** Dots in version numbers are replaced with underscores in the filename to avoid potential issues.

## Repository Structure

This repository contains **only tooling and configuration** — no SBOM data files.

```
./
├── README.md                           # This file
├── .gitignore                          # Excludes generated SBOM data
├── .github/workflows/
│   ├── sync-cncf-projects.yml          # Sync CNCF project list from landscape
│   ├── discover-cncf-repos.yml         # Discover subproject repos in CNCF orgs
│   ├── generate-sbom.yml               # Generate SBOMs and upload to S3
│   ├── generate-tooling-sbom.yml       # Generate SBOMs for this repo's tooling and CI chain
│   ├── watch-sandbox-applications.yml  # One-time SBOMs for CNCF sandbox applications
│   ├── reusable-generate-sbom.yml      # Reusable workflow for subproject batches
│   └── migrate-sboms-to-oci.yml        # One-time migration of legacy repo SBOMs to S3
└── util/
    ├── data/
    │   ├── cncf-projects.yaml          # Auto-synced CNCF project list (DO NOT EDIT)
    │   ├── repositories.yaml          # Manually maintained additional projects
    │   └── discovered-repos.yaml       # Subproject repos found in CNCF orgs (DO NOT EDIT)
    ├── extract-projects/               # Go tool to sync projects from CNCF landscape
    ├── discover-repos/                 # Go tool to find subproject repos in CNCF orgs
    ├── generate-index/                 # Go tool to generate an index of SBOMs
    ├── generate-tooling-sbom.sh        # Generates repo-tooling and CI-chain SBOMs for this repo
    ├── ingest-sbom-oci.sh              # Script to upload local SBOMs to OCI buckets
    ├── generate-sbom-local.sh          # Local testing script (Linux/macOS)
    └── generate-sbom-local.ps1         # Local testing script (Windows)
```

## GitHub Actions Workflows

### 1. Sync CNCF Projects (`sync-cncf-projects.yml`)

Automatically syncs the list of CNCF projects from the official landscape.

- **Scheduled**: Daily at 03:00 UTC
- **Manual trigger**: Via workflow_dispatch
- **Output**: `util/data/cncf-projects.yaml`

### 2. Discover Additional Repos (`discover-cncf-repos.yml`)

Scans GitHub organizations of CNCF projects to find additional subproject repositories with releases.

- **Scheduled**: Weekly on Monday at 04:00 UTC
- **Manual trigger**: Via workflow_dispatch
- **Output**: `util/data/discovered-repos.yaml`

This workflow finds subproject repositories that:
- Belong to the same GitHub org/user as a CNCF project
- Have at least one release
- Are not forks, archived, or disabled

### 3. Generate SBOMs (`generate-sbom.yml`)

Generates SBOMs for CNCF and manually added projects and **uploads them directly to OCI S3 buckets**.

- **Scheduled**: Weekly on Sunday at 02:00 UTC (processes only releases from the past week)
- **Manual trigger**: Via workflow_dispatch with optional filters

| Input | Description | Default |
|-------|-------------|---------|
| `project_filter` | Filter by owner/repo (e.g., "coredns/coredns") | empty (all projects) |
| `force_regenerate` | Force regenerate existing SBOMs | false |
| `releases_mode` | `recent` (past week) or `latest` (N latest releases) | recent |
| `max_releases` | Max releases per repo (only for `latest` mode) | 3 |
| `source` | `all`, `cncf`, `manual`, or `discovered` | all |

**How it works:**
1. Prepares repository matrices from `cncf-projects.yaml`, the manually maintained `repositories.yaml`, and `discovered-repos.yaml`
2. Each matrix job downloads Waybill and generates SBOMs using `waybill sbom scan --format spdx-2.3-json`
3. deps.dev and ClearlyDefined enrichment runs inline (license resolution, dependency graphs)
4. Generated SBOMs are immediately uploaded to the corresponding S3 bucket
5. Each repository job writes a compact JSON report, and the workflow publishes one consolidated run summary plus a `sbom-generation-report` artifact
6. No files are committed to the repository

#### Adding a project manually

Add an entry to `util/data/repositories.yaml`:

```yaml
repositories:
  - owner: OmniTrustILM
    repo: core
    name: OmniTrust ILM
```

Entries are included in scheduled and manually triggered `source=all` runs.
Use `source=manual` to scan only this list; `cncf` and `discovered` retain their
existing scopes. Duplicate owner/repo entries in the CNCF and manual lists are
scanned once (case-insensitive, with CNCF metadata taking precedence).
Manual projects use the project bucket and the existing project-name/version
key layout. The sync and discovery workflows do not overwrite this list.

For the first scan of an older release, run the generation workflow with
`source=manual`, `project_filter=OmniTrustILM/core`, and `releases_mode=latest`.
Scheduled runs keep the existing recent-release selection; adding an entry
does not itself trigger a run or backfill older releases.
The local Bash and PowerShell generators also read `repositories.yaml`.

### 4. Migrate SBOMs to OCI (`migrate-sboms-to-oci.yml`)

One-time / on-demand migration of any legacy SBOM files from the repository into OCI S3 buckets.

- **Manual trigger only**: Via workflow_dispatch
- Skips objects that already exist in the bucket (unless `FORCE` is set)
- Uses `util/ingest-sbom-oci.sh`

### 5. Generate Tooling SBOM (`generate-tooling-sbom.yml`)

Generates SBOMs for this repository's own tooling on every push, pull request, and manual run.

- **Triggers**: `push`, `pull_request`, `workflow_dispatch`
- **Artifact**: `tooling-sbom-<git-sha>`
- **Tracked files on `main`**:
  - [`tooling-sbom/tooling-repo.spdx.json`](./tooling-sbom/tooling-repo.spdx.json)
  - [`tooling-sbom/tooling-ci.spdx.json`](./tooling-sbom/tooling-ci.spdx.json)
- **Files**:
  - `tooling-repo.spdx.json` — Waybill-generated SBOM for this repository at the checked-out commit
  - `tooling-ci.spdx.json` — SPDX inventory of the GitHub Actions and downloaded tools involved in SBOM generation

This separates the repository source inventory from the CI/generation chain, so the SBOM production tooling is captured explicitly as part of the delivered artifact set.
The workflow generates files in `tooling-sbom-out/`, uploads them as an artifact for each run, and refreshes the tracked `tooling-sbom/` snapshots on pushes to `main`.

### 6. Watch Sandbox Applications (`watch-sandbox-applications.yml`)

Polls [cncf/sandbox issues](https://github.com/cncf/sandbox/issues) daily at 02:17 UTC
and on manual dispatch. Cross-repository issue creation does not directly trigger this
repository's workflows, so new applications are picked up on the next poll.

Issues must start with `[Sandbox]`. GitHub repository URLs are extracted only
from the `Project repo URL in scope of application` field. Each repository in
that field gets one SBOM per application issue; links elsewhere in the issue
are not scanned. Malformed application fields are reported in the logs.

The first run includes existing **open** applications. A persistent start
timestamp also allows subsequent polls to include newly created applications
that have already been closed. Historical closed applications are excluded.

For each unprocessed repository, the workflow selects its **latest stable
release**, falling back to the default branch if no stable release exists.
The selected ref is resolved to a commit SHA before scanning; branch snapshots
use that SHA as their version. The document name explicitly identifies the
repository and scanned version, independent of the temporary checkout directory.
No project build scripts are run.

SBOMs and processing state are stored in the dedicated **`sandbox-reviews`**
bucket, separate from CNCF project SBOMs. The optional `OCI_SANDBOX_BUCKET`
repository variable overrides this default. Application snapshots use the prefix:

```text
sandbox-applications/<issue-number>/<owner>/<repo>.spdx.json
```

For example, application #525 for KubeRay produces
`sandbox-applications/525/ray-project/kuberay.spdx.json`. The key remains stable
even if new releases appear: a successfully uploaded SBOM marks that
issue/repository as processed. Failed scans or uploads are retried on subsequent
polls. Workflow runs are serialized, with up to five repository scans in parallel;
more than 256 pending repositories are deferred to subsequent runs.

The timestamp is stored in the same sandbox bucket at
`sandbox-applications/.started-at` (not an SBOM).
Keep this state and the uploaded snapshots to preserve one-time processing.
The S3 key needs list, read, and write access to this prefix; access errors stop
discovery rather than being interpreted as empty state. The scan step receives
no S3 credentials. Generated SBOMs and their resolved revision metadata are also
retained as GitHub Actions artifacts for seven days.

### Required GitHub Secrets & Variables

The following must be configured in the repository settings:

**Secrets:**

| Secret | Description |
|--------|-------------|
| `OCI_S3_ACCESS_KEY` | S3-compatible access key with `PutObject` permission for the configured project, subproject, and sandbox buckets |
| `OCI_S3_SECRET_KEY` | S3-compatible secret key for OCI Object Storage |

**Variables:**

| Variable | Description | Example |
|----------|-------------|---------|
| `OCI_S3_ENDPOINT` | S3-compatible endpoint URL | `https://axtwf1hkrwcy.compat.objectstorage.us-sanjose-1.oraclecloud.com` |
| `OCI_S3_REGION` | S3 region | `us-sanjose-1` |
| `OCI_PROJECT_BUCKET` | Bucket name for project SBOMs | `cncf-project-sboms` |
| `OCI_SUBPROJECT_BUCKET` | Bucket name for subproject SBOMs | `cncf-subproject-sboms` |
| `OCI_SANDBOX_BUCKET` | Optional sandbox application bucket override (default: `sandbox-reviews`) | `sandbox-reviews` |

#### Troubleshooting upload failures

Upload failures fail the generation job, including partially successful uploads.
The logs show the target bucket/key, AWS CLI exit code and diagnostic output;
the `uploaded` output counts only successful uploads.

On S3-compatible storage, an error response with an empty `Message` can cause AWS
CLI to print `argument of type 'NoneType' is not a container or iterable` instead
of the service error. This has been reproduced with HTTP 403 `AccessDenied`.
Check the permissions and bucket policy for the S3 key stored in GitHub's
`OCI_S3_ACCESS_KEY` / `OCI_S3_SECRET_KEY` secrets. Successful read access does not
establish `PutObject` permission. Manually listed projects use `OCI_PROJECT_BUCKET`,
the same bucket as CNCF projects.

### Running the Workflow Manually

1. Go to Actions tab in GitHub
2. Select "Generate SBOM for CNCF Projects"
3. Click "Run workflow"
4. Optionally specify a project filter or change the releases mode

The workflow summary stays compact on purpose: detailed per-repository results are collected in the `sbom-generation-report` artifact instead of emitting a large per-matrix GitHub UI summary.

## Utility Tools

### extract-projects

Go tool that downloads the CNCF landscape and extracts all projects with status `graduated`, `incubating`, or `sandbox`.

```bash
cd util/extract-projects
go run . ../data/cncf-projects.yaml
```

### discover-repos

Go tool that scans GitHub organizations of CNCF projects to find additional subproject repositories with releases.

```bash
cd util/discover-repos
go run . /path/to/cncf-automation
```

The tool will:
- Read the list of CNCF projects from `cncf-projects.yaml`
- Scan each unique GitHub organization/user
- Find subproject repos that have releases and contain `go.mod`
- Output results to `discovered-repos.yaml`

### ingest-sbom-oci.sh

Script to upload local SBOM files to OCI S3 buckets. Supports both OCI CLI and S3-compatible auth modes.

```bash
# Using S3 auth (recommended for CI)
./util/ingest-sbom-oci.sh \
  --auth-mode s3 \
  --s3-endpoint https://axtwf1hkrwcy.compat.objectstorage.us-sanjose-1.oraclecloud.com \
  --s3-access-key "$ACCESS_KEY" \
  --s3-secret-key "$SECRET_KEY"

# Dry run to preview uploads
./util/ingest-sbom-oci.sh --dry-run

# Force overwrite existing objects
./util/ingest-sbom-oci.sh --force
```

Credentials can also be provided via environment variables or a `.env.sbom` / `.env` file.

### generate-tooling-sbom.sh

Generates the repository's own tooling SBOM plus a second SPDX document for the GitHub Actions and downloaded tools that form the SBOM generation chain.

```bash
# Full output (requires waybill in PATH)
./util/generate-tooling-sbom.sh

# Only regenerate the CI/generation-chain SBOM
./util/generate-tooling-sbom.sh --skip-repo-sbom

# Write directly into the tracked repo snapshot directory
./util/generate-tooling-sbom.sh --output-dir tooling-sbom
```

## Local Testing

### Prerequisites

- git
- [GitHub CLI (gh)](https://cli.github.com/)
- [jq](https://stedolan.github.io/jq/) (for bash script)
- [yq](https://github.com/mikefarah/yq)
- Waybill (auto-downloaded by the script, or install manually)

> **Note:** Go is no longer required for SBOM generation. Waybill is a precompiled Rust binary.

### Bash Script (Linux/macOS/WSL)

```bash
# Process all projects
./util/generate-sbom-local.sh

# Process specific repo
./util/generate-sbom-local.sh coredns/coredns

# Force regenerate
./util/generate-sbom-local.sh --force coredns/coredns

# Set max releases per repo (default: 3)
MAX_RELEASES=5 ./util/generate-sbom-local.sh
```

### PowerShell Script (Windows)

```powershell
# Process all projects
.\util\generate-sbom-local.ps1

# Process specific repo
.\util\generate-sbom-local.ps1 -ProjectFilter "coredns/coredns"

# Force regenerate
.\util\generate-sbom-local.ps1 -Force -ProjectFilter "coredns/coredns"

# Set max releases per repo
.\util\generate-sbom-local.ps1 -MaxReleases 5
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `GH_TOKEN` or `GITHUB_TOKEN` | GitHub token for API access (recommended for higher rate limits) |
| `MAX_RELEASES` | Maximum releases to process per repo (default: 3, bash only) |
| `WAYBILL_VERSION` | Waybill release version to use (default: v0.2.0) |

## Project List

CNCF projects are **automatically synced** from the official [CNCF Landscape](https://landscape.cncf.io).

Projects with the following status are included:
- `graduated`
- `incubating`
- `sandbox`

> **Note:** You do not need to manually add projects. The sync workflow runs daily and updates the project list automatically. If a project is missing, ensure it is properly listed in the CNCF Landscape with the correct project status.

## Release Filtering

The generator only processes stable releases:

**Included:**
- Full releases (e.g., v1.0.0, v2.5.3)
- Releases marked as non-prerelease and non-draft in GitHub

**Excluded:**
- Alpha releases (e.g., v1.0.0-alpha.1)
- Beta releases (e.g., v1.0.0-beta.2)
- Release candidates (e.g., v1.0.0-rc1)
- Development versions (e.g., v1.0.0-dev)
- Snapshots, nightly, canary builds
- Draft releases

## SBOM Format

Generated SBOMs are in SPDX 2.3 JSON format, containing:
- Package information with real dependency relationships (not flat fan-out)
- SHA-256 content hashes on every component
- License information enriched via deps.dev and ClearlyDefined
- Dependency relationships extracted from lockfiles (go.sum, Cargo.lock, package-lock.json, etc.)
- Per-component evidence blocks with confidence scoring

### Example SBOM Metadata

Each SBOM includes:
- SPDX 2.3 document information
- Creator: `Tool: waybill-0.2.0`
- Scope annotation (manifest vs artifact SBOM)
- Per-component `waybill:sbom-tier` annotations (source, deployed, analyzed, etc.)

## Troubleshooting

### Rate Limiting

If you encounter GitHub API rate limits:
1. Set the `GH_TOKEN` environment variable with a valid GitHub token
2. Run `gh auth login` to authenticate the GitHub CLI

### Waybill Installation

Waybill is a precompiled binary — no build step required:

```bash
# The local script auto-downloads Waybill if not found in PATH
./util/generate-sbom-local.sh

# Or install manually
curl -sL https://github.com/kusari-oss/waybill/releases/download/v0.2.0/waybill-v0.2.0-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo cp waybill-v0.2.0-x86_64-unknown-linux-gnu/waybill /usr/local/bin/
```

### Clone Failures

Some repositories may have protected tags or require authentication. The script will skip these and continue with other releases.

### Enrichment Timeouts

deps.dev and ClearlyDefined enrichment runs inline. If network is slow, scans may take longer (2-5 minutes per repo is normal). Use `--offline` flag with Waybill to skip enrichment for faster but less complete SBOMs.

### S3 Upload Issues

If uploads fail with `MissingContentLength`, ensure the AWS CLI version is up to date and the `AWS_REQUEST_CHECKSUM_CALCULATION=when_required` environment variable is set.

## Contributing

1. Fork the repository
2. Make your changes
3. Test locally with the provided scripts
4. Submit a pull request

For issues with specific CNCF projects, please contact the respective project maintainers directly.