Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: reorganize responsibilities and capabilities sections in README.md #719

Draft
wants to merge 17 commits into
base: main
Choose a base branch
from
Draft

docs: reorganize responsibilities and capabilities sections in README.md #719

Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
e5ab2e1
Update README.md
HmbleCreator Oct 22, 2024
75aff7d
Update README.md
HmbleCreator Oct 22, 2024
87cefee
docs: reorganize responsibilities and capabilities sections
HmbleCreator Oct 22, 2024
3cef6e2
Update README.md
HmbleCreator Oct 24, 2024
9eb0920
Update README.md
HmbleCreator Oct 24, 2024
4c44e9e
Update README.md
HmbleCreator Oct 24, 2024
bc44433
Update README.md
HmbleCreator Oct 24, 2024
69e3c0b
Update README.md
HmbleCreator Oct 24, 2024
b075177
Update README.md
HmbleCreator Oct 24, 2024
35b4b66
Update README.md
HmbleCreator Oct 24, 2024
b63581f
Update README.md
HmbleCreator Oct 24, 2024
60acdd1
Update README.md
HmbleCreator Oct 24, 2024
cfbda92
Update README.md
HmbleCreator Oct 24, 2024
e9149fe
Update README.md
HmbleCreator Oct 24, 2024
89da056
Merge branch 'CycloneDX:main' into main
HmbleCreator Oct 24, 2024
da87ed0
Merge branch 'main' into main
HmbleCreator Oct 24, 2024
86cb79e
Update README.md
HmbleCreator Oct 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 120 additions & 24 deletions README.md
View file
Open in desktop
HmbleCreator marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -14,36 +14,133 @@

----

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 and tools for working with 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].
Copy link
Member

@jkowalleck jkowalleck Oct 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

use one of the flavors here:
https://github.com/orgs/community/discussions/16925

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.


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.
## Installation

If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-of-materials documents, why not checkout
HmbleCreator marked this conversation as resolved.
Show resolved Hide resolved
[CycloneDX Python][cyclonedx-python] or [Jake][jake].
**Via pip:**
```shell
pip install cyclonedx-python-lib
```

## Documentation

View the documentation [here](https://cyclonedx-python-library.readthedocs.io/).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please bring back the paragraph that links to the rendered documentation.

**Via Conda:**
```shell
conda install -c conda-forge cyclonedx-python-lib
```

## Python Support

We endeavour to support all functionality for all [current actively supported Python versions](https://www.python.org/downloads/).
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.

## Changelog
## VEX Support

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

See our [CHANGELOG][chaneglog_file].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please bring back the link to the changelog.

Complete documentation is available on [Read the Docs][link_rtfd]. This includes:
- API Reference
- Usage Examples
- Integration Guides
- Best Practices

## Responsibilities

* 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

## Capabilities

### Enums
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the description next to the enum types do not add much value, as they duplicate the enums name and add the word type.
i'd rather remove the additional descriptions.

* `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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could you explain the idea behind this grouping? how is this organized, how came this together?
I really love to understand your reasoning. You might have fresh ideas that are beneficial for the project :-) please share your thoughts.

I mean, all these models were based of CycloneDX spec -- they actually reflect it.
If a grouping was actually necessary, it should correlate with the CycloneDX spec groups somehow.


#### 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the repositories are a mere collection of other tools.
please put them to their respective domain group

* `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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i did not know we have this. could you point me to the code that does this?

* Hash calculation helpers
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we do have this, but we dont want to brag about it, these are mere helpers for experts. we better not tell about them here.
please remove

* License expression parsing
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i did not know we have this. could you point me to the code that does this?

* XML/JSON serialization helpers
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we do have this, but we dont want to brag about it, thse are mere internal helpers for experts. we better not tell about them here.
please remove,


### Specification Support
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please make each version a code-block by surrounding it with `

* 1.6
* 1.5
* 1.4
* 1.3
* 1.2
* 1.1
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1.0 is missing.
we do have support for it, dont we?


## 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
Expand All @@ -56,30 +153,29 @@ 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please order the links back like they were.
file-links were grouped, shield-links were grouped, external-links were grouped ...

[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
[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

[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

[PEP-508]: https://www.python.org/dev/peps/pep-0508/
[link_gh-workflow-test]: https://github.com/CycloneDX/cyclonedx-python-lib/actions/workflows/python.yml?query=branch%3Amain