SecureSBOM API

sbomasm provides enterprise-grade cryptographic signing and verification for SBOMs through integration with ShiftLeftCyber's SecureSBOM API. The implementation supports CycloneDX embedded and detached signatures and SPDX detached signatures.

Why Sign SBOMs?

In today's interconnected software supply chain, SBOMs are shared across organizations, stored in repositories, and transmitted through various channels. Unsigned SBOMs are vulnerable - they can be modified by malicious actors, corrupted during transmission, or tampered with while stored, creating significant security and compliance risks.

For SBOM Producers

Cryptographically signing your SBOMs provides:

• Proof of authenticity - Verify you are the legitimate creator
• Non-repudiation - Cannot deny creating the signed SBOM
• Integrity assurance - Detect any unauthorized modifications
• Compliance confidence - Meet regulatory requirements for supply chain security

For SBOM Consumers

Signature verification enables you to:

• Trust the source - Confirm the SBOM comes from a verified producer
• Detect tampering - Identify if the SBOM has been modified in transit or storage
• Establish authenticity - Validate the SBOM represents the actual software components
• Maintain compliance - Ensure your supply chain meets security standards

Getting Started

SecureSBOM access requires an API key. Get started by:

1. Learn more about ShiftLeftCyber and the SecureSBOM solution
2. Request access by completing the contact form
3. Set up your environment with the provided API credentials
4. Start signing your SBOMs with enterprise-grade cryptographic security

The sections below provide comprehensive guidance on implementation, from basic usage to advanced CI/CD integration.

Overview

sbomasm supports the following commands to utilize the SecureSBOM API:

• securesbomkey - Manage cryptographic keys for signing and verification
• sign - Cryptographically sign an SBOM to prove authenticity
• verify - Verify the cryptographic signature of a signed SBOM

Basic Usage

Key Management

# Generate a new signing key
sbomasm securesbomkey generate

# List available keys
sbomasm securesbomkey list

# Get public key for sharing
sbomasm securesbomkey public <key-id>

Signing an SBOM

sbomasm sign --key-id <your-key-id> <input-sbom>

By default, CycloneDX signing returns a signed SBOM response with the signed document in signed_sbom. SPDX signing returns a detached signature response because SPDX signatures are not embedded into the SBOM.

Use --detached to request a detached signature response:

sbomasm sign --key-id <your-key-id> --detached --output signed-response.json <input-sbom>

Verifying a CycloneDX SBOM With Embedded Signature

sbomasm verify --key-id <key-id> <signed-sbom>

Verifying a CycloneDX SBOM With Detached Signature

sbomasm verify --key-id <key-id> --signature signed-cyclonedx-detached-response.json <original-sbom>

CycloneDX detached verification requires the detached signing response JSON, not only the raw signature value.

Verifying an SPDX SBOM With Detached Signature

sbomasm verify --key-id <key-id> --signature <base64-signature-json-payload-or-file> <original-sbom>

Command Options

Sign Command

Required Options

• --key-id <string>: Key ID to use for signing the SBOM

Signing Options

• --detached: Return a detached signature response instead of the default signing response

Authentication Options

• --api-key <string>: API key for authentication (or set SECURE_SBOM_API_KEY)
• --base-url <url>: Base URL for SecureSBOM API (or set SECURE_SBOM_BASE_URL)

Output Options

• --output <path>: Output file path for signed SBOM
  • Default: stdout
  • Use - for explicit stdout output
• --quiet: Suppress progress messages and status output

Network Options

• --timeout <duration>: Request timeout (default: 30s)
• --retry <number>: Number of retry attempts for failed requests (default: 3)

Verify Command

Required Options

• --key-id <string>: Public key ID used to verify the signature

Required Options (SPDX Verification)

• --signature <string>: Detached signature value, detached signing response JSON, or path to a signature response file

For SPDX, --signature may be a raw base64 signature, the full JSON signing response containing signature_b64, or a path to a file containing either form. For CycloneDX detached signatures, pass the full detached signing response JSON or a path to the detached signing response file.

Authentication Options

• --api-key <string>: API key for authentication (or set SECURE_SBOM_API_KEY)
• --base-url <url>: Base URL for SecureSBOM API (or set SECURE_SBOM_BASE_URL)

