From 4c44e9eb97aff27a603e4756863b8a522b39793b Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:10:33 +0530 Subject: [PATCH] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 219 +++++++++++++++++++++++++----------------------------- 1 file changed, 102 insertions(+), 117 deletions(-) diff --git a/README.md b/README.md index 28c4471f..c451e3b3 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # CycloneDX Python Library [![shield_pypi-version]][link_pypi] -[![shield_conda-forge-version]][link_conda-forge] +[![shield_conda-forge-version]][link_conda_forge] [![shield_rtfd]][link_rtfd] -[![shield_gh-workflow-test]][link_gh-workflow-test] +[![shield_gh-workflow-test]][link_gh_workflow_test] [![shield_coverage]][link_codacy] -[![shield_ossf-best-practices]][link_ossf-best-practices] +[![shield_ossf-best-practices]][link_ossf_best_practices] [![shield_license]][license_file] [![shield_website]][link_website] [![shield_slack]][link_slack] @@ -14,57 +14,78 @@ ---- -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. - -## Overview - -CycloneDX Python Library provides a comprehensive implementation for working with CycloneDX documents in Python. It supports creating, parsing, and validating Software Bill of Materials (SBOM) in both JSON and XML formats. - -## Key Features - -* **Full CycloneDX Support**: Implements [CycloneDX Specification][CycloneDX-spec] versions 1.0 through 1.5 -* **Multiple BOM Types**: - - SBOM (Software Bill of Materials) - - VEX (Vulnerability Exchange) - - VDR (Vulnerability Disclosure Report) - - OBOM (Operations BOM) - - MBOM (Manufacturing BOM) - - SaaSBOM (Software as a Service BOM) -* **Rich Data Models**: - - Components and Component repositories - - Dependencies management - - License expressions and repositories - - External references - - VEX (Vulnerability Exploitability eXchange) -* **Format Support**: - - JSON serialization and validation - - XML serialization and validation -* **Developer-Friendly**: - - Complete type hints - - Comprehensive documentation - - IDE integration support +Core functionality of [_CycloneDX_][link_website] for _Python_, +written in Python with full type hints. + +**This package is not designed for standalone use. It is a software library.** + +As of version `3.0.0`, the internal data model was adjusted to allow CycloneDX VEX documents to be produced as per [official examples](https://cyclonedx.org/capabilities/bomlink/#linking-external-vex-to-bom-inventory) linking VEX to a separate CycloneDX document. + +If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-of-materials documents, why not check out [CycloneDX Python][cyclonedx-python] or [Jake][jake]. + +## Responsibilities + +* Provide a general-purpose _Python_-implementation of [_CycloneDX_][CycloneDX]. +* Provide type hints and comprehensive documentation for developers. +* Provide data models to work with _CycloneDX_. +* Provide JSON- and XML-normalizers that... + * Support all shipped data models. + * Respect any injected [_CycloneDX_ Specification][CycloneDX-spec] and generate 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. +* Support [_pip_-based installation](https://pip.pypa.io/en/stable/) 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][CycloneDX-spec] for the following versions: + * `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 -Choose your preferred installation method: +Install via pip: ```shell -# Via pip pip install cyclonedx-python-lib - -# Via conda -conda install -c conda-forge cyclonedx-python-lib - -# With validation support -pip install cyclonedx-python-lib[validation] # Complete validation -pip install cyclonedx-python-lib[json-validation] # JSON-only validation -pip install cyclonedx-python-lib[xml-validation] # XML-only validation ``` -## Quick Start +## Usage -### Basic BOM Creation +See extended [examples]. ```python from cyclonedx.model.bom import Bom @@ -81,99 +102,64 @@ component = Component( bom.components.add(component) # Serialize to JSON or XML -json_output = outputter.output_json(bom) -xml_output = outputter.output_xml(bom) -``` - -### Complex Example: Working with JSON and XML - -```python -from cyclonedx.model.bom import Bom -from cyclonedx.schema import SchemaVersion -from cyclonedx.validation import JsonStrictValidator -from defusedxml import ElementTree as SafeElementTree - -# Create and validate JSON BOM -json_validator = JsonStrictValidator(SchemaVersion.V1_6) -validation_errors = json_validator.validate_str(json_data) -if not validation_errors: - bom_from_json = Bom.from_json(json_data) - -# Create and validate XML BOM -xml_validator = make_schemabased_validator(OutputFormat.XML, SchemaVersion.V1_6) -validation_errors = xml_validator.validate_str(xml_data) -if not validation_errors: - bom_from_xml = Bom.from_xml(SafeElementTree.fromstring(xml_data)) +json_output = bom.to_json() +xml_output = bom.to_xml() ``` -## Advanced Usage +## API Documentation -### Component with Dependencies +We ship code annotations so that your IDE and tools may pick up the documentation when you use this library downstream. -```python -from cyclonedx.model.bom import Bom -from cyclonedx.model.component import Component +There are also pre-rendered documentations hosted on [readthedocs][link_rtfd]. -# Create main component -app = Component( - name="myApp", - version="1.0.0", - component_type="application" -) +Additionally, there is a prepared config for [_Sphinx_](https://www.sphinx-doc.org/en/master/) that you can use to generate the docs for yourself. -# Create dependency -library = Component( - name="some-library", - version="2.1.0", - component_type="library" -) +## Schema Support -# Add to BOM with dependency relationship -bom = Bom() -bom.components.add(app) -bom.components.add(library) -bom.dependencies.add(app, [library]) -``` +This library has partial support for the CycloneDX specification. The following tables detail the current support status: -## Python Support +### Root Level Schema Support -Supports all current Python versions: -* Python 3.8 -* Python 3.9 -* Python 3.10 -* Python 3.11 -* Python 3.12 -* Python 3.13 +| Data Path | Supported? | Notes | +|----------------------------|------------|---------------------------------------------------| +| `bom[@version]` | Yes | | +| `bom[@serialNumber]` | Yes | | +| `bom.metadata` | Yes | Not supported: `lifecycles` | +| `bom.components` | Yes | Not supported: `modified`, `modelCard`, `data`, `signature` | +| `bom.externalReferences` | Yes | | +| `bom.dependencies` | Yes | Since version `2.3.0` | -## Documentation & Resources +### Internal Model Schema Support -* [Full API Documentation][link_rtfd] -* [GitHub Repository](https://github.com/CycloneDX/cyclonedx-python-lib) -* [CycloneDX Specification][CycloneDX-spec] -* Join the community: - * [Slack Channel][link_slack] - * [Discussion Group][link_discussion] - * [Twitter][link_twitter] +| Internal Model | Supported? | Notes | +|----------------------------|------------|---------------------------------------------------| +| `ComponentEvidence` | Yes | Not currently supported: `callstack`, `identity`, `occurrences` | +| `DisjunctiveLicense` | Yes | Not currently supported: `@bom-ref`, `licensing`, `properties` | -## Contributing +## Development & Contributing -We welcome contributions! Please see our [CONTRIBUTING][contributing_file] guide for details. +Feel free to open issues, bug reports, or pull requests. +See the [CONTRIBUTING][contributing_file] file for details. ## License -Licensed under the Apache License, Version 2.0. See the [LICENSE][license_file] file for details. +Permission to modify and redistribute is granted under the terms of the Apache 2.0 license. +See the [LICENSE][license_file] file for the full license. [CycloneDX]: https://cyclonedx.org/ [CycloneDX-spec]: https://github.com/CycloneDX/specification/tree/master#readme +[cyclonedx-python]: https://github.com/CycloneDX/cyclonedx-python +[jake]: https://github.com/sonatype-nexus-community/jake [license_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/LICENSE [contributing_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/CONTRIBUTING.md +[examples]: https://github.com/CycloneDX/cyclonedx-python-lib/tree/master/examples -[shield_pypi-version]: https://img.shields.io/pypi/v/cyclonedx-python-lib?logo=pypi&logoColor=white&label=PyPI "PyPI" -[shield_conda-forge-version]: https://img.shields.io/conda/vn/conda-forge/cyclonedx-python-lib?logo=anaconda&logoColor=white&label=conda-forge "conda-forge" +[shield_pypi-version]: https://img.shields.io/pypi/v/cyclonedx-python-lib?logo=pypi&logoColor=white "PyPI" +[shield_conda-forge-version]: https://img.shields.io/conda/vn/conda-forge/cyclonedx-python-lib?logo=anaconda&logoColor=white "conda-forge" [shield_rtfd]: https://img.shields.io/readthedocs/cyclonedx-python-library?logo=readthedocs&logoColor=white "Read the Docs" -[shield_gh-workflow-test]: https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-python-lib/python.yml?branch=main&logo=GitHub&logoColor=white "build" -[shield_coverage]: https://img.shields.io/codacy/coverage/1f9d451e9cdc49ce99c2a1247adab341?logo=Codacy&logoColor=white "test coverage" +[shield_gh-workflow-test]: https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-python-lib/python.yml?branch=master&logo=GitHub&logoColor=white "build" +[shield_coverage]: https://img.shields.io/codacy/coverage/TBD?logo=Codacy&logoColor=white "test coverage" [shield_ossf-best-practices]: https://img.shields.io/cii/percentage/7956?label=OpenSSF%20best%20practices "OpenSSF best practices" [shield_license]: https://img.shields.io/github/license/CycloneDX/cyclonedx-python-lib?logo=open%20source%20initiative&logoColor=white "license" [shield_website]: https://img.shields.io/badge/https://-cyclonedx.org-blue.svg "homepage" @@ -182,11 +168,10 @@ Licensed under the Apache License, Version 2.0. See the [LICENSE][license_file] [shield_twitter-follow]: https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white "twitter follow" [link_pypi]: https://pypi.org/project/cyclonedx-python-lib/ -[link_conda-forge]: https://anaconda.org/conda-forge/cyclonedx-python-lib +[link_conda_forge]: https://anaconda.org/conda-forge/cyclonedx-python-lib [link_rtfd]: https://cyclonedx-python-library.readthedocs.io/ -[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-python-lib/actions/workflows/python.yml?query=branch%3Amain [link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-python-lib -[link_ossf-best-practices]: https://www.bestpractices.dev/projects/7956 +[link_ossf_best_practices]: https://www.bestpractices.dev/projects/7956 [link_website]: https://cyclonedx.org/ [link_slack]: https://cyclonedx.org/slack/invite [link_discussion]: https://groups.io/g/CycloneDX