Update docs

takumakume · Aug 25, 2023 · 65563b1 · 65563b1
1 parent 74e01b8
commit 65563b1
Showing 1 changed file with 123 additions and 28 deletions.
diff --git a/README.md b/README.md
@@ -1,35 +1,110 @@
 # sbomreport-to-dependencytrack
 
-Tool to send trivy-operator's SBOM Report to Dependency Track,
-which can receive webhooks from Stdin and TrivyOperator and send them to Dependency Track.
-Project and tags can be generated with templates using SBOM Report values.
+```shell
+Send Aqua Security Trivy Operator's SBOM Report to OWASP Dependency-Track.
+
+two ways to use:
+
+1. command line tool to receive JSON of SBOM Report from stdin
+
+  $ kubectl get sbom hoge -o json | sbomreport-to-dependencytrac
+
+2. http server that receives JSON of SBOM Report from Trivy Operator webhook
+
+  $ sbomreport-to-dependencytrack server --port 80
+
+Templates with the SBOM Report as a variable can be used for the following items to be registered in the Dependency-Track.
+
+  * Project Name
+  * Project Version
+  * Project Tags
+  
+  $ kubectl get sbom hoge -o json | sbomreport-to-dependencytrack \
+      --base-url http://127.0.0.1:8081/ \
+      --api-key 1234567890 \
+      --project-name "[[.sbomReport.report.artifact.repository]]" \                  # e.g. "library/alpine"
+      --project-version "[[.sbomReport.report.artifact.tag]]" \                      # e.g. "3.13.5"
+      --project-tags "tag1,kube_namespace:[[.sbomReport.metadata.namespace]]" # e.g. ["tag1", "kube_namespace:default"]
+
+  For template, go-template and sprig functions can be used.
+  The delimiter of template is "[[" "]]". This is to avoid conflicts with other tools such as Helm.
+
+Environment variables can be used instead of command line arguments, which may be useful when running on Kubernetes.
+
+  $ kubectl get sbom hoge -o json | \
+      DT_BASE_URL=http://127.0.0.1:8081 \
+      DT_API_KEY=1234567890 \
+      DT_PROJECT_NAME="[[.sbomReport.report.artifact.repository]]" \
+      DT_PROJECT_VERSION="[[.sbomReport.report.artifact.tag]]" \
+      DT_PROJECT_TAGS="tag1,kube_namespace:[[.sbomReport.metadata.namespace]]" \
+      sbomreport-to-dependencytrack
+
+Dependency-Track APK key permissions required:
+
+  * BOM_UPLOAD 
+  * PORTFOLIO_MANAGEMENT 
+  * PROJECT_CREATION_UPLOAD 
+  * VIEW_PORTFOLIO 
+```
+
+# Quick start
+
+## Create API key for Dependency-Track
+
+Admin > Access Management > Teams
+
+Permissions:
+
+  * BOM_UPLOAD 
+  * PORTFOLIO_MANAGEMENT 
+  * PROJECT_CREATION_UPLOAD 
+  * VIEW_PORTFOLIO
+
+## case1: command line tool to receive JSON of SBOM Report from stdin
+
+install command
+
+```shell
+$ go install github.com/takumakume/sbomreport-to-dependencytrack@main
+```
+
+run command
 
 ```shell
-# from stdin
-$ kubectl get sbom hoge -o json | sbomreport-to-dependencytrack
-
-# from webhook
-$ sbomreport-to-dependencytrack server --port 80
-
-# set project name, version and tags
-#  - using go template with sprig functions 
-#  - delimiter: "[[" "]]" (no conflict with helm template)
-#  - ".sbomReport" variable: the root of the SBOM Report
-$ kubectl get sbom hoge -o json | sbomreport-to-dependencytrack \
-    --base_url http://localhost:8081 \
-    --api-key 1234567890 \
-    --project-name "[[ .sbomReport.report.artifact.repository ]]"
-    --project-version "[[ .sbomReport.report.artifact.tag ]]"
-    --project-tags "tag1,kube_cluster_name:production,kube_namespace:[[ .sbomReport.report.metadaga.namespace ]]"
-
-# set by environment variables
-$ kubectl get sbom hoge -o json | \
-    DT_BASE_URL=http://localhost:8081 \
-    DT_API_KEY=1234567890 \
-    DT_PROJECT_NAME="[[ .sbomReport.report.artifact.repository ]]" \
-    DT_PROJECT_VERSION="[[ .sbomReport.report.artifact.tag ]]" \
-    DT_PROJECT_TAGS="tag1,kube_cluster_name:production,kube_namespace:[[ .sbomReport.report.metadaga.namespace ]]" \
-    sbomreport-to-dependencytrack
+$ cat testdata/v1alpha1.json | sbomreport-to-dependencytrack \
+      --base-url http://<Dependency-Track API IP address>:<Port>/ \
+      --api-key ********************************* \
+      --project-name "[[.sbomReport.report.artifact.repository]]" \
+      --project-version "[[.sbomReport.report.artifact.tag]]" \
+      --project-tags "tag1,kube_namespace:[[.sbomReport.metadata.namespace]]"
+
+2023/08/25 21:56:54 Uploading BOM: project library/alpine:latest
+2023/08/25 21:56:54 Polling completion of upload BOM: project library/alpine:latest token aa5475a1-ff24-4402-b07b-c622733ea7ba
+2023/08/25 21:56:55 BOM upload completed: project library/alpine:latest token aa5475a1-ff24-4402-b07b-c622733ea7ba
+2023/08/25 21:56:55 Adding tags to project. project library/alpine:latest tags [tag1 kube_namespace:default]
+```
+
+## case2: http server that receives JSON of SBOM Report from Trivy Operator webhook
+
+run server
+
+```shell
+$ docker run -p 80:80 \
+  -e DT_BASE_URL=http://<Dependency-Track API IP address>:<Port>/ \
+  -e DT_API_KEY=********************************* \
+  -e DT_PROJECT_NAME="[[.sbomReport.report.artifact.repository]]" \
+  -e DT_PROJECT_VERSION="[[.sbomReport.report.artifact.tag]]" \
+  -e DT_PROJECT_TAGS="tag1,kube_namespace:[[.sbomReport.metadata.namespace]]" \
+  -it docker.io/takumakume/sbomreport-to-dependencytrack:latest server
+
+2023/08/25 13:05:41 Listening on :80
+
+# Run `curl localhost -X POST -d @testdata/v1alpha1.json`
+
+2023/08/25 22:05:44 Uploading BOM: project library/alpine:latest
+2023/08/25 22:05:44 Polling completion of upload BOM: project library/alpine:latest token 811585ae-39c9-402e-9e79-82e33a3d401d
+2023/08/25 22:05:45 BOM upload completed: project library/alpine:latest token 811585ae-39c9-402e-9e79-82e33a3d401d
+2023/08/25 22:05:45 Adding tags to project. project library/alpine:latest tags [tag1,kube_namespace:default]
 ```
 
 # install
@@ -46,3 +121,23 @@ helm install sbomreport-to-dependencytrack/sbomreport-to-dependencytrack
 # render manifests
 helm template sbomreport-to-dependencytrack/sbomreport-to-dependencytrack
 ```
+
+main settings in values.yaml
+
+```yaml
+config:
+  # Dependency Track API key secret name
+  apiKeySecretName: sbomreport-to-dependencytrack
+  
+  # Dependency Track base URL
+  baseUrl: "http://localhost:8081"
+
+  # Dependency Track project name template
+  projectName: "[[.sbomReport.report.artifact.repository]]"
+  
+  # Dependency Track project version template
+  projectVersion: "[[.sbomReport.report.artifact.tag]]"
+  
+  # Dependency Track project tag template (comma separated)
+  projectTags: ""
+```