You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Install from pypi.org as you would any other Python module:
28
+
29
+
```shell
30
+
pip install cyclonedx-python-lib
31
+
```
32
+
33
+
## Architecture
34
+
35
+
This module break out into three key areas:
36
+
37
+
1.**Parser**: Use a parser that suits your needs to automatically gather information about your environment or
38
+
application
39
+
2.**Model**: Internal models used to unify data from different parsers
40
+
3.**Output**: Choose and configure an output which allows you to define output format as well as the CycloneDX schema
41
+
version
42
+
43
+
### Parsing
44
+
45
+
You can use one of the parsers to obtain information about your project or environment. Available parsers:
46
+
47
+
| Parser | Class / Import | Description |
48
+
| ------- | ------ | ------ |
49
+
| CondaListJsonParser |`from cyclonedx.parser.conda import CondaListJsonParser`| Parses input provided as a `str` that is output from `conda list --json`|
50
+
| CondaListExplicitParser |`from cyclonedx.parser.conda import CondaListExplicitParser`| Parses input provided as a `str` that is output from `conda list --explicit` or `conda list --explicit --md5`|
51
+
| Environment |`from cyclonedx.parser.environment import EnvironmentParser`| Looks at the packaged installed in your current Python environment. |
52
+
| PipEnvParser |`from cyclonedx.parser.pipenv import PipEnvParser`| Parses `Pipfile.lock` content passed in as a string. |
53
+
| PipEnvFileParser |`from cyclonedx.parser.pipenv import PipEnvFileParser`| Parses the `Pipfile.lock` file at the supplied path. |
54
+
| PoetryParser |`from cyclonedx.parser.poetry import PoetryParser`| Parses `poetry.lock` content passed in as a string. |
55
+
| PoetryFileParser |`from cyclonedx.parser.poetry import PoetryFileParser`| Parses the `poetry.lock` file at the supplied path. |
56
+
| RequirementsParser |`from cyclonedx.parser.requirements import RequirementsParser`| Parses a multiline string that you provide that conforms to the `requirements.txt`[PEP-508] standard. |
57
+
| RequirementsFileParser |`from cyclonedx.parser.requirements import RequirementsFileParser`| Parses a file that you provide the path to that conforms to the `requirements.txt`[PEP-508] standard. |
58
+
59
+
#### Example
60
+
61
+
```py
62
+
from cyclonedx.parser.environment import EnvironmentParser
63
+
64
+
parser = EnvironmentParser()
65
+
```
66
+
67
+
#### Notes on Requirements parsing
68
+
69
+
CycloneDX software bill-of-materials require pinned versions of requirements. If your `requirements.txt` does not have
70
+
pinned versions, warnings will be recorded and the dependencies without pinned versions will be excluded from the
71
+
generated CycloneDX. CycloneDX schemas (from version 1.0+) require a component to have a version when included in a
72
+
CycloneDX bill of materials (according to schema).
73
+
74
+
If you need to use a `requirements.txt` in your project that does not have pinned versions an acceptable workaround
75
+
might be to:
76
+
77
+
```shell
78
+
pip install -r requirements.txt
79
+
pip freeze > requirements-frozen.txt
80
+
```
81
+
82
+
You can then feed in the frozen requirements from `requirements-frozen.txt`_or_ use the `Environment` parser one you
83
+
have `pip install`ed your dependencies.
84
+
85
+
### Modelling
86
+
87
+
You can create a BOM Model from either a Parser instance or manually using the methods avaialbel directly on the `Bom` class.
88
+
89
+
The model also supports definition of vulnerabilities for output using the CycloneDX schema extension for
90
+
[Vulnerability Disclosures](https://cyclonedx.org/use-cases/#vulnerability-disclosure) as of version 0.3.0.
91
+
92
+
**Note:** Known vulnerabilities associated with Components can be sourced from various data sources, but this library
93
+
will not source them for you. Perhaps look at [Jake][jake] if you're interested in this.
94
+
95
+
#### Example from a Parser
96
+
97
+
```py
98
+
from cyclonedx.model.bom import Bom
99
+
from cyclonedx.parser.environment import EnvironmentParser
100
+
101
+
parser = EnvironmentParser()
102
+
bom = Bom.from_parser(parser=parser)
103
+
```
104
+
105
+
### Generating Output
106
+
107
+
Once you have an instance of a `Bom` you can produce output in either `JSON` or `XML` against any of the supporting CycloneDX schema versions as you require.
108
+
109
+
We provide two helper methods:
110
+
111
+
* Output to string (for you to do with as you require)
112
+
* Output directly to a filename you provide
113
+
114
+
#### Example as JSON
115
+
116
+
```py
117
+
from cyclonedx.output import get_instance, OutputFormat
The Library API Documentation is available online at [https://cyclonedx.github.io/cyclonedx-python-lib/](https://cyclonedx.github.io/cyclonedx-python-lib/).
135
+
136
+
## Schema Support
137
+
138
+
This library is a work in progress and complete support for all parts of the CycloneDX schema will come in future releases.
139
+
140
+
Here is a summary of the parts of the schema supported by this library:
141
+
142
+
_Note: We refer throughout using XPath, but the same is true for both XML and JSON output formats._
143
+
144
+
<tablewidth="100%">
145
+
<thead>
146
+
<tr>
147
+
<th>XPath</th>
148
+
<th>Support v1.3</th>
149
+
<th>Support v1.2</th>
150
+
<th>Support v1.1</th>
151
+
<th>Support v1.0</th>
152
+
<th>Notes</th>
153
+
</tr>
154
+
</thead>
155
+
<tbody>
156
+
<tr>
157
+
<td><code>/bom</code></td>
158
+
<td>Y</td><td>Y</td><td>Y</td><td>Y</td>
159
+
<td>
160
+
This is the root element and is supported with all it's defined attributes.
161
+
</td>
162
+
</tr>
163
+
<tr>
164
+
<td><code>/bom/metadata</code></td>
165
+
<td>Y</td><td>Y</td><td>N/A</td><td>N/A</td>
166
+
<td>
167
+
<code>timestamp</code> and <code>tools</code> are currently supported
0 commit comments