chore(readme): Add usage examples to security actions

Kong · Apr 9, 2024 · 2370eea · 2370eea
1 parent 1f09c6f
commit 2370eea
Show file tree

Hide file tree

Showing 3 changed files with 154 additions and 81 deletions.
diff --git a/security-actions/sca/README.md b/security-actions/sca/README.md
@@ -127,6 +127,38 @@
 
 #### Usage Examples
 
-Refer [directory-scan](./github/workflows/dir-scan.yml) for scanning non-docker files / paths
-
-Refer [docker-image-scan](./github/workflows/docker-image-scan.yml) for scanning docker images / docker tar
+For scanning filesystem directories / paths:
+
+```yml
+name: SCA Repository Scan
+
+on:
+  pull_request:
+    branches:
+    - main
+  push:
+    branches:
+    - main
+    tags:
+    - '*'
+
+jobs:
+  sca:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: read
+      checks: write
+      pull-requests: write
+    name: Repository Scan
+    steps:
+        - uses: actions/checkout@v4
+        - name: Scan Repository
+          id: sca_repo
+          uses: Kong/public-shared-actions/security-actions/sca@main
+          with:
+            asset_prefix: <repo-name-slug> #output files prefix
+            dir: '.' # Path to directory where the repository is checked out
+            config: .syft.yaml # Custom config for overrides in repository root
+            fail_build: 'true' # Fail job if critical vulnerabilities are detected
+```
diff --git a/security-actions/scan-docker-image/README.md b/security-actions/scan-docker-image/README.md
@@ -125,6 +125,72 @@
 
 #### Usage Examples
 
-Refer [directory-scan](./github/workflows/dir-scan.yml) for scanning non-docker files / paths
-
-Refer [docker-image-scan](./github/workflows/docker-image-scan.yml) for scanning docker images / docker tar
+```yml
+name: SCA Docker Image Manifest
+
+on:
+  pull_request:
+    branches:
+    - main
+  push:
+    branches:
+    - main
+    tags:
+    - '*'
+
+jobs:
+  sca-docker-image:
+    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
+    name: Scan Docker Image
+    runs-on: ubuntu-22.04
+    env:
+      IMAGE: kong/kong-gateway-dev:latest # multi arch image input
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install regctl
+      uses: regclient/actions/regctl-installer@main
+
+    - name: Login to DockerHub
+      if: success()
+      uses: docker/login-action@v3
+      with:
+        username: ${{ secrets.GHA_DOCKERHUB_PULL_USER }}
+        password: ${{ secrets.GHA_KONG_ORG_DOCKERHUB_PUBLIC_TOKEN }}
+
+    - name: Parse Architecture Specific Image Manifest Digests
+      id: image_manifest_metadata
+      run: |
+        manifest_list_exists="$(
+          if regctl manifest get "${IMAGE}" --format raw-body --require-list -v panic &> /dev/null; then
+            echo true
+          else
+            echo false
+          fi
+        )"
+        echo "manifest_list_exists=$manifest_list_exists"
+        echo "manifest_list_exists=$manifest_list_exists" >> $GITHUB_OUTPUT
+
+        amd64_sha="$(regctl image digest "${IMAGE}" --platform linux/amd64 || echo '')"
+        arm64_sha="$(regctl image digest "${IMAGE}" --platform linux/arm64 || echo '')"
+        echo "amd64_sha=$amd64_sha"
+        echo "amd64_sha=$amd64_sha" >> $GITHUB_OUTPUT
+        echo "arm64_sha=$arm64_sha"
+        echo "arm64_sha=$arm64_sha" >> $GITHUB_OUTPUT
+
+    - name: Scan AMD64 Image digest
+      id: sbom_action_amd64
+      if: steps.image_manifest_metadata.outputs.amd64_sha != ''
+      uses: Kong/public-shared-actions/security-actions/scan-docker-image@main
+      with:
+        asset_prefix: kong-gateway-dev-linux-amd64
+        image: ${{env.IMAGE}}@${{ steps.image_manifest_metadata.outputs.amd64_sha }}
+
+    - name: Scan ARM64 Image digest
+      if: steps.image_manifest_metadata.outputs.manifest_list_exists == 'true' && steps.image_manifest_metadata.outputs.arm64_sha != ''
+      id: sbom_action_arm64
+      uses: Kong/public-shared-actions/security-actions/scan-docker-image@main
+      with:
+        asset_prefix: kong-gateway-dev-linux-arm64
+        image: ${{env.IMAGE}}@${{ steps.image_manifest_metadata.outputs.arm64_sha }}
+```
diff --git a/security-actions/sign-docker-image/README.md b/security-actions/sign-docker-image/README.md
@@ -77,80 +77,55 @@ COSIGN_REPOSITORY=kong/notary cosign verify -a repo="Kong/kong-ee" -a workflow="
 
 #### Usage Examples
 
-  ```yaml
+```yaml
   jobs:
