Skip to main content

Tutorial: Container image scans with Aqua Trivy

This tutorial shows you how to scan your container images using Aqua Trivy, a popular open-source scanning tool.

In this tutorial, you'll set up a simple orchestration workflow with two steps:

  1. A Background step that runs Docker-in-Docker as a service. This is required for any orchestrated or dataload scan of a container image.

  2. An Aqua-Trivy step that runs the scan and ingests the results into STO.


Set up your pipeline

Do the following:

  1. Select Security Testing Orchestration (left menu, top) > Pipelines > Create a Pipeline. Enter a name and click Start.

  2. In the new pipeline, select Add stage > Security.

  3. Set up your stage as follows:

    1. Enter a Stage Name.

    2. Disable Clone Codebase. You don't need a code repository for this tutorial.

  4. In the Pipeline Editor, go to Infrastructure and select Cloud, Linux, and AMD64 for the infrastructure, OS, and architecture.

    You can also use a Kubernetes or Docker build infrastructure, but these require additional work to set up. For more information, go to Set up a build infrastructure for STO.


The following step is required only for Kubernetes or Docker infrastructures. If you're using Harness Cloud, go to Add the Aqua-Trivy scan step.

Add a Docker-in-Docker background step

The following use cases require a Docker-in-Docker background step in your pipeline:

  • Container image scans on Kubernetes and Docker build infrastructures
  • Custom Scan steps on Kubernetes and Docker build infrastructures
    • Required for all target types and Orchestration/DataLoad modes

The following use cases do not require a Docker-in-Docker background step:

  • Harness Cloud AMD64 build infrastructures
  • SAST/DAST/configuration scans that use a scanner-specific step and not a Custom Scan step.
  • Ingestion scans where the data file has already been generated
Set up a Docker-in-Docker background step
  1. Go to the stage where you want to run the scan.

  2. In Overview, add the shared path /var/run.

  3. In Execution, do the following:

    1. Click Add Step and then choose Background.
    2. Configure the Background step as follows:
      1. Dependency Name = dind

      2. Container Registry = The Docker connector to download the DinD image. If you don't have one defined, go to Docker connector settings reference.

      3. Image = docker:dind

      4. Under Entry Point, add the following: dockerd

        In most cases, using dockerd is a faster and more secure way to set up the background step. For more information, go to the TLS section in the Docker quick reference.

        If the DinD service doesn't start with dockerd, clear the Entry Point field and then run the pipeline again. This starts the service with the default entry point.

      5. Under Additional Configuration, select the Privileged checkbox.

Configure the background step

Add the Aqua-Trivy scan step

Add an Aqua Trivy step to your pipeline after the DinD background step and configure it as follows:

  1. Scan Mode = Orchestration

  2. Target name — Click the Value Selector button on the right side of the input field and select Runtime Input.

  3. Target variant — Select Runtime Input.

  4. Container image Type = Docker v2

  5. Container image Domain =

  6. Container image name — Select Runtime Input.

  7. Container image tag — Select Runtime Input.

  8. Fail on Severity = Critical

Run the pipeline and check your results

  1. In the Pipeline Studio, select Run (top right).

  2. When prompted, enter your runtime inputs.

    • Under Target, enter the target name and variant.

    • Under Image, enter the [image name] and [tag] you want to use. In most cases, you want to use the repository for the target and the branch for the variant.

    If you're scanning the codebase for the first time, enter the root branch of your repo. This is usually the main or master branch.

    If you're scanning the example image mentioned above, enter snyklabs/goof for the target and image name, and latest for the target variant and image tag.

  3. Run the pipeline and then wait for the execution to finish.

    If you used the example image, you'll see that the pipeline failed for an entirely expected reason: you configured the Trivy step to fail the pipeline if the scan detected any critical vulnerabilities. The final log entry for the Semgrep step reads: Exited with message: fail_on_severity is set to critical and that threshold was reached.

    pipeline failed, critical issues found

  4. Select Security Tests and examine any issues detected by your scan.

    view scan results

Specify the baseline


It is good practice to specify a baseline for every target. Defining a baseline makes it easy for developers to drill down into "shift-left" issues in downstream variants and security personnel to drill down into "shift-right" issues in the baseline.

  1. Select Test Targets (left menu).

  2. Select the baseline you want for your target.

set the baseline

YAML pipeline example

Here's an example of the pipeline you created in this tutorial. If you copy this example, replace the placeholder values with appropriate values for your project, organization, and connectors.

name: tutorial-test-container-image-scan-v1
identifier: tutorialtestcontainerimagescanv1
projectIdentifier: YOUR_HARNESS_PROJECT_ID
tags: {}
- stage:
name: scan_image
identifier: scan_image
description: ""
type: SecurityTests
cloneCodebase: false
os: Linux
arch: Amd64
type: Cloud
spec: {}
- step:
type: Background
name: background_dind
identifier: background_dind
image: docker:dind
shell: Sh
- dockerd
- step:
type: AquaTrivy
name: scan_image
identifier: scan_image
mode: orchestration
config: default
name: <+input>
type: container
variant: <+input>
level: info
fail_on_severity: critical
privileged: true
type: docker_v2
name: <+input>
tag: <+input>
format: spdx-json
enabled: false
paths: []
enabled: false
- /var/run