README

Work with CycloneDX documents.
OWASP CycloneDX is a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction.

Note

This package is a software library not intended for standalone use.
For generating Software Bill of Materials (SBOM), check out CycloneDX PHP Composer Plugin.

Responsibilities

• Provide a general purpose php-implementation of CycloneDX.
• Provide phpDoc3- & psalm-compatible annotations for said implementation, so developers and dev-tools can rely on it.
• Provide data models to work with CycloneDX.
• Provide a JSON- and an XML-normalizer, that...
  • supports all shipped data models.
  • respects any injected CycloneDX Specification and generates valid output according to it.
  • can prepare data structures for JSON- and XML-serialization.
• Serialization:
  • Provide a JSON-serializer.
  • Provide an XML-serializer.
• Validation against CycloneDX Specification:
  • Provide a JSON-validator.
  • Provide an XML-validator.
• Provide composer-based autoloading for downstream usage.

Capabilities

• Enums for the following use cases:
  • ComponentType
  • ExternalReferenceType
  • HashAlgorithm
  • LicenseAcknowledgement
• Data models for the following use cases:
  • Bom
  • BomRef, BomRefRepository
  • Component, ComponentRepository, ComponentEvidence
  • ExternalReference, ExternalReferenceRepository
  • HashDictionary
  • LicenseExpression, NamedLicense, SpdxLicense, LicenseRepository
  • Metadata
  • Property, PropertyRepository
  • Tool, ToolRepository
• Utilities for the following use cases:
  • Generate valid random SerialNumbers for Bom.serialNumber
• Factories for the following use cases:
  • Create data models from any license descriptor string
• Implementation of the CycloneDX Specification for the following versions:
  • 1.7
  • 1.6
  • 1.5
  • 1.4
  • 1.3
  • 1.2
  • 1.1
• Normalizers that convert data models to JSON structures
• Normalizers that convert data models to XML structures
• Serializer that converts Bom data models to JSON string
• Serializer that converts Bom data models to XML string
• Validator that checks JSON against CycloneDX Specification
• Validator that checks XML against CycloneDX Specification

Installation

Install via composer:

composer require cyclonedx/cyclonedx-library

Usage

See extended examples.

$bom = new \CycloneDX\Core\Models\Bom();
$bom->getComponents()->addItems(
    new \CycloneDX\Core\Models\Component(
        \CycloneDX\Core\Enums\ComponentType::Library,
        'myComponent'
    )
);

API Documentation

We ship code annotations, so that your IDE and tools may pick up the documentation when you use this library downstream.

There are also pre-rendered documentations hosted on readthedocs.

Additionally, there is a prepared config for phpDoc3 that you can use to generate the docs for yourself.

Conflicts

Due to the fact that this library was split out of /src/Core of cyclonedx-php-composer (346e6200fb2f5086061b15c2ee44f540893ce97d) it will conflict with its original source: cyclonedx/cyclonedx-php-composer:<3.5.

Contributing

Feel free to open issues, bug reports or pull requests.
See the CONTRIBUTING file for details.

License

Permission to modify and redistribute is granted under the terms of the Apache 2.0 license.
See the LICENSE file for the full license.