* In order to be able to publish SBOM files to the Dependency Track server, the `BOM_UPLOAD` permission is mandatory.
* 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).
* The extra `VIEW_PORTFOLIO` and `PORTFOLIO_MANAGEMENT` permission are required if you want to automatically create one or several project ancestors prior to uploading the SBOM files.
- In order to be able to publish SBOM files to the Dependency Track server, the `BOM_UPLOAD` permission is **mandatory**.
- 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).
- 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/>
Granting those permissions is not recommended in the general case as they virtually give administration rights to the API Key owner.
## Project Path explained
## Project Path
Whenever a SBOM file is found, `sbom-scanner` uploads it to the Dependency Track server under a certain project.
The target project is determined by evaluating the _projectpath_ CLI option.
The target project is determined by evaluating the `--project-path` CLI option (or `$DEPTRACK_PROJECT_PATH` variable).
It is a slash (`/`) separated string, each part being of one the following forms:
The project path is a sequence of elements separated by forward slashes `/` (although the separator is also configurable with the `--path-separator` CLI option).
Each element is expected to be one of the following:
*`#11111111-2222-3333-4444-5555555555` (starts with a `#`): the part is a project UUID
*`project-name@version`: the part designates a project name and version
*`project-name`: the part designates a project name only (empty version)
1.`#11111111-1111-1111-1111-111111111111`: a project [Universally Unique Identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier)(starting with a hash `#`)
2.`project-name@version`: a **project name** and a **version** (separated with a `@`)
3.`project-name`: a **project name** only (empty version)
Lastly, the project path supports the `%{file_prefix}` pattern, that will be dynamically replaced with the SBOM filename prefix (before the first dot).
Ex: when processing the SBOM file `reports/docker-sbom.cyclonedx.json`, the `%{file_prefix}` will be equal to `docker-sbom`.
| `{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`. |
| `{sbom_name}` | `Metadata > Component > Name` info extracted from the SBOM file (json or xml) |
| `{sbom_version}` | `Metadata > Component > Version` info extracted from the SBOM file (json or xml) |
| `{sbom_type}` | `Metadata > Component > Type` info extracted from the SBOM file (json or xml) |
Project path examples:
-`#550e8400-e29b-41d4-a716-446655440000`: every SBOM found will be published to the project with UUID `550e8400-e29b-41d4-a716-446655440000`<br/>
: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)
*`#my-project@v1.1.0`: every SBOM found will be published to the project with name `my-project` and version `v1.1.0`<br/>
-`my-project@v1.1.0`: every SBOM found will be published to the project with name `my-project` and version `v1.1.0`<br/>
:information_source: depending on your API key permissions, `sbom-scanner` might try to automatically create the project if it doesn't exist<br/>
:information_source: as in the previous example, this configuration is suitable only if exactly one SBOM file is found
*`#11111111-2222-3333-4444-5555555555/my-project-%{file_prefix}`: every SBOM found will be published to a project named `my-project-%{file_prefix}`, direct child of project with UUID `11111111-2222-3333-4444-5555555555`<br/>
-`#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),
direct child of project with UUID `550e8400-e29b-41d4-a716-446655440000`<br/>
:information_source: depending on your API key permissions, `sbom-scanner` might try to automatically create the project if it doesn't exist
*`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/>
-`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/>
:information_source: depending on your API key permissions, `sbom-scanner` might try to automatically create the project and its ancestors if they don't exist
> :bulb: you may decide to overwrite the path separator (ex: double slash `//`) if you want your project names to contain slashes.
## Developers
`sbom-scanner` is implemented in Python and relies on [Poetry](https://python-poetry.org/) for its packaging and dependency management.
