Heimdall SBOM Validation Guide

This guide explains how to validate Heimdall-generated SBOMs for standards compliance.

Overview

Heimdall generates SBOMs in two formats:

CycloneDX (JSON format) - ISO/IEC 5962:2021 standard
SPDX (tag-value format) - ISO/IEC 5962:2021 standard

Both formats are validated for compliance with their respective specifications.

Validation Methods

1. Automated Validation Scripts

Heimdall provides two validation scripts:

Bash Validation Script

./scripts/validate_sboms.sh build

What it validates:

JSON syntax for CycloneDX files
Required CycloneDX fields (bomFormat, specVersion, version, metadata, components)
SPDX structure and required fields
File format compliance

Output:

Detailed validation logs in build/validation_results/
Summary report with pass/fail status
Individual validation logs for each SBOM

Python Validation Script

python3 scripts/validate_sboms_online.py build

What it validates:

Advanced CycloneDX schema validation
SPDX structure validation (both package and file formats)
Detailed error reporting
Links to online validation tools

2. Online Validation Tools

CycloneDX Validation

CycloneDX Tool Center: https://cyclonedx.org/tool-center/
Schema Documentation: https://cyclonedx.org/schema/
Specification: https://cyclonedx.org/specification/

Steps:

Upload your .json SBOM file to the tool center
The tool will validate against the official CycloneDX schema
Review any validation errors or warnings

SPDX Validation

SPDX Validator: https://tools.spdx.org/app/validate/
Specification: https://spdx.github.io/spdx-spec/
Tools Repository: https://github.com/spdx/tools

Steps:

Upload your .spdx file to the validator
The tool will validate against the SPDX specification
Review validation results

3. Manual Validation

CycloneDX Manual Checks

# Check JSON syntax
jq empty your-sbom.cyclonedx.json

# Validate required fields
jq '.bomFormat, .specVersion, .version, .metadata, .components' your-sbom.cyclonedx.json

# Check component structure
jq '.components[] | {type, name, version}' your-sbom.cyclonedx.json

SPDX Manual Checks

# Check required header fields
grep -E "^(SPDXVersion|DataLicense|DocumentName|DocumentNamespace):" your-sbom.spdx

# Check for package or file information
grep -E "^(PackageName|FileName):" your-sbom.spdx

# Validate SPDX version
grep "^SPDXVersion:" your-sbom.spdx

Validation Results

Expected Validation Outcomes

CycloneDX Files

✅ bomFormat: Must be "CycloneDX"
✅ specVersion: Must be one of "1.0", "1.1", "1.2", "1.3", "1.4", "1.5"
✅ version: Must be a positive integer
✅ metadata: Must contain timestamp and tools information
✅ components: Must be a non-empty array with valid component objects

SPDX Files

✅ SPDXVersion: Must start with "SPDX-"
✅ DataLicense: Must be a valid license identifier
✅ DocumentName: Must be present
✅ DocumentNamespace: Must be a valid URI
✅ Package/File Information: Must contain either PackageName or FileName entries

Common Validation Issues

CycloneDX Issues

Missing required fields: Ensure all top-level fields are present
Invalid specVersion: Use a supported CycloneDX version
Empty components array: SBOM should contain at least one component
Invalid component structure: Each component must have type and name

SPDX Issues

Missing header fields: All required SPDX header fields must be present
Invalid version format: SPDX version must follow the correct format
No package/file information: SBOM must contain component information
Invalid license identifiers: Use valid SPDX license identifiers

Extended DWARF Information Validation

Heimdall SBOMs include extended DWARF information in CycloneDX format:

Custom Properties

heimdall:source-files: Array of source file paths
heimdall:functions: Array of function names and locations
heimdall:compile-units: Array of compile unit information
heimdall:contains-debug-info: Boolean indicating debug info presence

Validation Commands

# Check for extended DWARF information
jq '.components[] | select(.properties) | .properties[] | select(.name | startswith("heimdall:"))' your-sbom.cyclonedx.json

# Validate source files property
jq '.components[] | select(.properties) | .properties[] | select(.name == "heimdall:source-files")' your-sbom.cyclonedx.json

# Validate functions property
jq '.components[] | select(.properties) | .properties[] | select(.name == "heimdall:functions")' your-sbom.cyclonedx.json

Integration with CI/CD

GitHub Actions Example

- name: Generate SBOMs
  run: ./scripts/generate_build_sboms.sh build

- name: Validate SBOMs
  run: ./scripts/validate_sboms.sh build

- name: Upload validation results
  uses: actions/upload-artifact@v3
  with:
    name: sbom-validation-results
    path: build/validation_results/

Jenkins Pipeline Example

stage('SBOM Validation') {
    steps {
        sh './scripts/generate_build_sboms.sh build'
        sh './scripts/validate_sboms.sh build'
        archiveArtifacts artifacts: 'build/validation_results/**/*'
    }
}

Troubleshooting

Validation Script Issues

Permission denied: Ensure scripts are executable (chmod +x scripts/*.sh)
Missing dependencies: Install required tools (jq, python3)
No SBOM files: Run the generation script first

Online Validation Issues

File too large: Some online tools have file size limits
Network issues: Use local validation as fallback
Format issues: Ensure files are properly formatted

Common Fixes

JSON syntax errors: Use jq to format and validate JSON
SPDX format issues: Check field formatting and required fields
Missing components: Ensure the build process generated components

Additional Resources

Standards Documentation

Validation Tools

Community Resources

Support

For validation issues specific to Heimdall:

Check the validation logs in build/validation_results/
Review the SBOM generation logs
Consult the Heimdall documentation
Open an issue on the Heimdall repository

For general SBOM validation questions:

Consult the respective standard specifications
Use the official validation tools

Sbom Validation Guide