CyberMind-FR 8769a60275 feat(sbom): Add CRA Annex I compliant SBOM pipeline

Implements comprehensive Software Bill of Materials generation for
EU Cyber Resilience Act compliance with ANSSI CSPN certification path.

SBOM Pipeline:
- scripts/check-sbom-prereqs.sh: Prerequisites validation (OpenWrt, tools, Kconfig)
- scripts/sbom-generate.sh: Multi-source SBOM generation (native, feed, rootfs, firmware)
- scripts/sbom-audit-feed.sh: PKG_HASH/PKG_LICENSE feed audit with MANIFEST.md
- Makefile: SBOM targets (sbom, sbom-quick, sbom-validate, sbom-scan, sbom-audit)
- .github/workflows/sbom-release.yml: CI with CVE gating and auto-security issues

Documentation:
- SECURITY.md: CRA Art. 13 §6 compliant vulnerability disclosure policy
- docs/sbom-pipeline.md: Architecture, CRA mapping, ANSSI CSPN guidance

AI Gateway (bonus feed):
- secubox-ai-gateway: 3-tier data classification (LOCAL_ONLY/SANITIZED/CLOUD_DIRECT)
- luci-app-ai-gateway: LuCI dashboard with provider management and audit logging

Output formats: CycloneDX 1.6 (primary) + SPDX 2.3 (secondary)
Tools: syft, grype, cyclonedx-cli (auto-installed if missing)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-03-04 08:01:00 +01:00

11 KiB

Raw Blame History

SecuBox SBOM Pipeline Documentation

Overview

The SecuBox SBOM (Software Bill of Materials) pipeline generates CycloneDX 1.6 and SPDX 2.3 compliant SBOMs for EU Cyber Resilience Act (CRA) Annex I compliance.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         SecuBox SBOM Pipeline                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│   │   Source A  │    │   Source B  │    │   Source C  │    │   Source D  │  │
│   │  OpenWrt    │    │   SecuBox   │    │   Rootfs    │    │  Firmware   │  │
│   │  Native     │    │   Feed      │    │   Scan      │    │   Image     │  │
│   │             │    │             │    │             │    │             │  │
│   │ Packages    │    │ Makefiles   │    │ Syft scan   │    │ Syft scan   │  │
│   │ .manifest   │    │ PKG_* vars  │    │ dir:rootfs  │    │ file:*.bin  │  │
│   └──────┬──────┘    └──────┬──────┘    └──────┬──────┘    └──────┬──────┘  │
│          │                  │                  │                  │         │
│          └──────────────────┴──────────────────┴──────────────────┘         │
│                                    │                                         │
│                                    ▼                                         │
│                          ┌─────────────────┐                                 │
│                          │   Merge & Dedup │                                 │
│                          │   (jq fusion)   │                                 │
│                          └────────┬────────┘                                 │
│                                   │                                          │
│                                   ▼                                          │
│                          ┌─────────────────┐                                 │
│                          │    Validate     │                                 │
│                          │ cyclonedx-cli   │                                 │
│                          └────────┬────────┘                                 │
│                                   │                                          │
│                    ┌──────────────┼──────────────┐                           │
│                    ▼              ▼              ▼                           │
│             ┌───────────┐  ┌───────────┐  ┌───────────┐                      │
│             │ CVE Scan  │  │ CRA Report│  │ Checksums │                      │
│             │  (grype)  │  │  Summary  │  │ sha256sum │                      │
│             └───────────┘  └───────────┘  └───────────┘                      │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Output Files:
├── secubox-VERSION.cdx.json          # CycloneDX 1.6 (primary)
├── secubox-VERSION.spdx.json         # SPDX 2.3 (alternative)
├── secubox-VERSION-cve-report.json   # Grype CVE scan results
├── secubox-VERSION-cve-table.txt     # Human-readable CVE table
├── secubox-VERSION-cra-summary.txt   # CRA compliance summary
├── sbom-warnings.txt                 # Missing metadata warnings
└── checksums.sha256                  # File integrity checksums

Prerequisites

Minimum Versions

Tool	Minimum Version	Purpose
OpenWrt	22.03	Native SBOM support
Perl	5.26+	package-metadata.pl
jq	1.6+	JSON processing
Syft	0.100+	Filesystem scanning
Grype	0.70+	CVE scanning
cyclonedx-cli	0.25+	SBOM validation

Environment Setup

# Check prerequisites
./scripts/check-sbom-prereqs.sh

# Install SBOM tools (if not present)
# Syft
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b ~/.local/bin

# Grype
curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b ~/.local/bin

# cyclonedx-cli
curl -sSfL -o ~/.local/bin/cyclonedx-cli \
  https://github.com/CycloneDX/cyclonedx-cli/releases/latest/download/cyclonedx-linux-x64
chmod +x ~/.local/bin/cyclonedx-cli

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

OpenWrt Kconfig

Enable native SBOM generation in .config:

CONFIG_JSON_CYCLONEDX_SBOM=y
CONFIG_COLLECT_KERNEL_DEBUG=n

Usage

Daily Development

# Full SBOM generation (all 4 sources)
./scripts/sbom-generate.sh

# Quick SBOM from existing artifacts (no rebuild)
./scripts/sbom-generate.sh --version 0.20