Output Options

• --output <format>: Output format, either text or json (default: text)
• --quiet: Suppress progress output (exit code indicates success/failure)

Network Options

• --timeout <duration>: Request timeout (default: 30s)
• --retry <number>: Number of retry attempts for failed requests (default: 3)

Securesbomkey Command

Subcommands

• generate: Generate a new cryptographic key pair
• list: List all available keys in your account
• public <key-id>: Retrieve the public key for sharing

Authentication Options

• --api-key <string>: API key for authentication (or set SECURE_SBOM_API_KEY)
• --base-url <url>: Base URL for SecureSBOM API (or set SECURE_SBOM_BASE_URL)

Output Options

• securesbomkey list --output table|json: Output list results as a table or JSON
• securesbomkey generate --output table|json: Output generated key details as a table or JSON
• securesbomkey public <key-id> --output <path>: Write the public key PEM to a file
• --quiet: Suppress progress output

How It Works

Signing Process

1. Authentication: Connects to SecureSBOM API using your API key
2. Key Validation: Verifies the specified key ID exists and is linked to your account
3. SBOM Processing: Parses and validates the input SBOM format
4. Signature Generation: Creates a cryptographic signature using your private key
5. Format Integration: Embeds the signature according to format standards:
   • CycloneDX: Supports embedded signatures and detached signature responses
   • SPDX: Uses detached signature responses
6. Output: Returns a JSON signing response. For embedded CycloneDX signatures, the signed SBOM is in signed_sbom. For detached signatures, the response contains the detached signature material.

Verification Process

1. Signature Extraction: Extracts an embedded CycloneDX signature from the signed SBOM or uses the detached signature value passed with --signature
2. Key Retrieval: Fetches the corresponding public key using the key ID
3. Hash Verification: Validates the SBOM content against the signature
4. Integrity Check: Confirms the SBOM has not been modified since signing
5. Result: Returns verification status and signature metadata

Key Management

The SecureSBOM API manages your cryptographic keys securely:

• Key Generation: Creates an ECDSA key pair
• Secure Storage: Private keys are securely stored by the SecureSBOM service
• Access Control: Keys are tied to your API account and access permissions
• Public Key Sharing: Public keys can be shared for verification purposes

Examples

Basic Signing and Verification

# Sign an SBOM
sbomasm sign --key-id prod-key-2024 --output signed-sbom.json sbom.json

# Verify a CycloneDX signed response with embedded signature
sbomasm verify --key-id prod-key-2024 signed-sbom.json

# Sign a CycloneDX SBOM with a detached signature response
sbomasm sign --key-id prod-key-2024 --detached --output signed-cdx-detached.json sbom.cdx.json

# Verify a CycloneDX SBOM with a detached signature response file
sbomasm verify --key-id prod-key-2024 --signature signed-cdx-detached.json sbom.cdx.json

# Verify an SPDX SBOM with a detached signature response file
sbomasm verify --key-id prod-key-2024 --signature signed-spdx.json sbom.spdx.json

Environment Variables Setup

# Set up API credentials
export SECURE_SBOM_API_KEY="your-api-key-here"

Output example:

Loading signed SBOM...
Verifying CycloneDX SBOM with embedded signature...
✓ SBOM signature is VALID
Message: signature is valid
Key ID: 045728s6-h18q-649z-67fdb-27c2afcab510
Algorithm: ES256
Verified at: 2025-09-08T06:51:41-04:00

Advanced Use Cases

CI/CD Pipeline Integration

GitHub Actions Example

name: Sign and Verify SBOM
on: [push]

jobs:
  sbom-security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Generate SBOM
        run: syft . -o cyclonedx-json=sbom.json
        
      - name: Sign SBOM
        env:
          SECURE_SBOM_API_KEY: ${{ secrets.SECURE_SBOM_API_KEY }}
        run: |
          sbomasm sign \
            --key-id ${{ secrets.SIGNING_KEY_ID }} \
            --output signed-sbom.json \
            sbom.json
            
      - name: Verify SBOM
        env:
          SECURE_SBOM_API_KEY: ${{ secrets.SECURE_SBOM_API_KEY }}
        run: |
          sbomasm verify \
            --key-id ${{ secrets.SIGNING_KEY_ID }} \
            signed-sbom.json
            
      - name: Upload Signed SBOM
        uses: actions/upload-artifact@v3
        with:
          name: signed-sbom
          path: signed-sbom.json

