dt-sbom-scanner 1.9.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. dt_sbom_scanner-1.9.1/LICENSE.txt +21 -0
  2. dt_sbom_scanner-1.9.1/PKG-INFO +270 -0
  3. dt_sbom_scanner-1.9.1/README.md +241 -0
  4. dt_sbom_scanner-1.9.1/dt_sbom_scanner/AnsiColors.py +22 -0
  5. dt_sbom_scanner-1.9.1/dt_sbom_scanner/__init__.py +0 -0
  6. dt_sbom_scanner-1.9.1/dt_sbom_scanner/sbom_utils.py +180 -0
  7. dt_sbom_scanner-1.9.1/dt_sbom_scanner/scan.py +1143 -0
  8. dt_sbom_scanner-1.9.1/pyproject.toml +100 -0
dt_sbom_scanner-1.9.1/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (C) 2024 Pierre Smeyers and contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
dt_sbom_scanner-1.9.1/PKG-INFO ADDED
@@ -0,0 +1,270 @@
1
+ Metadata-Version: 2.4
2
+ Name: dt-sbom-scanner
3
+ Version: 1.9.1
4
+ Summary: Dependency Track SBOM Scanner
5
+ License-Expression: MIT
6
+ License-File: LICENSE.txt
7
+ Keywords: tool,sbom,dependency track
8
+ Author: Pierre Smeyers
9
+ Author-email: pierre.smeyers@gmail.com
10
+ Requires-Python: >=3.12,<4.0
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Programming Language :: Python :: 3 :: Only
22
+ Requires-Dist: cyclonedx-python-lib (>=11.1.0,<12.0.0)
23
+ Requires-Dist: requests (>=2.32.5,<4.0.0)
24
+ Requires-Dist: urllib3 (>=2.6.0,<3.0.0)
25
+ Project-URL: Homepage, https://gitlab.com/to-be-continuous/tools/dt-sbom-scanner
26
+ Project-URL: Issues, https://gitlab.com/to-be-continuous/tools/dt-sbom-scanner/-/issues
27
+ Description-Content-Type: text/markdown
28
+
29
+ <img alt="Dependency Track SBOM Scanner logo" width="128px" src="https://gitlab.com/to-be-continuous/tools/dt-sbom-scanner/-/avatar">
30
+
31
+ [![pypi](https://img.shields.io/pypi/v/dt-sbom-scanner.svg)](https://pypi.org/project/dt-sbom-scanner/)
32
+ [![python](https://img.shields.io/pypi/pyversions/dt-sbom-scanner.svg)](https://pypi.org/project/dt-sbom-scanner/)
33
+
34
+ # Dependency Track SBOM Scanner
35
+
36
+ This project provides a CLI tool able to publish SBOM files to a [Dependency Track](https://docs.dependencytrack.org/) server.
37
+
38
+ ## Get started
39
+
40
+ ### Run SBOM Scanner as a Python program
41
+
42
+ `dt-sbom-scanner` requires Python 3.12 or higher and can be installed using pip package manager:
43
+
44
+ ```bash
45
+ pip install dt-sbom-scanner
46
+ ```
47
+
48
+ Then it can be run as a Python program:
49
+
50
+ ```bash
51
+ # obtain help
52
+ sbom-scanner --help
53
+
54
+ # run
55
+ sbom-scanner \
56
+ --base-api-url http://localhost:8080/api \
57
+ --api-key "$DT_API_KEY" \
58
+ --project-path "my-group/my-project/sub-{file_prefix}" \
59
+ **/*.cyclonedx.json
60
+ ```
61
+
62
+ ### Run SBOM Scanner CLI as a container
63
+
64
+ `dt-sbom-scanner` can also be run as a container image using Docker or Podman.
65
+
66
+ ```bash
67
+ # run from GitLab Container Registry
68
+ docker run \
69
+ --rm --volume $(pwd):/code --env DEPTRACK_API_KEY \
70
+ registry.gitlab.com/to-be-continuous/tools/dt-sbom-scanner:latest \
71
+ --base-api-url http://host.docker.internal:8080/api \
72
+ --api-key "$DT_API_KEY" \
73
+ --project-path "my-group/my-project/sub-{file_prefix}" \
74
+ **/*.cyclonedx.json
75
+ ```
76
+
77
+ ## Usage
78
+
79
+ ```bash
80
+ usage: sbom-scanner [-h] [-u BASE_API_URL] [-k API_KEY] [-i] [-p PROJECT_PATH] [-s PATH_SEPARATOR] [-t TAGS] [--parent-collection-logic {NONE,ALL,TAG,LATEST}]
81
+ [--parent-collection-logic-tag PARENT_COLLECTION_LOGIC_TAG] [--latest-depth LATEST_DEPTH] [-m] [-o MERGE_OUTPUT] [-l PURL_MAX_LEN] [-U] [-V MERGED_VEX_FILE] [-S] [-R RISK_SCORE_THRESHOLD]
82
+ [sbom_patterns ...]
83
+
84
+ This tool scans for SBOM files and publishes them to a Dependency Track server.
85
+
86
+ positional arguments:
87
+ sbom_patterns SBOM file patterns to publish (supports glob patterns). Default: '**/*.cyclonedx.json **/*.cyclonedx.xml'
88
+
89
+ options:
90
+ -h, --help show this help message and exit
91
+
92
+ Connection to Dependency Track platform:
93
+ -u BASE_API_URL, --base-api-url BASE_API_URL
94
+ Dependency Track server base API url (includes '/api')
95
+ -k API_KEY, --api-key API_KEY
96
+ Dependency Track API key
97
+ -i, --insecure Skip SSL verification
98
+
99
+ Project settings:
100
+ -p PROJECT_PATH, --project-path PROJECT_PATH
101
+ Dependency Track target project path to publish SBOM files to (see doc)
102
+ -s PATH_SEPARATOR, --path-separator PATH_SEPARATOR
103
+ Separator to use in project path (default: '/')
104
+ -t TAGS, --tags TAGS Comma separated list of tags to attach to the project
105
+ --parent-collection-logic {NONE,ALL,TAG,LATEST}
106
+ Set up how the parent aggregates its direct children (ALL: all, TAG: with tag matching --parent-collection-logic-tag, LATEST: flagged as latest, NONE: disable), default is ALL (DT version >= 4.13.0)
107
+ --parent-collection-logic-tag PARENT_COLLECTION_LOGIC_TAG
108
+ Tag for aggregation if --parent-collection-logic is set to TAG
109
+ --latest-depth LATEST_DEPTH
110
+ Number of trailing project path elements to mark as LATEST (defaults to 1 - _only the leaf element_).<br/>_Only supported on DT >= 4.12.0_
111
+
112
+ SBOM management:
113
+ -m, --merge Merge all SBOM files into one
114
+ -o MERGE_OUTPUT, --merge-output MERGE_OUTPUT
115
+ Output merged SBOM file (only used with merge enabled) - for debugging purpose
116
+ -l PURL_MAX_LEN, --purl-max-len PURL_MAX_LEN
117
+ PURLs max length (-1: auto, 0: no trim, >0: trim to size - default: -1)
118
+
119
+ VEX:
120
+ -U, --upload-vex Upload VEX file after SBOM analysis (requires VULNERABILITY_ANALYSIS permission). The VEX file(s) are resolved based on the sbom pattern(s). The first part of the SBOM file name is used
121
+ to match it with a VEX file (e.g. if there is an SBOM file 'example.cyclonedx.json', the corresponding VEX file name must be 'example.vex.json')
122
+ -V, --merged-vex-file MERGED_VEX_FILE
123
+ The VEX file to upload if multiple SBOMS are merged (--merge). Can only be used with --upload-vex and --merge.
124
+
125
+ Miscellaneous:
126
+ -S, --show-findings Wait for analysis and display found vulnerabilities
127
+ -R RISK_SCORE_THRESHOLD, --risk-score-threshold RISK_SCORE_THRESHOLD
128
+ Risk score threshold to fail the scan (<0: disabled - default: -1)
129
+
130
+ ```
131
+
132
+ ### Arguments
133
+
134
+ `dt-sbom-scanner` accepts SBOM file patterns to publish (supports glob patterns) as multiple positional arguments.
135
+
136
+ If none is specified, the program will look for SBOM files matching `**/*.cyclonedx.json` and `**/*.cyclonedx.xml`.
137
+
138
+ ### Options
139
+
140
+ #### Dependency Track connection
141
+
142
+ | CLI option | Env. Variable | Description |
143
+ | ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ |
144
+ | `-u` / `--base-api-url` | `$DEPTRACK_BASE_API_URL` | Dependency Track server base API url (includes `/api`) (**mandatory**) |
145
+ | `-k` / `--api-key` | `$DEPTRACK_API_KEY` | Dependency Track API key (**mandatory**) |
146
+ | `-i` / `--insecure` | `$DEPTRACK_INSECURE` | Skip SSL verification |
147
+
148
+ #### Project selection and settings
149
+
150
+ | CLI option | Env. Variable | Description |
151
+ | ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ |
152
+ | `-p` / `--project-path` | `$DEPTRACK_PROJECT_PATH` | Dependency Track target project path to publish SBOM files to (**mandatory**) |
153
+ | `-s` / `--path-separator` | `$DEPTRACK_PATH_SEPARATOR` | Separator to use in project path (default `/`) |
154
+ | `-t` / `--tags` | `$DEPTRACK_TAGS` | Comma separated list of tags to put in the project in `autoCreate` mode |
155
+ | `--parent-collection-logic` | `$DEPTRACK_PARENT_COLLECTION_LOGIC` | Set up how the parent aggregates its direct children (see doc), default is ALL |
156
+ | `--parent-collection-logic-tag` | `$DEPTRACK_PARENT_COLLECTION_LOGIC_TAG` | Tag for aggregation if `--parent-collection-logic` is set to `TAG` |
157
+ | `--latest-depth` | `$DEPTRACK_LATEST_DEPTH` | Number of trailing project path elements to mark as LATEST (defaults to 1 - _only the leaf element_).<br/>_Only supported on DT >= 4.12.0_ |
158
+
159
+
160
+ #### SBOM options
161
+
162
+ | CLI option | Env. Variable | Description |
163
+ | ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
164
+ | `-m` / `--merge` | `$DEPTRACK_MERGE` | Merge all SBOM files into one (default `false`) |
165
+ | `-o` / `--merge-output` | `$DEPTRACK_MERGE_OUTPUT` | Output merged SBOM file (only used with merge enabled) - for debugging purpose |
166
+ | `-l` / `--purl-max-len` | `$DEPTRACK_PURL_MAX_LEN` | PURLs max length (`-1`: auto, `0`: no trim, `>0`: trim to size - default: `-1`) |
167
+
168
+ #### VEX
169
+
170
+ | CLI option | Env. Variable | Description |
171
+ | -------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
172
+ | `-U` / `--upload-vex` | `$DEPTRACK_UPLOAD_VEX` | Upload VEX file after SBOM analysis (requires VULNERABILITY_ANALYSIS permission). The VEX file(s) are resolved based on the sbom pattern(s). The first part of the SBOM file name is used to match it with a VEX file (e.g. if there is an SBOM file 'example.cyclonedx.json', the corresponding VEX file name must be 'example.vex.json') |
173
+ | `-V` / `--merged-vex-file` | `$DEPTRACK_MERGED_VEX_FILE` | The VEX file to upload if multiple SBOMS are merged (--merge). Can only be used with --upload-vex and --merge. |
174
+
175
+ #### Miscellaneous
176
+
177
+ | CLI option | Env. Variable | Description |
178
+ | ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ |
179
+ | `-S` / `--show-findings` | `$DEPTRACK_SHOW_FINDINGS` | Wait for analysis and display found vulnerabilities |
180
+ | `-R` / `--risk-score-threshold` | `$DEPTRACK_RISK_SCORE_THRESHOLD` | Risk score threshold to fail the scan (`<0`: disabled - default: `-1`) |
181
+
182
+ ## API Key permissions
183
+
184
+ - In order to be able to publish SBOM files to the Dependency Track server, the `BOM_UPLOAD` permission is **mandatory**.
185
+ - The extra `PROJECT_CREATION_UPLOAD` permission is required if you want to automatically create the project while uploading the SBOM files if the project does not exist (but the parent project must exist).
186
+ - The extra `VIEW_VULNERABILITY` and `VIEW_PORTFOLIO` permissions are required if you want to display found vulnerabilities or compute risk score after SBOM analysis.<br/>
187
+ Granting those permissions without enabling [Portfolio ACLs](https://github.com/DependencyTrack/dependency-track/issues/1127) is not recommended in the general case as give a read access to all projects.
188
+ - The extra `VIEW_PORTFOLIO` and `PORTFOLIO_MANAGEMENT` permissions are required if you want to automatically create one or several project ancestors prior to uploading the SBOM files.<br/>
189
+ Granting those permissions is not recommended in the general case as they virtually give administration rights to the API Key owner.
190
+ - The extra `VULNERABILITY_ANALYSIS` permission is required if you want to upload VEX files after SBOM analysis.
191
+
192
+ ## Project Path
193
+
194
+ Whenever a SBOM file is found, `dt-sbom-scanner` uploads it to the Dependency Track server under a certain project.
195
+ The target project is determined by evaluating the `--project-path` CLI option (or `$DEPTRACK_PROJECT_PATH` variable).
196
+
197
+ The project path is a sequence of elements separated by forward slashes `/` (although the separator is also configurable with the `--path-separator` CLI option).
198
+ Each element is expected to be one of the following:
199
+
200
+ 1. `#11111111-1111-1111-1111-111111111111`: a project [Universally Unique Identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) (starting with a hash `#`)
201
+ 2. `project-name@version`: a **project name** and a **version** (separated with a `@`)
202
+ 3. `project-name`: a **project name** only (empty version)
203
+
204
+ Here is the project path regular grammar:
205
+
206
+ ```
207
+ <path> -> <element> '/' <path> | element
208
+ <element> -> <name> '@' <version> | <name> | '#' <UUID>
209
+ <name> -> [a-zA-Z0-9_-.]+
210
+ <version> -> [a-zA-Z0-9_-.]*
211
+ <UUID> -> [a-fA-F0-9]{8} '-' [a-fA-F0-9]{4} '-' [a-fA-F0-9]{4} '-' [a-fA-F0-9]{4} '-' [a-fA-F0-9]{12}
212
+ ```
213
+
214
+ Lastly, the project path supports some **expressions**, that will be dynamically replaced when being evaluated:
215
+
216
+ | Expression | Description |
217
+ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
218
+ | `{file_prefix}` | SBOM filename prefix (before the first dot).<br/>Ex: when processing the file `reports/docker-sbom.cyclonedx.json`, `{file_prefix}` will be `docker-sbom`. |
219
+ | `{sbom_name}` | `Metadata > Component > Name` info extracted from the SBOM file (json or xml) |
220
+ | `{sbom_version}` | `Metadata > Component > Version` info extracted from the SBOM file (json or xml) |
221
+ | `{sbom_type}` | `Metadata > Component > Type` info extracted from the SBOM file (json or xml) |
222
+
223
+ Project path examples:
224
+
225
+ - `#550e8400-e29b-41d4-a716-446655440000`: every SBOM found will be published to the project with UUID `550e8400-e29b-41d4-a716-446655440000`<br/>
226
+ :information_source: as Dependency Track is only able to store one SBOM per project, this configuration is suitable only if exactly one SBOM file is found (otherwise each one will overwrite the previous one)
227
+ - `my-project@v1.1.0`: every SBOM found will be published to the project with name `my-project` and version `v1.1.0`<br/>
228
+ :information_source: depending on your API key permissions, `dt-sbom-scanner` might try to automatically create the project if it doesn't exist<br/>
229
+ :information_source: as in the previous example, this configuration is suitable only if exactly one SBOM file is found
230
+ - `#550e8400-e29b-41d4-a716-446655440000/my-project-{file_prefix}@{sbom_version}`: every SBOM found will be published to a project named `my-project-{file_prefix}` and version `{sbom_version}` (extracted from the SBOM file),
231
+ direct child of project with UUID `550e8400-e29b-41d4-a716-446655440000`<br/>
232
+ :information_source: depending on your API key permissions, `dt-sbom-scanner` might try to automatically create the project if it doesn't exist
233
+ - `acme-program@v2/acme-services@v1.3/acme-user-api@v1.3/acme-user-api-{file_prefix}`: complete project path only defined by project names and versions<br/>
234
+ :information_source: depending on your API key permissions, `dt-sbom-scanner` might try to automatically create the project and its ancestors if they don't exist
235
+
236
+ > :bulb: you may decide to overwrite the path separator (ex: double slash `//`) if you want your project names to contain slashes.
237
+
238
+ ### Project collection logic
239
+
240
+ Since [4.13.0 version](https://docs.dependencytrack.org/changelog/#v4-13-0), Dependency Track supports the concept of [collection project](https://docs.dependencytrack.org/usage/collection-projects/).
241
+ A collection project won't be able to host a SBOM, however it will display all vulnerabilities and policy violations of its children.
242
+ `dt-sbom-scanner` will set the collection logic with the `--parent-collection-logic` optional argument (default value is `ALL`).
243
+
244
+ | `--parent-collection-logic` value | Dependency Track API value | Explanation |
245
+ | -------- | ------------------------------------ | --------------------- |
246
+ | `ALL` | `AGGREGATE_DIRECT_CHILDREN` | Parent project will collect metrics from all its direct children |
247
+ | `TAG` | `AGGREGATE_DIRECT_CHILDREN_WITH_TAG` | Parent project will collect metrics from direct children specified by a tag (which can be different from tags on the parent project itself) |
248
+ | `LATEST` | `AGGREGATE_LATEST_VERSION_CHILDREN` | Parent project will collect metrics from direct children flagged as latest |
249
+ | `NONE` | `NONE` | Parent project will behave like a normal project |
250
+
251
+ :information_source: since `dt-sbom-scanner` does not update existing projects, collection logic will only be configured on the parent project created by `dt-sbom-scanner`
252
+
253
+ See [Dependency Track documentation about collection project](https://docs.dependencytrack.org/usage/collection-projects/) for more details.
254
+
255
+ ## Developers
256
+
257
+ `dt-sbom-scanner` is implemented in Python and relies on [Poetry](https://python-poetry.org/) for its packaging and dependency management.
258
+
259
+ ```bash
260
+ # install dependencies
261
+ poetry install
262
+
263
+ # run from code
264
+ poetry run sbom-scanner \
265
+ --base-api-url http://localhost:8080/api \
266
+ --api-key "$DT_API_KEY" \
267
+ --project-path "my-group/my-project/sub-{file_prefix}" \
268
+ **/*.cyclonedx.json
269
+ ```
270
+
dt_sbom_scanner-1.9.1/README.md ADDED
@@ -0,0 +1,241 @@
1
+ <img alt="Dependency Track SBOM Scanner logo" width="128px" src="https://gitlab.com/to-be-continuous/tools/dt-sbom-scanner/-/avatar">
2
+
3
+ [![pypi](https://img.shields.io/pypi/v/dt-sbom-scanner.svg)](https://pypi.org/project/dt-sbom-scanner/)
4
+ [![python](https://img.shields.io/pypi/pyversions/dt-sbom-scanner.svg)](https://pypi.org/project/dt-sbom-scanner/)
5
+
6
+ # Dependency Track SBOM Scanner
7
+
8
+ This project provides a CLI tool able to publish SBOM files to a [Dependency Track](https://docs.dependencytrack.org/) server.
9
+
10
+ ## Get started
11
+
12
+ ### Run SBOM Scanner as a Python program
13
+
14
+ `dt-sbom-scanner` requires Python 3.12 or higher and can be installed using pip package manager:
15
+
16
+ ```bash
17
+ pip install dt-sbom-scanner
18
+ ```
19
+
20
+ Then it can be run as a Python program:
21
+
22
+ ```bash
23
+ # obtain help
24
+ sbom-scanner --help
25
+
26
+ # run
27
+ sbom-scanner \
28
+ --base-api-url http://localhost:8080/api \
29
+ --api-key "$DT_API_KEY" \
30
+ --project-path "my-group/my-project/sub-{file_prefix}" \
31
+ **/*.cyclonedx.json
32
+ ```
33
+
34
+ ### Run SBOM Scanner CLI as a container
35
+
36
+ `dt-sbom-scanner` can also be run as a container image using Docker or Podman.
37
+
38
+ ```bash
39
+ # run from GitLab Container Registry
40
+ docker run \
41
+ --rm --volume $(pwd):/code --env DEPTRACK_API_KEY \
42
+ registry.gitlab.com/to-be-continuous/tools/dt-sbom-scanner:latest \
43
+ --base-api-url http://host.docker.internal:8080/api \
44
+ --api-key "$DT_API_KEY" \
45
+ --project-path "my-group/my-project/sub-{file_prefix}" \
46
+ **/*.cyclonedx.json
47
+ ```
48
+
49
+ ## Usage
50
+
51
+ ```bash
52
+ usage: sbom-scanner [-h] [-u BASE_API_URL] [-k API_KEY] [-i] [-p PROJECT_PATH] [-s PATH_SEPARATOR] [-t TAGS] [--parent-collection-logic {NONE,ALL,TAG,LATEST}]
53
+ [--parent-collection-logic-tag PARENT_COLLECTION_LOGIC_TAG] [--latest-depth LATEST_DEPTH] [-m] [-o MERGE_OUTPUT] [-l PURL_MAX_LEN] [-U] [-V MERGED_VEX_FILE] [-S] [-R RISK_SCORE_THRESHOLD]
54
+ [sbom_patterns ...]
55
+
56
+ This tool scans for SBOM files and publishes them to a Dependency Track server.
57
+
58
+ positional arguments:
59
+ sbom_patterns SBOM file patterns to publish (supports glob patterns). Default: '**/*.cyclonedx.json **/*.cyclonedx.xml'
60
+
61
+ options:
62
+ -h, --help show this help message and exit
63
+
64
+ Connection to Dependency Track platform:
65
+ -u BASE_API_URL, --base-api-url BASE_API_URL
66
+ Dependency Track server base API url (includes '/api')
67
+ -k API_KEY, --api-key API_KEY
68
+ Dependency Track API key
69
+ -i, --insecure Skip SSL verification
70
+
71
+ Project settings:
72
+ -p PROJECT_PATH, --project-path PROJECT_PATH
73
+ Dependency Track target project path to publish SBOM files to (see doc)
74
+ -s PATH_SEPARATOR, --path-separator PATH_SEPARATOR
75
+ Separator to use in project path (default: '/')
76
+ -t TAGS, --tags TAGS Comma separated list of tags to attach to the project
77
+ --parent-collection-logic {NONE,ALL,TAG,LATEST}
78
+ Set up how the parent aggregates its direct children (ALL: all, TAG: with tag matching --parent-collection-logic-tag, LATEST: flagged as latest, NONE: disable), default is ALL (DT version >= 4.13.0)
79
+ --parent-collection-logic-tag PARENT_COLLECTION_LOGIC_TAG
80
+ Tag for aggregation if --parent-collection-logic is set to TAG
81
+ --latest-depth LATEST_DEPTH
82
+ Number of trailing project path elements to mark as LATEST (defaults to 1 - _only the leaf element_).<br/>_Only supported on DT >= 4.12.0_
83
+
84
+ SBOM management:
85
+ -m, --merge Merge all SBOM files into one
86
+ -o MERGE_OUTPUT, --merge-output MERGE_OUTPUT
87
+ Output merged SBOM file (only used with merge enabled) - for debugging purpose
88
+ -l PURL_MAX_LEN, --purl-max-len PURL_MAX_LEN
89
+ PURLs max length (-1: auto, 0: no trim, >0: trim to size - default: -1)
90
+
91
+ VEX:
92
+ -U, --upload-vex Upload VEX file after SBOM analysis (requires VULNERABILITY_ANALYSIS permission). The VEX file(s) are resolved based on the sbom pattern(s). The first part of the SBOM file name is used
93
+ to match it with a VEX file (e.g. if there is an SBOM file 'example.cyclonedx.json', the corresponding VEX file name must be 'example.vex.json')
94
+ -V, --merged-vex-file MERGED_VEX_FILE
95
+ The VEX file to upload if multiple SBOMS are merged (--merge). Can only be used with --upload-vex and --merge.
96
+
97
+ Miscellaneous:
98
+ -S, --show-findings Wait for analysis and display found vulnerabilities
99
+ -R RISK_SCORE_THRESHOLD, --risk-score-threshold RISK_SCORE_THRESHOLD
100
+ Risk score threshold to fail the scan (<0: disabled - default: -1)
101
+
102
+ ```
103
+
104
+ ### Arguments
105
+
106
+ `dt-sbom-scanner` accepts SBOM file patterns to publish (supports glob patterns) as multiple positional arguments.
107
+
108
+ If none is specified, the program will look for SBOM files matching `**/*.cyclonedx.json` and `**/*.cyclonedx.xml`.
109
+
110
+ ### Options
111
+
112
+ #### Dependency Track connection
113
+
114
+ | CLI option | Env. Variable | Description |
115
+ | ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ |
116
+ | `-u` / `--base-api-url` | `$DEPTRACK_BASE_API_URL` | Dependency Track server base API url (includes `/api`) (**mandatory**) |
117
+ | `-k` / `--api-key` | `$DEPTRACK_API_KEY` | Dependency Track API key (**mandatory**) |
118
+ | `-i` / `--insecure` | `$DEPTRACK_INSECURE` | Skip SSL verification |
119
+
120
+ #### Project selection and settings
121
+
122
+ | CLI option | Env. Variable | Description |
123
+ | ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ |
124
+ | `-p` / `--project-path` | `$DEPTRACK_PROJECT_PATH` | Dependency Track target project path to publish SBOM files to (**mandatory**) |
125
+ | `-s` / `--path-separator` | `$DEPTRACK_PATH_SEPARATOR` | Separator to use in project path (default `/`) |
126
+ | `-t` / `--tags` | `$DEPTRACK_TAGS` | Comma separated list of tags to put in the project in `autoCreate` mode |
127
+ | `--parent-collection-logic` | `$DEPTRACK_PARENT_COLLECTION_LOGIC` | Set up how the parent aggregates its direct children (see doc), default is ALL |
128
+ | `--parent-collection-logic-tag` | `$DEPTRACK_PARENT_COLLECTION_LOGIC_TAG` | Tag for aggregation if `--parent-collection-logic` is set to `TAG` |
129
+ | `--latest-depth` | `$DEPTRACK_LATEST_DEPTH` | Number of trailing project path elements to mark as LATEST (defaults to 1 - _only the leaf element_).<br/>_Only supported on DT >= 4.12.0_ |
130
+
131
+
132
+ #### SBOM options
133
+
134
+ | CLI option | Env. Variable | Description |
135
+ | ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
136
+ | `-m` / `--merge` | `$DEPTRACK_MERGE` | Merge all SBOM files into one (default `false`) |
137
+ | `-o` / `--merge-output` | `$DEPTRACK_MERGE_OUTPUT` | Output merged SBOM file (only used with merge enabled) - for debugging purpose |
138
+ | `-l` / `--purl-max-len` | `$DEPTRACK_PURL_MAX_LEN` | PURLs max length (`-1`: auto, `0`: no trim, `>0`: trim to size - default: `-1`) |
139
+
140
+ #### VEX
141
+
142
+ | CLI option | Env. Variable | Description |
143
+ | -------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
144
+ | `-U` / `--upload-vex` | `$DEPTRACK_UPLOAD_VEX` | Upload VEX file after SBOM analysis (requires VULNERABILITY_ANALYSIS permission). The VEX file(s) are resolved based on the sbom pattern(s). The first part of the SBOM file name is used to match it with a VEX file (e.g. if there is an SBOM file 'example.cyclonedx.json', the corresponding VEX file name must be 'example.vex.json') |
145
+ | `-V` / `--merged-vex-file` | `$DEPTRACK_MERGED_VEX_FILE` | The VEX file to upload if multiple SBOMS are merged (--merge). Can only be used with --upload-vex and --merge. |
146
+
147
+ #### Miscellaneous
148
+
149
+ | CLI option | Env. Variable | Description |
150
+ | ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------ |
151
+ | `-S` / `--show-findings` | `$DEPTRACK_SHOW_FINDINGS` | Wait for analysis and display found vulnerabilities |
152
+ | `-R` / `--risk-score-threshold` | `$DEPTRACK_RISK_SCORE_THRESHOLD` | Risk score threshold to fail the scan (`<0`: disabled - default: `-1`) |
153
+
154
+ ## API Key permissions
155
+
156
+ - In order to be able to publish SBOM files to the Dependency Track server, the `BOM_UPLOAD` permission is **mandatory**.
157
+ - The extra `PROJECT_CREATION_UPLOAD` permission is required if you want to automatically create the project while uploading the SBOM files if the project does not exist (but the parent project must exist).
158
+ - The extra `VIEW_VULNERABILITY` and `VIEW_PORTFOLIO` permissions are required if you want to display found vulnerabilities or compute risk score after SBOM analysis.<br/>
159
+ Granting those permissions without enabling [Portfolio ACLs](https://github.com/DependencyTrack/dependency-track/issues/1127) is not recommended in the general case as give a read access to all projects.
160
+ - The extra `VIEW_PORTFOLIO` and `PORTFOLIO_MANAGEMENT` permissions are required if you want to automatically create one or several project ancestors prior to uploading the SBOM files.<br/>
161
+ Granting those permissions is not recommended in the general case as they virtually give administration rights to the API Key owner.
162
+ - The extra `VULNERABILITY_ANALYSIS` permission is required if you want to upload VEX files after SBOM analysis.
163
+
164
+ ## Project Path
165
+
166
+ Whenever a SBOM file is found, `dt-sbom-scanner` uploads it to the Dependency Track server under a certain project.
167
+ The target project is determined by evaluating the `--project-path` CLI option (or `$DEPTRACK_PROJECT_PATH` variable).
168
+
169
+ The project path is a sequence of elements separated by forward slashes `/` (although the separator is also configurable with the `--path-separator` CLI option).
170
+ Each element is expected to be one of the following:
171
+
172
+ 1. `#11111111-1111-1111-1111-111111111111`: a project [Universally Unique Identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) (starting with a hash `#`)
173
+ 2. `project-name@version`: a **project name** and a **version** (separated with a `@`)
174
+ 3. `project-name`: a **project name** only (empty version)
175
+
176
+ Here is the project path regular grammar:
177
+
178
+ ```
179
+ <path> -> <element> '/' <path> | element
180
+ <element> -> <name> '@' <version> | <name> | '#' <UUID>
181
+ <name> -> [a-zA-Z0-9_-.]+
182
+ <version> -> [a-zA-Z0-9_-.]*
183
+ <UUID> -> [a-fA-F0-9]{8} '-' [a-fA-F0-9]{4} '-' [a-fA-F0-9]{4} '-' [a-fA-F0-9]{4} '-' [a-fA-F0-9]{12}
184
+ ```
185
+
186
+ Lastly, the project path supports some **expressions**, that will be dynamically replaced when being evaluated:
187
+
188
+ | Expression | Description |
189
+ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
190
+ | `{file_prefix}` | SBOM filename prefix (before the first dot).<br/>Ex: when processing the file `reports/docker-sbom.cyclonedx.json`, `{file_prefix}` will be `docker-sbom`. |
191
+ | `{sbom_name}` | `Metadata > Component > Name` info extracted from the SBOM file (json or xml) |
192
+ | `{sbom_version}` | `Metadata > Component > Version` info extracted from the SBOM file (json or xml) |
193
+ | `{sbom_type}` | `Metadata > Component > Type` info extracted from the SBOM file (json or xml) |
194
+
195
+ Project path examples:
196
+
197
+ - `#550e8400-e29b-41d4-a716-446655440000`: every SBOM found will be published to the project with UUID `550e8400-e29b-41d4-a716-446655440000`<br/>
198
+ :information_source: as Dependency Track is only able to store one SBOM per project, this configuration is suitable only if exactly one SBOM file is found (otherwise each one will overwrite the previous one)
199
+ - `my-project@v1.1.0`: every SBOM found will be published to the project with name `my-project` and version `v1.1.0`<br/>
200
+ :information_source: depending on your API key permissions, `dt-sbom-scanner` might try to automatically create the project if it doesn't exist<br/>
201
+ :information_source: as in the previous example, this configuration is suitable only if exactly one SBOM file is found
202
+ - `#550e8400-e29b-41d4-a716-446655440000/my-project-{file_prefix}@{sbom_version}`: every SBOM found will be published to a project named `my-project-{file_prefix}` and version `{sbom_version}` (extracted from the SBOM file),
203
+ direct child of project with UUID `550e8400-e29b-41d4-a716-446655440000`<br/>
204
+ :information_source: depending on your API key permissions, `dt-sbom-scanner` might try to automatically create the project if it doesn't exist
205
+ - `acme-program@v2/acme-services@v1.3/acme-user-api@v1.3/acme-user-api-{file_prefix}`: complete project path only defined by project names and versions<br/>
206
+ :information_source: depending on your API key permissions, `dt-sbom-scanner` might try to automatically create the project and its ancestors if they don't exist
207
+
208
+ > :bulb: you may decide to overwrite the path separator (ex: double slash `//`) if you want your project names to contain slashes.
209
+
210
+ ### Project collection logic
211
+
212
+ Since [4.13.0 version](https://docs.dependencytrack.org/changelog/#v4-13-0), Dependency Track supports the concept of [collection project](https://docs.dependencytrack.org/usage/collection-projects/).
213
+ A collection project won't be able to host a SBOM, however it will display all vulnerabilities and policy violations of its children.
214
+ `dt-sbom-scanner` will set the collection logic with the `--parent-collection-logic` optional argument (default value is `ALL`).
215
+
216
+ | `--parent-collection-logic` value | Dependency Track API value | Explanation |
217
+ | -------- | ------------------------------------ | --------------------- |
218
+ | `ALL` | `AGGREGATE_DIRECT_CHILDREN` | Parent project will collect metrics from all its direct children |
219
+ | `TAG` | `AGGREGATE_DIRECT_CHILDREN_WITH_TAG` | Parent project will collect metrics from direct children specified by a tag (which can be different from tags on the parent project itself) |
220
+ | `LATEST` | `AGGREGATE_LATEST_VERSION_CHILDREN` | Parent project will collect metrics from direct children flagged as latest |
221
+ | `NONE` | `NONE` | Parent project will behave like a normal project |
222
+
223
+ :information_source: since `dt-sbom-scanner` does not update existing projects, collection logic will only be configured on the parent project created by `dt-sbom-scanner`
224
+
225
+ See [Dependency Track documentation about collection project](https://docs.dependencytrack.org/usage/collection-projects/) for more details.
226
+
227
+ ## Developers
228
+
229
+ `dt-sbom-scanner` is implemented in Python and relies on [Poetry](https://python-poetry.org/) for its packaging and dependency management.
230
+
231
+ ```bash
232
+ # install dependencies
233
+ poetry install
234
+
235
+ # run from code
236
+ poetry run sbom-scanner \
237
+ --base-api-url http://localhost:8080/api \
238
+ --api-key "$DT_API_KEY" \
239
+ --project-path "my-group/my-project/sub-{file_prefix}" \
240
+ **/*.cyclonedx.json
241
+ ```
dt_sbom_scanner-1.9.1/dt_sbom_scanner/AnsiColors.py ADDED
@@ -0,0 +1,22 @@
1
+ class AnsiColors:
2
+ BLACK = "\033[0;30m"
3
+ RED = "\033[0;31m"
4
+ GREEN = "\033[0;32m"
5
+ YELLOW = "\033[0;33m"
6
+ BLUE = "\033[0;34m"
7
+ PURPLE = "\033[0;35m"
8
+ CYAN = "\033[0;36m"
9
+ WHITE = "\033[0;37m"
10
+
11
+ HGRAY = "\033[90m"
12
+ HRED = "\033[91m"
13
+ HGREEN = "\033[92m"
14
+ HYELLOW = "\033[93m"
15
+ HBLUE = "\033[94m"
16
+ HPURPLE = "\033[95m"
17
+ HCYAN = "\033[96m"
18
+ HWHITE = "\033[97m"
19
+
20
+ RESET = "\033[0m"
21
+ BOLD = "\033[1m"
22
+ UNDERLINE = "\033[4m"
dt_sbom_scanner-1.9.1/dt_sbom_scanner/__init__.py ADDED
File without changes