-  test-sign-docker-image:
-
-    permissions:
-      contents: read
-      packages: write # needed to upload to packages to registry
-      id-token: write # needed for signing the images with GitHub OIDC Token
-
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
-    name: Test Sign Docker Image
-    runs-on: ubuntu-22.04
-    env:
-      PRERELEASE_IMAGE: kongcloud/security-test-repo-pub:ubuntu_23_10 #particular reason for the choice of image: test multi arch image
-      TAGS: kongcloud/security-test-repo-pub:ubuntu_23_10,kongcloud/security-test-repo:ubuntu_23_10
-    steps:
-
-    - uses: actions/checkout@v3
-
-    - name: Install regctl
-      uses: regclient/actions/regctl-installer@main
-
-    - name: Parse Image Manifest Digest
-      id: image_manifest_metadata
-      run: |
-        manifest_list_exists="$(
-          if regctl manifest get "${PRERELEASE_IMAGE}" --format raw-body --require-list -v panic &> /dev/null; then
-            echo true
-          else
-            echo false
-          fi
-        )"
-        echo "manifest_list_exists=$manifest_list_exists"
-        echo "manifest_list_exists=$manifest_list_exists" >> $GITHUB_OUTPUT
-
-        manifest_sha="$(regctl image digest "${PRERELEASE_IMAGE}")"
-
-        echo "manifest_sha=$manifest_sha"
-        echo "manifest_sha=$manifest_sha" >> $GITHUB_OUTPUT
-
-    - name: Sign Image digest
-      id: sign_image_pre_release
-      if: steps.image_manifest_metadata.outputs.manifest_sha != ''
-      uses: ./security-actions/sign-docker-image
-      with:
-        cosign_output_prefix: ubuntu-23-10
-        signature_registry: kongcloud/security-test-repo-sig-pub
-        tags: ${{ env.TAGS }} 
-        image_digest: ${{ steps.image_manifest_metadata.outputs.manifest_sha }}
-        local_save_cosign_assets: true
-        registry_username: ${{ secrets.GHA_DOCKERHUB_PUSH_USER }}
-        registry_password: ${{ secrets.GHA_KONG_ORG_DOCKERHUB_PUSH_TOKEN }}
-
-    - name: Push Images
-      env:
-        RELEASE_TAG: kongcloud/security-test-repo:v1
-      run: |
-        docker pull ${PRERELEASE_IMAGE}
-        for tag in $RELEASE_TAG; do
-          regctl -v debug image copy ${PRERELEASE_IMAGE} $tag
-        done
-    
-    - name: Sign Image digest
-      id: sign_image_promotion
-      if: steps.image_manifest_metadata.outputs.manifest_sha != ''
-      uses: ./security-actions/sign-docker-image
+    sign-docker-image:
+
+      permissions:
+        contents: read
+        packages: write # needed to upload to packages to registry
+        id-token: write # needed for signing the images with GitHub OIDC Token
+
+      if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
+      name: Sign Docker Image
+      runs-on: ubuntu-22.04
       env:
-        RELEASE_TAG: kongcloud/security-test-repo:v1
-      with:
-        cosign_output_prefix: v1
-        signature_registry: kongcloud/security-test-repo-sig-pub
-        tags: ${{ env.RELEASE_TAG }} 
-        image_digest: ${{ steps.image_manifest_metadata.outputs.manifest_sha }}
-        local_save_cosign_assets: true
-        registry_username: ${{ secrets.GHA_DOCKERHUB_PUSH_USER }}
-        registry_password: ${{ secrets.GHA_DOCKERHUB_PUSH_TOKEN }}
-  ```
+        PRERELEASE_IMAGE: kongcloud/security-test-repo-pub:ubuntu_23_10 # multi arch image input
+      steps:
+
+      - uses: actions/checkout@v3
+
+      - name: Install regctl
+        uses: regclient/actions/regctl-installer@main
+
+      - name: Parse Image Manifest Digest
+        id: image_manifest_metadata
+        run: |
+          manifest_list_exists="$(
+            if regctl manifest get "${PRERELEASE_IMAGE}" --format raw-body --require-list -v panic &> /dev/null; then
+              echo true
+            else
+              echo false
+            fi
+          )"
+          echo "manifest_list_exists=$manifest_list_exists"
+          echo "manifest_list_exists=$manifest_list_exists" >> $GITHUB_OUTPUT
+
+          manifest_sha="$(regctl image digest "${PRERELEASE_IMAGE}")"
+
+          echo "manifest_sha=$manifest_sha"
+          echo "manifest_sha=$manifest_sha" >> $GITHUB_OUTPUT
+
+      - name: Sign Image digest
+        id: sign_image_pre_release
+        if: steps.image_manifest_metadata.outputs.manifest_sha != ''
+        uses: Kong/public-shared-actions/security-actions/sign-docker-image@main
+        with:
+          cosign_output_prefix: ubuntu-23-10
+          signature_registry: kongcloud/security-test-repo-sig-pub # overrides repository to push image signatures; defaults to image repository
+          tags: ${{ env.PRERELEASE_IMAGE }}
+          image_digest: ${{ steps.image_manifest_metadata.outputs.manifest_sha }}
+          local_save_cosign_assets: true
+          registry_username: ${{ secrets.GHA_DOCKERHUB_PUSH_USER }}
+          registry_password: ${{ secrets.GHA_KONG_ORG_DOCKERHUB_PUSH_TOKEN }}
+```