# Offline mode (no network, uses cached databases)
./scripts/sbom-generate.sh --offline

# Skip CVE scan (faster)
./scripts/sbom-generate.sh --no-cve

Using Makefile Targets

# Full build + SBOM
make sbom

# SBOM only (no rebuild)
make sbom-quick

# Validate existing SBOM
make sbom-validate

# CVE scan only
make sbom-scan

# Clean SBOM outputs
make sbom-clean

# Show help
make sbom-help

Audit Feed Packages

# Check all SecuBox feed packages for missing metadata
./scripts/sbom-audit-feed.sh

# Output: feeds/secubox/MANIFEST.md

Adding a New Package

When adding a new package to the SecuBox feed, ensure SBOM compatibility:

Checklist

PKG_NAME defined
PKG_VERSION defined
PKG_LICENSE defined (SPDX identifier)
PKG_HASH defined (sha256)
PKG_SOURCE_URL defined (optional but recommended)

Example Makefile

include $(TOPDIR)/rules.mk

PKG_NAME:=my-package
PKG_VERSION:=1.0.0
PKG_RELEASE:=1

PKG_SOURCE_URL:=https://github.com/example/my-package/archive
PKG_SOURCE:=$(PKG_NAME)-$(PKG_VERSION).tar.gz
PKG_HASH:=a1b2c3d4e5f6...  # sha256sum of the source tarball

PKG_LICENSE:=MIT
PKG_LICENSE_FILES:=LICENSE

PKG_MAINTAINER:=Your Name <email@example.com>

Compute PKG_HASH

# Download and hash the source
wget https://example.com/package-1.0.0.tar.gz
sha256sum package-1.0.0.tar.gz

# Or use the OpenWrt download helper
make package/my-package/download V=s
sha256sum dl/my-package-1.0.0.tar.gz

CRA Annex I Mapping

CRA Requirement	SBOM Implementation
Art. 13(5) - Component identification	`components[].purl` (Package URL)
Art. 13(5) - Supplier identification	`metadata.component.supplier`
Art. 13(5) - Version information	`components[].version`
Art. 13(5) - Dependencies	`dependencies[]` array
Art. 13(5) - License information	`components[].licenses[]`
Art. 13(6) - Machine-readable format	CycloneDX 1.6 JSON + SPDX 2.3
Art. 13(6) - Vulnerability disclosure	SECURITY.md + VEX documents
Art. 13(7) - Unique identification	PURL + `serialNumber` UUID
Annex I(2) - Integrity verification	`hashes[]` with SHA-256

ANSSI CSPN Submission

For CSPN certification, include the following in your dossier:

Required Documents

SBOM Files
- secubox-VERSION.cdx.json (primary)
- secubox-VERSION.spdx.json (alternative)
Provenance
- checksums.sha256 (integrity verification)
- Git commit hash from metadata
Vulnerability Analysis
- secubox-VERSION-cve-report.json
- secubox-VERSION-cra-summary.txt
Process Documentation
- This document (docs/sbom-pipeline.md)
- SECURITY.md (vulnerability disclosure policy)

Submission Checklist

All components have PKG_HASH and PKG_LICENSE
SBOM validates with cyclonedx-cli
No unaddressed Critical CVEs
VEX document explains any accepted risks
SOURCE_DATE_EPOCH reproducibility verified

Troubleshooting

Common Errors

"OpenWrt version < 22.03"

The native CycloneDX SBOM support requires OpenWrt 22.03 or later.

Solution: Upgrade your OpenWrt fork or use sbom-generate.sh without native support (it will fall back to Makefile parsing).

"package-metadata.pl not found"

The SBOM generation script is missing from your OpenWrt checkout.

Solution:

git checkout origin/master -- scripts/package-metadata.pl

"syft: command not found"

Syft is not installed or not in PATH.

Solution:

curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

"SBOM validation failed"

The generated SBOM has schema errors.

Solution:

Check sbom-warnings.txt for missing metadata
Fix Makefiles with missing PKG_HASH or PKG_LICENSE
Regenerate SBOM

"Grype database update failed"

Network connectivity issue or rate limiting.

Solution:

Use --offline mode with cached database
Or manually update: grype db update

Debug Mode

# Verbose output
DEBUG=1 ./scripts/sbom-generate.sh

# Keep intermediate files
KEEP_TEMP=1 ./scripts/sbom-generate.sh

Version History

Version	Date	Changes
1.0	2026-03-04	Initial pipeline implementation

Maintained by CyberMind Produits SASU Contact: secubox@cybermind.fr

11 KiB Raw Blame History

SecuBox SBOM Pipeline Documentation

Overview

Architecture

Prerequisites

Minimum Versions

Environment Setup

OpenWrt Kconfig

Usage

Daily Development

Using Makefile Targets

Audit Feed Packages

Adding a New Package

Checklist

Example Makefile

Compute PKG_HASH

CRA Annex I Mapping

ANSSI CSPN Submission

Required Documents

Submission Checklist

Troubleshooting

Common Errors

"OpenWrt version < 22.03"

"package-metadata.pl not found"

"syft: command not found"

"SBOM validation failed"

"Grype database update failed"

Debug Mode

Version History

11 KiB

Raw Blame History