Lib4SBOM

Common errors

• SBOMParserException: Error parsing SBOM file

  cause An error occurred during the internal processing or validation of the SBOM file content, or the file is malformed.
  fix Examine the traceback for more details. Check the input SBOM file for syntax errors or adherence to its declared specification. Try parsing with `sbom_type='auto'` or explicitly specifying the type to help narrow down the issue.

• FileNotFoundError: [Errno 2] No such file or directory: 'your_sbom_file.json'

  cause The specified SBOM file path does not exist or is incorrect.
  fix Verify that the file path provided to `parse_file()` is correct and accessible. Use an absolute path or ensure the file is in the current working directory.

• SBOM parser returns empty lists (e.g., for packages, files, relationships) when parsing a valid CycloneDX 1.5 JSON file.

  cause The parser might not correctly detect or fully support certain nuances of newer CycloneDX versions, leading to data extraction failures, even if the file seems syntactically valid. This was reported for CycloneDX 1.5 JSON.
  fix Explicitly set `sbom_type='cyclonedx'` in the `SBOMParser` constructor. If the issue persists, consider downgrading the CycloneDX spec version if possible, or review GitHub issues for specific fixes related to CycloneDX 1.5+ parsing.

Warnings

• breaking Major version updates (e.g., v0.9.0, v0.10.0) introduce support for newer SPDX and CycloneDX specifications (e.g., CycloneDX 1.7, SPDX3). While efforts are made for backward compatibility, ensure your schemas and data adhere to the expected version, especially when converting between formats.
  Fix: Review the release notes for specific version changes. Explicitly set SBOM versions during generation using environment variables like `LIB4SBOM_CYCLONEDX_VERSION` or `LIB4SBOM_SPDX_VERSION` to match your target specification. For SPDX3, set `LIB4SBOM_SPDX3` environment variable.
• gotcha The `SBOMParser`'s `auto` detection mode relies on file extensions and content heuristics. Providing an incorrect file type (e.g., an SPDX JSON to a CycloneDX parser) or a non-standard file extension can lead to silent failures or empty results.
  Fix: Explicitly set the `sbom_type` parameter when initializing `SBOMParser` (e.g., `SBOMParser(sbom_type='spdx')`) if the SBOM format is known to avoid misdetection. Ensure file extensions align with standard SBOM formats (e.g., `.spdx`, `.cdx.json`).
• breaking When converting SBOMs, especially from SPDX 2 to SPDX 3, specific license expressions (e.g., `Apache-2.0 WITH LLVM-exception` or `Apache-1.0+`) can be lost or incorrectly handled, leading to compliance issues.
  Fix: Test conversions thoroughly for critical license information. Monitor GitHub issues #88 and #89 for official fixes. Manual verification and correction of license fields may be necessary post-conversion for affected versions.
• gotcha The library relies on various external schema validators (e.g., `jsonschema`, `xmlschema`). Issues with these dependencies or schema mismatches can cause validation failures, even if the SBOM content appears correct.
  Fix: Ensure all required dependencies are installed and up-to-date. If validation errors occur, check the specific error messages for clues about schema violations. Consider using debug output (`debug=True` in `SBOMValidator`) to get more verbose validation feedback.

Install

• pip install lib4sbom Install stable version

Imports

• SBOMParser

  from lib4sbom.parser import SBOMParser

• SBOMGenerator

  from lib4sbom.generator import SBOMGenerator

• SBOMOutput

  from lib4sbom.output import SBOMOutput

• SBOM
  wrong:

  from lib4sbom.generator import SBOM

  correct:

  from lib4sbom.sbom import SBOM

  The core SBOM object for manipulation is in `lib4sbom.sbom`, not `lib4sbom.generator` or `lib4sbom.parser`.

Quickstart

This quickstart demonstrates how to parse an existing SBOM file using the `SBOMParser` class. It creates a simple SPDX 2.3 TagValue file, parses it, and then extracts package information. The `sbom_type` parameter can be set to 'spdx', 'cyclonedx', or 'auto' for automatic detection.

import os
from lib4sbom.parser import SBOMParser

# Create a dummy SPDX SBOM file for demonstration
sbom_content = """
SPDXVersion: SPDX-2.3
DataLicense: CC0-1.0
SPDXID: SPDXRef-DOCUMENT
DocumentName: example-sbom
DocumentNamespace: https://spdx.org/spdxdocs/spdx-example-44455566-31b3-40e1-b4f0-4660f9450c26
Creator: Tool: lib4sbom-example
Created: 2026-04-16T12:00:00Z

PackageName: SamplePackage
SPDXID: SPDXRef-Package-Sample
PackageVersion: 1.0.0
PackageSupplier: Organization: Example Org (contact@example.org)
PackageDownloadLocation: NOASSERTION
PackageLicenseConcluded: MIT
PackageLicenseDeclared: MIT
PackageCopyrightText: NOASSERTION
"""

example_sbom_file = "example.spdx"
with open(example_sbom_file, "w") as f:
    f.write(sbom_content)

# Initialize the SBOM parser
sbom_parser = SBOMParser(sbom_type='spdx') # 'auto' can also be used, or 'cyclonedx'

# Parse the SBOM file
try:
    sbom_parser.parse_file(example_sbom_file)
    print(f"Successfully parsed SBOM type: {sbom_parser.get_type()}")

    # Retrieve packages and print their names
    packages = sbom_parser.get_packages()
    if packages:
        print("Packages found:")
        for pkg in packages:
            print(f"  - {pkg.get_name()} ({pkg.get_version()})")
    else:
        print("No packages found in SBOM.")

except FileNotFoundError:
    print(f"Error: SBOM file '{example_sbom_file}' not found.")
except Exception as e:
    print(f"An error occurred during parsing: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(example_sbom_file):
        os.remove(example_sbom_file)