diff --git a/README.md b/README.md index f08e3e63..0f63f2e4 100644 --- a/README.md +++ b/README.md @@ -20,17 +20,19 @@ that provides advanced supply chain capabilities for cyber risk reduction. This Python package provides data models, validators and more, to help you create/render/read CycloneDX documents. -**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 checkout -[CycloneDX Python][cyclonedx-python] or [Jake][jake]. +> [!NOTE] +> This package is a software library not intended for standalone use. +> For generating Software Bill of Materials (SBOM), check out [CycloneDX Python][cyclonedx-python] or [Jake][jake]. ## Documentation -View the documentation [here](https://cyclonedx-python-library.readthedocs.io/). +Complete documentation is available on [Read the Docs][link_rtfd]. This includes: +- Responsibilities & Capabilities +- Install Instructions +- API Reference +- Usage Examples +- Integration Guides +- Best Practices ## Python Support diff --git a/docs/index.rst b/docs/index.rst index 787ce717..72910310 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -41,6 +41,7 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o :maxdepth: 2 :caption: Contents: + responsibilities_capabilities install architecture examples diff --git a/docs/install.rst b/docs/install.rst index 6e8514f7..490f4563 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -26,6 +26,10 @@ Install from `pypi.org`_ as you would any other Python module using your preferr .. _pypi.org: https://pypi.org/project/cyclonedx-python-lib/ .. _conda-forge: https://anaconda.org/conda-forge/cyclonedx-python-lib +Some dependencies might be optional - they are referenced via the *extras*. + +.. _install extras: + Extras ------ diff --git a/docs/responsibilities_capabilities.rst b/docs/responsibilities_capabilities.rst new file mode 100644 index 00000000..783c43d3 --- /dev/null +++ b/docs/responsibilities_capabilities.rst @@ -0,0 +1,70 @@ +.. # Licensed under the Apache License, Version 2.0 (the "License"); + # you may not use this file except in compliance with the License. + # You may obtain a copy of the License at + # + # http://www.apache.org/licenses/LICENSE-2.0 + # + # Unless required by applicable law or agreed to in writing, software + # distributed under the License is distributed on an "AS IS" BASIS, + # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + # See the License for the specific language governing permissions and + # limitations under the License. + # + # SPDX-License-Identifier: Apache-2.0 + +Responsibilities +================ + +* Provide a general purpose Python-implementation of `CycloneDX`_. +* Provide type hints for said implementation, so developers and dev-tools can rely on it. +* Provide data models to work with `CycloneDX`_. +* Provide data model-validators according to `CycloneDX Specification`_. +* Provide JSON- and XML-serializers, that... + * support all shipped data models. + * respect any supported `CycloneDX Specification`_ and generates valid output accordingly. + * generate reproducible/deterministic results. +* Provide formal JSON- and XML-validators according to `CycloneDX Specification`_. +* Provide mechanisms for JSON- and XML-deserialization of all shipped data models. +* Pre-populate `bom-ref`, so linkage is possible. (affects only some data models) + +Capabilities +============ + +* Enums and Data models for the following use cases: + * :mod:`Bom and Metadata ` + * :mod:`BomRef ` + * :mod:`Component, Evidence, Patch, Pedigree, and more ` + * :mod:`Organizational Contact and Entity ` + * :mod:`Cryptographic properties and more ` + * :mod:`Definition and Standard ` + * :mod:`Dependency ` + * :mod:`Impact and related Analysis ` + * :mod:`Issue ` + * :mod:`License Named, SPDX, Expression, and more ` + * :mod:`Lifecycle ` + * :mod:`Release Notes ` + * :mod:`Service ` + * :mod:`Tool ` + * :mod:`Vulnerability and related Analysis ` + * :mod:`Attachment Copyright, DataFlow, ExternalReference, Hash, Property, and more ` +* Factories for the following use cases: + * Create data models from any license descriptor string +* Builders for the following use cases: + * Build a :class:`Component ` data model that represents this library + * Build a :class:`Tool ` data model that represents this library +* Implementation of the `CycloneDX Specification`_ for the following versions: + * ``1.6`` + * ``1.5`` + * ``1.4`` + * ``1.3`` + * ``1.2`` + * ``1.1`` + * ``1.0`` +* Serializer that converts :class:`Bom ` data models to XML string +* Serializer that converts :class:`Bom ` data models to JSON string +* Formal validators for JSON string and XML string. + Requires optional dependencies as described in :ref:`install instructions `. +* Shipped data model are serializable to and deserializable from both, JSON and XML. + +.. _CycloneDX: https://cyclonedx.org/ +.. _CycloneDX Specification: https://github.com/CycloneDX/specification/#readme