# 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-05-10

## 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 [mikebom](https://github.com/kusari-sandbox/mikebom) with deps.dev enrichment for license and dependency resolution. The generation process runs weekly and supports **all ecosystems** that mikebom 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 [mikebom](https://github.com/kusari-sandbox/mikebom) (v0.1.0-alpha.16)
- 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
│   ├── 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)
    │   └── 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
    ├── 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 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`, or `discovered` | all |

**How it works:**
1. Prepares a matrix of repositories from `cncf-projects.yaml` and `discovered-repos.yaml`
2. Each matrix job downloads mikebom and generates SBOMs using `mikebom 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. No files are committed to the repository

### 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`

### Required GitHub Secrets & Variables

The following must be configured in the repository settings:

**Secrets:**

| Secret | Description |
|--------|-------------|
| `OCI_S3_ACCESS_KEY` | S3-compatible access key for OCI Object Storage |
| `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` |

### 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

## 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.

## 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)
- mikebom (auto-downloaded by the script, or install manually)

> **Note:** Go is no longer required for SBOM generation. mikebom 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) |
| `MIKEBOM_VERSION` | mikebom release version to use (default: v0.1.0-alpha.16) |

## 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: mikebom-0.1.0-alpha.16`
- Scope annotation (manifest vs artifact SBOM)
- Per-component `mikebom: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

### mikebom Installation

mikebom is a precompiled binary — no build step required:

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

# Or install manually
curl -sL https://github.com/kusari-sandbox/mikebom/releases/download/v0.1.0-alpha.16/mikebom-v0.1.0-alpha.16-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo cp mikebom-v0.1.0-alpha.16-x86_64-unknown-linux-gnu/mikebom /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 mikebom 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.