Skip to content

sbom-verification.md

Latest commit

 

History

History
253 lines (190 loc) · 7.05 KB

sbom-verification.md

File metadata and controls

253 lines (190 loc) · 7.05 KB

SBOM Verification Guide

This guide explains how to verify and use Software Bill of Materials (SBOM) files distributed with Scopes releases.

Overview

Scopes releases include comprehensive SBOM files that provide:

  • Complete dependency inventory: All direct and transitive dependencies
  • Vulnerability tracking: Integration with security databases
  • License compliance: Full license information for all components
  • Supply chain transparency: Build-time dependency resolution

SBOM Formats

CycloneDX (Recommended for Security)

  • Format: JSON
  • Focus: Security-oriented with vulnerability tracking
  • Features: VEX (Vulnerability Exploitability eXchange) support
  • Files: sbom/scopes-sbom.json (source SBOM), sbom/scopes-binary-sbom.json (binary SBOM)

CycloneDX Advantages

  • Native vulnerability database integration
  • Real-time security analysis capabilities
  • OWASP ecosystem compatibility
  • Continuous security monitoring support

Verification Steps

1. Automated Verification (Recommended)

Use the JAR bundle package that includes SBOM validation:

# Linux/macOS - Extract JAR bundle
tar -xzf scopes-v1.0.0-jar-bundle.tar.gz
cd scopes-v1.0.0-jar-bundle

# SBOM files are included in the bundle
ls sbom/scopes-sbom.json sbom/scopes-binary-sbom.json

# Run installation with automatic verification
./install.sh  # Includes SBOM verification
# Windows PowerShell - Extract JAR bundle
Expand-Archive scopes-v1.0.0-jar-bundle.zip -DestinationPath .
cd scopes-v1.0.0-jar-bundle

# SBOM files are included in the bundle
Get-ChildItem sbom\scopes-sbom.json, sbom\scopes-binary-sbom.json

# Run installation with automatic verification
.\install.ps1  # Includes SBOM verification

2. Manual Download and Verify Checksums

# Download and extract the JAR bundle
wget https://github.com/kamiazya/scopes/releases/download/v1.0.0/scopes-v1.0.0-jar-bundle.tar.gz
tar -xzf scopes-v1.0.0-jar-bundle.tar.gz
cd scopes-v1.0.0-jar-bundle

# Verify SBOM integrity using the included verification files
sha256sum -c verification/scopes.jar.sha256

3. Validate SBOM Format

# Install CycloneDX CLI tools
npm install -g @cyclonedx/cli

# Validate SBOM format compliance (from within the extracted bundle)
cyclonedx validate sbom/scopes-sbom.json
cyclonedx validate sbom/scopes-binary-sbom.json

4. SLSA Provenance Integration

SBOM files are included in the SLSA provenance generation process:

# Verify JAR file is covered by SLSA provenance
slsa-verifier verify-artifact scopes.jar \
  --provenance-path verification/multiple.intoto.jsonl \
  --source-uri github.com/kamiazya/scopes

Security Analysis

Vulnerability Scanning

# Scan for known vulnerabilities (source SBOM)
cyclonedx analyze sbom/scopes-sbom.json

# Scan binary SBOM
cyclonedx analyze sbom/scopes-binary-sbom.json

# Generate vulnerability report
cyclonedx analyze sbom/scopes-binary-sbom.json --output-format json > vulnerabilities.json

License Compliance

# Extract license information (source SBOM)
cyclonedx licenses sbom/scopes-sbom.json

# Generate license report
cyclonedx licenses sbom/scopes-sbom.json --output-format csv > licenses.csv

Integration with Security Tools

OWASP Dependency-Track

# Upload source SBOM to Dependency-Track server
curl -X POST "http://dtrack-server/api/v1/bom" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d @sbom/scopes-sbom.json

Grype Vulnerability Scanner

# Scan binary SBOM with Grype
grype sbom:sbom/scopes-binary-sbom.json

# Generate detailed report
grype sbom:sbom/scopes-binary-sbom.json -o json > grype-report.json

Syft Analysis

# Analyze binary SBOM with Syft
syft scan sbom/scopes-binary-sbom.json

# Convert between formats
syft convert sbom/scopes-binary-sbom.json -o spdx-json > sbom.spdx.json

Continuous Monitoring

Automated Vulnerability Alerts

# Example GitHub Actions workflow for monitoring
name: SBOM Security Monitor
on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM

jobs:
  monitor:
    runs-on: ubuntu-latest
    steps:
    - name: Download and extract latest JAR bundle
      run: |
        wget https://github.com/kamiazya/scopes/releases/latest/download/scopes-jar-bundle.tar.gz
        tar -xzf scopes-jar-bundle.tar.gz
        cd scopes-*-jar-bundle

    - name: Scan for vulnerabilities
      run: |
        cd scopes-*-jar-bundle
        grype sbom:sbom/scopes-binary-sbom.json --fail-on critical

Policy Enforcement

{
  "name": "Scopes Security Policy",
  "rules": [
    {
      "type": "vulnerability",
      "severity": "critical",
      "action": "fail"
    },
    {
      "type": "license",
      "allowed": ["Apache-2.0", "MIT", "BSD-3-Clause"],
      "action": "warn"
    }
  ]
}

Best Practices

For Users

  1. Always verify checksums before using SBOM files
  2. Regularly scan for new vulnerabilities
  3. Monitor license compliance for your use case
  4. Store SBOM files for audit and compliance requirements

For Security Teams

  1. Integrate with existing tools (SIEM, vulnerability management)
  2. Set up automated monitoring for new releases
  3. Establish response procedures for critical vulnerabilities
  4. Maintain audit trails of SBOM verification activities

For Compliance Teams

  1. Archive SBOM files with release artifacts
  2. Document verification procedures in compliance frameworks
  3. Regular compliance checks against organizational policies
  4. Third-party audit support with complete dependency information

Troubleshooting

SBOM Validation Fails

  • Ensure you're using compatible tool versions
  • Check for file corruption by verifying checksums
  • Validate network connectivity for tool downloads

Missing Dependencies

  • Some dependencies may be build-time only
  • Check both runtime and compile-time configurations
  • Verify against actual deployed binaries

Tool Compatibility Issues

  • Use recommended tool versions from documentation
  • Check tool-specific format requirements
  • Consider format conversion when necessary

Related Documentation

Resources

Questions?

If you have questions about SBOM verification:

  • Check our Security Policy
  • Open an issue in the repository
  • Contact the maintainers directly

Remember: SBOM files are living documents - dependencies and vulnerabilities change over time, so regular verification is essential for maintaining security.