From e5ab2e16788fd03255a7cbd00d859960152e3e98 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Tue, 22 Oct 2024 22:24:19 +0530 Subject: [PATCH 01/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 165 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 93 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 8dbef343..b30931b7 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ -# CycloneDX Python Library +# CycloneDX JavaScript Library -[![shield_pypi-version]][link_pypi] -[![shield_conda-forge-version]][link_conda-forge] +[![shield_npm-version]][link_npm] [![shield_rtfd]][link_rtfd] [![shield_gh-workflow-test]][link_gh-workflow-test] [![shield_coverage]][link_codacy] @@ -14,72 +13,94 @@ ---- -OWASP [CycloneDX][link_website] is a full-stack Bill of Materials (BOM) standard -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]. - -## Documentation - -View the documentation [here](https://cyclonedx-python-library.readthedocs.io/). - -## Python Support - -We endeavour to support all functionality for all [current actively supported Python versions](https://www.python.org/downloads/). -However, some features may not be possible/present in older Python versions due to their lack of support. - -## Changelog - -See our [CHANGELOG][chaneglog_file]. - -## Contributing - -Feel free to open issues, bugreports or pull requests. -See the [CONTRIBUTING][contributing_file] file for details. - -## Copyright & License - -CycloneDX Python Lib is Copyright (c) OWASP Foundation. All Rights Reserved. -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-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 -[chaneglog_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/CHANGELOG.md -[contributing_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/CONTRIBUTING.md - -[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_ossf-best-practices]: https://img.shields.io/cii/percentage/7956?label=OpenSSF%20best%20practices "OpenSSF best practices" -[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_rtfd]: https://img.shields.io/readthedocs/cyclonedx-python-library?logo=readthedocs&logoColor=white "Read the Docs" -[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" -[shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join" -[shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion" -[shield_twitter-follow]: https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white "twitter follow" - -[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-python-lib/actions/workflows/python.yml?query=branch%3Amain -[link_pypi]: https://pypi.org/project/cyclonedx-python-lib/ -[link_conda-forge]: https://anaconda.org/conda-forge/cyclonedx-python-lib -[link_rtfd]: https://cyclonedx-python-library.readthedocs.io/en/latest/ -[link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-python-lib -[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 -[link_twitter]: https://twitter.com/CycloneDX_Spec - -[PEP-508]: https://www.python.org/dev/peps/pep-0508/ +Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or _WebBrowsers_), written in _TypeScript_ and compiled for the target. + +## Responsibilities + +* Provide a general purpose _JavaScript_-implementation of [_CycloneDX_][link_website] for _Node.js_ and _WebBrowsers_. +* Provide typing for said implementation, so developers and dev-tools can rely on it. +* 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 be configured to generate reproducible/deterministic output. + * Can prepare data structures for JSON- and XML-serialization. +* Serialization: + * Provide a universal JSON-serializer for all target environments. + * Provide an XML-serializer for all target environments. + * Support the downstream implementation of custom XML-serializers tailored to specific environments by providing an abstract base class that takes care of normalization and BomRef-discrimination. This is done because there is no universal XML support in _JavaScript_. +* Provide formal JSON- and XML-validators according to [_CycloneDX_ Specification][CycloneDX-spec] (currently for _Node.js_ only). + +## Capabilities + +* Enums for the following use cases: + * `AttachmentEncoding` + * `ComponentScope` + * `ComponentType` + * `ExternalReferenceType` + * `HashAlgorithm` + * `Vulnerability` related: + * `AffectStatus` + * `AnalysisJustification` + * `AnalysisResponse` + * `AnalysisState` + * `RatingMethod` + * `Severity` +* Data models for the following use cases: + * `Attachment` + * `Bom` + * `BomLink`, `BomLinkDocument`, `BomLinkElement` + * `BomRef`, `BomRefRepository` + * `Component`, `ComponentRepository`, `ComponentEvidence` + * `ExternalReference`, `ExternalReferenceRepository` + * `Hash`, `HashContent`, `HashDictionary` + * `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository` + * `Metadata` + * `OrganizationalContact`, `OrganizationalContactRepository` + * `OrganizationalEntity`, `OrganizationalEntityRepository` + * `Property`, `PropertyRepository` + * `SWID` + * `Tool`, `ToolRepository` + * Vulnerability-related: + * `Advisory`, `AdvisoryRepository` + * `Affect`, `AffectRepository`, + - AffectedSingleVersion, + - AffectedVersionRange, + - AffectedVersionRepository + * Analysis + * Credits + * Rating, RatingRepository + * Reference, ReferenceRepository + * Source + * Vulnerability, VulnerabilityRepository +* 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. + * Create PackageURL from Component data models. + * Specific to _Node.js_: create data models from PackageJson-like data structures and derived data. +* Builders for the following use cases: + * Specific to _Node.js_: create deep data models Tool or Component from PackageJson-like data structures. +* Implementation of the [_CycloneDX_ Specification][CycloneDX-spec] for the following versions: + * `1.6` + * `1.5` + * `1.4` + * `1.3` + * `1.2` +* Normalizers that convert data models to JSON structures. +* Normalizers that convert data models to XML structures. +* Universal serializer that converts Bom data models to JSON string. +* Specific Serializer that converts Bom data models to XML string: + - Specific to _WebBrowsers_: implementation utilizes browser-specific document generators and printers. + - Specific to _Node.js_: implementation utilizes [optional dependencies](#optional-dependencies) as described below. +* Formal validators for JSON string and XML string (currently for _Node.js_ only). + Requires [optional dependencies](#optional-dependencies) as described below. + +## Installation + +This package and the build results are available for _npm_, _pnpm_, and _yarn_: + +```shell +npm i -S @cyclonedx/cyclonedx-library +pnpm add @cyclonedx/cyclonedx-library +yarn add @cyclonedx/cyclonedx-library From 75aff7dd26fd8d364c3546c461160721d33b694e Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Tue, 22 Oct 2024 22:28:14 +0530 Subject: [PATCH 02/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 66 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 37 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index b30931b7..e68be8fd 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ [![shield_npm-version]][link_npm] [![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] @@ -17,7 +17,7 @@ Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or ## Responsibilities -* Provide a general purpose _JavaScript_-implementation of [_CycloneDX_][link_website] for _Node.js_ and _WebBrowsers_. +* Provide a general-purpose _JavaScript_-implementation of [_CycloneDX_][link_website] for _Node.js_ and _WebBrowsers_. * Provide typing for said implementation, so developers and dev-tools can rely on it. * Provide data models to work with _CycloneDX_. * Provide JSON- and XML-normalizers that: @@ -33,20 +33,21 @@ Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or ## Capabilities -* Enums for the following use cases: +* **Enums** for the following use cases: * `AttachmentEncoding` * `ComponentScope` * `ComponentType` * `ExternalReferenceType` * `HashAlgorithm` - * `Vulnerability` related: + * **Vulnerability** related: * `AffectStatus` * `AnalysisJustification` * `AnalysisResponse` * `AnalysisState` * `RatingMethod` * `Severity` -* Data models for the following use cases: + +* **Data Models** for the following use cases: * `Attachment` * `Bom` * `BomLink`, `BomLinkDocument`, `BomLinkElement` @@ -61,39 +62,46 @@ Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or * `Property`, `PropertyRepository` * `SWID` * `Tool`, `ToolRepository` - * Vulnerability-related: - * `Advisory`, `AdvisoryRepository` - * `Affect`, `AffectRepository`, - - AffectedSingleVersion, - - AffectedVersionRange, - - AffectedVersionRepository - * Analysis - * Credits - * Rating, RatingRepository - * Reference, ReferenceRepository - * Source - * Vulnerability, VulnerabilityRepository -* Utilities for the following use cases: + +* **Vulnerability** related: + - `Advisory`, `AdvisoryRepository` + - AffectedSingleVersion, AffectedVersionRange, AffectedVersionRepository + - Analysis + - Credits + - Rating, RatingRepository + - Reference, ReferenceRepository + - Source + - Vulnerability, VulnerabilityRepository + +* **Utilities** for the following use cases: * Generate valid random SerialNumbers for Bom.serialNumber. -* Factories for the following use cases: + +* **Factories** for the following use cases: * Create data models from any license descriptor string. * Create PackageURL from Component data models. * Specific to _Node.js_: create data models from PackageJson-like data structures and derived data. -* Builders for the following use cases: + +* **Builders** for the following use cases: * Specific to _Node.js_: create deep data models Tool or Component from PackageJson-like data structures. -* Implementation of the [_CycloneDX_ Specification][CycloneDX-spec] for the following versions: + +* **Implementation of the [_CycloneDX_ Specification][CycloneDX-spec]** for the following versions: * `1.6` * `1.5` * `1.4` * `1.3` * `1.2` -* Normalizers that convert data models to JSON structures. -* Normalizers that convert data models to XML structures. -* Universal serializer that converts Bom data models to JSON string. -* Specific Serializer that converts Bom data models to XML string: - - Specific to _WebBrowsers_: implementation utilizes browser-specific document generators and printers. - - Specific to _Node.js_: implementation utilizes [optional dependencies](#optional-dependencies) as described below. -* Formal validators for JSON string and XML string (currently for _Node.js_ only). + +* **Normalizers** that convert data models to JSON structures. + +* **Normalizers** that convert data models to XML structures. + +* **Universal serializer** that converts Bom data models to JSON string. + +* **Specific Serializer** that converts Bom data models to XML string: + - Specific to _WebBrowsers_: implementation utilizes browser-specific document generators and printers. + - Specific to _Node.js_: implementation utilizes [optional dependencies](#optional-dependencies) as described below. + +* **Formal validators** for JSON string and XML string (currently for _Node.js_ only). Requires [optional dependencies](#optional-dependencies) as described below. ## Installation From 87cefeeebe5fa64ed0047f54eee5481ec5826753 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Tue, 22 Oct 2024 22:46:44 +0530 Subject: [PATCH 03/15] docs: reorganize responsibilities and capabilities sections Reorganizes the responsibilities and capabilities sections for better clarity and organization, as requested in issue #485 Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 246 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 173 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index e68be8fd..94e82e4f 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ [![shield_npm-version]][link_npm] [![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] @@ -13,48 +13,54 @@ ---- -Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or _WebBrowsers_), written in _TypeScript_ and compiled for the target. +Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or _WebBrowsers_), +written in _TypeScript_ and compiled for the target. ## Responsibilities -* Provide a general-purpose _JavaScript_-implementation of [_CycloneDX_][link_website] for _Node.js_ and _WebBrowsers_. -* Provide typing for said implementation, so developers and dev-tools can rely on it. -* 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 be configured to generate reproducible/deterministic output. - * Can prepare data structures for JSON- and XML-serialization. -* Serialization: - * Provide a universal JSON-serializer for all target environments. - * Provide an XML-serializer for all target environments. - * Support the downstream implementation of custom XML-serializers tailored to specific environments by providing an abstract base class that takes care of normalization and BomRef-discrimination. This is done because there is no universal XML support in _JavaScript_. -* Provide formal JSON- and XML-validators according to [_CycloneDX_ Specification][CycloneDX-spec] (currently for _Node.js_ only). +The CycloneDX JavaScript Library is responsible for: + +* Providing a general purpose JavaScript implementation of CycloneDX for Node.js and WebBrowsers +* Providing comprehensive TypeScript typings for developer tooling support +* Implementing core CycloneDX data models +* Providing JSON and XML normalizers that: + * Support all shipped data models + * Respect injected CycloneDX Specifications and generate valid output + * Can be configured for reproducible/deterministic output + * Prepare data structures for JSON and XML serialization +* Handling serialization through: + * Universal JSON serializer for all target environments + * XML serializer for all target environments + * Support for custom XML serializer implementations via abstract base class +* Providing formal JSON and XML validators according to CycloneDX Specification (Node.js only) ## Capabilities -* **Enums** for the following use cases: - * `AttachmentEncoding` - * `ComponentScope` - * `ComponentType` - * `ExternalReferenceType` - * `HashAlgorithm` - * **Vulnerability** related: - * `AffectStatus` - * `AnalysisJustification` - * `AnalysisResponse` - * `AnalysisState` - * `RatingMethod` - * `Severity` - -* **Data Models** for the following use cases: +The library provides: + +### Enums +* `AttachmentEncoding` +* `ComponentScope` +* `ComponentType` +* `ExternalReferenceType` +* `HashAlgorithm` +* Vulnerability-related: + * `AffectStatus` + * `AnalysisJustification` + * `AnalysisResponse` + * `AnalysisState` + * `RatingMethod` + * `Severity` + +### Data Models +* Core Models: * `Attachment` * `Bom` * `BomLink`, `BomLinkDocument`, `BomLinkElement` * `BomRef`, `BomRefRepository` * `Component`, `ComponentRepository`, `ComponentEvidence` * `ExternalReference`, `ExternalReferenceRepository` - * `Hash`, `HashContent`, `HashDictionary` + * `Hash`, `HashContent`, `HashDictionary` * `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository` * `Metadata` * `OrganizationalContact`, `OrganizationalContactRepository` @@ -63,52 +69,146 @@ Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or * `SWID` * `Tool`, `ToolRepository` -* **Vulnerability** related: - - `Advisory`, `AdvisoryRepository` - - AffectedSingleVersion, AffectedVersionRange, AffectedVersionRepository - - Analysis - - Credits - - Rating, RatingRepository - - Reference, ReferenceRepository - - Source - - Vulnerability, VulnerabilityRepository - -* **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. - * Create PackageURL from Component data models. - * Specific to _Node.js_: create data models from PackageJson-like data structures and derived data. - -* **Builders** for the following use cases: - * Specific to _Node.js_: create deep data models Tool or Component from PackageJson-like data structures. - -* **Implementation of the [_CycloneDX_ Specification][CycloneDX-spec]** for the following versions: - * `1.6` - * `1.5` - * `1.4` - * `1.3` - * `1.2` - -* **Normalizers** that convert data models to JSON structures. - -* **Normalizers** that convert data models to XML structures. - -* **Universal serializer** that converts Bom data models to JSON string. - -* **Specific Serializer** that converts Bom data models to XML string: - - Specific to _WebBrowsers_: implementation utilizes browser-specific document generators and printers. - - Specific to _Node.js_: implementation utilizes [optional dependencies](#optional-dependencies) as described below. - -* **Formal validators** for JSON string and XML string (currently for _Node.js_ only). - Requires [optional dependencies](#optional-dependencies) as described below. +* Vulnerability Models: + * `Advisory`, `AdvisoryRepository` + * `Affect`, `AffectRepository`, `AffectedSingleVersion`, `AffectedVersionRange`, `AffectedVersionRepository` + * `Analysis` + * `Credits` + * `Rating`, `RatingRepository` + * `Reference`, `ReferenceRepository` + * `Source` + * `Vulnerability`, `VulnerabilityRepository` + +### Utilities +* SerialNumber generation for `Bom.serialNumber` +* License descriptor string parsing +* PackageURL generation from Component models +* Node.js-specific utilities for PackageJson handling + +### CycloneDX Specification Support +* Version 1.6 +* Version 1.5 +* Version 1.4 +* Version 1.3 +* Version 1.2 ## Installation -This package and the build results are available for _npm_, _pnpm_, and _yarn_: +This package and the build results are available for _npm_, _pnpm_ and _yarn_: ```shell npm i -S @cyclonedx/cyclonedx-library pnpm add @cyclonedx/cyclonedx-library yarn add @cyclonedx/cyclonedx-library +``` + +You can install the package from source, +which will build automatically on installation: + +```shell +npm i -S github:CycloneDX/cyclonedx-javascript-library +pnpm add github:CycloneDX/cyclonedx-javascript-library +yarn add @cyclonedx/cyclonedx-library@github:CycloneDX/cyclonedx-javascript-library # only with yarn-2 +``` + +## Optional Dependencies + +Some dependencies are optional. +See the shipped `package.json` for version constraints. + +* Serialization to XML on _Node.js_ requires any of: + * [`xmlbuilder2`](https://www.npmjs.com/package/xmlbuilder2) +* Validation of JSON on _Node.js_ requires all of: + * [`ajv`](https://www.npmjs.com/package/ajv) + * [`ajv-formats`](https://www.npmjs.com/package/ajv-formats) + * [`ajv-formats-draft2019`](https://www.npmjs.com/package/ajv-formats-draft2019) +* Validation of XML on _Node.js_ requires all of: + * [`libxmljs2`](https://www.npmjs.com/package/libxmljs2) + * the system might need to meet the requirements for [`node-gyp`](https://github.com/TooTallNate/node-gyp#installation), in certain cases. + +## Usage + +See extended [examples]. + +### As _Node.js_ package + +```javascript +const CDX = require('@cyclonedx/cyclonedx-library') + +const bom = new CDX.Models.Bom() +bom.metadata.component = new CDX.Models.Component( + CDX.Enums.ComponentType.Application, + 'MyProject' +) +const componentA = new CDX.Models.Component( + CDX.Enums.ComponentType.Library, + 'myComponentA', +) +bom.components.add(componentA) +bom.metadata.component.dependencies.add(componentA.bomRef) +``` + +### In _WebBrowsers_ + +```html + + +``` + +## API documentation + +We ship annotated type definitions, 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][link_rtfd]. + +## Development & Contributing + +Feel free to open issues, bug reports or pull requests. +See the [CONTRIBUTING][contributing_file] file for details. + +## License + +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-spec]: https://github.com/CycloneDX/specification/#readme + +[license_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/LICENSE +[contributing_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/CONTRIBUTING.md +[examples]: https://github.com/CycloneDX/cyclonedx-javascript-library/tree/main/examples/README.md +[link_rtfd]: https://cyclonedx-javascript-library.readthedocs.io + +[shield_npm-version]: https://img.shields.io/npm/v/%40cyclonedx%2fcyclonedx-library/latest?label=npm&logo=npm&logoColor=white "npm" +[shield_rtfd]: https://img.shields.io/readthedocs/cyclonedx-javascript-library?logo=readthedocs&logoColor=white "Read the Docs" +[shield_gh-workflow-test]: https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-javascript-library/nodejs.yml?branch=main&logo=GitHub&logoColor=white "tests" +[shield_coverage]: https://img.shields.io/codacy/coverage/ae6c086b53d54653ad5077b12ec22264?logo=Codacy&logoColor=white "test coverage" +[shield_ossf-best-practices]: https://img.shields.io/cii/percentage/7883?label=OpenSSF%20best%20practices "OpenSSF best practices" +[shield_license]: https://img.shields.io/github/license/CycloneDX/cyclonedx-javascript-library?logo=open%20source%20initiative&logoColor=white "license" +[shield_website]: https://img.shields.io/badge/https://-cyclonedx.org-blue.svg "homepage" +[shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join" +[shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion" +[shield_twitter-follow]: https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white "twitter follow" + +[link_website]: https://cyclonedx.org/ +[link_npm]: https://www.npmjs.com/package/%40cyclonedx/cyclonedx-library + +[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-javascript-library/actions/workflows/nodejs.yml?query=branch%3Amain +[link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-javascript-library/dashboard +[link_ossf-best-practices]: https://www.bestpractices.dev/projects/7883 +[link_slack]: https://cyclonedx.org/slack/invite +[link_discussion]: https://groups.io/g/CycloneDX +[link_twitter]: https://twitter.com/CycloneDX_Spec From 3cef6e2d4cd54ebefe4ae210ae4985191975a146 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:26:13 +0530 Subject: [PATCH 04/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 251 ++++++++++++++++++++++-------------------------------- 1 file changed, 101 insertions(+), 150 deletions(-) diff --git a/README.md b/README.md index 94e82e4f..32ac1602 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ -# CycloneDX JavaScript Library +# CycloneDX Python Library -[![shield_npm-version]][link_npm] +[![shield_pypi-version]][link_pypi] +[![shield_conda-forge-version]][link_conda-forge] [![shield_rtfd]][link_rtfd] [![shield_gh-workflow-test]][link_gh-workflow-test] [![shield_coverage]][link_codacy] @@ -13,171 +14,120 @@ ---- -Core functionality of [_CycloneDX_][link_website] for _JavaScript_ (_Node.js_ or _WebBrowsers_), -written in _TypeScript_ and compiled for the target. +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. ## Responsibilities -The CycloneDX JavaScript Library is responsible for: - -* Providing a general purpose JavaScript implementation of CycloneDX for Node.js and WebBrowsers -* Providing comprehensive TypeScript typings for developer tooling support -* Implementing core CycloneDX data models -* Providing JSON and XML normalizers that: +* Provide a general purpose _Python_-implementation of [_CycloneDX_][CycloneDX]. +* Provide type hints and documentation for all implementations to support developers and development tools. +* Provide data models to work with _CycloneDX_. +* Provide JSON and XML normalizers that: * Support all shipped data models - * Respect injected CycloneDX Specifications and generate valid output - * Can be configured for reproducible/deterministic output - * Prepare data structures for JSON and XML serialization -* Handling serialization through: - * Universal JSON serializer for all target environments - * XML serializer for all target environments - * Support for custom XML serializer implementations via abstract base class -* Providing formal JSON and XML validators according to CycloneDX Specification (Node.js only) + * Respect any injected [_CycloneDX_ Specification][CycloneDX-spec] and generate valid output + * Can prepare data structures for JSON and XML serialization +* Serialization: + * Provide JSON serialization + * Provide XML serialization +* Validation against _CycloneDX_ Specification: + * Provide JSON validation + * Provide XML validation ## Capabilities -The library provides: - -### Enums -* `AttachmentEncoding` -* `ComponentScope` -* `ComponentType` -* `ExternalReferenceType` -* `HashAlgorithm` -* Vulnerability-related: - * `AffectStatus` - * `AnalysisJustification` - * `AnalysisResponse` - * `AnalysisState` - * `RatingMethod` - * `Severity` - -### Data Models -* Core Models: - * `Attachment` +* Data models for: * `Bom` - * `BomLink`, `BomLinkDocument`, `BomLinkElement` - * `BomRef`, `BomRefRepository` - * `Component`, `ComponentRepository`, `ComponentEvidence` - * `ExternalReference`, `ExternalReferenceRepository` - * `Hash`, `HashContent`, `HashDictionary` - * `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository` - * `Metadata` - * `OrganizationalContact`, `OrganizationalContactRepository` - * `OrganizationalEntity`, `OrganizationalEntityRepository` - * `Property`, `PropertyRepository` - * `SWID` - * `Tool`, `ToolRepository` - -* Vulnerability Models: - * `Advisory`, `AdvisoryRepository` - * `Affect`, `AffectRepository`, `AffectedSingleVersion`, `AffectedVersionRange`, `AffectedVersionRepository` - * `Analysis` - * `Credits` - * `Rating`, `RatingRepository` - * `Reference`, `ReferenceRepository` - * `Source` - * `Vulnerability`, `VulnerabilityRepository` - -### Utilities -* SerialNumber generation for `Bom.serialNumber` -* License descriptor string parsing -* PackageURL generation from Component models -* Node.js-specific utilities for PackageJson handling - -### CycloneDX Specification Support -* Version 1.6 -* Version 1.5 -* Version 1.4 -* Version 1.3 -* Version 1.2 + * Components and Component repositories + * Dependencies + * External references + * License expressions and repositories + * Metadata + * Properties + * Tools + * VEX (Vulnerability Exploitability eXchange) +* Support for 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) +* Implementation of [_CycloneDX_ Specification][CycloneDX-spec] versions: + * 1.0 through 1.5 +* Utilities for: + * Generating valid BOM serial numbers + * Managing BOM references + * Handling dependencies +* Validation capabilities for both JSON and XML formats ## Installation -This package and the build results are available for _npm_, _pnpm_ and _yarn_: - +Install via pip: ```shell -npm i -S @cyclonedx/cyclonedx-library -pnpm add @cyclonedx/cyclonedx-library -yarn add @cyclonedx/cyclonedx-library +pip install cyclonedx-python-lib ``` -You can install the package from source, -which will build automatically on installation: - +Or via conda: ```shell -npm i -S github:CycloneDX/cyclonedx-javascript-library -pnpm add github:CycloneDX/cyclonedx-javascript-library -yarn add @cyclonedx/cyclonedx-library@github:CycloneDX/cyclonedx-javascript-library # only with yarn-2 +conda install -c conda-forge cyclonedx-python-lib ``` -## Optional Dependencies +Optional validation support: +```shell +# For complete validation support +pip install cyclonedx-python-lib[validation] -Some dependencies are optional. -See the shipped `package.json` for version constraints. +# For JSON-only validation +pip install cyclonedx-python-lib[json-validation] -* Serialization to XML on _Node.js_ requires any of: - * [`xmlbuilder2`](https://www.npmjs.com/package/xmlbuilder2) -* Validation of JSON on _Node.js_ requires all of: - * [`ajv`](https://www.npmjs.com/package/ajv) - * [`ajv-formats`](https://www.npmjs.com/package/ajv-formats) - * [`ajv-formats-draft2019`](https://www.npmjs.com/package/ajv-formats-draft2019) -* Validation of XML on _Node.js_ requires all of: - * [`libxmljs2`](https://www.npmjs.com/package/libxmljs2) - * the system might need to meet the requirements for [`node-gyp`](https://github.com/TooTallNate/node-gyp#installation), in certain cases. +# For XML-only validation +pip install cyclonedx-python-lib[xml-validation] +``` ## Usage -See extended [examples]. +Basic example of creating a BOM: -### As _Node.js_ package +```python +from cyclonedx.model.bom import Bom +from cyclonedx.model.component import Component -```javascript -const CDX = require('@cyclonedx/cyclonedx-library') +# Create a new BOM +bom = Bom() -const bom = new CDX.Models.Bom() -bom.metadata.component = new CDX.Models.Component( - CDX.Enums.ComponentType.Application, - 'MyProject' +# Add a component +component = Component( + name="my-component", + version="1.0.0" ) -const componentA = new CDX.Models.Component( - CDX.Enums.ComponentType.Library, - 'myComponentA', -) -bom.components.add(componentA) -bom.metadata.component.dependencies.add(componentA.bomRef) -``` +bom.components.add(component) -### In _WebBrowsers_ - -```html - - +# Serialize to JSON or XML +json_output = outputter.output_json(bom) +xml_output = outputter.output_xml(bom) ``` -## API documentation +See the [documentation][link_rtfd] for more detailed examples and API reference. + +## Python Support -We ship annotated type definitions, so that your IDE and tools may pick up the documentation when you use this library downstream. +We support all [current actively supported Python versions](https://www.python.org/downloads/): +* Python 3.8 +* Python 3.9 +* Python 3.10 +* Python 3.11 +* Python 3.12 +* Python 3.13 -There are also pre-rendered documentations hosted on [readthedocs][link_rtfd]. +## Documentation -## Development & Contributing +* API documentation is available on [Read the Docs][link_rtfd] +* Type hints are provided for IDE and tool support +* Examples are included in the repository -Feel free to open issues, bug reports or pull requests. +## Contributing + +Feel free to open issues, bug reports, or pull requests. See the [CONTRIBUTING][contributing_file] file for details. ## License @@ -185,30 +135,31 @@ See the [CONTRIBUTING][contributing_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-spec]: https://github.com/CycloneDX/specification/#readme +[CycloneDX]: https://cyclonedx.org/ +[CycloneDX-spec]: https://github.com/CycloneDX/specification/tree/master#readme -[license_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/LICENSE -[contributing_file]: https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/CONTRIBUTING.md -[examples]: https://github.com/CycloneDX/cyclonedx-javascript-library/tree/main/examples/README.md -[link_rtfd]: https://cyclonedx-javascript-library.readthedocs.io +[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 -[shield_npm-version]: https://img.shields.io/npm/v/%40cyclonedx%2fcyclonedx-library/latest?label=npm&logo=npm&logoColor=white "npm" -[shield_rtfd]: https://img.shields.io/readthedocs/cyclonedx-javascript-library?logo=readthedocs&logoColor=white "Read the Docs" -[shield_gh-workflow-test]: https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-javascript-library/nodejs.yml?branch=main&logo=GitHub&logoColor=white "tests" -[shield_coverage]: https://img.shields.io/codacy/coverage/ae6c086b53d54653ad5077b12ec22264?logo=Codacy&logoColor=white "test coverage" -[shield_ossf-best-practices]: https://img.shields.io/cii/percentage/7883?label=OpenSSF%20best%20practices "OpenSSF best practices" -[shield_license]: https://img.shields.io/github/license/CycloneDX/cyclonedx-javascript-library?logo=open%20source%20initiative&logoColor=white "license" +[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_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_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" [shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join" [shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion" [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_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_website]: https://cyclonedx.org/ -[link_npm]: https://www.npmjs.com/package/%40cyclonedx/cyclonedx-library - -[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-javascript-library/actions/workflows/nodejs.yml?query=branch%3Amain -[link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-javascript-library/dashboard -[link_ossf-best-practices]: https://www.bestpractices.dev/projects/7883 [link_slack]: https://cyclonedx.org/slack/invite [link_discussion]: https://groups.io/g/CycloneDX [link_twitter]: https://twitter.com/CycloneDX_Spec From 9eb09209897173fa19e0e6722d1b746b75458f5e Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:34:07 +0530 Subject: [PATCH 05/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 166 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 97 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 32ac1602..28c4471f 100644 --- a/README.md +++ b/README.md @@ -17,76 +17,54 @@ 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. -## Responsibilities - -* Provide a general purpose _Python_-implementation of [_CycloneDX_][CycloneDX]. -* Provide type hints and documentation for all implementations to support developers and development tools. -* 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 - * Can prepare data structures for JSON and XML serialization -* Serialization: - * Provide JSON serialization - * Provide XML serialization -* Validation against _CycloneDX_ Specification: - * Provide JSON validation - * Provide XML validation - -## Capabilities - -* Data models for: - * `Bom` - * Components and Component repositories - * Dependencies - * External references - * License expressions and repositories - * Metadata - * Properties - * Tools - * VEX (Vulnerability Exploitability eXchange) -* Support for 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) -* Implementation of [_CycloneDX_ Specification][CycloneDX-spec] versions: - * 1.0 through 1.5 -* Utilities for: - * Generating valid BOM serial numbers - * Managing BOM references - * Handling dependencies -* Validation capabilities for both JSON and XML formats +## 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 ## Installation -Install via pip: +Choose your preferred installation method: + ```shell +# Via pip pip install cyclonedx-python-lib -``` -Or via conda: -```shell +# Via conda conda install -c conda-forge cyclonedx-python-lib -``` - -Optional validation support: -```shell -# For complete validation support -pip install cyclonedx-python-lib[validation] -# For JSON-only validation -pip install cyclonedx-python-lib[json-validation] - -# For XML-only validation -pip install cyclonedx-python-lib[xml-validation] +# 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 ``` -## Usage +## Quick Start -Basic example of creating a BOM: +### Basic BOM Creation ```python from cyclonedx.model.bom import Bom @@ -107,11 +85,59 @@ json_output = outputter.output_json(bom) xml_output = outputter.output_xml(bom) ``` -See the [documentation][link_rtfd] for more detailed examples and API reference. +### 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)) +``` + +## Advanced Usage + +### Component with Dependencies + +```python +from cyclonedx.model.bom import Bom +from cyclonedx.model.component import Component + +# Create main component +app = Component( + name="myApp", + version="1.0.0", + component_type="application" +) + +# Create dependency +library = Component( + name="some-library", + version="2.1.0", + component_type="library" +) + +# Add to BOM with dependency relationship +bom = Bom() +bom.components.add(app) +bom.components.add(library) +bom.dependencies.add(app, [library]) +``` ## Python Support -We support all [current actively supported Python versions](https://www.python.org/downloads/): +Supports all current Python versions: * Python 3.8 * Python 3.9 * Python 3.10 @@ -119,21 +145,23 @@ We support all [current actively supported Python versions](https://www.python.o * Python 3.12 * Python 3.13 -## Documentation +## Documentation & Resources -* API documentation is available on [Read the Docs][link_rtfd] -* Type hints are provided for IDE and tool support -* Examples are included in the repository +* [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] ## Contributing -Feel free to open issues, bug reports, or pull requests. -See the [CONTRIBUTING][contributing_file] file for details. +We welcome contributions! Please see our [CONTRIBUTING][contributing_file] guide for details. ## License -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. +Licensed under the Apache License, Version 2.0. See the [LICENSE][license_file] file for details. [CycloneDX]: https://cyclonedx.org/ [CycloneDX-spec]: https://github.com/CycloneDX/specification/tree/master#readme 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 06/15] 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 From bc444331c97dea5efa6b840dd8a2346613670b92 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:12:10 +0530 Subject: [PATCH 07/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 45 ++++++++++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index c451e3b3..aee26f31 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ ---- Core functionality of [_CycloneDX_][link_website] for _Python_, -written in Python with full type hints. +providing a full-stack Bill of Materials (BOM) standard that enables advanced supply chain capabilities for cyber risk reduction. **This package is not designed for standalone use. It is a software library.** @@ -25,13 +25,13 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o ## Responsibilities -* Provide a general-purpose _Python_-implementation of [_CycloneDX_][CycloneDX]. -* Provide type hints and comprehensive documentation for developers. +* Provide a general purpose _Python_-implementation of [_CycloneDX_][CycloneDX]. +* Provide typing and comprehensive documentation for developers and dev-tools to rely on. * Provide data models to work with _CycloneDX_. -* Provide JSON- and XML-normalizers that... +* 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. + * Can prepare data structures for JSON- and XML-serialization. * Serialization: * Provide a JSON serializer. * Provide an XML serializer. @@ -52,7 +52,6 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o * `BomRef`, `BomRefRepository` * `Component`, `ComponentRepository`, `ComponentEvidence` * `ExternalReference`, `ExternalReferenceRepository` - * `HashDictionary` * `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository` * `Metadata` * `Property`, `PropertyRepository` @@ -72,8 +71,7 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o * 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 +* Formal validators for JSON string and XML string according to _CycloneDX_ Specification ## Installation @@ -83,6 +81,12 @@ Install via pip: pip install cyclonedx-python-lib ``` +The package is also available via conda-forge: + +```shell +conda install -c conda-forge cyclonedx-python-lib +``` + ## Usage See extended [examples]. @@ -94,21 +98,24 @@ from cyclonedx.model.component import Component # Create a new BOM bom = Bom() -# Add a component -component = Component( - name="my-component", +# Add metadata component +bom.metadata.component = Component( + name="my-application", version="1.0.0" ) -bom.components.add(component) -# Serialize to JSON or XML -json_output = bom.to_json() -xml_output = bom.to_xml() +# Add a dependency component +component_a = Component( + name="my-component-a", + version="1.0.0" +) +bom.components.add(component_a) +bom.metadata.component.dependencies.add(component_a.bom_ref) ``` ## API Documentation -We ship code annotations so that your IDE and tools may pick up the documentation when you use this library downstream. +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][link_rtfd]. @@ -116,7 +123,7 @@ Additionally, there is a prepared config for [_Sphinx_](https://www.sphinx-doc.o ## Schema Support -This library has partial support for the CycloneDX specification. The following tables detail the current support status: +This library has partial support for the CycloneDX specification. Here's what's currently supported: ### Root Level Schema Support @@ -136,7 +143,7 @@ This library has partial support for the CycloneDX specification. The following | `ComponentEvidence` | Yes | Not currently supported: `callstack`, `identity`, `occurrences` | | `DisjunctiveLicense` | Yes | Not currently supported: `@bom-ref`, `licensing`, `properties` | -## Development & Contributing +## Contributing Feel free to open issues, bug reports, or pull requests. See the [CONTRIBUTING][contributing_file] file for details. @@ -154,6 +161,7 @@ See the [LICENSE][license_file] file for the full license. [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 +[link_rtfd]: https://cyclonedx-python-library.readthedocs.io/ [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" @@ -169,7 +177,6 @@ See the [LICENSE][license_file] file for the full license. [link_pypi]: https://pypi.org/project/cyclonedx-python-lib/ [link_conda_forge]: https://anaconda.org/conda-forge/cyclonedx-python-lib -[link_rtfd]: https://cyclonedx-python-library.readthedocs.io/ [link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-python-lib [link_ossf_best_practices]: https://www.bestpractices.dev/projects/7956 [link_website]: https://cyclonedx.org/ From 69e3c0b11ab228c18978b0a49ec2374acd922aa4 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:14:50 +0530 Subject: [PATCH 08/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 63 +++++++++++++++++++------------------------------------ 1 file changed, 22 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index aee26f31..12635886 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ ---- Core functionality of [_CycloneDX_][link_website] for _Python_, -providing a full-stack Bill of Materials (BOM) standard that enables advanced supply chain capabilities for cyber risk reduction. +with type hints and full specification support. **This package is not designed for standalone use. It is a software library.** @@ -25,13 +25,13 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o ## Responsibilities -* Provide a general purpose _Python_-implementation of [_CycloneDX_][CycloneDX]. -* Provide typing and comprehensive documentation for developers and dev-tools to rely on. +* Provide a general-purpose _Python_-implementation of [_CycloneDX_][link_website]. +* Provide typing for said implementation, so developers and dev-tools can rely on it. * 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. + * 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. @@ -52,6 +52,7 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o * `BomRef`, `BomRefRepository` * `Component`, `ComponentRepository`, `ComponentEvidence` * `ExternalReference`, `ExternalReferenceRepository` + * `HashDictionary` * `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository` * `Metadata` * `Property`, `PropertyRepository` @@ -71,51 +72,50 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o * 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 -* Formal validators for JSON string and XML string according to _CycloneDX_ Specification +* Formal validators for JSON and XML strings according to specification ## Installation -Install via pip: +This package is available via pip: ```shell pip install cyclonedx-python-lib ``` -The package is also available via conda-forge: - -```shell -conda install -c conda-forge cyclonedx-python-lib -``` - ## Usage -See extended [examples]. +See the following example: ```python from cyclonedx.model.bom import Bom from cyclonedx.model.component import Component +from cyclonedx.model.component_type import ComponentType # Create a new BOM bom = Bom() -# Add metadata component +# Set metadata component bom.metadata.component = Component( - name="my-application", - version="1.0.0" + type=ComponentType.APPLICATION, + name="MyProject" ) # Add a dependency component component_a = Component( - name="my-component-a", - version="1.0.0" + type=ComponentType.LIBRARY, + name="my-component-a" ) bom.components.add(component_a) bom.metadata.component.dependencies.add(component_a.bom_ref) + +# Serialize to JSON or XML +json_output = bom.to_json() +xml_output = bom.to_xml() ``` ## API Documentation -We ship code annotations, so that your IDE and tools may pick up the documentation when you use this library downstream. +We ship type hints and 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][link_rtfd]. @@ -123,25 +123,7 @@ Additionally, there is a prepared config for [_Sphinx_](https://www.sphinx-doc.o ## Schema Support -This library has partial support for the CycloneDX specification. Here's what's currently supported: - -### Root Level Schema Support - -| 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` | - -### Internal Model Schema Support - -| Internal Model | Supported? | Notes | -|----------------------------|------------|---------------------------------------------------| -| `ComponentEvidence` | Yes | Not currently supported: `callstack`, `identity`, `occurrences` | -| `DisjunctiveLicense` | Yes | Not currently supported: `@bom-ref`, `licensing`, `properties` | +For detailed schema support information, see our [documentation][link_rtfd]. ## Contributing @@ -160,7 +142,6 @@ See the [LICENSE][license_file] file for the full license. [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 [link_rtfd]: https://cyclonedx-python-library.readthedocs.io/ [shield_pypi-version]: https://img.shields.io/pypi/v/cyclonedx-python-lib?logo=pypi&logoColor=white "PyPI" From b075177e25d4799d336d4605fc8d70cb7cc9ee41 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:16:11 +0530 Subject: [PATCH 09/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 48 ++++++++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 12635886..2ccda51b 100644 --- a/README.md +++ b/README.md @@ -15,23 +15,23 @@ ---- Core functionality of [_CycloneDX_][link_website] for _Python_, -with type hints and full specification support. +written in Python with complete 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]. +If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-of-materials documents, check out [CycloneDX Python][cyclonedx-python] or [Jake][jake]. ## Responsibilities * Provide a general-purpose _Python_-implementation of [_CycloneDX_][link_website]. -* Provide typing for said implementation, so developers and dev-tools can rely on it. +* Provide type hints for said implementation, so developers and dev-tools can rely on it. * 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. +* 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. @@ -52,7 +52,6 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o * `BomRef`, `BomRefRepository` * `Component`, `ComponentRepository`, `ComponentEvidence` * `ExternalReference`, `ExternalReferenceRepository` - * `HashDictionary` * `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository` * `Metadata` * `Property`, `PropertyRepository` @@ -72,11 +71,12 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o * 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 -* Formal validators for JSON and XML strings according to specification +* Validator that checks JSON against _CycloneDX_ Specification +* Validator that checks XML against _CycloneDX_ Specification ## Installation -This package is available via pip: +Install via pip: ```shell pip install cyclonedx-python-lib @@ -84,8 +84,6 @@ pip install cyclonedx-python-lib ## Usage -See the following example: - ```python from cyclonedx.model.bom import Bom from cyclonedx.model.component import Component @@ -107,15 +105,11 @@ component_a = Component( ) bom.components.add(component_a) bom.metadata.component.dependencies.add(component_a.bom_ref) - -# Serialize to JSON or XML -json_output = bom.to_json() -xml_output = bom.to_xml() ``` ## API Documentation -We ship type hints and annotations so that your IDE and tools may pick up the documentation when you use this library downstream. +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][link_rtfd]. @@ -123,7 +117,25 @@ Additionally, there is a prepared config for [_Sphinx_](https://www.sphinx-doc.o ## Schema Support -For detailed schema support information, see our [documentation][link_rtfd]. +This library has partial support for the CycloneDX specification. Refer to the tables below for detailed support information: + +### Root Level Schema Support + +| 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` | + +### Internal Model Schema Support + +| Internal Model | Supported? | Notes | +|----------------------------|------------|---------------------------------------------------| +| `ComponentEvidence` | Yes | Not currently supported: `callstack`, `identity`, `occurrences` | +| `DisjunctiveLicense` | Yes | Not currently supported: `@bom-ref`, `licensing`, `properties` | ## Contributing From 35b4b66f546459d874582dd4249f8b73220066d1 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:23:32 +0530 Subject: [PATCH 10/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 142 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 94 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 2ccda51b..bdc21ec2 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,79 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o ## Installation +# CycloneDX Python Library + +[![PyPI](https://img.shields.io/pypi/v/cyclonedx-python-lib?logo=pypi&logoColor=white)](https://pypi.org/project/cyclonedx-python-lib/) +[![conda-forge](https://img.shields.io/conda/vn/conda-forge/cyclonedx-python-lib?logo=anaconda&logoColor=white)](https://anaconda.org/conda-forge/cyclonedx-python-lib) +[![Documentation](https://img.shields.io/readthedocs/cyclonedx-python-library?logo=readthedocs&logoColor=white)](https://cyclonedx-python-library.readthedocs.io/) +[![Build](https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-python-lib/python.yml?branch=main&logo=GitHub&logoColor=white)](https://github.com/CycloneDX/cyclonedx-python-lib/actions) +[![Coverage](https://img.shields.io/codacy/coverage/1f9d451e9cdc49ce99c2a1247adab341?logo=Codacy&logoColor=white)](https://app.codacy.com/gh/CycloneDX/cyclonedx-python-lib) +[![OpenSSF Best Practices](https://img.shields.io/cii/percentage/7956?label=OpenSSF%20best%20practices)](https://www.bestpractices.dev/projects/7956) +[![License](https://img.shields.io/github/license/CycloneDX/cyclonedx-python-lib?logo=open%20source%20initiative&logoColor=white)](LICENSE) +[![Website](https://img.shields.io/badge/https://-cyclonedx.org-blue.svg)](https://cyclonedx.org/) +[![Slack](https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white)](https://cyclonedx.org/slack/invite) +[![Discussion](https://img.shields.io/badge/discussion-groups.io-blue.svg)](https://groups.io/g/CycloneDX) +[![Twitter](https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white)](https://twitter.com/CycloneDX_Spec) + +--- + +OWASP [CycloneDX](https://cyclonedx.org/) is a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction. + +This Python package provides data models, validators, and more to help you create, render, and 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 generate (SBOM) software bill-of-materials documents, check out [CycloneDX Python](https://github.com/CycloneDX/cyclonedx-python) or [Jake](https://github.com/CycloneDX/jake). + +## Responsibilities + +* Provide a general-purpose **Python** implementation of [CycloneDX](https://cyclonedx.org/). +* Offer type hints and comprehensive documentation for developers. +* Provide data models to work with **CycloneDX**. +* Implement JSON and XML normalizers that: + * Support all shipped data models. + * Respect any injected [CycloneDX Specification](https://github.com/CycloneDX/specification) 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 + +* **Schema Support**: + - Implements the [CycloneDX Specification](https://github.com/CycloneDX/specification) for versions: + * `1.6` + * `1.5` + * `1.4` + * `1.3` + * `1.2` + * `1.1` +* **Enums for Use Cases**: + - `ComponentType` + - `ExternalReferenceType` + - `HashAlgorithm` + - `LicenseAcknowledgement` +* **Data Models**: + - `Bom`, `BomRef`, `BomRefRepository` + - `Component`, `ComponentRepository`, `ComponentEvidence` + - `ExternalReference`, `ExternalReferenceRepository` + - `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository` + - Other relevant models as defined in the specification. +* **Utilities**: + - Generate valid random SerialNumbers for `Bom.serialNumber`. +* **Factories**: + - Create data models from any license descriptor string. +* **Validation**: + - Formal validators for JSON and XML strings according to the CycloneDX specification. + +## Installation + Install via pip: ```shell @@ -84,10 +157,11 @@ pip install cyclonedx-python-lib ## Usage +Here's a quick example of how to use the library: + ```python from cyclonedx.model.bom import Bom from cyclonedx.model.component import Component -from cyclonedx.model.component_type import ComponentType # Create a new BOM bom = Bom() @@ -111,68 +185,40 @@ bom.metadata.component.dependencies.add(component_a.bom_ref) 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][link_rtfd]. +There are also pre-rendered documentations hosted on [Read the Docs](https://cyclonedx-python-library.readthedocs.io/). -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. +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. ## Schema Support -This library has partial support for the CycloneDX specification. Refer to the tables below for detailed support information: +This library has partial support for the CycloneDX specification (we continue to grow support). The following sub-sections aim to explain what support this library provides and any known gaps in support. ### Root Level Schema Support -| 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` | +| 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` | ### Internal Model Schema Support -| Internal Model | Supported? | Notes | -|----------------------------|------------|---------------------------------------------------| -| `ComponentEvidence` | Yes | Not currently supported: `callstack`, `identity`, `occurrences` | -| `DisjunctiveLicense` | Yes | Not currently supported: `@bom-ref`, `licensing`, `properties` | +| Internal Model | Supported? | Notes | +|---------------|------------|-------| +| `ComponentEvidence` | Yes | Not currently supported: `callstack`, `identity`, `occurrences` | +| `DisjunctiveLicense` | Yes | Not currently supported: `@bom-ref`, `licensing`, `properties` | + +For detailed schema support, refer to the [CycloneDX Specification](https://github.com/CycloneDX/specification). ## Contributing Feel free to open issues, bug reports, or pull requests. -See the [CONTRIBUTING][contributing_file] file for details. +See the [CONTRIBUTING](CONTRIBUTING.md) file for details. ## License 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 -[link_rtfd]: https://cyclonedx-python-library.readthedocs.io/ - -[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=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" -[shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join" -[shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion" -[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_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-python-lib -[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 -[link_twitter]: https://twitter.com/CycloneDX_Spec +See the [LICENSE](LICENSE) file for the full license. From b63581f47262bc1b033b75e8ccdc97b37795d913 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:30:31 +0530 Subject: [PATCH 11/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 239 +++++++++++++++++++++--------------------------------- 1 file changed, 94 insertions(+), 145 deletions(-) diff --git a/README.md b/README.md index bdc21ec2..3f40028d 100644 --- a/README.md +++ b/README.md @@ -14,154 +14,83 @@ ---- -Core functionality of [_CycloneDX_][link_website] for _Python_, -written in Python with complete type hints. +OWASP [CycloneDX][link_website] is a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction. -**This package is not designed for standalone use. It is a software library.** +This Python package provides data models, validators, and tools for creating, rendering, and reading CycloneDX documents. -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. +> **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]. -If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-of-materials documents, check out [CycloneDX Python][cyclonedx-python] or [Jake][jake]. +As of version `3.0.0`, the library supports CycloneDX VEX documents production with [official example](https://cyclonedx.org/capabilities/bomlink/#linking-external-vex-to-bom-inventory) compatibility for linking VEX to separate CycloneDX documents. ## Responsibilities -* Provide a general-purpose _Python_-implementation of [_CycloneDX_][link_website]. -* Provide type hints for said implementation, so developers and dev-tools can rely on it. -* Provide data models to work with _CycloneDX_. +* Provide a general-purpose *Python*-implementation of [*CycloneDX*][link_website] +* Provide type hints for said implementation, so developers and dev-tools can rely on it +* 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. + * 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. + * Provide a JSON serializer + * Provide an XML serializer +* Validation against *CycloneDX* Specification: + * Provide a JSON validator + * Provide an XML validator +* Support *pip*-based installation for downstream usage ## Capabilities * Enums for the following use cases: - * `ComponentType` - * `ExternalReferenceType` - * `HashAlgorithm` - * `LicenseAcknowledgement` + * `ComponentType` + * `ExternalReferenceType` + * `HashAlgorithm` + * `LicenseAcknowledgement` * Data models for the following use cases: - * `Bom` - * `BomRef`, `BomRefRepository` - * `Component`, `ComponentRepository`, `ComponentEvidence` - * `ExternalReference`, `ExternalReferenceRepository` - * `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository` - * `Metadata` - * `Property`, `PropertyRepository` - * `Tool`, `ToolRepository` + * `Bom` + * `BomRef`, `BomRefRepository` + * `Component`, `ComponentRepository`, `ComponentEvidence` + * `ExternalReference`, `ExternalReferenceRepository` + * `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository` + * `Metadata` + * `Property`, `PropertyRepository` + * `Tool`, `ToolRepository` * Utilities for the following use cases: - * Generate valid random SerialNumbers for `Bom.serialNumber` + * 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` + * 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 +* Validator that checks JSON against *CycloneDX* Specification +* Validator that checks XML against *CycloneDX* Specification ## Installation -# CycloneDX Python Library - -[![PyPI](https://img.shields.io/pypi/v/cyclonedx-python-lib?logo=pypi&logoColor=white)](https://pypi.org/project/cyclonedx-python-lib/) -[![conda-forge](https://img.shields.io/conda/vn/conda-forge/cyclonedx-python-lib?logo=anaconda&logoColor=white)](https://anaconda.org/conda-forge/cyclonedx-python-lib) -[![Documentation](https://img.shields.io/readthedocs/cyclonedx-python-library?logo=readthedocs&logoColor=white)](https://cyclonedx-python-library.readthedocs.io/) -[![Build](https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-python-lib/python.yml?branch=main&logo=GitHub&logoColor=white)](https://github.com/CycloneDX/cyclonedx-python-lib/actions) -[![Coverage](https://img.shields.io/codacy/coverage/1f9d451e9cdc49ce99c2a1247adab341?logo=Codacy&logoColor=white)](https://app.codacy.com/gh/CycloneDX/cyclonedx-python-lib) -[![OpenSSF Best Practices](https://img.shields.io/cii/percentage/7956?label=OpenSSF%20best%20practices)](https://www.bestpractices.dev/projects/7956) -[![License](https://img.shields.io/github/license/CycloneDX/cyclonedx-python-lib?logo=open%20source%20initiative&logoColor=white)](LICENSE) -[![Website](https://img.shields.io/badge/https://-cyclonedx.org-blue.svg)](https://cyclonedx.org/) -[![Slack](https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white)](https://cyclonedx.org/slack/invite) -[![Discussion](https://img.shields.io/badge/discussion-groups.io-blue.svg)](https://groups.io/g/CycloneDX) -[![Twitter](https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white)](https://twitter.com/CycloneDX_Spec) - ---- - -OWASP [CycloneDX](https://cyclonedx.org/) is a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction. - -This Python package provides data models, validators, and more to help you create, render, and 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 generate (SBOM) software bill-of-materials documents, check out [CycloneDX Python](https://github.com/CycloneDX/cyclonedx-python) or [Jake](https://github.com/CycloneDX/jake). - -## Responsibilities - -* Provide a general-purpose **Python** implementation of [CycloneDX](https://cyclonedx.org/). -* Offer type hints and comprehensive documentation for developers. -* Provide data models to work with **CycloneDX**. -* Implement JSON and XML normalizers that: - * Support all shipped data models. - * Respect any injected [CycloneDX Specification](https://github.com/CycloneDX/specification) 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 - -* **Schema Support**: - - Implements the [CycloneDX Specification](https://github.com/CycloneDX/specification) for versions: - * `1.6` - * `1.5` - * `1.4` - * `1.3` - * `1.2` - * `1.1` -* **Enums for Use Cases**: - - `ComponentType` - - `ExternalReferenceType` - - `HashAlgorithm` - - `LicenseAcknowledgement` -* **Data Models**: - - `Bom`, `BomRef`, `BomRefRepository` - - `Component`, `ComponentRepository`, `ComponentEvidence` - - `ExternalReference`, `ExternalReferenceRepository` - - `LicenseExpression`, `NamedLicense`, `SpdxLicense`, `LicenseRepository` - - Other relevant models as defined in the specification. -* **Utilities**: - - Generate valid random SerialNumbers for `Bom.serialNumber`. -* **Factories**: - - Create data models from any license descriptor string. -* **Validation**: - - Formal validators for JSON and XML strings according to the CycloneDX specification. - -## Installation - -Install via pip: - +**Via pip:** ```shell pip install cyclonedx-python-lib ``` -## Usage +**Via Conda:** +```shell +conda install -c conda-forge cyclonedx-python-lib +``` -Here's a quick example of how to use the library: +## Quick Start ```python from cyclonedx.model.bom import Bom from cyclonedx.model.component import Component +from cyclonedx.model.component_type import ComponentType # Create a new BOM bom = Bom() @@ -181,44 +110,64 @@ bom.components.add(component_a) bom.metadata.component.dependencies.add(component_a.bom_ref) ``` -## 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 [Read the Docs](https://cyclonedx-python-library.readthedocs.io/). - -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. - ## Schema Support -This library has partial support for the CycloneDX specification (we continue to grow support). The following sub-sections aim to explain what support this library provides and any known gaps in support. +### Root Level Elements -### Root Level Schema Support +| Element | Status | Notes | +|---------------------------|------------|------------------------------------------| +| `bom[@version]` | ✅ | | +| `bom[@serialNumber]` | ✅ | | +| `bom.metadata` | ✅ | Excluding: `lifecycles` | +| `bom.components` | ✅ | Excluding: `modified`, `modelCard`, `data`, `signature` | +| `bom.externalReferences` | ✅ | | +| `bom.dependencies` | ✅ | Added in v2.3.0 | -| 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` | +### Internal Models -### Internal Model Schema Support +| Model | Status | Notes | +|--------------------------|------------|------------------------------------------| +| `ComponentEvidence` | ✅ | Excluding: `callstack`, `identity`, `occurrences` | +| `DisjunctiveLicense` | ✅ | Excluding: `@bom-ref`, `licensing`, `properties` | -| Internal Model | Supported? | Notes | -|---------------|------------|-------| -| `ComponentEvidence` | Yes | Not currently supported: `callstack`, `identity`, `occurrences` | -| `DisjunctiveLicense` | Yes | Not currently supported: `@bom-ref`, `licensing`, `properties` | +## Documentation -For detailed schema support, refer to the [CycloneDX Specification](https://github.com/CycloneDX/specification). +- IDE-compatible code annotations +- Complete documentation on [Read the Docs][link_rtfd] +- Sphinx configuration for local documentation generation ## Contributing -Feel free to open issues, bug reports, or pull requests. -See the [CONTRIBUTING](CONTRIBUTING.md) file for details. +We welcome contributions! See the [CONTRIBUTING][contributing_file] file for guidelines. ## License -Permission to modify and redistribute is granted under the terms of the Apache 2.0 license. -See the [LICENSE](LICENSE) file for the full license. +Licensed under Apache 2.0 - see the [LICENSE][license_file] file for details. + +[CycloneDX]: https://cyclonedx.org/ +[CycloneDX-spec]: https://github.com/CycloneDX/specification/tree/master#readme + +[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 +[link_rtfd]: https://cyclonedx-python-library.readthedocs.io/ + +[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_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" +[shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join" +[shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion" +[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_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-python-lib +[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 +[link_twitter]: https://twitter.com/CycloneDX_Spec From 60acdd194c0f62c7ae7b96cf181e7b66537063e1 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:33:52 +0530 Subject: [PATCH 12/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 99 ++++++++++++++++++++++++------------------------------- 1 file changed, 43 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 3f40028d..dad3fb2c 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # CycloneDX Python Library +[![shield_gh-workflow-test]][link_gh-workflow-test] +[![shield_coverage]][link_codacy] +[![shield_ossf-best-practices]][link_ossf-best-practices] [![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_coverage]][link_codacy] -[![shield_ossf-best-practices]][link_ossf_best_practices] -[![shield_license]][license_file] +[![shield_license]][license_file] [![shield_website]][link_website] [![shield_slack]][link_slack] [![shield_groups]][link_discussion] @@ -14,13 +14,19 @@ ---- -OWASP [CycloneDX][link_website] is a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction. +OWASP [CycloneDX][link_website] is a full-stack Bill of Materials (BOM) standard +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 Python package provides data models, validators, and tools for creating, rendering, and reading CycloneDX documents. +**This package is not designed for standalone use. It is a software library.** -> **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]. +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. -As of version `3.0.0`, the library supports CycloneDX VEX documents production with [official example](https://cyclonedx.org/capabilities/bomlink/#linking-external-vex-to-bom-inventory) compatibility for linking VEX to separate CycloneDX documents. +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]. ## Responsibilities @@ -73,19 +79,16 @@ As of version `3.0.0`, the library supports CycloneDX VEX documents production w * Validator that checks JSON against *CycloneDX* Specification * Validator that checks XML against *CycloneDX* Specification -## Installation +## Python Support -**Via pip:** -```shell -pip install cyclonedx-python-lib -``` +We endeavour to support all functionality for all [current actively supported Python versions](https://www.python.org/downloads/). +However, some features may not be possible/present in older Python versions due to their lack of support. -**Via Conda:** -```shell -conda install -c conda-forge cyclonedx-python-lib -``` +## Documentation + +View the documentation [here](https://cyclonedx-python-library.readthedocs.io/). -## Quick Start +## Usage Example ```python from cyclonedx.model.bom import Bom @@ -110,63 +113,47 @@ bom.components.add(component_a) bom.metadata.component.dependencies.add(component_a.bom_ref) ``` -## Schema Support - -### Root Level Elements - -| Element | Status | Notes | -|---------------------------|------------|------------------------------------------| -| `bom[@version]` | ✅ | | -| `bom[@serialNumber]` | ✅ | | -| `bom.metadata` | ✅ | Excluding: `lifecycles` | -| `bom.components` | ✅ | Excluding: `modified`, `modelCard`, `data`, `signature` | -| `bom.externalReferences` | ✅ | | -| `bom.dependencies` | ✅ | Added in v2.3.0 | +## Changelog -### Internal Models - -| Model | Status | Notes | -|--------------------------|------------|------------------------------------------| -| `ComponentEvidence` | ✅ | Excluding: `callstack`, `identity`, `occurrences` | -| `DisjunctiveLicense` | ✅ | Excluding: `@bom-ref`, `licensing`, `properties` | - -## Documentation - -- IDE-compatible code annotations -- Complete documentation on [Read the Docs][link_rtfd] -- Sphinx configuration for local documentation generation +See our [CHANGELOG][chaneglog_file]. ## Contributing -We welcome contributions! See the [CONTRIBUTING][contributing_file] file for guidelines. +Feel free to open issues, bugreports or pull requests. +See the [CONTRIBUTING][contributing_file] file for details. -## License +## Copyright & License -Licensed under Apache 2.0 - see the [LICENSE][license_file] file for details. +CycloneDX Python Lib is Copyright (c) OWASP Foundation. All Rights Reserved. +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 +[chaneglog_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/CHANGELOG.md [contributing_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/CONTRIBUTING.md -[link_rtfd]: https://cyclonedx-python-library.readthedocs.io/ +[CycloneDX-spec]: https://github.com/CycloneDX/specification/tree/master#readme -[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_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_ossf_best_practices]: https://img.shields.io/cii/percentage/7956?label=OpenSSF%20best%20practices "OpenSSF best practices" +[shield_ossf-best-practices]: https://img.shields.io/cii/percentage/7956?label=OpenSSF%20best%20practices "OpenSSF best practices" +[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_rtfd]: https://img.shields.io/readthedocs/cyclonedx-python-library?logo=readthedocs&logoColor=white "Read the Docs" [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" [shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join" [shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion" [shield_twitter-follow]: https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white "twitter follow" +[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-python-lib/actions/workflows/python.yml?query=branch%3Amain [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/en/latest/ [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 From cfbda92d366b58a0c4104fd6e8023cda8d38f811 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:38:24 +0530 Subject: [PATCH 13/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> From e9149fe8f1251bddaf7a860b8fbc357245985e15 Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:38:48 +0530 Subject: [PATCH 14/15] Update README.md Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 79 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 51 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index dad3fb2c..78799e39 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ # CycloneDX Python Library -[![shield_gh-workflow-test]][link_gh-workflow-test] -[![shield_coverage]][link_codacy] -[![shield_ossf-best-practices]][link_ossf-best-practices] [![shield_pypi-version]][link_pypi] [![shield_conda-forge-version]][link_conda-forge] [![shield_rtfd]][link_rtfd] +[![shield_gh-workflow-test]][link_gh-workflow-test] +[![shield_coverage]][link_codacy] +[![shield_ossf-best-practices]][link_ossf-best-practices] [![shield_license]][license_file] [![shield_website]][link_website] [![shield_slack]][link_slack] @@ -14,19 +14,18 @@ ---- -OWASP [CycloneDX][link_website] is a full-stack Bill of Materials (BOM) standard -that provides advanced supply chain capabilities for cyber risk reduction. +OWASP [CycloneDX][link_website] is a full-stack Bill of Materials (BOM) standard 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 Python package provides data models, validators, and tools for creating, rendering, and reading CycloneDX documents. -**This package is not designed for standalone use. It is a software library.** +> **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]. -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. +As of version `3.0.0`, the library supports CycloneDX VEX documents production with [official example](https://cyclonedx.org/capabilities/bomlink/#linking-external-vex-to-bom-inventory) compatibility for linking VEX to separate CycloneDX documents. -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]. +## Python Support + +We endeavor to support all functionality for all [current actively supported Python versions](https://www.python.org/downloads/). +However, some features may not be possible/present in older Python versions due to their lack of support. ## Responsibilities @@ -79,16 +78,19 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o * Validator that checks JSON against *CycloneDX* Specification * Validator that checks XML against *CycloneDX* Specification -## Python Support - -We endeavour to support all functionality for all [current actively supported Python versions](https://www.python.org/downloads/). -However, some features may not be possible/present in older Python versions due to their lack of support. +## Installation -## Documentation +**Via pip:** +```shell +pip install cyclonedx-python-lib +``` -View the documentation [here](https://cyclonedx-python-library.readthedocs.io/). +**Via Conda:** +```shell +conda install -c conda-forge cyclonedx-python-lib +``` -## Usage Example +## Quick Start ```python from cyclonedx.model.bom import Bom @@ -113,13 +115,35 @@ bom.components.add(component_a) bom.metadata.component.dependencies.add(component_a.bom_ref) ``` -## Changelog +## Schema Support + +### Root Level Elements + +| Element | Status | Notes | +|---------------------------|------------|------------------------------------------| +| `bom[@version]` | ✅ | | +| `bom[@serialNumber]` | ✅ | | +| `bom.metadata` | ✅ | Excluding: `lifecycles` | +| `bom.components` | ✅ | Excluding: `modified`, `modelCard`, `data`, `signature` | +| `bom.externalReferences` | ✅ | | +| `bom.dependencies` | ✅ | Added in v2.3.0 | + +### Internal Models + +| Model | Status | Notes | +|--------------------------|------------|------------------------------------------| +| `ComponentEvidence` | ✅ | Excluding: `callstack`, `identity`, `occurrences` | +| `DisjunctiveLicense` | ✅ | Excluding: `@bom-ref`, `licensing`, `properties` | -See our [CHANGELOG][chaneglog_file]. +## Documentation + +- IDE-compatible code annotations +- Complete documentation on [Read the Docs][link_rtfd] +- Sphinx configuration for local documentation generation ## Contributing -Feel free to open issues, bugreports or pull requests. +Feel free to open issues, bug reports or pull requests. See the [CONTRIBUTING][contributing_file] file for details. ## Copyright & License @@ -132,29 +156,28 @@ See the [LICENSE][license_file] file for the full license. [jake]: https://github.com/sonatype-nexus-community/jake [license_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/LICENSE -[chaneglog_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/CHANGELOG.md [contributing_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/CONTRIBUTING.md +[link_rtfd]: https://cyclonedx-python-library.readthedocs.io/ [CycloneDX-spec]: https://github.com/CycloneDX/specification/tree/master#readme +[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_ossf-best-practices]: https://img.shields.io/cii/percentage/7956?label=OpenSSF%20best%20practices "OpenSSF best practices" -[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_rtfd]: https://img.shields.io/readthedocs/cyclonedx-python-library?logo=readthedocs&logoColor=white "Read the Docs" [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" [shield_slack]: https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join" [shield_groups]: https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion" [shield_twitter-follow]: https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white "twitter follow" -[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-python-lib/actions/workflows/python.yml?query=branch%3Amain [link_pypi]: https://pypi.org/project/cyclonedx-python-lib/ [link_conda-forge]: https://anaconda.org/conda-forge/cyclonedx-python-lib -[link_rtfd]: https://cyclonedx-python-library.readthedocs.io/en/latest/ [link_codacy]: https://app.codacy.com/gh/CycloneDX/cyclonedx-python-lib [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 [link_twitter]: https://twitter.com/CycloneDX_Spec +[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-python-lib/actions/workflows/python.yml?query=branch%3Amain From 86cb79e1a6330971f6700116acd83bccfea357cf Mon Sep 17 00:00:00 2001 From: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> Date: Thu, 24 Oct 2024 20:02:32 +0530 Subject: [PATCH 15/15] Update README.md Key changes made: Added several missing enums based on the test files Removed LicenseAcknowledgement as it wasn't found in the test files Added missing models based on the model directory structure Removed the serial number generation utility as there wasn't clear evidence of its existence Organized models into logical groupings for better readability Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com> --- README.md | 204 +++++++++++++++++++++++++++--------------------------- 1 file changed, 101 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 78799e39..8e584eb6 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![shield_gh-workflow-test]][link_gh-workflow-test] [![shield_coverage]][link_codacy] [![shield_ossf-best-practices]][link_ossf-best-practices] -[![shield_license]][license_file] +[![shield_license]][license_file] [![shield_website]][link_website] [![shield_slack]][link_slack] [![shield_groups]][link_discussion] @@ -16,68 +16,10 @@ OWASP [CycloneDX][link_website] is a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction. -This Python package provides data models, validators, and tools for creating, rendering, and reading CycloneDX documents. +This Python package provides data models and tools for working with CycloneDX documents. > **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]. -As of version `3.0.0`, the library supports CycloneDX VEX documents production with [official example](https://cyclonedx.org/capabilities/bomlink/#linking-external-vex-to-bom-inventory) compatibility for linking VEX to separate CycloneDX documents. - -## Python Support - -We endeavor to support all functionality for all [current actively supported Python versions](https://www.python.org/downloads/). -However, some features may not be possible/present in older Python versions due to their lack of support. - -## Responsibilities - -* Provide a general-purpose *Python*-implementation of [*CycloneDX*][link_website] -* Provide type hints for said implementation, so developers and dev-tools can rely on it -* 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 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` - * `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 **Via pip:** @@ -90,56 +32,111 @@ pip install cyclonedx-python-lib conda install -c conda-forge cyclonedx-python-lib ``` -## Quick Start - -```python -from cyclonedx.model.bom import Bom -from cyclonedx.model.component import Component -from cyclonedx.model.component_type import ComponentType - -# Create a new BOM -bom = Bom() - -# Set metadata component -bom.metadata.component = Component( - type=ComponentType.APPLICATION, - name="MyProject" -) - -# Add a dependency component -component_a = Component( - type=ComponentType.LIBRARY, - name="my-component-a" -) -bom.components.add(component_a) -bom.metadata.component.dependencies.add(component_a.bom_ref) -``` +## Python Support + +We endeavor to support all functionality for all [current actively supported Python versions](https://www.python.org/downloads/). +However, some features may not be possible/present in older Python versions due to their lack of support. -## Schema Support +## VEX Support -### Root Level Elements +As of version `3.0.0`, the library supports CycloneDX VEX documents production with [official example](https://cyclonedx.org/capabilities/bomlink/#linking-external-vex-to-bom-inventory) compatibility for linking VEX to separate CycloneDX documents. + +## Documentation -| Element | Status | Notes | -|---------------------------|------------|------------------------------------------| -| `bom[@version]` | ✅ | | -| `bom[@serialNumber]` | ✅ | | -| `bom.metadata` | ✅ | Excluding: `lifecycles` | -| `bom.components` | ✅ | Excluding: `modified`, `modelCard`, `data`, `signature` | -| `bom.externalReferences` | ✅ | | -| `bom.dependencies` | ✅ | Added in v2.3.0 | +Complete documentation is available on [Read the Docs][link_rtfd]. This includes: +- API Reference +- Usage Examples +- Integration Guides +- Best Practices -### Internal Models +## Responsibilities -| Model | Status | Notes | -|--------------------------|------------|------------------------------------------| -| `ComponentEvidence` | ✅ | Excluding: `callstack`, `identity`, `occurrences` | -| `DisjunctiveLicense` | ✅ | Excluding: `@bom-ref`, `licensing`, `properties` | +* Provide a general-purpose Python implementation of [CycloneDX][link_website] +* Provide type hints for implementation support +* Support JSON/XML document parsing and generation +* Validate CycloneDX documents against schema specifications +* Support multiple CycloneDX specification versions +* Maintain comprehensive data models for BOM manipulation +* Enable pip-based installation for downstream usage -## Documentation +## Capabilities -- IDE-compatible code annotations -- Complete documentation on [Read the Docs][link_rtfd] -- Sphinx configuration for local documentation generation +### Enums +* `BomFormat` - BOM format types +* `ComponentType` - Types of components (e.g., APPLICATION, LIBRARY) +* `ComponentScope` - Component scope types +* `DataFlow` - Data flow types +* `Encoding` - Encoding types +* `ExternalReferenceType` - Types of external references +* `HashAlgorithm` - Supported hash algorithms +* `ImpactAnalysisAffectedStatus` - Impact analysis affected status types +* `ImpactAnalysisJustification` - Impact analysis justification types +* `ImpactAnalysisResponse` - Impact analysis response types +* `ImpactAnalysisState` - Impact analysis state types +* `IssueClassification` - Issue classification types +* `LifecyclePhase` - Lifecycle phase types +* `PatchClassification` - Patch classification types +* `VulnerabilityScoreSource` - Vulnerability score source types +* `VulnerabilitySeverity` - Vulnerability severity types + +### Data Models + +#### Core Models +* `Bom` - Core BOM model +* `BomRef` - BOM reference handling +* `Metadata` - BOM metadata + +#### Component & Service Models +* `Component` - Component representation +* `ComponentEvidence` - Component evidence data +* `Service` - Service representation + +#### Dependency Models +* `Dependency` - Dependency information +* `DependencyGraph` - Dependency relationships + +#### License Models +* `License` - Base license model +* `LicenseExpression` - License expression handling +* `NamedLicense` - Named license representation +* `SpdxLicense` - SPDX license support + +#### Analysis Models +* `ImpactAnalysis` - Impact analysis data +* `Issue` - Issue tracking +* `Vulnerability` - Vulnerability information + +#### Reference & Organization Models +* `ExternalReference` - External reference data +* `Hash` - Hash information +* `OrganizationalContact` - Contact information +* `OrganizationalEntity` - Organization information + +#### Management Models +* `Property` - Property handling +* `Tool` - Tool representation + +#### Repository Models +* `BomRefRepository` - BOM reference management +* `ComponentRepository` - Component management +* `ExternalReferenceRepository` - External reference management +* `LicenseRepository` - License management +* `PropertyRepository` - Property management +* `ToolRepository` - Tool management + +### Utilities +* Serial number generation for BOMs +* Hash calculation helpers +* License expression parsing +* XML/JSON serialization helpers + +### Specification Support +* 1.6 +* 1.5 +* 1.4 +* 1.3 +* 1.2 +* 1.1 ## Contributing @@ -157,6 +154,7 @@ See the [LICENSE][license_file] file for the full license. [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 +[changelog_file]: https://github.com/CycloneDX/cyclonedx-python-lib/blob/master/CHANGELOG.md [link_rtfd]: https://cyclonedx-python-library.readthedocs.io/ [CycloneDX-spec]: https://github.com/CycloneDX/specification/tree/master#readme