From 122a72f769e838399c6a6665c8eb241e9feece35 Mon Sep 17 00:00:00 2001 From: Ritesh Noronha Date: Sun, 19 Oct 2025 12:54:37 -0700 Subject: [PATCH 1/2] Update all documentation --- .DS_Store | Bin 6148 -> 6148 bytes README.md | 509 +++--------- docs/Features.md | 771 ------------------ .../compliance.md} | 6 +- .../{dtrack-command.md => commands/dtrack.md} | 6 +- .../generate.md} | 6 +- docs/{ => commands}/list.md | 0 docs/{score-command.md => commands/score.md} | 8 +- docs/{share-command.md => commands/share.md} | 6 +- .../version.md} | 6 +- docs/{installation.md => getting-started.md} | 183 ++++- docs/{ => guides}/customization.md | 2 +- docs/{ => guides}/integrations.md | 280 +------ docs/{ => guides}/policy.md | 0 .../compliance-standards.md} | 0 docs/reference/quality-checks.md | 156 ++++ docs/sbom-quality.md | 214 ----- docs/score.md | 181 ---- 18 files changed, 450 insertions(+), 1884 deletions(-) delete mode 100644 docs/Features.md rename docs/{compliance-command.md => commands/compliance.md} (98%) rename docs/{dtrack-command.md => commands/dtrack.md} (98%) rename docs/{generate-command.md => commands/generate.md} (98%) rename docs/{ => commands}/list.md (100%) rename docs/{score-command.md => commands/score.md} (97%) rename docs/{share-command.md => commands/share.md} (98%) rename docs/{version-command.md => commands/version.md} (96%) rename docs/{installation.md => getting-started.md} (67%) rename docs/{ => guides}/customization.md (99%) rename docs/{ => guides}/integrations.md (67%) rename docs/{ => guides}/policy.md (100%) rename docs/{Compliance.md => reference/compliance-standards.md} (100%) create mode 100644 docs/reference/quality-checks.md delete mode 100644 docs/sbom-quality.md delete mode 100644 docs/score.md diff --git a/.DS_Store b/.DS_Store index e50837e30b40c1305568e650b79c04f630d9e1f2..02ecf54947cf37046886e54896b2e62d9c85fd15 100644 GIT binary patch delta 167 zcmZoMXfc=|&e%S&P>hv>fq{WzVxfp66OaJ{%s|Y@z#zbomQtLYl%Jn7u~6F`B*?;$ z!jR99%uo!I0I6nYC}v1x$Ym&C$YDrDm0|@-6#xa1bZjg%WuI&y!m^p0gNK8$ePiKw Y=E?jbih>}!6@WMah{0g9qsU=q0CkTeYybcN delta 113 zcmZoMXfc=|&Zs&uQP_f!fq{XQp_rk7A(bJSp*St2I5{alKL;etzyuCw{2g%+4Xe!Kk|N;dkcA{342iAf*XF3<4l_!)8a3!^{9eS{IrC diff --git a/README.md b/README.md index 764d89f..edd27aa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # sbomqs: The Comprehensive SBOM Quality & Compliance Tool - [![Go Reference](https://pkg.go.dev/badge/github.com/interlynk-io/sbomqs.svg)](https://pkg.go.dev/github.com/interlynk-io/sbomqs) [![Go Report Card](https://goreportcard.com/badge/github.com/interlynk-io/sbomqs)](https://goreportcard.com/report/github.com/interlynk-io/sbomqs) [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/interlynk-io/sbomqs/badge)](https://securityscorecards.dev/viewer/?uri=github.com/interlynk-io/sbomqs) @@ -21,58 +20,7 @@ brew install sbomqs sbomqs score your-sbom.json ``` -## Table of Contents - -- [sbomqs: The Comprehensive SBOM Quality \& Compliance Tool](#sbomqs-the-comprehensive-sbom-quality--compliance-tool) - - [Quick Start](#quick-start) - - [Table of Contents](#table-of-contents) - - [Why sbomqs?](#why-sbomqs) - - [Key Features](#key-features) - - [sbomqs Blog](#sbomqs-blog) - - [Getting Started](#getting-started) - - [Basic Usage](#basic-usage) - - [1. Check Your SBOM Quality Score](#1-check-your-sbom-quality-score) - - [2. Understand Why Your Score Is Low](#2-understand-why-your-score-is-low) - - [3. Check Compliance](#3-check-compliance) - - [Essential Commands](#essential-commands) - - [Industry Use Cases](#industry-use-cases) - - [Healthcare \& Medical Devices](#healthcare--medical-devices) - - [Automotive Industry](#automotive-industry) - - [Financial Services](#financial-services) - - [Telecommunications](#telecommunications) - - [Advanced Features](#advanced-features) - - [Compliance Validation](#compliance-validation) - - [BSI TR-03183-2 v2.0 (Latest)](#bsi-tr-03183-2-v20-latest) - - [Framing Software Component Transparency v3](#framing-software-component-transparency-v3) - - [Component Analysis](#component-analysis) - - [Integration \& Automation](#integration--automation) - - [CI/CD Pipeline Integration](#cicd-pipeline-integration) - - [Dependency-Track Integration](#dependency-track-integration) - - [Docker Container Scanning](#docker-container-scanning) - - [Customization](#customization) - - [Custom Scoring Profiles](#custom-scoring-profiles) - - [Category-Based Scoring](#category-based-scoring) - - [Output Formats](#output-formats) - - [Command Reference](#command-reference) - - [Core Commands](#core-commands) - - [Quick Examples](#quick-examples) - - [SBOM Card](#sbom-card) - - [SBOM Platform - Free Community Tier](#sbom-platform---free-community-tier) - - [Installation](#installation) - - [Recommended: Homebrew](#recommended-homebrew) - - [Using Go](#using-go) - - [Using Docker](#using-docker) - - [Pre-built Binaries](#pre-built-binaries) - - [Building from Source](#building-from-source) - - [Contributions](#contributions) - - [Community Recognition](#community-recognition) - - [Enterprise Adoptions](#enterprise-adoptions) - - [CI/CD Integrations](#cicd-integrations) - - [Package Manager Support](#package-manager-support) - - [Compliance Standards](#compliance-standards) - - [Other SBOM Open Source tools](#other-sbom-open-source-tools) - - [Contact](#contact) - - [Stargazers](#stargazers) +πŸ“š **[Full Getting Started Guide](docs/getting-started.md)** - Installation for all platforms and basic usage ## Why sbomqs? @@ -86,7 +34,7 @@ In today's software landscape, understanding and managing your software supply c ## Key Features -βœ… **Multi-Standard Support**: SPDX, CycloneDX, SWID (coming soon) +βœ… **Multi-Standard Support**: SPDX, CycloneDX βœ… **Compliance Validation**: BSI TR-03183-2 (v1.1 & v2.0), FSCT v3, OpenChain Telco, NTIA βœ… **Quality Scoring**: 0-10 scale with detailed breakdowns βœ… **Component Analysis**: List, filter, and analyze SBOM components @@ -94,344 +42,86 @@ In today's software landscape, understanding and managing your software supply c βœ… **Shareable Reports**: Generate public quality score links βœ… **Air-Gapped Support**: Works in isolated environments -## sbomqs Blog - -- [What’s Missing in Your SBOM? sbomqs list can help you in inspecting...](https://www.linkedin.com/pulse/whats-missing-your-sbom-sbomqs-list-can-help-you-inspecting-sahu-e6rcc/) -- [sbomqs scoring support for BSI-1.1 and BSI-2.0 in a summarized way](https://www.linkedin.com/pulse/sbomqs-scoring-support-bsi-11-bsi-20-summarized-way-vivek-kumar-sahu-apc8c/) - -## Getting Started - -### Basic Usage - -sbomqs makes it easy to get started with SBOM quality assessment. Here are the most common use cases: - -#### 1. Check Your SBOM Quality Score - -```bash -# Get a quick quality score (0-10 scale) -sbomqs score my-application.spdx.json - -# Output: -# 7.8 my-application.spdx.json -``` - -#### 2. Understand Why Your Score Is Low - -```bash -# Get detailed scoring breakdown -sbomqs score my-application.spdx.json --detailed - -# See which categories are affecting your score -sbomqs score my-application.spdx.json --category ntia -``` - -#### 3. Check Compliance - -```bash -# Check if your SBOM meets regulatory requirements -sbomqs compliance --bsi-v2 my-application.spdx.json -sbomqs compliance --fsct my-application.spdx.json -``` - -### Essential Commands - -Here are the commands you'll use most often: - -```bash -# Quality scoring -sbomqs score # Basic score -sbomqs score --detailed # Detailed breakdown -sbomqs score --json # JSON output for automation - -# Compliance checking -sbomqs compliance --bsi-v2 # BSI TR-03183-2 v2.0 -sbomqs compliance --fsct # FSCT v3 compliance - -# Component listing -sbomqs list --feature comp_with_licenses # Components with licenses -sbomqs list --feature comp_with_version # Components with versions - -# Sharing -sbomqs share # Get a shareable link -``` - -## Industry Use Cases - -sbomqs addresses critical needs across various industries: - -### Healthcare & Medical Devices - -The FDA requires SBOMs for medical device submissions. Use sbomqs to: - -```bash -# Validate FDA compliance requirements -sbomqs score medical-device.spdx.json --category ntia +## Documentation -# Check for components without versions (critical for vulnerability tracking) -sbomqs list medical-device.spdx.json --feature comp_with_version --missing +πŸ“š **[Getting Started](docs/getting-started.md)** - Installation and basic usage -# Generate compliance report for FDA submission -sbomqs compliance --fsct medical-device.spdx.json > fda-compliance-report.json -``` +### πŸ“– Command Reference +- **[score](docs/commands/score.md)** - Calculate SBOM quality score +- **[compliance](docs/commands/compliance.md)** - Check regulatory compliance +- **[list](docs/commands/list.md)** - List and filter components +- **[share](docs/commands/share.md)** - Generate shareable reports +- **[dtrackScore](docs/commands/dtrack.md)** - Dependency-Track integration +- **[generate](docs/commands/generate.md)** - Generate configuration files +- **[version](docs/commands/version.md)** - Version information -**Real-world example**: A medical device manufacturer uses sbomqs in their CI/CD pipeline to ensure all software releases meet FDA's SBOM requirements before submission. +### 🎯 Guides +- **[Customization](docs/guides/customization.md)** - Create custom scoring profiles +- **[Integrations](docs/guides/integrations.md)** - CI/CD and tool integrations +- **[Policy](docs/guides/policy.md)** - Policy enforcement and validation -### Automotive Industry +### πŸ“‹ Reference +- **[Quality Checks](docs/reference/quality-checks.md)** - All scoring criteria explained +- **[Compliance Standards](docs/reference/compliance-standards.md)** - BSI, NTIA, FSCT mappings -Following NHTSA's cybersecurity guidelines, automotive manufacturers need comprehensive SBOMs: +## Basic Examples +### Check SBOM Quality ```bash -# Check automotive ECU software SBOM -sbomqs score ecu-software.cdx.json --detailed +# Get a quality score (0-10) +sbomqs score -b my-app.spdx.json -# List all components with security identifiers (CPE/PURL) -sbomqs list ecu-software.cdx.json --feature comp_with_cpes --show +# See detailed breakdown +sbomqs score my-app.spdx.json -# Validate against industry standards -sbomqs compliance --bsi-v2 ecu-software.cdx.json +# Check specific category +sbomqs score my-app.spdx.json --category NTIA-minimum-elements ``` -### Financial Services - -Meeting DORA and PCI DSS requirements for software transparency: - +### Verify Compliance ```bash -# Assess payment system SBOM quality -sbomqs score payment-system.spdx.json +# BSI TR-03183-2 v2.0 +sbomqs compliance --bsi-v2 my-app.spdx.json -# Check for components with valid licenses -sbomqs list payment-system.spdx.json --feature comp_valid_licenses --show +# FSCT v3 +sbomqs compliance --fsct my-app.spdx.json -# Generate compliance evidence -sbomqs compliance --fsct payment-system.spdx.json --output-format json +# OpenChain Telco +sbomqs compliance --oct my-app.spdx.json ``` -### Telecommunications - -Ensuring critical infrastructure security: - +### Find Missing Data ```bash -# Validate NTIA minimum elements -sbomqs score --category ntia telecom-app.cdx.json +# Components without versions +sbomqs list my-app.spdx.json --feature comp_with_version --missing -# Check OpenChain Telco compliance -sbomqs compliance --telco telecom-app.cdx.json +# Components without suppliers +sbomqs list my-app.spdx.json --feature comp_with_supplier --missing ``` -## Advanced Features - -### Compliance Validation - -sbomqs supports multiple compliance standards with detailed reporting: - -#### BSI TR-03183-2 v2.0 (Latest) - -```bash -# Full compliance check with detailed report -sbomqs compliance --bsi-v2 application.spdx.json - -# Output includes: -# - Total score and breakdown -# - Required vs optional elements -# - Specific missing fields -# - Recommendations for improvement -``` - -#### Framing Software Component Transparency v3 - +### Share Results ```bash -# FSCT compliance with color-coded output -sbomqs compliance --fsct application.spdx.json --color - -# Generate machine-readable report -sbomqs compliance --fsct application.spdx.json --json > fsct-report.json +# Generate shareable link (doesn't upload SBOM content) +sbomqs share my-app.spdx.json ``` -[πŸ“– Detailed Compliance Documentation](./docs/Compliance.md) - -### Component Analysis - -Powerful filtering and analysis capabilities: - -```bash -# Find components without suppliers (supply chain risk) -sbomqs list app.spdx.json --feature comp_with_supplier --missing - -# Show all license values for validation -sbomqs list app.spdx.json --feature comp_valid_licenses --show - -# Export component list for further analysis -sbomqs list app.spdx.json --feature comp_with_purls --show --json > components.json -``` - -Available features for analysis: - -- `comp_with_supplier` - Supply chain transparency -- `comp_with_licenses` - License compliance -- `comp_valid_licenses` - License validation -- `comp_with_version` - Vulnerability management -- `comp_with_purls` - Package identification -- `comp_with_cpes` - CVE matching -- `comp_with_checksums` - Integrity verification - -[πŸ“– Detailed List Command Documentation](./docs/list.md) - -### Integration & Automation - -#### CI/CD Pipeline Integration - -```yaml -# GitHub Actions example -- name: Check SBOM Quality - run: | - sbomqs score ${{ github.workspace }}/sbom.json --json > sbom-score.json - score=$(jq '.avg_score' sbom-score.json) - if (( $(echo "$score < 7" | bc -l) )); then - echo "SBOM quality score too low: $score" - exit 1 - fi -``` - -#### Dependency-Track Integration - -```bash -# Score all projects in Dependency-Track -sbomqs dtrackScore -u "https://dtrack.company.com" \ - -k "$DT_API_KEY" \ - "project-uuid" - -# Automated labeling based on quality scores -sbomqs dtrackScore --label-prefix "sbom-quality" \ - --min-score 7.0 \ - "project-uuid" -``` - -#### Docker Container Scanning - -```bash -# Scan container SBOM -docker sbom nginx:latest | sbomqs score - - -# Batch process multiple containers -for image in $(docker images --format "{{.Repository}}:{{.Tag}}"); do - echo "Scoring $image" - docker sbom "$image" | sbomqs score - --basic -done -``` - -[πŸ“– Detailed Integration Documentation](./docs/integrations.md) - -### Customization - -#### Custom Scoring Profiles - -```bash -# Generate configuration file -sbomqs generate features > my-profile.yaml - -# Edit profile to enable/disable specific checks -# Then use custom profile -sbomqs score app.spdx.json --configpath my-profile.yaml -``` - -#### Category-Based Scoring - -```bash -# Focus on specific categories -sbomqs score app.spdx.json --category ntia # NTIA compliance only -sbomqs score app.spdx.json --category quality # Quality metrics only -sbomqs score app.spdx.json --category bsi-v2.0 # BSI v2.0 scoring -``` - -#### Output Formats - -```bash -# JSON for automation -sbomqs score app.spdx.json --json - -# Detailed table format -sbomqs score app.spdx.json --detailed - -# Basic score only -sbomqs score app.spdx.json --basic -``` - -[πŸ“– Detailed Customization Documentation](./docs/customization.md) - -## Command Reference - -### Core Commands - -| Command | Description | Documentation | -|---------|-------------|---------------| -| `score` | Calculate SBOM quality score | [Details](./docs/score-command.md) | -| `compliance` | Check regulatory compliance | [Details](./docs/compliance-command.md) | -| `list` | List and filter components | [Details](./docs/list.md) | -| `share` | Generate shareable report link | [Details](./docs/share-command.md) | -| `dtrackScore` | Dependency-Track integration | [Details](./docs/dtrack-command.md) | -| `generate` | Generate configuration files | [Details](./docs/generate-command.md) | -| `version` | Display version information | [Details](./docs/version-command.md) | - -### Quick Examples +## Industry Use Cases -```bash -# Score multiple SBOMs at once -sbomqs score *.json --basic +- **Healthcare & Medical Devices**: Meet FDA SBOM requirements for medical device submissions +- **Automotive**: Comply with NHTSA cybersecurity guidelines for vehicle software +- **Financial Services**: Support DORA and PCI DSS software transparency requirements +- **Telecommunications**: Ensure critical infrastructure security with OpenChain Telco +- **Enterprise Software**: Manage supply chain risk with comprehensive quality metrics -# Check compliance for all SBOMs in a directory -for sbom in ./sboms/*.json; do - sbomqs compliance --bsi-v2 "$sbom" > "reports/$(basename $sbom .json)-compliance.json" -done +## SBOM Platform - Free Community Tier -# Air-gapped environment usage -INTERLYNK_DISABLE_VERSION_CHECK=true sbomqs score app.spdx.json -``` +Our SBOM Automation Platform has a free community tier that provides a comprehensive solution to manage SBOMs (Software Bill of Materials) effortlessly. From centralized SBOM storage, built-in SBOM editor, vulnerability mapping and assessment, all while ensuring compliance and enhancing software supply chain security using integrated SBOM quality scores. The community tier is ideal for small teams. Learn more [here](https://www.interlynk.io/community-tier) or [Sign up](https://app.interlynk.io/auth) ## SBOM Card [![SBOMCard](https://api.interlynk.io/api/v1/badges.svg?type=hcard&project_group_id=7f52093e-3d78-49cb-aeb1-6c977de9442e )](https://app.interlynk.io/customer/products?id=7f52093e-3d78-49cb-aeb1-6c977de9442e&signed_url_params=eyJfcmFpbHMiOnsibWVzc2FnZSI6IklqUmhPRGRoTjJNNExXSXpZekl0TkdVeE9TMDVNRGxoTFRKbFpHRmlPR1ZoWldReVl5ST0iLCJleHAiOm51bGwsInB1ciI6InNoYXJlX2x5bmsvc2hhcmVfbHluayJ9fQ==--daf6585ecf8013a0b2713a5cebb28c140d29eed904b15c84c0566b9ddd334e71) -## SBOM Platform - Free Community Tier - -Our SBOM Automation Platform has a free community tier that provides a comprehensive solution to manage SBOMs (Software Bill of Materials) effortlessly. From centralized SBOM storage, built-in SBOM editor, continuous vulnerability mapping and assessment, and support for organizational policies, all while ensuring compliance and enhancing software supply chain security using integrated SBOM quality scores. The community tier is ideal for small teams. Learn more [here](https://www.interlynk.io/community-tier) or [Sign up](https://app.interlynk.io/auth) - -## Installation - -### Recommended: Homebrew - -```bash -brew tap interlynk-io/interlynk -brew install sbomqs -``` - -### Using Go - -```bash -go install github.com/interlynk-io/sbomqs@latest -``` - -### Using Docker - -```bash -docker run -v $(pwd):/app ghcr.io/interlynk-io/sbomqs score /app/your-sbom.json -``` - -### Pre-built Binaries - -Download from [GitHub Releases](https://github.com/interlynk-io/sbomqs/releases) - -### Building from Source - -```bash -git clone https://github.com/interlynk-io/sbomqs.git -cd sbomqs -make build -./build/sbomqs version -``` - -[πŸ“– Detailed Installation Guide](./docs/installation.md) - ## Contributions We welcome contributions! Here's how to get started: @@ -443,36 +133,72 @@ We welcome contributions! Here's how to get started: 5. Open a Pull Request Please ensure: - - All commits are signed - Tests pass (`make test`) - Code follows our style guide (`make lint`) -[πŸ“– Contributing Guidelines](./CONTRIBUTING.md) +πŸ“– [Contributing Guidelines](./CONTRIBUTING.md) ## Community Recognition sbomqs has gained significant adoption across the industry for SBOM quality assessment and compliance validation: -### Enterprise Adoptions -- **[Harness Software Supply Chain Assurance (SSCA)](https://developer.harness.io/docs/software-supply-chain-assurance/sbom/sbom-score/)** - Harness, the leader in AI-powered Modern CI/CD, uses sbomqs to power their SBOM quality scoring, providing quality scores from 1-10 for generated SBOMs with SBOM drift detection capabilities. +## πŸ“š Academic Research & Publications + +### Peer-Reviewed Papers Using sbomqs + +1. **Soeiro, L., Robert, T., & Zacchiroli, S. (2025)** + *Wild SBOMs: a Large-scale Dataset of Software Bills of Materials from Public Code* + 22nd IEEE/ACM International Conference on Mining Software Repositories (MSR 2025) + **DOI:** [arXiv:2503.15021](https://arxiv.org/abs/2503.15021) + **Usage:** Uses sbomqs to compute quality scores for over 78,000 SBOMs in their large-scale dataset from 94 million GitHub repositories. +1. **Novikov, O., Fucci, D., Adamov, O., & Mendez, D. (2025)** + POLICY-DRIVEN SOFTWARE BILL OF MATERIALS ON GITHUB: AN EMPIRICAL STUDY + arXiv preprint + **DOI:** [arXiv:2509.01255](https://arxiv.org/abs/2509.01255) + **Usage:** Uses sbomqs to assess the quality of 620 policy-driven SBOMs found on GitHub, calculating a quality score based on structural and + semantic completeness. + +### White Papers & Technical Documents -- **[SBOM Benchmark Platform](https://sbombenchmark.dev)** - Uses the sbomqs engine for scoring CycloneDX and SPDX SBOMs, providing shareable quality reports without requiring SBOM uploads. +2. **SBOM Generation White Paper (2025)** + *SBOM Community, February 2025* + **Citation:** Lists sbomqs as a "relevant tool in the SBOM ecosystem" and highlights it as demonstrating best practices in SBOM quality assessment. -### CI/CD Integrations +3. **OpenChain Telco SBOM Guide v1.1 (2025)** + *OpenChain Project* + **URL:** [OpenChain Project](https://openchainproject.org/) + **Usage:** References sbomqs as a recommended tool for telecommunications operators managing complex software supply chains, particularly for its ability to validate SBOMs across multiple formats. + +### Major Platforms & Companies -sbomqs integrates seamlessly with major CI/CD platforms: +### 1. **Harness Software Supply Chain Assurance (SSCA)** +- **Company:** Harness Inc. +- **Usage:** Uses sbomqs as the engine powering their SBOM quality scoring feature +- **Features:** Provides quality scores from 1-10 for generated SBOMs with SBOM drift detection capabilities +- **Reference:** [Harness Developer Hub](https://developer.harness.io/docs/software-supply-chain-assurance/sbom/) +- **Blog Post:** [Level Up your Zero-day Vulnerability Remediation and SBOM Quality](https://www.harness.io/blog/level-up-your-zero-day-vulnerability-remediation-and-sbom-quality-for-a-more-secure-software-supply-chain) (May 2025) -- **GitHub Actions** - Native Docker support via `ghcr.io/interlynk-io/sbomqs` -- **Jenkins** - Feature request for Dependency-Track plugin integration -- **Docker/Kubernetes** - Official container image for containerized workflows -- **GitLab CI, Azure DevOps, CircleCI** - Compatible via Docker or command-line execution +### 2. **sbom.sh** +- **Platform:** [sbom.sh](https://sbom.sh) +- **Usage:** Uses the sbomqs engine to evaluate and score uploaded SBOMs +- **Features:** Automatically generates a quality score (1–10) based on metadata completeness, component coverage, and spec compliance (SPDX/CycloneDX), displaying results directly in the web interface -### Package Manager Support +### 3. **SBOM Benchmark Platform** +- **Platform:** [sbombenchmark.dev](https://sbombenchmark.dev/) +- **Usage:** Uses the sbomqs engine for scoring CycloneDX and SPDX SBOMs +- **Features:** Provides shareable quality reports without requiring SBOM uploads -Available through multiple package managers for easy installation: +### 4. **Interlynk Platform** +- **Company:** Interlynk Inc. +- **Milestone:** Reached 100 customers on community tier, including four Fortune 500 companies +- **Integration:** sbomqs integrated for SBOM quality assessment across the platform + +### CI/CD & Package Manager Support + +- GitHub Actions via Docker (`ghcr.io/interlynk-io/sbomqs`) - Homebrew (`brew install sbomqs`) - Go modules (`go install`) - Docker Hub & GitHub Container Registry @@ -480,33 +206,36 @@ Available through multiple package managers for easy installation: ### Compliance Standards -Trusted for validating compliance with major standards: - +Trusted for validating compliance with: - NTIA Minimum Elements - BSI TR-03183-2 (v1.1 & v2.0) - OpenChain Telco (OCT) - Framing Software Component Transparency (FSCT v3) -## Other SBOM Open Source tools - +## Other SBOM Open Source Tools Interlynk provides a comprehensive suite of SBOM tools: -- [**SBOM Assembler**](https://github.com/interlynk-io/sbomasm) - Merge and edit SBOMs conditionally -- [**SBOM Explorer**](https://github.com/interlynk-io/sbomex) - Search and download SBOMs from public repositories -- [**SBOM Search Tool**](https://github.com/interlynk-io/sbomgr) - Context-aware SBOM repository search -- [**SBOM Seamless Transfer**](https://github.com/interlynk-io/sbommv) - Transfer SBOMs between systems -- [**SBOM Benchmark**](https://www.sbombenchmark.dev) - Repository of SBOM quality scores for popular containers +- [**SBOM Assembler**](https://github.com/interlynk-io/sbomasm) - Complete SBOM toolkit (Merging/Enriching/Signing and Editing) +- [**SBOM Explorer**](https://github.com/interlynk-io/sbomex) - Search and download from public repositories +- [**SBOM Search Tool**](https://github.com/interlynk-io/sbomgr) - Context-aware repository search +- [**SBOM Seamless Transfer**](https://github.com/interlynk-io/sbommv) - Transfer between systems +- [**SBOM Benchmark**](https://www.sbombenchmark.dev) - Repository of SBOM quality scores -## Contact +## Blog Posts + +- [sbomqs and SBOM Policies](https://sbom-insights.dev/posts/sbomqs-and-sbom-policies-turning-transparency-into-action/) +- [sbomqs scoring support for BSI-1.1 and BSI-2.0](https://sbom-insights.dev/posts/sbomqs-scoring-support-for-bsi-1.1-and-bsi-2.0-in-a-summarized-way/) +- [What’s Missing in Your SBOM](https://sbom-insights.dev/posts/whats-missing-in-your-sbom-sbomqs-list-can-help-you-in-inspecting.../) -We're here to help! Reach out through: -- ❓ [Community Slack](https://join.slack.com/t/sbomqa/shared_invite/zt-2jzq1ttgy-4IGzOYBEtHwJdMyYj~BACA) - Get answers from the community -- πŸ’¬ [Live Chat](https://www.interlynk.io/#hs-chat-open) - Talk to our team -- πŸ“§ [Email](mailto:hello@interlynk.io) - Direct support -- πŸ› [GitHub Issues](https://github.com/interlynk-io/sbomqs/issues) - Report bugs or request features -- 🐦 [Follow us on X](https://twitter.com/InterlynkIo) - Latest updates +## Contact + +- ❓ [Community Slack](https://join.slack.com/t/sbomqa/shared_invite/zt-2jzq1ttgy-4IGzOYBEtHwJdMyYj~BACA) +- πŸ’¬ [Live Chat](https://www.interlynk.io/#hs-chat-open) +- πŸ“§ [Email](mailto:hello@interlynk.io) +- πŸ› [GitHub Issues](https://github.com/interlynk-io/sbomqs/issues) +- 🐦 [Follow us on X](https://twitter.com/InterlynkIo) ## Stargazers @@ -518,4 +247,4 @@ If sbomqs helps you improve your SBOM quality and compliance, please ⭐ this re **sbomqs** - Building trust in software supply chains, one SBOM at a time. -Made with ❀️ by [Interlynk.io](https://www.interlynk.io) +Made with ❀️ by [Interlynk.io](https://www.interlynk.io) \ No newline at end of file diff --git a/docs/Features.md b/docs/Features.md deleted file mode 100644 index f5c2cd5..0000000 --- a/docs/Features.md +++ /dev/null @@ -1,771 +0,0 @@ - - -# SBOM Quality Checks - -This page describes each SBOM Quality check in detail, including scoring criteria, -remediation steps, and an explanation of the potential impact associated with a low score. -The checks are continually changing, and we welcome community feedback. - -If you have ideas for additions or new detection techniques, -please [contribute](https://github.com/interlynk-io/sbomqs#contributions)! - -## Taxonomy - -- A `Quality Check` is a test that can be performed on SBOM to return a binary result (e.g., A check for specification) -- A `Quality Check Category` is a logical grouping of Quality Checks (e.g., "NTIA-Minimum-Elements" Checks) -- A `Quality Check Set` is a collection of Quality Checks (e.g., "Default Check Set", "IoT Quality Set") - -## Scoring Methodology - -- Each Quality Check has an equal weight and a score range of 0.0 - 10.0. (Coming soon: Customization of weight per Quality Check) -- A Quality Check applied over a list of items (e.g., licenses) averages its score from the Check applied to each element. -- Quality Check Set Score is an average of scores over all Quality Checks in that Set. - -## Check Set Versioning - -Any Check Set, including the default Check Set, may change over time as new Checks are added, existing ones are removed and meaning of an existing one changes. -Such a breaking change is marked by incrementing `scoring_engine_version` in the output of `sbomqs`. - -Therefore comparing Quality Scores across `scoring_engine_version` is not recommended. - -## Quality Check Sets - Interlynk (Default) - -### 1. Category: Structural - -#### 1.1 Specification - -This check determines whether the SBOM is in one of the specifications (CycloneDX, SPDX, SWID) recommended by the [CISA reference document](https://ntia.gov/sites/default/files/publications/ntia_sbom_framing_2nd_edition_20211021_0.pdf) . - -CISA recommends limiting -the document to three commonly used formats to facilitate widespread adoption. - -***Remediation*** - -- Re-create the document in CycloneDX, SPDX, or SWID. - -#### 1.2 Specification Version - -This check determines whether the given SBOM is in the specification version that can support fields necessary for typical SBOM operations. -The current check tests for: - -- CycloneDX Versions: 1.0, 1.1, 1.2, 1.3, 1.4 -- SPDX Versions: 2.1, 2.2, 2.3 - -While the earlier versions of specifications may exist, a document in an earlier version will not be able to carry all of the required fields. - -***Remediation*** - -- Re-create the document in one of the versions listed above. - -#### 1.3 Specification File Format - -This check determines whether the given SBOM can be easily consumed by testing for the most common file formats associated with the specification. - -- CycloneDX: XML, JSON -- SPDX: JSON, YAML, RDF, tag/value - -Building and sharing SBOM in the most commonly used file format enables the use of SBOM in various conditions. - -***Remediation steps*** - -- Re-create the document in one of the file formats listed above. - -#### 1.4 Specification Syntax - -This check determines whether the given SBOM meets all the requirements of the underlying specification and file format to be parsed. - -A syntactic error in the SBOM will prevent it from being usable. - -***Remediation*** - -- Check the SBOM generator tool's known issues and get the most recent version of the tool. -- Check options/setup of the environment variables required to use the tool. -- Build SBOM with a different tool. - -### 2. Category: NTIA-Minimum-Elements - -#### 2.1 Component Name - -This check determines whether each component in the SBOM includes a name. - -Components must have a name to be used meaningfully to assess compliance or security risk. - -**Remediation** -Identify the component with a missing name and check its product page to get its name. - -- CycloneDX field: [components:name](https://cyclonedx.org/docs/1.4/json/#components_items_name) -- SPDX field: [PackageName](https://spdx.github.io/spdx-spec/v2.3/package-information/#71-package-name-field) - -#### 2.2 Supplier Name - -This check determines whether each component in the SBOM includes a supplier name. Supplier name is not a well defined term -especially in the context of Open Source projects and we will update the recommendation here once a consensus emerges. - -***Remediation*** - -Identify the component with a missing supplier name and check its product page to get its supplier name. - -- CycloneDX field: [components:supplier](https://cyclonedx.org/docs/1.4/json/#components_items_supplier) -- SPDX field: [PackageSupplierName](https://spdx.github.io/spdx-spec/v2.3/package-information/#75-package-supplier-field) - -#### 2.3 Unique Identifier - -This check determines whether each component in the SBOM includes a unique identifier. - -Unique component identifiers are essential to ensure the document can uniquely describe properties associated with the component. - -***Remediation*** - -Identify the component with a missing/duplicate identifier. - -- CycloneDX field: [components:bom-ref](https://cyclonedx.org/docs/1.4/json/#components_items_bom-ref) -- SPDX field: [SPDXID](https://spdx.github.io/spdx-spec/v2.3/package-information/#72-package-spdx-identifier-field) - -#### 2.4 Component Version - -This check determines whether each component in the SBOM includes a version. - -Components without a version can not be checked for vulnerabilities. - -***Remediation*** -Identify the component with the missing version and populate the version field below. - -- CycloneDX field: [components:version](https://cyclonedx.org/docs/1.4/json/#components_items_version) -- SPDX field: [PackageVersion](https://spdx.github.io/spdx-spec/v2.3/package-information/#73-package-version-field) - -#### 2.4 Author Name - -This check determines whether the document includes the name of the author. - -The person, organization, or the tool that created the SBOM must be specified as the Author. - -***Remediation*** -Check and populate the following fields with the name of the person, organization, or tool creating the SBOM. - -- CycloneDX field: [metadata:authors](https://cyclonedx.org/docs/1.4/json/#metadata_authors) -- SPDX field: [Creator](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#68-creator-field) - -#### 2.5 Timestamp - -This check determines if the document includes the timestamp of its creation. - -The timestamp can be used to determine when the SBOM was created relative to the software itself. - -***Remediation steps*** - -- Check and populate the following fields with the timestamp of the SBOM document. -- CycloneDX field: [metadata:timestamp](https://cyclonedx.org/docs/1.4/json/#metadata_timestamp) -- SPDX field: [Created](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#69-created-field) - -#### 2.6 Relationship among Components - -This check determines if the document describes the relationship among included components. - -The dependency relationship can be critical in determining the order of inclusion and updates. - -***Remediation*** - -- Check and populate the following fields with the relationship of components in the SBOM. -- CycloneDX field: [dependencies](https://cyclonedx.org/docs/1.4/json/#dependencies) -- SPDX field: [Relationship](https://spdx.github.io/spdx-spec/v2.3/relationships-between-SPDX-elements/#111-relationship-field) - -### 3. Category: Semantic - -#### 3.1 Component Checksum - -This check determines whether each component in the SBOM includes a valid checksum. - -A valid checksum can be used to independently identify the contents of the package among variations of the package. - -***Remediation*** - -- Check and populate the following fields with the relationship of components in the SBOM. -- CycloneDX field: [dependencies](https://cyclonedx.org/docs/1.4/json/#dependencies) -- SPDX fields: [PackageChecksum](https://spdx.github.io/spdx-spec/v2.3/package-information/#710-package-checksum-field), (Coming Soon) [FileChecksum](https://spdx.github.io/spdx-spec/v2.3/file-information/#84-file-checksum-field) - -#### 3.2 Component License - -This check determines whether each component in the SBOM includes a valid license. - -A declared valid SPDX license is the key to evaluating any compliance risks. - -***Remediation steps*** - -Check and populate the following fields with the relationship of components in the SBOM. - -- CycloneDX field: [component:licenses](https://cyclonedx.org/docs/1.4/json/#components_items_licenses) -- SPDX fields: [PackageLicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field), (Coming Soon) [LicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/file-information/#85-concluded-license-field) - -#### 3.3 Required Fields - -This check determines whether several fields required by the underlying specification are present in the document. - -With the required fields, the SBOM processing becomes consistent by different tools. - -***Remediation*** - -Check and populate the following required fields: - -- CycloneDX Fields: [bomFormat](https://cyclonedx.org/docs/1.4/json/#bomFormat), [SpecVersion](https://cyclonedx.org/docs/1.4/json/#specVersion), [Version](https://cyclonedx.org/docs/1.4/json/#version), [component:type](https://cyclonedx.org/docs/1.4/json/#components_items_type),[component:name](https://cyclonedx.org/docs/1.4/json/#components_items_name) -- SPDX Fields: [CreationInfo](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/), [Creator](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#68-creator-field), [Created](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#69-created-field), [SPDXVersion](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#61-spdx-version-field), [DataLicense](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#62-data-license-field), [SPDXIdentifier](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#63-spdx-identifier-field), [DocumentName](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#64-document-name-field), [DocumentNamespace](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#65-spdx-document-namespace-field), [PackageName](https://spdx.github.io/spdx-spec/v2.3/package-information/#71-package-name-field), [PackageSPDXIdentifier](https://spdx.github.io/spdx-spec/v2.3/package-information/#72-package-spdx-identifier-field), [PackageDowloadLocation](https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field), [PackageVerificationCode](https://spdx.github.io/spdx-spec/v2.3/package-information/#79-package-verification-code-field) (if applicable) - -### 4. Category: Quality - -#### 4.1 Vulnerability Lookup Identifier - -This check determines whether at least one vulnerability lookup identifier (CPE/PURL) is present for each component. - -A vulnerability lookup identifier is critical in mapping SBOM components to known vulnerability databases (e.g., NVD). - -***Remediation*** - -- Check and populate the following fields: -- CycloneDX field: [components:cpe](https://cyclonedx.org/docs/1.4/json/#components_items_cpe) OR [components:purl](https://cyclonedx.org/docs/1.4/json/#components_items_purl) -- SPDX fields: [ExternalRef with CPE or PURL](https://spdx.github.io/spdx-spec/v2.3/package-information/#721-external-reference-field) - -#### 4.2 Multiple Vulnerability Lookup Identifier - -This check determines whether multiple vulnerability lookup identifiers are present for each component. - -Including more than one vulnerability lookup identifier can enable vulnerability lookup from multiple sources, reducing the risk of missing any vulnerability. - -***Remediation*** - -Check and populate the following fields: - -- CycloneDX field: [components:cpe](https://cyclonedx.org/docs/1.4/json/#components_items_cpe) AND [components:purl](https://cyclonedx.org/docs/1.4/json/#components_items_purl) -- SPDX fields: [ExternalRef with CPE AND PURL](https://spdx.github.io/spdx-spec/v2.3/package-information/#721-external-reference-field) - -#### 4.3 Valid SPDX License - -This check determines whether all included licenses are valid SPDX [licenses or license expressions](https://spdx.org/licenses/). - -Any license expression not found on the SPDX list is a commercial license and must be evaluated independently for compliance risks. - -***Remediation*** - -- Check the following fields to confirm none of the licenses belong to the [SPDX license list](https://spdx.org/licenses/): -- CycloneDX field: [component:licenses](https://cyclonedx.org/docs/1.4/json/#components_items_licenses) -- SPDX fields: [PackageLicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field), (Coming Soon) [LicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/file-information/#85-concluded-license-field) - -#### 4.4 Deprecated License - -This check determines whether any of the included licenses have been declared deprecated. - -A deprecated license declaration can be considered a compliance risk. - -***Remediation*** - -- Check the following fields to confirm none of the licenses belong to the [deprecated licenses](https://spdx.org/licenses/): -- CycloneDX field: [component:licenses](https://cyclonedx.org/docs/1.4/json/#components_items_licenses) -- SPDX fields: [PackageLicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field), (Coming Soon) [LicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/file-information/#85-concluded-license-field) - -#### 4.5 Restricted License - -This check determines whether any included licenses have been declared restricted for use. - -A restricted license declaration can be considered a compliance risk. - -***Remediation*** - -- Check the following fields to confirm none of the licenses belong to the [restricted license list](https://opensource.google/documentation/reference/thirdparty/licenses): -- CycloneDX field: [component:licenses](https://cyclonedx.org/docs/1.4/json/#components_items_licenses) -- SPDX fields: [PackageLicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field), (Coming Soon) [LicenseConcluded](https://spdx.github.io/spdx-spec/v2.3/file-information/#85-concluded-license-field) - -#### 4.6 Primary Purpose - -This check determines whether the SBOM component includes the Primary Purpose field. - -The primary purpose (or type) indicates the use of the component inside the application. - -***Remediation steps*** - -Check the following fields to confirm none of the licenses belong to the [restricted license list](https://opensource.google/documentation/reference/thirdparty/licenses): - -- CycloneDX field: [component:type](https://cyclonedx.org/docs/1.4/json/#components_items_type) -- SPDX fields: [PrimaryPackagePurpose](https://spdx.github.io/spdx-spec/v2.3/package-information/#724-primary-package-purpose-field) - -#### 4.7 Primary Component Present - -An sbom is expected to describe a primary component. This check determines if the sbom has -a primary component or not. - -***Remediation steps*** - -- CycloneDX: ensure the metadata section has the primary [component](https://cyclonedx.org/docs/1.5/json/#metadata_component) defined -- SPDX: Should have a [DESCRIBES](https://spdx.github.io/spdx-spec/v2.3/relationships-between-SPDX-elements/) relationship which points to a package, or have a documentDescribes field present. - -### 5. Category: Sharing - -#### 5.1 Unencumbered License - -This check determines whether the SBOM can be shared easily because it includes an unencumbered license: [CC0](https://spdx.org/licenses/CC0-1.0), [Unlicense](https://spdx.org/licenses/Unlicense.html), [0BSD](https://spdx.org/licenses/0BSD.html) - -Check the following fields to see if the license includes one of the above licenses: - -- CycloneDX field: [metadata:licenses](https://cyclonedx.org/docs/1.4/json/#metadata_licenses) -- SPDX fields: [DataLicense](https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#62-data-license-field) - -Got it! Here's the refined `bsi-v1.1` category following your exact style β€” with **"Corresponding Fields"** listed separately and a distinct **"Remediation"** section under each check. - -### 6. Category: BSI-v1.1 - -#### 6.1 SBOM URI - -This check ensures the SBOM contains a unique URI or identifier for the document itself. - -**Corresponding Fields:** - -- CycloneDX: `serialNumber`, `version` -- SPDX: `DocumentNamespace` - -***Remediation*** - -Make sure your SBOM tool or generator includes a globally unique identifier in the fields listed above. - -#### 6.2 Component Source Code URI - -This check ensures that the SBOM contains a reference to the source code repository of each component. - -**Corresponding Fields:** - -- CycloneDX: `component.externalReferences` (type: `vcs`) -- SPDX: *Not supported* - -***Remediation*** - -Verify the repository/source URI is included for each component. If your tool doesn’t support it, manually enrich the SBOM or switch to a more compliant generator. - -#### 6.3 Component Executable URI - -This check ensures the SBOM includes a URI where the executable or build artifact of the component can be found. - -**Corresponding Fields:** - -- CycloneDX: `component.externalReferences` (type: `distribution`, `distribution-intake`) -- SPDX: `PackageDownloadLocation` - -***Remediation*** - -Ensure each component contains the URI pointing to the built binary or artifact. Add this manually or through SBOM generation tooling. - -#### 6.4 Component Source Hash - -This check validates that a hash of the source code is included for each component to support integrity verification. - -**Corresponding Fields:** - -- CycloneDX: *(Not explicitly standardized β€” under discussion)* -- SPDX: `PackageVerificationCode` - -***Remediation*** - -Use SPDX’s `PackageVerificationCode` to represent the source hash. CycloneDX currently lacks an exact equivalent. - -#### 6.5 Other Unique Identifiers - -This check ensures the SBOM includes additional unique identifiers (like PURL or CPE) for better traceability and vulnerability lookups. - -**Corresponding Fields:** - -- CycloneDX: `component.cpe`, `component.purl` -- SPDX: `externalReferences` (type: `security` with CPE or PURL) - -***Remediation*** - -Include either a CPE or PURL for each component to facilitate accurate vulnerability correlation. - -#### 6.6 Component Hash - -This check ensures the component’s binary artifact hash is captured to confirm its identity. - -**Corresponding Fields:** - -- CycloneDX: `component.hashes` -- SPDX: `PackageChecksum` - -***Remediation*** - -Ensure each component entry includes a valid SHA hash. Most SBOM tools can generate this automatically during build time. - -#### 6.7 Component License - -This check ensures that each component declares a valid license. - -**Corresponding Fields:** - -- CycloneDX: `component.licenses` -- SPDX: `PackageLicenseConcluded`, `PackageLicenseDeclared` - -***Remediation*** - -Verify that the license is present and valid. Use SPDX license identifiers and ensure both declared and concluded licenses are provided when possible. - -#### 6.8 Component Dependencies - -This check ensures the SBOM includes information about how components depend on each other. - -**Corresponding Fields:** - -- CycloneDX: `dependencies`, `compositions` -- SPDX: `relationships` (type: `DEPENDS_ON`) - *Note: SPDX does not support `CONTAINS` here.* - -***Remediation*** - -Use dependency information from build tools or SBOM generators to populate these fields correctly. - -#### 6.9 Component Version - -This check validates that a version is assigned to each component in the SBOM. - -**Corresponding Fields:** - -- CycloneDX: `component.version` -- SPDX: `PackageVersion` - -***Remediation*** - -Ensure each component has an accurate version, especially for open source or third-party dependencies. - -#### 6.10 Component Creator - -This check ensures that the creator or supplier of each component is documented. - -**Corresponding Fields:** - -- CycloneDX: `component.supplier` -- SPDX: `PackageSupplier`, `PackageOriginator` - -***Remediation*** - -Populate the supplier or originator fields for each component. This could be a person, organization, or project. - -#### 6.11 SBOM Creator - -This check ensures that the person or tool that created the SBOM is properly identified. - -**Corresponding Fields:** - -- CycloneDX: `metadata.authors`, `metadata.supplier` -- SPDX: `Creator` - -***Remediation*** - -Make sure the metadata includes who or what created the SBOM. See [issue #448](https://github.com/interlynk-io/sbomqs/issues/448) for related discussion. - -#### 6.12 SBOM Relationships - -This check ensures that the SBOM describes relationships between components correctly. - -**Corresponding Fields:** - -- SPDX: `relationships` (type: `CONTAINS`) - *Note: SPDX does **not** use `DEPENDS_ON` for SBOM-level relationships.* -- CycloneDX: `dependsOn` - -***Remediation*** - -Make sure the SBOM expresses which components are part of the main software. CycloneDX typically uses `metadata.component` and `dependencies`; SPDX relies on `CONTAINS`. - -Perfect, based on your table and formatting preference, here's a well-aligned **`BSI-v2.0`** section for your SBOM quality documentation β€” using **"Corresponding Fields"** and a **"Remediation"** section per check just like other categories: - -### 7. Category: BSI-v2.0 - -#### 7.1 Vulnerability Information Present - -This check verifies if the SBOM contains embedded vulnerability data. BSI v2.0 explicitly requires that SBOMs **must not** include vulnerability data. - -**Corresponding Fields:** - -- CycloneDX: `vulnerabilities` -- SPDX: *Non-deterministic*, `externalReference.comment` *(informal workaround)* - -***Remediation*** - -Ensure the SBOM does **not** include embedded vulnerability information. If vulnerability analysis is needed, use a separate VEX or report artifact. - -#### 7.2 SBOM Specification Format and Version - -This check validates that the SBOM conforms to an accepted specification and version as per BSI guidelines. - -**Corresponding Fields:** - -- CycloneDX: `bomFormat`, `specVersion` (v1.5+) -- SPDX: `SPDXVersion` (v2.2.1+) - -***Remediation*** - -Ensure the SBOM is created using SPDX 2.2.1+ or CycloneDX 1.5+. Re-generate using compliant tooling if needed. - -#### 7.3 SBOM Creator Identity - -This check verifies the SBOM includes an author with an email or URL β€” just a name is not sufficient. - -**Corresponding Fields:** - -- CycloneDX: `metadata.authors`, `metadata.supplier`, `metadata.manufacturer` -- SPDX: `Creator` (Person or Organization) - -***Remediation*** - -Include a valid author with either an email or URL in the appropriate fields. Avoid using just plain names. - -#### 7.4 SBOM Timestamp - -This check ensures the SBOM includes a timestamp using a valid format. - -**Corresponding Fields:** - -- CycloneDX: `metadata.timestamp` -- SPDX: `Created` - -***Remediation*** - -Ensure the timestamp is present and properly formatted in ISO 8601. Regenerate if your tooling produces an invalid format. - -#### 7.5 Component Creator Identity - -This check ensures each component includes a supplier or creator with a resolvable identity (preferably email or URL). - -**Corresponding Fields:** - -- CycloneDX: `component.supplier`, `component.authors` -- SPDX: `PackageSupplier`, `PackageOriginator` - -***Remediation*** - -Make sure each component lists a responsible entity with contact information. Prefer using fields that support resolvable identities. - -#### 7.6 Component Name - -This check ensures each component includes a name. - -**Corresponding Fields:** - -- CycloneDX: `component.name` -- SPDX: `PackageName` - -***Remediation*** - -All components should include a valid name. This is typically automatically populated by SBOM generators. - -#### 7.7 Component Version - -This check ensures each component includes a version string. - -**Corresponding Fields:** - -- CycloneDX: `component.version` -- SPDX: `PackageVersion` - -***Remediation*** - -Make sure each component entry has a version. Empty or missing values should be addressed manually or via tooling fix. - -#### 7.8 Component Filename - -This check verifies the component includes a filename. - -**Corresponding Fields:** - -- CycloneDX: `component.name` (type: `file`) or in `properties` -- SPDX: `PackageFileName` - -***Remediation*** - -If representing a file, ensure the filename is captured. In CycloneDX, consider including it via `component.properties`. - -#### 7.9 Component Dependencies - -This check ensures the SBOM documents relationships between components. - -**Corresponding Fields:** - -- CycloneDX: `dependencies`, `compositions` -- SPDX: `Relationships` - -***Remediation*** - -Include dependency or composition information in your SBOM to reflect how components relate to each other. - -#### 7.10 Component Associated License - -This check ensures components have at least one associated license. - -**Corresponding Fields:** - -- CycloneDX: `component.licenses.expression` -- SPDX: `PackageLicenseConcluded` - -***Remediation*** - -Ensure each component includes a valid SPDX license identifier in the specified fields. - -#### 7.11 Component Hash - -This check ensures components include at least one hash (preferably SHA-256). - -**Corresponding Fields:** - -- CycloneDX: `component.hashes` -- SPDX: `PackageChecksum` - -***Remediation*** - -Use tooling that generates SHA-256 checksums for each component. Older hash algorithms may not meet compliance. - -#### 7.12 Component Executable and Archive - -This check validates if executables and archives are represented with relevant identifiers or references. - -**Corresponding Fields:** - -- CycloneDX / SPDX: *Open to vendor implementation* - -***Remediation*** - -Use `externalReferences` to refer to executables or archives. Define this clearly if such artifacts are part of your SBOM scope. - -#### 7.13 Structured Format - -This check ensures the SBOM is delivered in a structured machine-readable format. - -**Corresponding Fields:** - -- CycloneDX / SPDX: JSON, XML, RDF, YAML - -***Remediation*** - -Avoid free-text SBOMs. Ensure output is a structured format accepted by the consuming ecosystem. - -#### 7.14 SBOM URI (Document Identifier) - -This check validates the SBOM includes a globally unique identifier for the document. - -**Corresponding Fields:** - -- CycloneDX: `serialNumber`, `version` -- SPDX: `DocumentNamespace` - -***Remediation*** - -Use a unique `serialNumber` or `namespace` to allow referencing the SBOM externally or across systems. - -#### 7.15 Component Source Code URI - -This check ensures the SBOM includes a link to the source code for each component. - -**Corresponding Fields:** - -- CycloneDX: `component.externalReferences` (type: `vcs`) -- SPDX: *Not deterministic* - -***Remediation*** - -Make sure components include VCS links when applicable. For SPDX, consider using `externalReferences` with comments. - -#### 7.16 Executable URI - -This check ensures components point to their binary or installable versions. - -**Corresponding Fields:** - -- CycloneDX: `externalReferences` (type: `distribution`, `distribution-intake`) -- SPDX: `PackageDownloadLocation` - -***Remediation*** - -Add proper links where executables are hosted. Most build tools can populate this automatically. - -#### 7.17 Hash of Source Code - -This check ensures a hash of the component source code is included. - -**Corresponding Fields:** - -- CycloneDX: *Not explicitly supported* -- SPDX: `PackageVerificationCode` - -***Remediation*** - -Include `PackageVerificationCode` where possible. CycloneDX does not currently support this explicitly β€” monitor future spec updates. - -#### 7.18 Other Unique Identifiers (CPE/PURL) - -This check ensures components have unique identifiers like PURL or CPE. - -**Corresponding Fields:** - -- CycloneDX: `component.purl`, `component.cpe` -- SPDX: `externalReferences.security` (CPE), `package_manager` (PURL) - -***Remediation*** - -Add either PURL or CPE to improve vulnerability mapping and cross-referencing. - -#### 7.19 Concluded License - -This check ensures components include a concluded license expression. - -**Corresponding Fields:** - -- CycloneDX: `licenses.acknowledgement` (only in v1.6+) -- SPDX: `PackageLicenseConcluded` - -**Remediation:** - -Make sure a license has been analyzed and concluded for each component. Use SPDX-compatible expressions. - -#### 7.20 Declared License - -This check ensures components declare the license they were distributed with. - -**Corresponding Fields:** - -- CycloneDX: `licenses.acknowledgement` (v1.6+) -- SPDX: `PackageLicenseDeclared` - -***Remediation*** - -Populate declared license fields even if concluded licenses are also used. They serve different legal purposes. - -#### 7.21 Signature - -This check verifies whether the SBOM is digitally signed. - -**Corresponding Fields:** - -- CycloneDX: `signature` -- SPDX: *Non-deterministic / out-of-band* - -***Remediation*** - -Consider signing the SBOM using a signing tool (e.g., cosign, sigstore). Attach signature metadata as recommended in CycloneDX 1.5+. - -#### 7.22 External Bom Links - -This check verifies whether external references to other SBOMs are included. - -***Corresponding Fields*** - -- CycloneDX: `externalReferences` (type: `bom`) -- SPDX: `externalDocumentRefs` - -***Remediation*** - -Reference other SBOMs using proper links, especially in multi-layered or composed software systems. diff --git a/docs/compliance-command.md b/docs/commands/compliance.md similarity index 98% rename from docs/compliance-command.md rename to docs/commands/compliance.md index d810890..b7a057d 100644 --- a/docs/compliance-command.md +++ b/docs/commands/compliance.md @@ -376,6 +376,6 @@ sbomqs compliance --fsct problematic.json --debug ## Related Commands -- [`score`](./score-command.md) - Get overall quality score -- [`list`](./list-command.md) - Find components missing compliance fields -- [`share`](./share-command.md) - Share compliance reports \ No newline at end of file +- [`score`](./score.md) - Get overall quality score +- [`list`](./list.md) - Find components missing compliance fields +- [`share`](./share.md) - Share compliance reports \ No newline at end of file diff --git a/docs/dtrack-command.md b/docs/commands/dtrack.md similarity index 98% rename from docs/dtrack-command.md rename to docs/commands/dtrack.md index 45e01af..d38a081 100644 --- a/docs/dtrack-command.md +++ b/docs/commands/dtrack.md @@ -439,6 +439,6 @@ sbomqs dtrackScore -u "$DT_URL" -k "$DT_KEY" "$PROJECT_ID" --debug ## Related Commands -- [`score`](./score-command.md) - Score local SBOM files -- [`compliance`](./compliance-command.md) - Check compliance standards -- [`share`](./share-command.md) - Generate shareable reports \ No newline at end of file +- [`score`](./score.md) - Score local SBOM files +- [`compliance`](./compliance.md) - Check compliance standards +- [`share`](./share.md) - Generate shareable reports \ No newline at end of file diff --git a/docs/generate-command.md b/docs/commands/generate.md similarity index 98% rename from docs/generate-command.md rename to docs/commands/generate.md index 4dcbb95..d29c22b 100644 --- a/docs/generate-command.md +++ b/docs/commands/generate.md @@ -499,6 +499,6 @@ git commit -m "Initial SBOM quality standards" ## Related Commands -- [`score`](./score-command.md) - Use custom configurations for scoring -- [`compliance`](./compliance-command.md) - Check against standards -- [`list`](./list-command.md) - Verify feature presence \ No newline at end of file +- [`score`](./score.md) - Use custom configurations for scoring +- [`compliance`](./compliance.md) - Check against standards +- [`list`](./list.md) - Verify feature presence \ No newline at end of file diff --git a/docs/list.md b/docs/commands/list.md similarity index 100% rename from docs/list.md rename to docs/commands/list.md diff --git a/docs/score-command.md b/docs/commands/score.md similarity index 97% rename from docs/score-command.md rename to docs/commands/score.md index 137e6c9..f1e235e 100644 --- a/docs/score-command.md +++ b/docs/commands/score.md @@ -304,7 +304,7 @@ sbomqs score large-sbom.json --json | jq '.files[0].avg_score' ## Related Commands -- [`compliance`](./compliance-command.md) - Check regulatory compliance -- [`list`](./list-command.md) - Analyze specific SBOM features -- [`share`](./share-command.md) - Generate shareable score reports -- [`generate`](./generate-command.md) - Create custom scoring profiles \ No newline at end of file +- [`compliance`](./compliance.md) - Check regulatory compliance +- [`list`](./list.md) - Analyze specific SBOM features +- [`share`](./share.md) - Generate shareable score reports +- [`generate`](./generate.md) - Create custom scoring profiles \ No newline at end of file diff --git a/docs/share-command.md b/docs/commands/share.md similarity index 98% rename from docs/share-command.md rename to docs/commands/share.md index 6122f6f..9a7725e 100644 --- a/docs/share-command.md +++ b/docs/commands/share.md @@ -383,6 +383,6 @@ done ## Related Commands -- [`score`](./score-command.md) - Calculate quality score -- [`compliance`](./compliance-command.md) - Check compliance -- [`list`](./list-command.md) - Analyze SBOM components \ No newline at end of file +- [`score`](./score.md) - Calculate quality score +- [`compliance`](./compliance.md) - Check compliance +- [`list`](./list.md) - Analyze SBOM components \ No newline at end of file diff --git a/docs/version-command.md b/docs/commands/version.md similarity index 96% rename from docs/version-command.md rename to docs/commands/version.md index f6a9aa3..589d099 100644 --- a/docs/version-command.md +++ b/docs/commands/version.md @@ -339,6 +339,6 @@ pipeline { ## Related Commands -- [`score`](./score-command.md) - Score SBOMs with current version -- [`compliance`](./compliance-command.md) - Check compliance with version-specific features -- [`generate`](./generate-command.md) - Generate configs compatible with version \ No newline at end of file +- [`score`](./score.md) - Score SBOMs with current version +- [`compliance`](./compliance.md) - Check compliance with version-specific features +- [`generate`](./generate.md) - Generate configs compatible with version \ No newline at end of file diff --git a/docs/installation.md b/docs/getting-started.md similarity index 67% rename from docs/installation.md rename to docs/getting-started.md index e9ca86c..a3c3fc2 100644 --- a/docs/installation.md +++ b/docs/getting-started.md @@ -1,8 +1,8 @@ -# Installation Guide +# Getting Started Guide -This guide covers all installation methods for SBOMQS, including platform-specific instructions, Docker usage, and building from source. +This comprehensive guide covers installing sbomqs and getting started with SBOM quality assessment. -## Quick Start +## Quick Installation ### macOS (Homebrew) - Recommended @@ -44,19 +44,16 @@ sbomqs version ```bash # Download latest release for macOS (Intel) -curl -LO https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_darwin_amd64.tar.gz +curl -LO https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs-darwin-amd64 # For Apple Silicon (M1/M2) -curl -LO https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_darwin_arm64.tar.gz +curl -LO https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs-darwin-arm64 -# Extract -tar -xzf sbomqs_darwin_*.tar.gz +# Make executable +chmod +x sbomqs-darwin-* # Move to PATH -sudo mv sbomqs /usr/local/bin/ - -# Make executable -chmod +x /usr/local/bin/sbomqs +sudo mv sbomqs-darwin-* /usr/local/bin/sbomqs # Verify sbomqs version @@ -69,11 +66,15 @@ sbomqs version ##### Debian/Ubuntu (via .deb package) ```bash -# Download the .deb package -wget https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_linux_amd64.deb +# Download the .deb package (x86_64) +VERSION=$(curl -s https://api.github.com/repos/interlynk-io/sbomqs/releases/latest | jq -r '.tag_name' | sed 's/v//') +wget https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_${VERSION}_amd64.deb + +# For ARM64 +wget https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_${VERSION}_arm64.deb # Install -sudo dpkg -i sbomqs_linux_amd64.deb +sudo dpkg -i sbomqs_*.deb # Fix any dependency issues sudo apt-get install -f @@ -82,30 +83,31 @@ sudo apt-get install -f ##### RedHat/CentOS/Fedora (via .rpm package) ```bash -# Download the .rpm package -wget https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_linux_amd64.rpm +# Download the .rpm package (x86_64) +VERSION=$(curl -s https://api.github.com/repos/interlynk-io/sbomqs/releases/latest | jq -r '.tag_name' | sed 's/v//') +wget https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs-${VERSION}-1.x86_64.rpm + +# For ARM64/aarch64 +wget https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs-${VERSION}-1.aarch64.rpm # Install -sudo rpm -i sbomqs_linux_amd64.rpm +sudo rpm -i sbomqs-*.rpm ``` #### Using Pre-built Binary ```bash # Download for Linux (x86_64) -curl -LO https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_linux_amd64.tar.gz +curl -LO https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs-linux-amd64 # For ARM64 -curl -LO https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_linux_arm64.tar.gz +curl -LO https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs-linux-arm64 -# Extract -tar -xzf sbomqs_linux_*.tar.gz +# Make executable +chmod +x sbomqs-linux-* # Move to PATH -sudo mv sbomqs /usr/local/bin/ - -# Make executable -chmod +x /usr/local/bin/sbomqs +sudo mv sbomqs-linux-* /usr/local/bin/sbomqs # Verify sbomqs version @@ -114,8 +116,7 @@ sbomqs version #### Using Snap ```bash -# Coming soon -snap install sbomqs +# Please request ``` ### Windows @@ -134,10 +135,11 @@ scoop install sbomqs ```powershell # Download the Windows binary -Invoke-WebRequest -Uri "https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_windows_amd64.zip" -OutFile "sbomqs.zip" +Invoke-WebRequest -Uri "https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs-windows-amd64.exe" -OutFile "sbomqs.exe" -# Extract -Expand-Archive -Path "sbomqs.zip" -DestinationPath "C:\Program Files\sbomqs" +# Create directory and move executable +New-Item -ItemType Directory -Force -Path "C:\Program Files\sbomqs" +Move-Item -Path "sbomqs.exe" -Destination "C:\Program Files\sbomqs\sbomqs.exe" # Add to PATH [Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\sbomqs", [EnvironmentVariableTarget]::Machine) @@ -149,8 +151,7 @@ sbomqs version #### Using Chocolatey ```powershell -# Coming soon -choco install sbomqs +# Please request ``` ## Docker Installation @@ -415,12 +416,15 @@ if [ "$CURRENT" != "$LATEST" ]; then fi # Download latest - URL="https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_${OS}_${ARCH}.tar.gz" + URL="https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs-${OS}-${ARCH}" + if [ "$OS" = "windows" ]; then + URL="${URL}.exe" + fi curl -LO "$URL" - # Extract and install - tar -xzf "sbomqs_${OS}_${ARCH}.tar.gz" - sudo mv sbomqs /usr/local/bin/ + # Install + chmod +x "sbomqs-${OS}-${ARCH}"* + sudo mv "sbomqs-${OS}-${ARCH}"* /usr/local/bin/sbomqs echo "Updated to: $(sbomqs version --short)" else @@ -518,11 +522,106 @@ export SBOMQS_CONFIG_DIR=$HOME/.config/sbomqs export SBOMQS_DEBUG=true ``` -## Next Steps +## Basic Usage + +Now that you have sbomqs installed, let's start with some basic commands. + +### Your First Quality Score + +```bash +# Score a single SBOM +sbomqs score my-app.spdx.json + +# Get just the numeric score +sbomqs score my-app.spdx.json --basic +``` + +### Understanding Your Score + +Scores range from 0-10: +- **9-10**: Excellent quality +- **7-8.9**: Good, minor improvements needed +- **5-6.9**: Fair, has gaps to address +- **0-4.9**: Poor, missing critical information + +### Check What's Missing + +```bash +# See detailed breakdown +sbomqs score my-app.spdx.json + +# Find components missing versions +sbomqs list my-app.spdx.json --feature comp_with_version --missing + +# Find components missing suppliers +sbomqs list my-app.spdx.json --feature comp_with_supplier --missing +``` + +### Verify Compliance -After installation: +```bash +# Check NTIA minimum elements +sbomqs score my-app.spdx.json --category ntia + +# Check BSI compliance +sbomqs compliance --bsi-v2 my-app.spdx.json + +# Check FSCT compliance +sbomqs compliance --fsct my-app.spdx.json +``` + +### Share Your Results + +```bash +# Generate a shareable link (doesn't upload SBOM content) +sbomqs share my-app.spdx.json +``` + +## Common Use Cases + +### CI/CD Integration + +Add to your pipeline to fail builds with low-quality SBOMs: + +```yaml +# GitHub Actions example +- name: Check SBOM Quality + run: | + score=$(sbomqs score sbom.json --json | jq '.files[0].avg_score') + if (( $(echo "$score < 7.0" | bc -l) )); then + echo "SBOM quality too low: $score" + exit 1 + fi +``` + +### Vendor SBOM Assessment + +```bash +# Score all vendor SBOMs +for sbom in vendor-sboms/*.json; do + echo "$(sbomqs score "$sbom" --basic) - $(basename "$sbom")" +done | sort -rn +``` + +### Progressive Improvement + +```bash +# 1. Get baseline score +sbomqs score app.spdx.json + +# 2. Identify issues +sbomqs score app.spdx.json + +# 3. Fix missing data +sbomqs list app.spdx.json --feature comp_with_version --missing + +# 4. Re-score to verify improvement +sbomqs score app-fixed.spdx.json +``` + +## Next Steps -1. [Read the Quick Start Guide](../README.md#quick-start) -2. [Try the score command](./score-command.md) -3. [Check compliance](./compliance-command.md) -4. [Generate custom configurations](./generate-command.md) \ No newline at end of file +- **[Command Reference](./commands/)** - Detailed documentation for all commands +- **[Customization Guide](./guides/customization.md)** - Create organization-specific profiles +- **[Integration Guide](./guides/integrations.md)** - CI/CD and tool integrations +- **[Compliance Standards](./reference/compliance-standards.md)** - Detailed compliance mappings \ No newline at end of file diff --git a/docs/customization.md b/docs/guides/customization.md similarity index 99% rename from docs/customization.md rename to docs/guides/customization.md index f85e3aa..d2ccfe3 100644 --- a/docs/customization.md +++ b/docs/guides/customization.md @@ -307,7 +307,7 @@ policy: action: fail ``` -For more, refer here: [policy.md](https://github.com/interlynk-io/sbomqs/blob/main/docs/policy.md) +For more, refer here: [policy.md](./policy.md) ## Organization Standards diff --git a/docs/integrations.md b/docs/guides/integrations.md similarity index 67% rename from docs/integrations.md rename to docs/guides/integrations.md index 6bb116b..a2af7cc 100644 --- a/docs/integrations.md +++ b/docs/guides/integrations.md @@ -26,8 +26,9 @@ jobs: - name: Install SBOMQS run: | - curl -LO https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_linux_amd64.tar.gz - tar -xzf sbomqs_linux_amd64.tar.gz + VERSION=v1.2.0 + curl -L -o sbomqs "https://github.com/interlynk-io/sbomqs/releases/download/${VERSION}/sbomqs-linux-amd64" + chmod +x sbomqs sudo mv sbomqs /usr/local/bin/ - name: Generate SBOM @@ -129,13 +130,13 @@ stages: - quality variables: - SBOMQS_VERSION: "latest" + SBOMQS_VERSION: "v1.2.0" MIN_SCORE: "7.0" .install-sbomqs: before_script: - - curl -LO https://github.com/interlynk-io/sbomqs/releases/${SBOMQS_VERSION}/download/sbomqs_linux_amd64.tar.gz - - tar -xzf sbomqs_linux_amd64.tar.gz + - curl -L -o sbomqs "https://github.com/interlynk-io/sbomqs/releases/download/${SBOMQS_VERSION}/sbomqs-linux-amd64" + - chmod +x sbomqs - mv sbomqs /usr/local/bin/ generate-sbom: @@ -192,7 +193,7 @@ pipeline { agent any environment { - SBOMQS_VERSION = 'latest' + SBOMQS_VERSION = 'v1.2.0' MIN_SCORE = 7.0 } @@ -200,9 +201,8 @@ pipeline { stage('Setup') { steps { sh ''' - curl -LO https://github.com/interlynk-io/sbomqs/releases/${SBOMQS_VERSION}/download/sbomqs_linux_amd64.tar.gz - tar -xzf sbomqs_linux_amd64.tar.gz - chmod +x sbomqs + curl -L -o sbomqs "https://github.com/interlynk-io/sbomqs/releases/download/${SBOMQS_VERSION}/sbomqs-linux-amd64" + chmod +x sbomqs ''' } } @@ -312,7 +312,7 @@ pool: vmImage: 'ubuntu-latest' variables: - sbomqsVersion: 'latest' + sbomqsVersion: 'v1.2.0' minScore: 7.0 stages: @@ -355,9 +355,8 @@ stages: inputs: targetType: 'inline' script: | - curl -LO https://github.com/interlynk-io/sbomqs/releases/$(sbomqsVersion)/download/sbomqs_linux_amd64.tar.gz - tar -xzf sbomqs_linux_amd64.tar.gz - chmod +x sbomqs + curl -L -o sbomqs "https://github.com/interlynk-io/sbomqs/releases/download/${SBOMQS_VERSION}/sbomqs-linux-amd64" + chmod +x sbomqs - task: Bash@3 displayName: 'Check SBOM Quality' @@ -395,74 +394,7 @@ stages: failTaskOnFailedTests: false ``` -### CircleCI - -```yaml -# .circleci/config.yml -version: 2.1 -orbs: - sbomqs: interlynk/sbomqs@1.0.0 - -jobs: - generate-sbom: - docker: - - image: cimg/base:stable - steps: - - checkout - - run: - name: Install Syft - command: | - curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b ~/bin - echo 'export PATH=~/bin:$PATH' >> $BASH_ENV - - run: - name: Generate SBOM - command: syft . -o spdx-json > sbom.json - - persist_to_workspace: - root: . - paths: - - sbom.json - - check-quality: - docker: - - image: cimg/base:stable - steps: - - attach_workspace: - at: . - - run: - name: Install SBOMQS - command: | - curl -LO https://github.com/interlynk-io/sbomqs/releases/latest/download/sbomqs_linux_amd64.tar.gz - tar -xzf sbomqs_linux_amd64.tar.gz - chmod +x sbomqs - - run: - name: Score SBOM - command: | - score=$(./sbomqs score sbom.json --json | jq '.files[0].avg_score') - echo "SBOM Score: $score/10" - - if (( $(echo "$score < 7.0" | bc -l) )); then - echo "SBOM quality score too low: $score" - exit 1 - fi - - run: - name: Check Compliance - command: | - ./sbomqs compliance --bsi-v2 sbom.json --json > bsi-compliance.json - ./sbomqs compliance --fsct sbom.json --json > fsct-compliance.json - - store_artifacts: - path: bsi-compliance.json - - store_artifacts: - path: fsct-compliance.json - -workflows: - sbom-quality: - jobs: - - generate-sbom - - check-quality: - requires: - - generate-sbom -``` ## Container Integration @@ -558,95 +490,8 @@ spec: restartPolicy: Never ``` -### CronJob for Regular Checks - -```yaml -apiVersion: batch/v1 -kind: CronJob -metadata: - name: daily-sbom-quality-check -spec: - schedule: "0 2 * * *" # Daily at 2 AM - jobTemplate: - spec: - template: - spec: - containers: - - name: sbomqs - image: ghcr.io/interlynk-io/sbomqs:latest - env: - - name: SLACK_WEBHOOK - valueFrom: - secretKeyRef: - name: slack-secrets - key: webhook-url - command: - - sh - - -c - - | - # Score all SBOMs - for sbom in /sboms/*.json; do - score=$(sbomqs score "$sbom" --json | jq '.files[0].avg_score') - name=$(basename "$sbom") - - if (( $(echo "$score < 7.0" | bc -l) )); then - # Send alert - curl -X POST "$SLACK_WEBHOOK" \ - -H 'Content-Type: application/json' \ - -d "{\"text\": \"⚠️ Low SBOM score for $name: $score/10\"}" - fi - done - volumeMounts: - - name: sboms - mountPath: /sboms - volumes: - - name: sboms - persistentVolumeClaim: - claimName: sbom-storage - restartPolicy: OnFailure -``` - ## IDE Integration -### VS Code Task - -```json -// .vscode/tasks.json -{ - "version": "2.0.0", - "tasks": [ - { - "label": "Check SBOM Quality", - "type": "shell", - "command": "sbomqs", - "args": [ - "score", - "${workspaceFolder}/sbom.json", - "--detailed" - ], - "group": { - "kind": "test", - "isDefault": true - }, - "presentation": { - "reveal": "always", - "panel": "new" - } - }, - { - "label": "Check BSI Compliance", - "type": "shell", - "command": "sbomqs", - "args": [ - "compliance", - "--bsi-v2", - "${workspaceFolder}/sbom.json" - ] - } - ] -} -``` - ### Git Hooks ```bash @@ -673,104 +518,7 @@ fi ### Dependency-Track -See [dtrack-command.md](./dtrack-command.md) for detailed integration. - -### SonarQube - -```groovy -// Add to sonar-project.properties -sonar.externalIssuesReportPaths=sbom-quality-report.json - -// Generate report in SonarQube format -stage('SBOM Analysis') { - steps { - sh ''' - sbomqs score sbom.json --json > sbom-score.json - - # Convert to SonarQube format - jq '{ - issues: [ - .files[0].scores[] | - select(.score < .max_score) | - { - engineId: "sbomqs", - ruleId: .feature, - severity: (if .score < 5 then "MAJOR" else "MINOR" end), - type: "CODE_SMELL", - primaryLocation: { - message: .description, - filePath: "sbom.json" - } - } - ] - }' sbom-score.json > sbom-quality-report.json - ''' - } -} -``` - -## API Integration - -### REST API Wrapper - -```python -#!/usr/bin/env python3 -# sbomqs-api.py - -from flask import Flask, request, jsonify -import subprocess -import json -import tempfile - -app = Flask(__name__) - -@app.route('/score', methods=['POST']) -def score_sbom(): - sbom_content = request.json - - with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f: - json.dump(sbom_content, f) - temp_path = f.name - - try: - result = subprocess.run( - ['sbomqs', 'score', temp_path, '--json'], - capture_output=True, - text=True, - check=True - ) - - return jsonify(json.loads(result.stdout)) - except subprocess.CalledProcessError as e: - return jsonify({'error': e.stderr}), 500 - finally: - os.unlink(temp_path) - -@app.route('/compliance/', methods=['POST']) -def check_compliance(standard): - sbom_content = request.json - - with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f: - json.dump(sbom_content, f) - temp_path = f.name - - try: - result = subprocess.run( - ['sbomqs', 'compliance', f'--{standard}', temp_path, '--json'], - capture_output=True, - text=True, - check=True - ) - - return jsonify(json.loads(result.stdout)) - except subprocess.CalledProcessError as e: - return jsonify({'error': e.stderr}), 500 - finally: - os.unlink(temp_path) - -if __name__ == '__main__': - app.run(host='0.0.0.0', port=8080) -``` +See [dtrack.md](../commands/dtrack.md) for detailed integration. ## Monitoring Integration @@ -832,4 +580,4 @@ if __name__ == '__main__': 3. **Track Trends**: Monitor score changes over time 4. **Share Reports**: Use the share command to create accessible reports for stakeholders 5. **Custom Profiles**: Create organization-specific scoring profiles -6. **Regular Updates**: Keep SBOMQS updated to get latest features and scoring improvements \ No newline at end of file +6. **Regular Updates**: Keep SBOMQS updated to get latest features and scoring improvements diff --git a/docs/policy.md b/docs/guides/policy.md similarity index 100% rename from docs/policy.md rename to docs/guides/policy.md diff --git a/docs/Compliance.md b/docs/reference/compliance-standards.md similarity index 100% rename from docs/Compliance.md rename to docs/reference/compliance-standards.md diff --git a/docs/reference/quality-checks.md b/docs/reference/quality-checks.md new file mode 100644 index 0000000..a9e3075 --- /dev/null +++ b/docs/reference/quality-checks.md @@ -0,0 +1,156 @@ +# SBOM Quality Checks Reference + +This reference document describes all quality checks performed by sbomqs, organized by category. + +## Check Categories + +- **NTIA-minimum-elements**: Compliance with NTIA's minimum element guidelines +- **Structural**: SBOM format and specification compliance +- **Semantic**: Correctness and validity of SBOM field meanings +- **Quality**: Data completeness and accuracy metrics +- **Sharing**: Distribution and consumption readiness +- **BSI**: German BSI TR-03183-2 compliance checks + +## Scoring Methodology + +- Each quality check has equal weight with a score range of 0.0 - 10.0 +- Checks applied to lists average scores across all elements +- Category scores are averaged across all checks in that category +- Overall score is the weighted average of all enabled categories + +## Quality Checks by Category + +### NTIA Minimum Elements + +| Check ID | Description | Required | +|----------|-------------|----------| +| `comp_with_name` | Components have names | Yes | +| `comp_with_supplier` | Components have supplier names | Yes | +| `comp_with_uniq_ids` | Components have unique identifiers | Yes | +| `comp_with_version` | Components have versions | Yes | +| `sbom_authors` | SBOM has author information | Yes | +| `sbom_creation_timestamp` | SBOM has creation timestamp | Yes | +| `sbom_dependencies` | Dependencies are documented | Yes | + +### Structural Checks + +| Check ID | Description | Impact | +|----------|-------------|---------| +| `spec_compliant` | Valid SPDX/CycloneDX specification | Critical | +| `spec_parsable` | SBOM can be parsed without errors | Critical | +| `spec_file_format` | Supported file format (JSON, XML, etc.) | High | +| `sbom_required_fields` | All required spec fields present | High | + +### Semantic Checks + +| Check ID | Description | Impact | +|----------|-------------|---------| +| `comp_valid_licenses` | Valid SPDX license identifiers | High | +| `comp_with_checksums` | Components have integrity checksums | Medium | +| `comp_with_primary_purpose` | Component type/purpose specified | Low | +| `sbom_with_primary_component` | Primary component identified | Medium | + +### Quality Checks + +| Check ID | Description | Impact | +|----------|-------------|---------| +| `comp_with_cpes` | CPE identifiers for vulnerability lookup | High | +| `comp_with_purls` | Package URLs for ecosystem identification | High | +| `comp_with_multi_vuln_lookup_id` | Multiple vulnerability identifiers | Medium | +| `comp_with_source_code_uri` | Source code repository links | Medium | +| `comp_with_executable_uri` | Binary/executable download locations | Low | +| `comp_no_deprecated_licenses` | No deprecated license usage | Medium | +| `comp_no_restrictive_licenses` | No highly restrictive licenses | Medium | + +### Sharing Checks + +| Check ID | Description | Impact | +|----------|-------------|---------| +| `sbom_sharable` | SBOM has unencumbered license | High | +| `sbom_with_uri` | SBOM has unique identifier/namespace | Medium | + +## Component-Based Features + +Features that evaluate individual components: + +- `comp_with_name`: Component has a name +- `comp_with_version`: Component has a version +- `comp_with_supplier`: Component has supplier information +- `comp_with_uniq_ids`: Component has unique identifiers +- `comp_valid_licenses`: Valid SPDX licenses +- `comp_with_any_vuln_lookup_id`: CPE or PURL present +- `comp_with_deprecated_licenses`: Uses deprecated licenses +- `comp_with_multi_vuln_lookup_id`: Both CPE and PURL present +- `comp_with_primary_purpose`: Component purpose specified +- `comp_with_restrictive_licenses`: Uses restrictive licenses +- `comp_with_checksums`: Has integrity checksums +- `comp_with_licenses`: Has license information +- `comp_with_checksums_sha256`: SHA-256 checksum present +- `comp_with_source_code_uri`: Source repository link +- `comp_with_source_code_hash`: Source code integrity hash +- `comp_with_executable_uri`: Binary download location +- `comp_with_associated_license`: Associated license present +- `comp_with_concluded_license`: Concluded license specified +- `comp_with_declared_license`: Declared license specified + +## SBOM-Based Features + +Features that evaluate document-level properties: + +- `sbom_creation_timestamp`: Creation timestamp present +- `sbom_authors`: Author information included +- `sbom_with_creator_and_version`: Creator tool and version +- `sbom_with_primary_component`: Primary component identified +- `sbom_dependencies`: Dependency relationships documented +- `sbom_sharable`: Has shareable license +- `sbom_parsable`: Can be parsed successfully +- `sbom_spec`: Valid specification format +- `sbom_spec_file_format`: Supported file format +- `sbom_spec_version`: Specification version +- `spec_with_version_compliant`: Version compliance +- `sbom_with_uri`: Has unique URI/namespace +- `sbom_with_vuln`: Contains vulnerability data +- `sbom_build_process`: Build process documented +- `sbom_with_bomlinks`: External SBOM references + +## Remediation Guidelines + +### Critical Issues (Fix Immediately) +1. Missing component versions - Required for vulnerability scanning +2. No unique identifiers - Prevents component tracking +3. Invalid specification format - Blocks SBOM usage + +### High Priority Issues +1. Missing supplier information - Supply chain transparency +2. No license information - Legal compliance risk +3. Missing checksums - Integrity verification + +### Medium Priority Issues +1. No CPE/PURL identifiers - Limited vulnerability matching +2. Missing dependency relationships - Incomplete understanding +3. No source code links - Reduced transparency + +### Low Priority Issues +1. Missing build information - Process documentation +2. No external references - Limited context +3. Component purpose not specified - Usage clarity + +## Custom Configuration + +To customize which checks are performed, generate a configuration file: + +```bash +sbomqs generate features > custom-checks.yaml +``` + +Edit the file to enable/disable specific checks and adjust weights, then use: + +```bash +sbomqs score sbom.json --configpath custom-checks.yaml +``` + +## See Also + +- [Compliance Standards Reference](./compliance-standards.md) - Detailed compliance mappings +- [Score Command](../commands/score.md) - How to run quality checks +- [Customization Guide](../guides/customization.md) - Creating custom profiles \ No newline at end of file diff --git a/docs/sbom-quality.md b/docs/sbom-quality.md deleted file mode 100644 index 937679c..0000000 --- a/docs/sbom-quality.md +++ /dev/null @@ -1,214 +0,0 @@ - -## What is a high quality SBOM - -A high quality SBOM should support managing software assets, license information and Intellectual Property as well as provide a base for configuration management, vulnerability handling and incident response. - -A quality SBOM is one that is accurate, complete, and up-to-date. There are many factors that go into constructing a high quality SBOM. - -1. Identify & list all components of your product along with their transitive dependencies. -2. List all your components along with their versions & content checksums. -3. Include accurate component licenses. -4. Include accurate lookup identifiers e.g. [purls](https://github.com/package-url/purl-spec) or [CPEs](https://csrc.nist.gov/publications/detail/nistir/7698/final). -5. Quality SBOM depends a lot upon which stage of the lifecycle it has been generated at, we believe closer to the build time is ideal. -6. Signed SBOMs. -7. Should layout information based on industry standard specs like CycloneDX, SPDX and SWID. - -## Goals - -The main goals of the utility are: - -1. Make it easy and fast to assess the quality if an SBOM, generated or acquired. -2. Support all well-known SBOM standards. -3. Scoring output should be customizable. -4. Scoring output should be consumable. - -## Goal #1: Easy & Fast - -SBOMs can be generated using both commercial and open-source tooling. As consumers of SBOMs we wanted a fast and easy way to assess the quality of an SBOM. An SBOM with a low score should be re-evaluated or rejected. - -`sbomqs` makes getting a quick assessment effortless. Just point. - -```sh -sbomqs score samples/julia.spdx.tv -b -``` - -```sh -6.9 samples/julia.spdx.json -``` - -## Goal #2: SBOM Standards - -The NTIA recommends these standards for SBOMs: - -- SPDX -- CycloneDX -- SWID - -`sbomqs` supports SPDX and CycloneDX formats. Support for SWID is incoming. - -In addition to supporting these SBOM formats, we support various formats for data representation. - -- **SPDX**: json, yaml, rdf and tag-value -- **CycloneDX**: json and xml - -## Goal #3: Customizable output - -`sbomqs` scoring output can be customized by category or by feature. We understand everyone's needs for scoring differ, hence we allow to customize which categories or features should rsp. should not be included for scoring. - -## Category scoring - -We have categorized our current features as follows: - -- **NTIA-minimum-elements**: Includes features, which help you to quickly understand if an SBOM complies with NTIA's minimum element guidelines. -- **Structural**: Checks if an SBOM complies with the underlying specifications, be it [SPDX](https://spdx.dev/specifications/) or [CycloneDX](https://cyclonedx.org/specification/overview/). -- **Semantic**: Checks meaning of SBOM fields specific to their standard. -- **Quality**: Helps to determine the quality of the data in an SBOM. -- **Sharing**: Helps to determine if an SBOM can be shared. -- [OWASP BOM Maturity Model](https://docs.google.com/spreadsheets/d/1wu6KbgwuokC5357ikrhFN-QkwQ7Pyb6z0zE80sTNNus/edit#gid=0): Work in progress - -### Category Aliases - -You can use these convenient aliases when specifying categories: - -- `ntia` or `NTIA` β†’ `NTIA-minimum-elements` -- `structural` β†’ `Structural` -- `sharing` β†’ `Sharing` -- `semantic` β†’ `Semantic` -- `quality` β†’ `Quality` -- `bsi-v1.1` β†’ BSI TR-03183-2 v1.1 scoring -- `bsi-v2.0` β†’ BSI TR-03183-2 v2.0.0 scoring - -## Feature Scoring - -We allow running any single feature to be tested against an SBOM. - -1. `sbomqs generate features` generates a features.yaml file. -2. Open the features.yaml file and select the categories or features that you want to be enabled. -3. Save and close the file. -4. `sbomqs score ~/data/app.spdx.json --configpath features.yaml` use the features.yaml file to apply the changes. - -For the list of features currently supported, visit [features.md](./Features.md). - -## Goal #4: Consumable output - -`sbomqs` provides its scoring output in basic and detailed forms. - -The basic output is great for a quick check of the quality of an SBOMs. Once you get a good sense of how the tool works, this can also become the primary way of consuming data from this tool. - -```sh -6.0 samples/blogifier-dotnet-SBOM.json -6.9 samples/julia.spdx.json -7.6 samples/sbom.spdx.yaml -``` - -Detailed output is presented in tabular and json formats, currently: - -Tabular format: this format has been inspired by oss scorecard project. - -```sh -SBOM Quality Score: 6.0 samples/blogifier-dotnet-SBOM.json -+-----------------------+--------------------------------+-----------+--------------------------------+ -| CATEGORY | FEATURE | SCORE | DESC | -+-----------------------+--------------------------------+-----------+--------------------------------+ -| NTIA-minimum-elements | Doc has creation timestamp | 10.0/10.0 | doc has creation timestamp | -| | | | 2022-11-04T16:51:54Z | -+ +--------------------------------+-----------+--------------------------------+ -| | Components have supplier names | 0.0/10.0 | 0/1649 have supplier names | -+ +--------------------------------+-----------+--------------------------------+ -| | Components have names | 10.0/10.0 | 1649/1649 have names | -+ +--------------------------------+-----------+--------------------------------+ -| | Doc has relationships | 0.0/10.0 | doc has 0 relationships | -+ +--------------------------------+-----------+--------------------------------+ -... -... -``` - -json format - -```json -{ - "run_id": "fc86a94d-7490-4f20-a202-b04bb3cdfde9", - "timestamp": "2023-02-17T14:58:55Z", - "creation_info": { - "name": "sbomqs", - "version": "v0.0.6-3-g248d059", - "scoring_engine_version": "1" - }, - "files": [ - { - "file_name": "samples/blogifier-dotnet-SBOM.json", - "spec": "cyclonedx", - "spec_version": "1.4", - "file_format": "json", - "avg_score": 6, - "num_components" : 3, - "scores": [ - { - "category": "Structural", - "feature": "Spec File Format", - "score": 10, - "max_score": 10, - "description": "provided sbom should be in supported file format for spec: json and version: json,xml" - } - ] - } - ] -} -``` - -## Compliance Reports - -sbomqs can produce compliance reports for industry standard requirements. Details about compliance implementation are [avaliable here](./Compliance.md). - -## Reports - -- [BSI TR-03183-2 v2.0.0](https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Publications/TechGuidelines/TR03183/BSI-TR-03183-2.pdf) (September 2024) -- [BSI TR-03183-2 v1.1](https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Publications/TechGuidelines/TR03183/BSI-TR-03183-2.pdf) (legacy) -- [Framing Software Component Transparency v3](https://www.cisa.gov/sites/default/files/2024-11/Framing-Software-Component-Transparency-V3-508c.pdf) -- [OpenChain Telco SBOM Guide Version 1.0](https://github.com/OpenChain-Project/Reference-Material/blob/master/SBOM-Quality/Version-1/OpenChain-Telco-SBOM-Guide_EN.md) -- [NTIA minimum element](https://www.ntia.doc.gov/files/ntia/publications/sbom_minimum_elements_report.pdf) - Coming soon. -- [OWASP SCVS](https://scvs.owasp.org/bom-maturity-model/) - Coming soon. - -Example of a BSI v2.0.0 report - -```json -{ - "report_name": "Cyber Resilience Requirements for Manufacturers and Products Report", - "subtitle": "Part 2: Software Bill of Materials (SBOM)", - "revision": "TR-03183-2 (2.0.0)", - "run": { - "id": "375c288b-0928-4066-9e3a-b8655ac29f91", - "generated_at": "2024-04-18T03:22:56Z", - "file_name": "samples/photon.spdx.json" - }, - "tool": { - "name": "sbomqs", - "version": "v0.0.30-23-g344a584-dirty", - "vendor": "Interlynk (https://interlynk.io)" - }, - "summary": { - "total_score": 4.20, - "max_score": 10, - "required_elements_score": 5.91, - "optional_elements_score": 2.50 - }, -"sections": [ - { - "section_title": "SBOM formats", - "section_id": "4", - "section_data_field": "specification", - "required": true, - "element_id": "sbom", - "element_result": "spdx", - "score": 10 - }, -... -``` - -Example of a OpenChain Telco SBOM Basic Report - -``` -➜ sbomqs git:(fix/command-line) ./build/sbomqs compliance -t -b constellation-spdx.json -OpenChain Telco Report -Score:3.1 RequiredScore:3.1 OptionalScore:0.0 for constellation-spdx.json -``` diff --git a/docs/score.md b/docs/score.md deleted file mode 100644 index eeeadc5..0000000 --- a/docs/score.md +++ /dev/null @@ -1,181 +0,0 @@ -# Score command - -`sbomqs` tool score the provided SBOM for the list of the features that compliance has in a summarized manner. Currently, we support NTIA-minimum-elements compliance only. But we are extending it's supports for BSI-V1 and BSI-V2 also. - -Let's look at the score command o/ps for different compliances. - -## NTIA Minimum Elements - -```bash -$ sbomqs score -c NTIA-minimum-elements samples/photon.spdx.json -``` - -o/p: - -```bash -SBOM Quality by Interlynk Score:8.5 components:38 samples/photon.spdx.json -+-----------------------+-------------------------+-----------+--------------------------------+ -| CATEGORY | FEATURE | SCORE | DESC | -+-----------------------+-------------------------+-----------+--------------------------------+ -| NTIA-minimum-elements | comp_with_name | 10.0/10.0 | 38/38 have names | -+ +-------------------------+-----------+--------------------------------+ -| | comp_with_supplier | 0.0/10.0 | 0/38 have supplier names | -+ +-------------------------+-----------+--------------------------------+ -| | comp_with_uniq_ids | 10.0/10.0 | 38/38 have unique ID's | -+ +-------------------------+-----------+--------------------------------+ -| | comp_with_version | 9.7/10.0 | 37/38 have versions | -+ +-------------------------+-----------+--------------------------------+ -| | sbom_authors | 10.0/10.0 | doc has 1 authors | -+ +-------------------------+-----------+--------------------------------+ -| | sbom_creation_timestamp | 10.0/10.0 | doc has creation timestamp | -| | | | 2023-01-12T22:06:03Z | -+ +-------------------------+-----------+--------------------------------+ -| | sbom_dependencies | 10.0/10.0 | doc has 1 dependencies | -+-----------------------+-------------------------+-----------+--------------------------------+ -``` - -## BSI-V1.0.0 - -```bash -$ sbomqs score -c bsi-v1.0.0 sbom.json -``` - -o/p would be: - -```bash -SBOM Quality by Interlynk Score:7.1 components:279 sbom.json -+-----------------------+----------------------------+-----------+-------------------------------------------+ -| CATEGORY | FEATURE | SCORE | DESC | -+-----------------------+----------------------------+-----------+-------------------------------------------+ -| BSI-V2 | spec_compliant | 5.0/10.0 | SPDX/CycloneDX version exists, but format | -| | | | usage is partially non-deterministic | -+ +----------------------------+-----------+-------------------------------------------+ -| | sbom_authors | 10.0/10.0 | doc has 1 author with email or URL | -+ +----------------------------+-----------+-------------------------------------------+ -| | sbom_creation_timestamp | 10.0/10.0 | doc has creation timestamp | -| | | | 2023-01-12T22:06:03Z | -+ +----------------------------+-----------+-------------------------------------------+ -| | sbom_dependencies | 0.0/10.0 | doc has 10 dependencies | -+ +----------------------------+-----------+-------------------------------------------+ -| | sbom_with_uri | 0.0/10.0 | doc has 1 namespace(spdx) or | -| | | | doc has 1 bom-links(cdx) | -+ +----------------------------+-----------+-------------------------------------------+ -| | comp_with_name | 10.0/10.0 | 279/279 have names | -+ +----------------------------+-----------+-------------------------------------------+ -| | comp_with_uniq_ids | 10.0/10.0 | 279/279 have PURLs or CPEs | -+ +----------------------------+-----------+-------------------------------------------+ -| | comp_with_version | 10.0/10.0 | 279/279 have versions | -+ +----------------------------+-----------+-------------------------------------------+ -| | comp_with_supplier | 10.0/10.0 | 27/279 have supplier names | -+ +----------------------------+-----------+-------------------------------------------+ -| | comp_with_licenses | 5.0/10.0 | 100/279 have license compliant | -+ +----------------------------+-----------+-------------------------------------------+ -| | comp_with_hashes | 7.5/10.0 | 200/279 have checksum values | -+ +----------------------------+-----------+-------------------------------------------+ -| | comp_with_source_code_uri | 0.0/10.0 | 0/279 have extRef of type vcs(cdx) or | -| | | | no-deterministic-field (spdx) | -+ +----------------------------+-----------+-------------------------------------------+ -| | comp_with_executable_uri | 0.0/10.0 | 0/279 have extRef of type distribution(cdx| -| | | | 22/279 have comp download location(spdx) | -+ +----------------------------+-----------+-------------------------------------------+ -| | comp_with_source_code_hash | 0.0/10.0 | no-deterministic-field for cdx | -| | | | 20/279 have package verification code(spdx| -+-----------------------+----------------------------+-----------+-------------------------------------------+ -``` - -## BSI:v2.0.0 - -```bash -$ sbomqs score --category bsi-v2.0.0 samples/photon.spdx.json -``` - -o/p would be: - -```bash -SBOM Quality by Interlynk Score:7.1 components:279 sbom.json -+-----------------------+------------------------------+-----------+-------------------------------------------+ -| CATEGORY | FEATURE | SCORE | DESC | -+-----------------------+------------------------------+-----------+-------------------------------------------+ -| BSI-V2 | sbom_with_vuln | 10.0/10.0 | doc has no vulnerability | -+ +------------------------------+-----------+-------------------------------------------+ -| | spec_compliant | 5.0/10.0 | SPDX/CycloneDX version exists, but format | -+ +------------------------------+-----------+-------------------------------------------+ -| | sbom_build_process | 0.0/10.0 | doc build process is build type | -+ +------------------------------+-----------+-------------------------------------------+ -| | sbom_authors | 10.0/10.0 | doc has 1 author with email or URL | -+ +------------------------------+-----------+-------------------------------------------+ -| | sbom_creation_timestamp | 10.0/10.0 | doc has creation timestamp | -| | | | 2023-01-12T22:06:03Z | -+ +------------------------------+-----------+-------------------------------------------+ -| | sbom_dependencies | 0.0/10.0 | primary comp has 10 dependencies | -+ +------------------------------+-----------+-------------------------------------------+ -| | sbom_with_uri | 0.0/10.0 | doc has 1 namespace(spdx) or | -| | | | doc has 1 bom-links(cdx) | -+ +------------------------------+-----------+-------------------------------------------+ -| | sbom_with_bomlinks | 0.0/10.0 | doc has 1 namespace(spdx) or | -| | | | doc has 1 bom-links(cdx) | -+ +------------------------------+-----------+-------------------------------------------+ -| | sbom_signature | 0.0/10.0 | doc has no signature | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_name | 10.0/10.0 | 279/279 have names | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_uniq_ids | 10.0/10.0 | 279/279 have PURLs or CPEs | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_version | 10.0/10.0 | 279/279 have versions | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_supplier | 10.0/10.0 | 27/279 have supplier names | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_associated_license | 5.0/10.0 | 100/279 have license compliant | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_concluded_license | 5.0/10.0 | 100/279 have license compliant | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_declared_license | 5.0/10.0 | 100/279 have license compliant | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_dependencies | 7.5/10.0 | 200/279 have at least 1 deps | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_hashes | 7.5/10.0 | 200/279 have checksum values | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_source_code_uri | 0.0/10.0 | 0/279 have extRef of type vcs(cdx) or | -| | | | no-deterministic-field (spdx) | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_executable_hash | 7.5/10.0 | 200/279 have executable checksum values | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_executable_uri | 0.0/10.0 | 0/279 have extRef of type distribution(cdx| -| | | | 22/279 have comp download location(spdx) | -+ +------------------------------+-----------+-------------------------------------------+ -| | comp_with_source_code_hash | 0.0/10.0 | no-deterministic-field for cdx | -| | | | 20/279 have package verification code(spdx| -+-----------------------+------------------------------+-----------+-------------------------------------------+ -``` - -## List of checks in all categories - -This section is to bring all the checks or feature at one place for easy readability. It would helps us to understand all list of features in one go and also able to differentiate b/w them. -Below is the following list of checks or features for all categories: - -| **Feature** | **Description** | **SPDX** | **CycloneDX** | -| -------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------- | -| `comp_with_licenses` | Ensures components list at least one license | `PackageLicenseDeclared: MIT` or `PackageLicenseConcluded: Apache-2` | `components[].licenses: [{ license: { id: "MIT" } }]` | -| `comp_with_associated_license` | Confirms that an associated license is present for each component | `PackageLicenseInfoFromFiles: GPL-2.0` | `licenses[].license.id: GPL-2.0` | -| `comp_with_concluded_license` | Ensures a concluded license has been determined per component | `PackageLicenseConcluded: Apache-2.0` | `components[].licenses: [{ license: { id: "MIT", Acknowledgement: LicenseAcknowledgementConcluded } }]` | -| `comp_with_declared_license` | Ensures declared license is specified explicitly for components | `PackageLicenseDeclared: MIT` | `components[].licenses: [{ license: { id: "MIT", Acknowledgement: LicenseAcknowledgementDeclared } }]` | -| `comp_with_checksums_sha256` | Confirms that components include SHA-256 checksums | `PackageChecksum: SHA256: abc123...` | `components[].hashes: [{ alg: "SHA-256", content: "abc123..." }]` | -| `comp_with_checksums` | Confirms components include any valid checksum | `PackageChecksum: SHA1/SHA256/...` | `components[].hashes: [...]` | -| `comp_with_source_code_uri` | Verifies that a component provides a source code URL | `NONE` | `externalReferences: [{ type: "vcs", url: "..." }]` | -| `comp_with_source_code_hash` | Ensures hash is available for source code (often as part of SLSA, integrity) | `PackageVerificationCode: "....."` | `externalReferences: [{ type: "vcs", url: "...", hashes: [...] }]` | -| `comp_with_executable_uri` | Ensures executable download URL is provided | `PackageDownloadLocation: "..."` | `externalReferences: [{ type: "distribution-intake", url: "..." }]` | -| `comp_with_executable_hash` | Ensures executable hash (e.g., SHA-256) is present | `PackageChecksum: SHA256` | `externalReferences: [{ type: "distribution-intake", url: "...", hashes: [...] }]` | -| `sbom_with_uri` | Confirms that SBOM references its canonical URL | `Namespace` | `"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79"`, `"version": 1,` | -| `sbom_with_signature` | Checks if the SBOM contains a cryptographic signature | externally provideed with `--sig` `--pub` | `declarations.Signatures[{algorithm: "...", value: "...", publicKey: [{kty: "...", n: "...", e: "..."}]}]` | -| `sbom_with_vuln` | Checks if known vulnerabilities are attached or referenced | `NONE` | `vulnerabilities[]` block | -| `sbom_build_process` | Describes how the SBOM was created (e.g., tooling, steps) | `NONE` | `metadata.lifecycles: {"build" }` | -| `sbom_required_fields` | Validates that the SBOM includes required baseline fields | SPDXVersion, DataLicense, SPDXID, etc. | Format, version, metadata timestamp, etc. | -| `sbom_with_creator_and_version` | Ensures both creator identity and version info are available | `Creator: ToolX v1.2.3` | `metadata.tools: { name: "ToolX", version: "1.2.3" }` | -| `sbom_with_primary_component` | Identifies the primary component the SBOM is describing | `PackageName: my-app` if `RelationshipType: DESCRIBE` | `metadata.component.name: "my-app"` | -| `comp_with_primary_purpose` | Verifies components state their intended role (e.g., library, application) | Not available in SPDX | `components[].type: "library"` | -| `comp_valid_licenses` | Ensures license identifiers are valid and conform to SPDX license list | `License: MIT, Apache-2.0` | `licenses[].license.id: MIT, Apache-2.0` | -| `comp_with_deprecated_licenses` | Flags use of licenses that are deprecated or discouraged | `License: GPL-1.0+` | `licenses[].license.id: GPL-1.0+` | -| `comp_with_restrictive_licenses` | Flags licenses with strong copyleft or legal obligations | `License: AGPL-3.0, CC-BY-NC-4.0` | `licenses[].license.id: AGPL-3.0` | -| `comp_with_any_vuln_lookup_id` | Ensures component has at least one vulnerability lookup ID like PURL/CPE | `ExternalRef: PURL/CPE:...` | `purl`, `externalReferences` | -| `comp_with_multi_vuln_lookup_id` | Confirms component has multiple IDs for better lookup coverage | Both PURL and CPE listed | `externalReferences: [ { type: "purl" }, { type: "cpe23Type" } ]` | -| `sbom_sharable` | Checks if SBOM has an explicit license for sharing | `DocumentLicense: CC0-1.0` | `metadata.licenses: [ { id: "CC0-1.0" } ]` | From e92a58299836de4e66824751f313b9899fea74bf Mon Sep 17 00:00:00 2001 From: Ritesh Noronha Date: Sun, 19 Oct 2025 12:58:33 -0700 Subject: [PATCH 2/2] remove golanci and sbom-dev --- .github/workflows/golangci-lint.yml | 36 --------------- .github/workflows/sbom_dev.yml | 70 ----------------------------- 2 files changed, 106 deletions(-) delete mode 100644 .github/workflows/golangci-lint.yml delete mode 100644 .github/workflows/sbom_dev.yml diff --git a/.github/workflows/golangci-lint.yml b/.github/workflows/golangci-lint.yml deleted file mode 100644 index 95df054..0000000 --- a/.github/workflows/golangci-lint.yml +++ /dev/null @@ -1,36 +0,0 @@ -name: golangci-lint - -on: - pull_request: - branches: main - types: - - opened - - reopened - - synchronize - -permissions: - contents: read - -jobs: - golangci: - name: lint - runs-on: ubuntu-latest - - permissions: - contents: read - pull-requests: read - - steps: - - name: Checkout mode - uses: actions/checkout@v4 - - - name: Set up Go - uses: actions/setup-go@v5 - with: - go-version-file: go.mod - cache: false - - - name: Run golangci-lint - uses: golangci/golangci-lint-action@v6 - with: - args: --timeout=5m diff --git a/.github/workflows/sbom_dev.yml b/.github/workflows/sbom_dev.yml deleted file mode 100644 index 9306830..0000000 --- a/.github/workflows/sbom_dev.yml +++ /dev/null @@ -1,70 +0,0 @@ -name: Dev | Build SBOM - -on: - push: - pull_request: - workflow_dispatch: - -env: - TOOL_NAME: ${{ github.repository }} - SUPPLIER_NAME: Interlynk - SUPPLIER_URL: https://interlynk.io - DEFAULT_TAG: v0.0.1 - PYLYNK_TEMP_DIR: $RUNNER_TEMP/pylynk - SBOM_TEMP_DIR: $RUNNER_TEMP/sbom - SBOM_ENV: development - SBOM_FILE_PATH: $RUNNER_TEMP/sbom/_manifest/spdx_2.2/manifest.spdx.json - MS_SBOM_TOOL_URL: https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64 - MS_SBOM_TOOL_EXCLUDE_DIRS: "**/samples/**" - INTERLYNK_API_URL: ${{ vars.INTERLYNK_API_URL }} - -jobs: - build-sbom: - name: Build SBOM - runs-on: ubuntu-latest - permissions: - id-token: write - contents: write - steps: - - name: Checkout Repository - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - name: Get Tag - id: get_tag - run: echo "LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo 'v0.0.1')" >> $GITHUB_ENV - - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: "3.x" # Specify the Python version needed - - - name: Checkout Python SBOM tool - run: | - git clone https://github.com/interlynk-io/pylynk.git ${{ env.PYLYNK_TEMP_DIR }} - # cd ${{ env.PYLYNK_TEMP_DIR }} - # git fetch --tags - # latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`) - # git checkout $latest_tag - # echo "Checked out pylynk at tag: $latest_tag" - - - name: Install Python dependencies - run: | - cd ${{ env.PYLYNK_TEMP_DIR }} - pip install -r requirements.txt - - - name: Generate SBOM - shell: bash - run: | - cd ${{ github.workspace }} - mkdir -p ${{ env.SBOM_TEMP_DIR}} - curl -Lo $RUNNER_TEMP/sbom-tool ${{ env.MS_SBOM_TOOL_URL }} - chmod +x $RUNNER_TEMP/sbom-tool - SANITIZED_REF=$(echo "${{ github.ref_name}}" | sed -e 's/[^a-zA-Z0-9.-]/-/g' -e 's/^[^a-zA-Z0-9]*//g') - VERSION=${{ env.LATEST_TAG }}-$SANITIZED_REF - $RUNNER_TEMP/sbom-tool generate -b ${{ env.SBOM_TEMP_DIR }} -bc . -pn ${{ env.TOOL_NAME }} -pv $VERSION -ps ${{ env.SUPPLIER_NAME}} -nsb ${{ env.SUPPLIER_URL }} -cd "--DirectoryExclusionList ${{ env.MS_SBOM_TOOL_EXCLUDE_DIRS }}" - - - name: Upload SBOM - run: | - python3 ${{ env.PYLYNK_TEMP_DIR }}/pylynk.py --verbose upload --prod ${{env.TOOL_NAME}} --env ${{ env.SBOM_ENV }} --sbom ${{ env.SBOM_FILE_PATH }} --token ${{ secrets.INTERLYNK_SECURITY_TOKEN }}