From b9f59bb778d92256866fd21705060db22c4bf2ae Mon Sep 17 00:00:00 2001
From: Wes Dean <wdean@flexion.us>
Date: Fri, 1 Mar 2024 13:08:34 -0500
Subject: [PATCH] Update docs with runtime, CLI flags

---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 54 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 84a660f..68d63d0 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,37 @@
 # Upload Sarif results to Defect Dojo
 
+## Quickstart
+
+This should get you started:
+
+```bash
+export DD_TOKEN="${DEFECT_DOJO_AUTH_TOKEN}"
+curl -s \
+  - o './upload_sarif_to_defectdojo.bash' \
+  -L 'https://raw.githubusercontent.com/wesley-dean-flexion/upload-sarif-to-defectdojo/main/upload_sarif_to_defectdojo.bash'
+./upload_sarif_to_defectdojo.bash \
+  -p "${PRODUCT}" \
+  -e "${ENGAGEMENT}" \
+  -s "${DEFECT_DOJO_SERVER}" \
+  /path/to/SARIF/files/*.sarif
+ ```
+
+The script can be...
+
+* downloaded at runtime ([raw script link](https://raw.githubusercontent.com/wesley-dean-flexion/upload-sarif-to-defectdojo/main/upload_sarif_to_defectdojo.bash))
+* pulled from [GHCR](https://github.com/wesley-dean-flexion/upload-sarif-to-defectdojo/pkgs/container/upload-sarif-to-defectdojo)
+* pulled from [DockerHub](https://hub.docker.com/r/wesleydeanflexion/upload-sarif-to-defectdojo)
+
 ## Overview
 
 This is a shell script that will iterate across a series of filenames
 passed in and upload the results to a DefectDojo instance.  This
-hope is to have one process generate SARIF results (e.g., Megalinter)
-so that this script can upload the results.
+hope is to have one process generate SARIF results (e.g.,
+[Megalinter](https://megalinter.io/))
+so that this script can upload the results.  The original intent of
+this script was to upload SARIF-formatted reports produced by
+[Megalinter](https://megalinter.io/), but it can work with any
+tool that produces SARIF output (e.g., `semgrep --sarif`).
 
 There exist actions in the GitHub Actions Marketplace that will
 upload SARIF results to DefectDojo, such as:
@@ -99,24 +125,34 @@ docker run \
 
 ### DD_TOKEN
 
-`DD_TOKEN` is authentication token for interacting with DefectDojo (required)
+`DD_TOKEN` is authentication token for interacting with DefectDojo (required).
+
+**DD_TOKEN is required!!**
 
 The API token may be found throught DefectDojo's web user interface
 by going to `<server name>/api/key-v2`
 
+Note: there is no CLI argument to pass the token via the command line as
+doing so may result in the token being stored in the shell's history;
+it must be passed via environment variable or configuration file.
+
 ### DD_PRODUCT
 
 `DD_PRODCT` is name of the product in DefectDojo (required)
 
+**DD_PRODUCT is required!!***
+
 ### DD_ENGAGEMENT
 
-`DD_ENGAGEMENT` is name of the engagement in DefectDojo
+`DD_ENGAGEMENT` is name of the engagement in DefectDojo.
 
 The default value is "cicd" (lowercase, no slash).
 
+Set via CLI with `-e` or `--engagement`
+
 ### DD_SERVER_PROTO
 
-`DD_SERVER_PROTO` is the protocol / scheme to use when talking to DefectDojo
+`DD_SERVER_PROTO` is the protocol / scheme to use when talking to DefectDojo.
 
 The default value is `https`.
 
@@ -124,6 +160,8 @@ The default value is `https`.
 
 `DD_SERVER_HOST` is the hostname of the DefectDojo server (required)
 
+Set via CLI with `-s` or `--server`
+
 ### DD_SERVER_PATH
 
 `SS_SERVER_PATH` is path on the server to the import-scan API endpoint
@@ -139,10 +177,14 @@ DefectDojo accepts ISO-8601 dates (but just year, month, and day)
 for when scans took place; the default value is when the file being
 uploaded was last modified
 
-### DD_MINIMUM_SEVERITY
+Set via CLI with `-d` or `--date`
+
+### DD_MINIMUM_SEVERITY (-s)
 
 `DD_MINIMUM_SEVERITY` IS minimum severity level to be imported
 
+Set via CLI with `-S` or `--severity`.
+
 The default value is 'Info'; values may be:
 
 * Info
@@ -167,6 +209,8 @@ The default value is 'true'
 
 `DD_SCAN_TYPE` is the type of scan results to be imported
 
+Set via CLI with `-t` or --scan-type`
+
 The default value is determined by the file's extension
 
 ### DD_CLOSE_OLD_FINDINGS
@@ -199,12 +243,16 @@ will always be grouped
 
 `DD_FILE_TYPE` is the MIME type for the file to be uploaded
 
+Set via CLI with `-m` or `--mime`
+
 The default value is determined by the file's extension
 
 ### DD_BRANCH
 
 `DD_BRANCH` is the SCM branch where the finding was applicable
 
+Set via CLI with `-b` or `--branch`
+
 This is an optional field with no default
 
 ### DD_COMMIT_HASH