Refine provider docs (#106)

* arrange architecture docs to reside before adding a provider for more context

Signed-off-by: Alex Goodman <[email protected]>

* add example provider implementation

Signed-off-by: Alex Goodman <[email protected]>

* add development shell

Signed-off-by: Alex Goodman <[email protected]>

* update documentation with more details about provider makeup and configuration

Signed-off-by: Alex Goodman <[email protected]>

* add a developer shell

Signed-off-by: Alex Goodman <[email protected]>

* add .env file support

Signed-off-by: Alex Goodman <[email protected]>

* not formatting of new provider steps

Signed-off-by: Alex Goodman <[email protected]>

* add note about poetry shell session

Signed-off-by: Alex Goodman <[email protected]>

* typo example provider title

Signed-off-by: Alex Goodman <[email protected]>

---------

Signed-off-by: Alex Goodman <[email protected]>

.github/scripts/dev-shell.sh

@@ -0,0 +1,124 @@
+set -euo pipefail
+
+DEV_VUNNEL_PROVIDERS=$@
+GRYPE_CONFIG=$(pwd)/.grype.yaml
+GRYPE_DB_CONFIG=$(pwd)/.grype-db.yaml
+DEV_POETRY_ENV_PATH=$(poetry env info --path)
+
+BOLD="\033[1m"
+UNDERLINE="\033[4m"
+RED="\033[31m"
+MAGENTA="\033[35m"
+RESET="\033[0m"
+
+function step() {
+  echo "${MAGENTA}• $*${RESET} ..."
+}
+
+function title() {
+  echo "${BOLD}$*${RESET}"
+}
+
+function error() {
+  echo "${RED}$*${RESET}"
+}
+
+if [ -z  "$*" ]
+then
+    error "At least one provider must be specified"
+    echo "examples:"
+    echo "   make dev provider=\"nvd\""
+    echo "   make dev providers=\"oracle wolfi\""
+
+    exit 1
+fi
+
+set +u
+if [ -n "${DEV_VUNNEL_SHELL:-}" ]; then
+    error "Already in a vunnel development shell"
+    exit 0
+fi
+set -u
+
+function finish {
+    error "Unable to setup development shell. Bailing..."
+}
+trap finish EXIT
+
+
+title "Entering vunnel development shell..."
+
+if [ -f .env ]; then
+    step "Sourcing .env file"
+    set -o allexport
+    source .env
+    set +o allexport
+fi
+
+step "Configuring with providers: $DEV_VUNNEL_PROVIDERS"
+
+step "Writing grype config: $GRYPE_CONFIG"
+cat << EOF > "$GRYPE_CONFIG"
+check-for-app-update: false
+db:
+  auto-update: false
+  validate-age: false
+  cache-dir: $(pwd)/.cache/grype
+EOF
+export GRYPE_CONFIG
+
+step "Writing grype-db config: $GRYPE_DB_CONFIG"
+cat << EOF > "$GRYPE_DB_CONFIG"
+pull:
+  parallelism: 1
+provider:
+  root: ./data
+  vunnel:
+    executor: local
+    env:
+      GITHUB_TOKEN: \$GITHUB_TOKEN
+      NVD_API_KEY: \$NVD_API_KEY
+  configs:
+EOF
+for provider in $DEV_VUNNEL_PROVIDERS; do
+  echo "    - name: $provider" >> "$GRYPE_DB_CONFIG"
+done
+export GRYPE_DB_CONFIG
+
+step "Activating poetry virtual env: $DEV_POETRY_ENV_PATH"
+source "$DEV_POETRY_ENV_PATH/bin/activate"
+
+pids=""
+
+step "Installing editable version of vunnel"
+pip install -e . > /dev/null &
+pids="$pids $!"
+
+step "Building grype"
+make build-grype &
+pids="$pids $!"
+
+step "Building grype-db"
+make build-grype-db &
+pids="$pids $!"
+
+wait $pids
+
+export PATH=${DEV_VUNNEL_BIN_DIR}:$PATH
+export DEV_VUNNEL_SHELL=true
+
+echo
+echo "Note: development builds ${UNDERLINE}grype${RESET} and ${UNDERLINE}grype-db${RESET} are now available in your path."
+echo "To update these builds run '${UNDERLINE}make build-grype${RESET}' and '${UNDERLINE}make build-grype-db${RESET}' respectively."
+echo "To run your provider and update the grype database run '${UNDERLINE}make update-db${RESET}'."
+echo "Type '${UNDERLINE}exit${RESET}' to exit the development shell."
+
+# we were able to setup everything, no need to detect failures from this point on...
+trap - EXIT
+
+$SHELL
+
+unset DEV_VUNNEL_SHELL
+unset DEV_VUNNEL_PROVIDERS
+
+title "Exiting vunnel development shell 👋"

.github/scripts/update-dev-db.sh

@@ -0,0 +1,38 @@
+set -euo pipefail
+
+BIN_DIR=./bin
+GRYPE=${BIN_DIR}/grype
+GRYPE_DB=${BIN_DIR}/grype-db
+
+BOLD="\033[1m"
+RED="\033[31m"
+MAGENTA="\033[35m"
+RESET="\033[0m"
+
+function step() {
+  echo "${MAGENTA}• $*${RESET} ..."
+}
+
+function title() {
+  echo "${BOLD}$*${RESET}"
+}
+
+function error() {
+  echo "${RED}$*${RESET}"
+}
+
+step "Updating vunnel providers"
+${GRYPE_DB} pull -v
+
+rm -rf build
+
+step "Building grype-db"
+${GRYPE_DB} build
+
+step "Packaging grype-db"
+${GRYPE_DB} package
+GRYPE_DB_TAR=build/grype-db.tar.gz
+mv build/vulnerability-db_*.tar.gz ${GRYPE_DB_TAR}
+
+step "Importing DB into grype"
+${GRYPE} db import ${GRYPE_DB_TAR}

.gitignore

@@ -1,8 +1,15 @@
 .vunnel.yaml
+.grype-db.yaml
+.grype.yaml
+.grype
+.grype-db
+
+/bin
 /data/
 /backup/
 .pytype/
 .wily/
+.cache/
 
 /.tmp/
 CHANGELOG.md
@@ -120,6 +127,7 @@ ENV/
 .DS_Store
 
 .pytest_cache
+.ruff_cache
 
 dropin.cache