Integrate Docker Scout with Artifactory

Table of contents

Integrating Docker Scout with JFrog Artifactory lets you run image analysis automatically on images in Artifactory registries.

Local image analysis

You can analyze Artifactory images for vulnerabilities locally using Docker Desktop or the Docker CLI. You first need to authenticate with JFrog Artifactory using the docker login command. For example:

docker login {URL}

Tip

For cloud-hosted Artifactory you can find the credentials for your Artifactory repository by selecting it in the Artifactory UI and then the Set Me Up button.

Remote image analysis

To automatically analyze images running in remote environments you need to deploy the Docker Scout Artifactory agent. The agent is a standalone service that analyzes images and uploads the result to Docker Scout. You can view the results using the Docker Scout Dashboard.

How the agent works

The Docker Scout Artifactory agent is available as an image on Docker Hub. The agent works by continuously polling Artifactory for new images. When it finds a new image, it performs the following steps:

Pull the image from Artifactory
Analyze the image
Upload the analysis result to Docker Scout

The agent records the Software Bill of Materials (SBOM) for the image, and the SBOMs for all of its base images. The recorded SBOMs include both Operating System (OS)-level and application-level programs or dependencies that the image contains.

Additionally, the agent sends the following metadata about the image to Docker Scout:

The source repository URL and commit SHA for the image
Build instructions
Build date
Tags and digest
Target platforms
Layer sizes

The agent never transacts the image itself, nor any data inside the image, such as code, binaries, and layer blobs.

The agent doesn't detect and analyze pre-existing images. It only analyzes images that appear in the registry while the agent is running.

Deploy the agent

This section describes the steps for deploying the Artifactory agent.

Prerequisites

Before you deploy the agent, ensure that you meet the prerequisites:

The server where you host the agent can access the following resources over the network:
- Your JFrog Artifactory instance
- hub.docker.com, port 443, for authenticating with Docker
- api.dso.docker.com, port 443, for transacting data to Docker Scout
The registries are Docker V2 registries. V1 registries aren't supported.

The agent supports all versions of JFrog Artifactory and JFrog Container Registry.

Create the configuration file

You configure the agent using a JSON file. The agent expects the configuration file to be in /opt/artifactory-agent/data/config.json on startup.

The configuration file includes the following properties:

Property	Description
`agent_id`	Unique identifier for the agent.
`docker.organization_name`	Name of the Docker organization.
`docker.username`	Username of the admin user in the Docker organization.
`docker.pat`	Personal access token of the admin user with read and write permissions.
`artifactory.base_url`	Base URL of the Artifactory instance.
`artifactory.username`	Username of the Artifactory user with read permissions that the agent will use.
`artifactory.password`	Password or API token for the Artifactory user.
`artifactory.image_filters`	Optional: List of repositories and images to analyze.

If you don't specify any repositories in artifactory.image_filters, the agent runs image analysis on all images in your Artifactory instance.

The following snippet shows a sample configuration:

{
  "agent_id": "acme-prod-agent",
  "docker": {
    "organization_name": "acme",
    "username": "mobythewhale",
    "pat": "dckr_pat__dsaCAs_xL3kNyupAa7dwO1alwg"
  },
  "artifactory": [
    {
      "base_url": "https://acme.jfrog.io",
      "username": "acmeagent",
      "password": "hayKMvFKkFp42RAwKz2K",
      "image_filters": [
        {
          "repository": "dev-local",
          "images": ["internal/repo1", "internal/repo2"]
        },
        {
          "repository": "prod-local",
          "images": ["staging/repo1", "prod/repo1"]
        }
      ]
    }
  ]
}

Create a configuration file and save it somewhere on the server where you plan to run the agent. For example, /var/opt/artifactory-agent/config.json.

Run the agent

The following example shows how to run the Docker Scout Artifactory agent using docker run. This command creates a bind mount for the directory containing the JSON configuration file created earlier at /opt/artifactory-agent/data inside the container. Make sure the mount path you use is the directory containing the config.json file.

Important

Use the v1 tag of the Artifactory agent image. Don't use the latest tag as doing so may incur breaking changes.

$ docker run \
  --mount type=bind,src=/var/opt/artifactory-agent,target=/opt/artifactory-agent/data \
  docker/artifactory-agent:v1

Analyzing pre-existing data

By default the agent detects and analyzes images as they're created and updated. If you want to use the agent to analyze pre-existing images, you can use backfill mode. Use the --backfill-from=TIME command line option, where TIME is an ISO 8601 formatted time, to run the agent in backfill mode. If you use this option, the agent analyzes all images pushed between that time and the current time when the agent starts, then exits.

For example:

$ docker run \
  --mount type=bind,src=/var/opt/artifactory-agent,target=/opt/artifactory-agent/data \
  docker/artifactory-agent:v1 --backfill-from=2022-04-10T10:00:00Z

When running a backfill multiple times, the agent won't analyze images that it's already analyzed. To force re-analysis, provide the --force command line flag.

View analysis results

You can view the image analysis results in the Docker Scout Dashboard.

Go to Images page in the Docker Scout Dashboard.

This page displays the Docker Scout-enabled repositories in your organization.
Select the image in the list.
Select the tag.

When you have selected a tag, you're taken to the vulnerability report for that tag. Here, you can select if you want to view all vulnerabilities in the image, or vulnerabilities introduced in a specific layer. You can also filter vulnerabilities by severity, and whether or not there's a fix version available.