ROX-24175: vuln-mgmt export API examples (#100)

* ROX-24175: vuln-mgmt export API examples

* address feedback

Author: stehessel

vulnerability-management/export-workloads/README.md

@@ -0,0 +1,54 @@
+# Export workload vulnerabilities via shell script
+
+The `/v1/export/vuln-mgmt/workloads` API exports workload vulnerabilities in the form
+of deployments and their associated images including image vulnerabilities.
+
+The following sections provide use case examples utilizing either the shell or Python.
+
+## Shell script
+
+See `export-workloads.sh` for a shell script example based on `curl` and `jq`.
+
+### Export all workloads
+```shell
+export-workloads.sh
+```
+
+### Export all workloads from the cluster `prod`
+```shell
+export-workloads.sh "Cluster%3Aprod"
+```
+
+### Export all workloads matching the query `Deployment:app Namespace:default`
+```shell
+export-workloads.sh "Deployment%3Aapp%2BNamespace%3Adefault"
+```
+
+### Export all workloads with a timeout of 60 seconds
+```shell
+export-workloads.sh "" 60
+```
+
+## Python script
+
+See `export-workloads.py` for a python script example.
+
+### Export all workloads
+```shell
+export-workloads.py
+```
+
+### Export all workloads from the cluster `prod`
+```shell
+export-workloads.py --query="Cluster%3Aprod"
+```
+
+### Export all workloads matching the query `Deployment:app Namespace:default`
+```shell
+export-workloads.py --query="Deployment%3Aapp%2BNamespace%3Adefault"
+```
+
+### Export all workloads with a timeout of 60 seconds
+```shell
+export-workloads.py --timeout=60
+```

vulnerability-management/export-workloads/export-workloads.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python
+
+# This script pulls workload vulnerabilities in the form of deployments and their
+# associated images including image vulnerabilities.
+#
+# The output is streamed to STDOUT as a series of Python objects with the schema
+#
+# {"result": {"deployment": {...}, "images": [...]}}
+# ...
+# {"result": {"deployment": {...}, "images": [...]}}
+#
+# Further processing may be done on the parsed objects.
+#
+# Requires ROX_ENDPOINT and ROX_API_TOKEN environment variables.
+# The API token requires read access on images and deployments.
+
+import argparse
+import json
+import os
+import requests
+
+parser = argparse.ArgumentParser("export-workloads")
+parser.add_argument("--query", help="query to filter the deployments (default \"\")", default="")
+parser.add_argument("--timeout", help="timeout in seconds (default 0 = no timeout)", default=0, type=int)
+args = parser.parse_args()
+
+endpoint = os.environ["ROX_ENDPOINT"].removeprefix("https://")
+url = f"https://{endpoint}/v1/export/vuln-mgmt/workloads"
+parameters = f"query={args.query}&timeout={args.timeout}"
+headers = {"Authorization": f"Bearer {os.environ['ROX_API_TOKEN']}"}
+
+session = requests.Session()
+with session.get(f"{url}?{parameters}", headers=headers, stream=True) as resp:
+    resp.raise_for_status()
+    for line in resp.iter_lines():
+        if line:
+            # Parse JSON object for further processing. Here we simply print out the content.
+            obj = json.loads(line)
+            print(f"{obj}\n")

vulnerability-management/export-workloads/export-workloads.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+
+# This script pulls workload vulnerabilities in the form of deployments and their
+# associated images including image vulnerabilities.
+#
+# The output is streamed to STDOUT as valid JSON with the schema
+#
+# [
+#   {"result": {"deployment": {...}, "images": [...]}},
+#   ...
+#   {"result": {"deployment": {...}, "images": [...]}}
+# ]
+#
+# Requires ROX_ENDPOINT and ROX_API_TOKEN environment variables.
+# The API token requires read access on images and deployments.
+
+set -euo pipefail
+
+case $1 in
+*help)
+	echo "$0 [query] [timeout]"
+	;;
+esac
+
+if [[ -z "${ROX_ENDPOINT}" ]]; then
+	echo >&2 "ROX_ENDPOINT must be set"
+	exit 1
+fi
+
+if [[ -z "${ROX_API_TOKEN}" ]]; then
+	echo >&2 "ROX_API_TOKEN must be set"
+	exit 1
+fi
+
+endpoint=https://${ROX_ENDPOINT#https://}
+query=$1
+timeout=${2:-0}
+
+curl -sk -H "Authorization: Bearer ${ROX_API_TOKEN}" \
+	"${endpoint}/v1/export/vuln-mgmt/workloads?query=$query&timeout=$timeout" |
+	# Use `jq -nc --slurp` instead for higher throughput but more memory usage.
+	jq -nc --stream "[fromstream(inputs)]"