documentation

readme.md

@@ -1,6 +1,96 @@
-# Python Client Packages for the DependencyTrack and DefectDojo API
+# DependencyTrack and DefectDojo Automation
 
-## Download the OpenAPI definitions
+
+## Using
+
+### Distribution
+
+The glue logic comes in a docker image and can be started as a docker container. Due to the dependencies, especially the ones related to the 
+APIs of DependencyTrack and DefectDojo this approach has been chosen.
+
+The image is available at
+
+```
+quay.io/wollud1969/dtrack-defectdojo-automation
+```
+
+and at
+
+```
+devnexus.krohne.com:18079/repository/docker-krohne/dtrack-defectdojo-automation
+```
+
+The tag to be used at the moment is `1.0.5`.
+
+
+
+
+### Start script
+
+On Linux I've created two files to start the beast:
+
+env-sbom-dd-dt
+```
+DTRACK_API_URL=https://dtrack-api-rd.krohne.com
+DEFECTDOJO_URL=https://defectdojo-rd.krohne.com
+DTRACK_TOKEN=...
+DEFECTDOJO_TOKEN=...
+```
+
+The correct values for the tokens must be set here, obviously.
+
+sbom-dd-dt.sh
+```
+#!/bin/bash
+
+docker run -t -v $PWD:/work --rm --env-file ~/env-sbom-dt-dd devnexus.krohne.com:18079/repository/docker-krohne/dtrack-defectdojo-automation:1.0.5 "$@"
+```
+
+I've both files directly in my home-dir.
+
+### File locations
+
+When using the container and the script, you must consider that the container has no full access to your filesystem and you need to mount required parts of your filesystem into the container. In the above script I do this with the option `-v $PWD:/work`. This option mounts the current directory (the one from where you are starting the script and thus the container) into the directory `/work` within the container.
+
+This is required when scanning a directory or uploading a prepared SBOM file.
+
+### Options of the container/script
+
+The container has the glue logic script as entrypoint. To find out about the options, call
+
+```
+dehottgw@DE01RDDEV01:~$ docker run -t -v $PWD:/work --rm --env-file ~/env-sbom-dt-dd devnexus.krohne.com:18079/repository/docker-krohne/dtrack-defectdojo-automation:1.0.5 -- -h
+usage: sbom-dt-dd.py [-h] --name NAME --version VERSION --description DESCRIPTION --type TYPE --classifier
+                     {APPLICATION,FRAMEWORK,LIBRARY,CONTAINER,OPERATING_SYSTEM,DEVICE,FIRMWARE,FILE,PLATFORM,DEVICE_DRIVER,MACHINE_LEARNING_MODEL,DATA}
+                     [--uploadsbom] [--sbomfile SBOMFILE] [--target TARGET] [--verbose]
+sbom-dt-dd.py: error: the following arguments are required: --name/-n, --version/-v, --description/-d, --type/-t, --classifier/-c
+dehottgw@DE01RDDEV01:~$ 
+```
+
+Note the double-dash at the end of the commandline before the `-h`. It is necessary, otherwise the `-h` would be considered as an option for the docker command itself.
+
+
+### SBOM upload example
+
+For this example I've a file `combined-sbom.json` in the directory `software1`:
+
+```
+cd software1/
+~/sbom-dt-dd.sh --name software1-server --version 0.0.1 --description "Server software for the Software1 platform" --type 1 --classifier APPLICATION --uploadsbom --sbomfile /work/combined-sbom.json -V
+```
+
+
+
+
+
+
+
+
+## Building
+
+### Python Client Packages for the DependencyTrack and DefectDojo API
+
+#### Download the OpenAPI definitions
 
 ```
 curl https://dtrack-api.hottis.de/api/openapi.json \
@@ -10,7 +100,7 @@ curl https://defectdojo.hottis.de/api/v2/oa3/schema/?format=json \
 ```
 
 
-## Naive Generation of the Client Package for DefectDojo
+#### Naive Generation of the Client Package for DefectDojo
 
 ```
 docker run \
@@ -28,7 +118,7 @@ docker run \
 
 For DefectDojo the naive code generation works.
 
-## Naive Generation of the Client Package for DependencyTrack
+#### Naive Generation of the Client Package for DependencyTrack
 
 ```
 docker run \
@@ -43,7 +133,7 @@ docker run \
     --package-name dependencytrack_api
 ```
 
-## Fixed Generation of the Client Package for DependencyTrack
+#### Fixed Generation of the Client Package for DependencyTrack
 
 In the OpenAPI definition of DependencyTrack a regex is used which is not understood by Python's
 default regex implement `re`, which in turn is hardwired in the openapi-generator provided code.