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:
-
A Background step that runs Docker-in-Docker as a service. This is required for any orchestrated or dataload scan of a container image.
-
An Aqua-Trivy step that runs the scan and ingests the results into STO.
-
This tutorial has the following prerequisites:
- A Harness account and STO module license.
- You must have a Security Testing Developer or SecOps role assigned.
- A basic understanding of key STO concepts and good practices is highly recommended. Here are some good resources:
- A connector to the Docker v2-compliant registry with the image you want to scan. This tutorial uses an example image on Docker Hub that contains known vulnerabilities.
Set up your pipeline
Do the following:
-
Select Security Testing Orchestration (left menu, top) > Pipelines > Create a Pipeline. Enter a name and click Start.
-
In the new pipeline, select Add stage > Security Tests.
-
Set up your stage as follows:
-
Enter a Stage Name.
-
Disable Clone Codebase. You don't need a code repository for this tutorial.
-
-
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
- Required for Orchestration and Dataload scan modes
- Security steps (not step palettes) on Kubernetes and Docker build infrastructures
- Required for all target types and Orchestration/DataLoad modes
The following use cases do not require Docker-in-Docker:
- Harness Cloud AMD64 build infrastructures
- SAST/DAST/configuration scans that use scanner templates (not Security steps)
- Ingestion scans where the data file has already been generated
Set up a Docker-in-Docker background step
-
Go to the stage where you want to run the scan.
-
In Overview, add the shared path
/var/run
. -
In Execution, do the following:
-
Click Add Step and then choose Background.
-
Configure the Background step as follows:
-
Dependency Name =
dind
-
Container Registry = The Docker connector to download the DinD image. If you don't have one defined, go to Docker connector settings reference.
-
Image =
docker:dind
-
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.- Under Optional Configuration, select the Privileged checkbox.
-
-
- Visual setup
- YAML setup

Add a Background step to your pipeline and set it up as follows:
- step:
type: Background
name: background-dind-service
identifier: Background_1
spec:
connectorRef: CONTAINER_IMAGE_REGISTRY_CONNECTOR
image: docker:dind
shell: Sh
entrypoint:
- dockerd
privileged: true