Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history 
Signed-off-by: Humble Creator <140157584+HmbleCreator@users.noreply.github.com>
  • Loading branch information
@HmbleCreator
HmbleCreator authored Oct 24, 2024
1 parent 9eb0920 commit 4c44e9e
Showing 1 changed file with 102 additions and 117 deletions.
219 changes: 102 additions & 117 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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]
Expand All @@ -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
Expand All @@ -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"
Expand All @@ -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
Expand Down

0 comments on commit 4c44e9e

Please sign in to comment.