docs: Add demo scripts and gif (#75)

Co-authored-by: Ashna Mehrotra <ashnamehrotra@gmail.com>
Co-authored-by: Sertaç Özercan <852750+sozercan@users.noreply.github.com>

README.md

@@ -6,6 +6,10 @@
 
 `copa` is a CLI tool written in [Go](https://golang.org) and based on [buildkit](https://github.com/moby/buildkit) that can be used to directly patch container images given the vulnerability scanning results from popular tools like [Trivy](https://github.com/aquasecurity/trivy).
 
+## Demo
+
+![intro](demo/copa-demo.gif)
+
 ## Why?
 
 We needed the ability to patch containers quickly without going upstream for a full rebuild. As the window between [vulnerability disclosure and active exploitation continues to narrow](https://www.bleepingcomputer.com/news/security/hackers-scan-for-vulnerabilities-within-15-minutes-of-disclosure/), there is a growing operational need to patch critical security vulnerabilities in container images so they can be quickly redeployed into production. The need is especially acute when those vulnerabilities are:

demo/README.md

@@ -0,0 +1,3 @@
+# Demo
+
+This demo leverages work from https://github.com/paxtonhare/demo-magic. Run `copa-demo.sh` from a shell to run the demo. Once complete, you can run `copa-demo-cleanup.sh` to remove outputs from the demo.

demo/copa-demo-cleanup.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+########################
+# include the magic
+########################
+. demo-magic.sh
+
+# hide the evidence
+clear
+
+# Put your stuff here
+pei "docker kill buildkitd"
+pei "docker rmi nginx:1.21.6-patched"
+pei "docker rmi nginx:1.21.6"
+pei "rm nginx.1.21.6.json"

demo/copa-demo.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+########################
+# include the magic
+########################
+. demo-magic.sh
+
+# hide the evidence
+clear
+
+# Put your stuff here
+
+p "Pulling nginx:1.21.6 container image from DockerHub"
+pei "docker pull nginx:1.21.6"
+
+p "Use Trivy to scan the nginx:1.21.6 container image saving the output to nginx.1.21.6.json"
+pei "trivy image --vuln-type os --ignore-unfixed -f json -o nginx.1.21.6.json nginx:1.21.6"
+
+p "Use Trivy to output the number of vulnerabilities in the nginx:1.21.6 container image"
+pei "trivy image --vuln-type os --ignore-unfixed nginx:1.21.6 | grep Total"
+
+p "Run buildkit in a container locally, we'll need it to run copa"
+pei "docker run --detach --rm --privileged -p 127.0.0.1:8888:8888/tcp --name buildkitd --entrypoint buildkitd moby/buildkit:v0.11.4 --addr tcp://0.0.0.0:8888"
+
+p "Confirm the buildkit container is running"
+pei "docker ps"
+
+p "Use copa to patch the nginx:1.21.6 container image outputting the patched container image to nginx:1.21.6-patched"
+pei "copa patch -i docker.io/library/nginx:1.21.6 -r nginx.1.21.6.json -t 1.21.6-patched -a tcp://0.0.0.0:8888"
+
+p "Check that the nginx:1.21.6-patched container image is present locally" 
+pei "docker images"
+
+p "Use Trivy to scan the nginx:1.21.6-patched container image"
+pei "trivy image --vuln-type os --ignore-unfixed nginx:1.21.6-patched | grep Total"
+
+p "Verify that the patched container image runs"
+pei "docker run nginx:1.21.6-patched"
+
+p "Learn more about Copa at - https://github.com/project-copacetic/copacetic" 
+
+

demo/demo-magic.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+
+###############################################################################
+#
+# demo-magic.sh
+#
+# Copyright (c) 2015-2022 Paxton Hare
+#
+# This script lets you script demos in bash. It runs through your demo script
+# when you press ENTER. It simulates typing and runs commands.
+#
+###############################################################################
+
+# the speed to simulate typing the text
+TYPE_SPEED=20
+
+# no wait after "p" or "pe"
+NO_WAIT=false
+
+# if > 0, will pause for this amount of seconds before automatically proceeding with any p or pe
+PROMPT_TIMEOUT=0
+
+# don't show command number unless user specifies it
+SHOW_CMD_NUMS=false
+
+
+# handy color vars for pretty prompts
+BLACK="\033[0;30m"
+BLUE="\033[0;34m"
+GREEN="\033[0;32m"
+GREY="\033[0;90m"
+CYAN="\033[0;36m"
+RED="\033[0;31m"
+PURPLE="\033[0;35m"
+BROWN="\033[0;33m"
+WHITE="\033[0;37m"
+BOLD="\033[1m"
+COLOR_RESET="\033[0m"
+
+C_NUM=0
+
+# prompt and command color which can be overriden
+DEMO_PROMPT="$ "
+DEMO_CMD_COLOR=$BOLD
+DEMO_COMMENT_COLOR=$GREY
+
+##
+# prints the script usage
+##
+function usage() {
+  echo -e ""
+  echo -e "Usage: $0 [options]"
+  echo -e ""
+  echo -e "  Where options is one or more of:"
+  echo -e "  -h  Prints Help text"
+  echo -e "  -d  Debug mode. Disables simulated typing"
+  echo -e "  -n  No wait"
+  echo -e "  -w  Waits max the given amount of seconds before "
+  echo -e "      proceeding with demo (e.g. '-w5')"
+  echo -e ""
+}
+
+##
+# wait for user to press ENTER
+# if $PROMPT_TIMEOUT > 0 this will be used as the max time for proceeding automatically
+##
+function wait() {
+  if [[ "$PROMPT_TIMEOUT" == "0" ]]; then
+    read -rs
+  else
+    read -rst "$PROMPT_TIMEOUT"
+  fi
+}
+
+##
+# print command only. Useful for when you want to pretend to run a command
+#
+# takes 1 param - the string command to print
+#
+# usage: p "ls -l"
+#
+##
+function p() {
+  if [[ ${1:0:1} == "#" ]]; then
+    cmd=$DEMO_COMMENT_COLOR$1$COLOR_RESET
+  else
+    cmd=$DEMO_CMD_COLOR$1$COLOR_RESET
+  fi
+
+  # render the prompt
+  x=$(PS1="$DEMO_PROMPT" "$BASH" --norc -i </dev/null 2>&1 | sed -n '${s/^\(.*\)exit$/\1/p;}')
+
+  # show command number is selected
+  if $SHOW_CMD_NUMS; then
+   printf "[$((++C_NUM))] $x"
+  else
+   printf "$x"
+  fi
+
+  # wait for the user to press a key before typing the command
+  if [ $NO_WAIT = false ]; then
+    wait
+  fi
+
+  if [[ -z $TYPE_SPEED ]]; then
+    echo -en "$cmd"
+  else
+    echo -en "$cmd" | pv -qL $[$TYPE_SPEED+(-2 + RANDOM%5)];
+  fi
+
+  # wait for the user to press a key before moving on
+  if [ $NO_WAIT = false ]; then
+    wait
+  fi
+  echo ""
+}
+
+##
+# Prints and executes a command
+#
+# takes 1 parameter - the string command to run
+#
+# usage: pe "ls -l"
+#
+##
+function pe() {
+  # print the command
+  p "$@"
+  run_cmd "$@"
+}
+
+##
+# print and executes a command immediately
+#
+# takes 1 parameter - the string command to run
+#
+# usage: pei "ls -l"
+#
+##
+function pei {
+  NO_WAIT=true pe "$@"
+}
+
+##
+# Enters script into interactive mode
+#
+# and allows newly typed commands to be executed within the script
+#
+# usage : cmd
+#
+##
+function cmd() {
+  # render the prompt
+  x=$(PS1="$DEMO_PROMPT" "$BASH" --norc -i </dev/null 2>&1 | sed -n '${s/^\(.*\)exit$/\1/p;}')
+  printf "$x\033[0m"
+  read command
+  run_cmd "${command}"
+}
+
+function run_cmd() {
+  function handle_cancel() {
+    printf ""
+  }
+
+  trap handle_cancel SIGINT
+  stty -echoctl
+  eval $@
+  stty echoctl
+  trap - SIGINT
+}
+
+
+function check_pv() {
+  command -v pv >/dev/null 2>&1 || {
+
+    echo ""
+    echo -e "${RED}##############################################################"
+    echo "# HOLD IT!! I require pv for simulated typing but it's " >&2
+    echo "# not installed. Aborting." >&2;
+    echo -e "${RED}##############################################################"
+    echo ""
+    echo -e "${COLOR_RESET}Disable simulated typing: "
+    echo ""
+    echo -e "   unset TYPE_SPEED"
+    echo ""
+    echo "Installing pv:"
+    echo ""
+    echo  "   Mac: $ brew install pv"
+    echo ""
+    echo  "   Other: https://www.ivarch.com/programs/pv.shtml"
+    echo  ""
+    exit 1;
+  }
+}
+
+#
+# handle some default params
+# -h for help
+# -d for disabling simulated typing
+#
+while getopts ":dhncw:" opt; do
+  case $opt in
+    h)
+      usage
+      exit 1
+      ;;
+    d)
+      unset TYPE_SPEED
+      ;;
+    n)
+      NO_WAIT=true
+      ;;
+    c)
+      SHOW_CMD_NUMS=true
+      ;;
+    w)
+      PROMPT_TIMEOUT=$OPTARG
+      ;;
+  esac
+done
+
+##
+# Do not check for pv. This trusts the user to not set TYPE_SPEED later in the
+# demo in which case an error will occur if pv is not installed.
+##
+if [[ -n "$TYPE_SPEED" ]]; then
+  check_pv
+fi