Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history 
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>
  • Loading branch information
@HmbleCreator
HmbleCreator authored Oct 24, 2024
1 parent da87ed0 commit 86cb79e
Showing 1 changed file with 101 additions and 103 deletions.
204 changes: 101 additions & 103 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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:**
Expand All @@ -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

Expand All @@ -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

Expand Down

0 comments on commit 86cb79e

Please sign in to comment.