Jenkins Pipeline Example

pipeline {
    agent any
    
    environment {
        SECURE_SBOM_API_KEY = credentials('secure-sbom-api-key')
        SIGNING_KEY_ID = 'prod-signing-key-2024'
    }
    
    stages {
        stage('Generate SBOM') {
            steps {
                sh 'syft . -o cyclonedx-json=sbom.json'
            }
        }
        
        stage('Sign SBOM') {
            steps {
                sh '''
                    sbomasm sign \
                        --key-id ${SIGNING_KEY_ID} \
                        --output signed-sbom.json \
                        sbom.json
                '''
            }
        }
        
        stage('Verify SBOM') {
            steps {
                sh '''
                    sbomasm verify \
                        --key-id ${SIGNING_KEY_ID} \
                        signed-sbom.json
                '''
            }
        }
        
        stage('Archive') {
            steps {
                archiveArtifacts artifacts: 'signed-sbom.json'
            }
        }
    }
}

Batch Processing

Process multiple SBOMs in bulk:

#!/bin/bash
# batch-sign.sh

SIGNING_KEY="batch-key-2024"
INPUT_DIR="sboms"
OUTPUT_DIR="signed-sboms"

mkdir -p "$OUTPUT_DIR"

for sbom in "$INPUT_DIR"/*.json; do
    filename=$(basename "$sbom")
    echo "Signing $filename..."
    
    sbomasm sign \
        --key-id "$SIGNING_KEY" \
        --output "$OUTPUT_DIR/signed-$filename" \
        "$sbom"
        
    if [ $? -eq 0 ]; then
        echo "✓ Successfully signed $filename"
    else
        echo "✗ Failed to sign $filename"
    fi
done

Supply Chain Verification

#!/bin/bash
# verify-supply-chain.sh

VENDOR_KEY="vendor-public-key"
INTERNAL_KEY="internal-key-2024"

# Verify vendor-provided CycloneDX SBOM with embedded signature
echo "Verifying vendor SBOM..."
if sbomasm verify --key-id "$VENDOR_KEY" --quiet vendor-sbom.json; then
    echo "✓ Vendor SBOM signature valid"
else
    echo "✗ Vendor SBOM signature invalid - stopping process"
    exit 1
fi

# Process and re-sign with internal key
echo "Adding internal components and re-signing..."
sbomasm merge vendor-sbom.json internal-components.json | \
    sbomasm sign --key-id "$INTERNAL_KEY" - > final-sbom.json

echo "Supply chain SBOM processing complete"

Error Handling

Common error scenarios and solutions:

Authentication Errors

Error: API key is required. Use --api-key flag or set SECURE_SBOM_API_KEY environment variable

Solution: Set up your API credentials properly

Key Not Found

Error: key ID 'invalid-key' not found

Solution: Verify the key exists with sbomasm securesbomkey list

Network Timeouts

Error: request timeout after 30s

Solution: Increase timeout or check network connectivity

sbomasm sign --timeout 60s --retry 5 --key-id my-key sbom.json

Supported Formats

Current Support

Format	Version	Signing	Verification	Notes
CycloneDX	1.6+	Yes	Yes	Embedded and detached signature support
CycloneDX	1.4-1.5	Yes	Yes	Compatible with CycloneDX signature format
SPDX	2.3+	Yes	Yes	Detached signature support only

Future Enhancements

• Signature Metadata: Additional signature attributes and custom claims
• Support for Air-Gapped Verification: Verify a signed SBOM offline with only the public key
• CycloneDX Multi-Signature Support: Multiple signatures on single SBOM
• Signature Chain Support: Hierarchical signature chains for supply chain trust
• Certificate Authority (CA) integration for key management

Support

For any feature requests or issues related to SBOM signing and verification, use the following contact form.

For general sbomasm issues, please use the GitHub issues page.