Manage Targets

AWS CI/CD

ZeroThreat integrates with AWS CodePipeline to help you run automated security scans during your CI/CD process. This allows you to detect vulnerabilities early and ensure that security checks are part of your build pipeline before deployment.

This guide walks you through the steps to connect your AWS pipeline with ZeroThreat using a buildspec.yml file.

Prerequisites

Before you begin:

  • Make sure your target is verified in ZeroThreat.
  • You have access to an active AWS account.
  • You’re familiar with the basics of AWS CodePipeline and CodeBuild.
  • You’re on the Enterprise plan in ZeroThreat, or any other plan that includes CI/CD features. (The target must also be associated with the subscription). Check the ZeroThreat Plans page for more details.

Step 1: Enable AWS Integration in ZeroThreat

  1. Go to the Targets section in your ZeroThreat dashboard.
  2. Click on the “Continuous Integration” button next to your desired target.
Thumbnail
  1. In the CI/CD settings drawer, enable AWS CI/CD Integration and confirm your selection.
Thumbnail

Once confirmed, a unique ZT_TOKEN will be generated. This token is used to trigger and authorize scans from your AWS pipeline.

Step 2: Choose Scan Settings

  1. Select or create a Scan Profile suitable for your environment.
Thumbnail
  1. If you're scanning authenticated sections of your app, select the appropriate Login Template for authenticated scans.
A scan profile is required for API scans in CI/CD integration. Without it, the integration pipeline cannot start the scan.

Step 3: Add buildspec.yml to Your Project

In your project repository (connected to CodePipeline), add a file named buildspec.yml at the root. This file contains the scan logic that will be executed by AWS CodeBuild.

Use the below buildspec.yml:

version: 0.2

phases:
  install:
    runtime-versions:
      python: 3.11
    commands:
      - apt-get update && apt-get install -y curl jq

  pre_build:
    commands:
      - |
        set -e

        if [ -z "$ZT_TOKEN" ]; then
          echo "ZT_TOKEN input is required but not provided."
          exit 1
        fi

        ON_PREM_PROXY_API_URL="${ON_PREM_PROXY_API_URL:-}"

        if [ -z "$ON_PREM_PROXY_API_URL" ]; then
          API_BASE_URL="https://api.zerothreat.ai"
          echo "Using ZeroThreat Cloud API."
        else
          API_BASE_URL="${ON_PREM_PROXY_API_URL%/}"

          case "$API_BASE_URL" in
            http://*|https://*) ;;
            *)
              echo "ON_PREM_PROXY_API_URL must start with http:// or https://"
              exit 1
              ;;
          esac

          URL_WITHOUT_PROTOCOL="${API_BASE_URL#http://}"
          URL_WITHOUT_PROTOCOL="${URL_WITHOUT_PROTOCOL#https://}"

          case "$URL_WITHOUT_PROTOCOL" in
            */*|*\?*|*#*)
              echo "ON_PREM_PROXY_API_URL must be the base URL only. Do not include /api or any other path."
              echo "Example: https://test-proxy.com"
              exit 1
              ;;
          esac

          echo "Using ZeroThreat On-Prem API: $API_BASE_URL"
        fi

        export API_BASE_URL

  build:
    commands:
      - echo "Starting security scan..."

      - |
        set -e

        payload=$(jq -n --arg token "$ZT_TOKEN" '{token: $token}')

        response=$(curl -sS -X POST "$API_BASE_URL/api/scan/devops" \
          -H "Content-Type: application/json" \
          -d "$payload")

        status=$(echo "$response" | jq -r '.status')
        code=$(echo "$response" | jq -r '.code')
        message=$(echo "$response" | jq -r '.message')
        url=$(echo "$response" | jq -r '.url')

        if [ "$status" = "200" ]; then
          echo "Scan started successfully."
          echo "Scan Report URL: $url"
        else
          echo "Failed to initiate scan"
          echo "Reason: $message"
          exit 1
        fi

        if [ "$WAIT_FOR_ANALYSIS" = "true" ]; then
          scanStatus=1
          while [ "$scanStatus" -lt 4 ]; do
            sleep 300
            response=$(curl -sS -X GET "$API_BASE_URL/api/scan/devops/$code")
            scanStatus=$(echo "$response" | jq -r '.scanStatus')

            if [ -z "$scanStatus" ] || [ "$scanStatus" = "null" ]; then
              echo "Scan polling failed: invalid status response."
              exit 1
            fi

            if [ "$scanStatus" -ge 4 ]; then
              echo "Scan completed successfully."
              break
            else
              echo "Scan still in progress..."
            fi
          done
        fi

artifacts:
  files:
    - "**/*"
ZT_TOKEN is used to start scan on your target. WAIT_FOR_ANALYSIS determines whether the build waits for the scan to complete. Both should be passed as environment variables (explained below).
For ZeroThreat On-Prem CI/CD Integrations

ON_PREM_PROXY_API_URL is an optional environment variable required only for ZeroThreat On-Prem CI/CD integrations. It is empty by default and is not required for ZeroThreat Cloud users.

If you are using ZeroThreat On-Prem, enter the base URL of your deployed On-Prem instance so AWS CodeBuild can connect to it and trigger scans for internal targets.

ON_PREM_PROXY_API_URL: <your-zerothreat-on-prem-deployed-url>

Do not add /api or any other path at the end. The URL should point to your ZeroThreat On-Prem instance, such as the proxy that routes to localhost:3203.

Correct:   https://test-proxy.com
Incorrect: https://test-proxy.com/api

If ON_PREM_PROXY_API_URL is left empty, the pipeline will use the default ZeroThreat Cloud API.

If you are using ON_PREM_PROXY_API_URL, make sure the deployed On-Prem URL is accessible from AWS CodeBuild and is not restricted to only your internal network.

Step 4: Set Up the AWS Pipeline

  1. Go to AWS CodePipeline and click “Create Pipeline.”
Thumbnail
  1. Use Custom Pipeline, give it a name, and configure general settings as needed.
Thumbnail
  1. Choose and configure general pipelines settings according to your requirement.
Thumbnail
  1. Under Source Provider, select your code source (In our example we will use GitHub).
    Thumbnail
  2. In the Build Stage and Create a new project.
Thumbnail
  1. Now inside Create build project configure project settings as you like.
Thumbnail
  1. Under Buildspec, choose “Use a buildspec file” and set the file name to buildspec.yml.
Thumbnail
  1. Go to the Environment Variables section and add:
  • ZT_TOKEN – (Paste your token generated in Step 1 in ZeroThreat)
  • WAIT_FOR_ANALYSIS – true or false
  • ON_PREM_PROXY_API_URL – Optional. Required only for ZeroThreat On-Prem CI/CD integrations. For ZeroThreat Cloud, leave it empty.
Thumbnail
  1. Optionally continue configuring Test and Deploy stages as needed for your project.
  2. Click “Create Pipeline” to finish setup.
  3. Once your pipeline is set up, every time it is triggered, a new scan will automatically start in ZeroThreat.
Thumbnail

Your AWS pipeline is now integrated with ZeroThreat. Every time your pipeline runs, it will trigger a security scan using the API Collection and target settings you've configured.

You can monitor the scan status and view results in the Scans section of ZeroThreat.