Identify compromised images with Terraform Cloud

When you query an image ID from HCP Packer, you want to be confident that it is not compromised or outdated. The data source image validation Terraform Cloud run task scans your Terraform resources for references to hcp_packer_iteration and hcp_packer_image data sources. Once it detects a referenced data resource, it will warn you if it retrieves a revoked image iteration or an image iteration scheduled for revocation. This scanning is available for all HCP Packer users.

Since it relies on the HCP Packer data sources to validate the image IDs, data source image validation supports all Terraform resources. The run task also has paid resource image validation, which currently only supports this list of resources. The paid validation feature checks images referenced by hard-coded image IDs.

In this tutorial, you will use the Terraform Cloud run task for HCP Packer to prevent your Terraform configuration from referencing revoked image iterations. You will first associate the run task with a Terraform Cloud workspace, then test the run task against configuration that includes a revoked iteration.

Prerequisites

This tutorial assumes that you are familiar with:

• The standard Packer and HCP Packer workflows. If you are new to Packer, complete the Get Started tutorials first. If you are new to HCP Packer, complete the Get Started HCP Packer tutorials first.
• The Terraform and Terraform Cloud plan/apply workflows. If you're new to Terraform itself, refer first to the Getting Started tutorials. If you are new to Terraform Cloud, refer to the Get Started - Terraform Cloud tutorials.

To follow along with this tutorial, you will need:

• Packer 1.7.10 installed locally
• Terraform 1.1.7 or later installed locally
• An AWS account with credentials set as local environment variables
• A HCP account with the HCP Packer Plus tier
• A Terraform Cloud account.
  • Terraform Cloud workspace admin permissions to associate run tasks to a workspace.

In addition, you must have a Terraform Cloud run task integrated with HCP Packer. If you do not have one set up, follow the Set Up Terraform Cloud Run Task for HCP Packer tutorial.

Create and set HCP service principal ID and key

In HCP Packer, go to Access control (IAM) in the left navigation menu, then select the Service principals tab.

Create a service principal named packer with the Contributor role.

Once you create the service principal, click the service principal name to view its details. From the detail page, click + Generate key to create a client ID and secret.

Copy and save the client ID and secret; you will not be able to retrieve the secret later. You will use these credentials in the next step.

Once you generate the keys for the service principal, set the client ID and secret as environment variables so that Packer can authenticate with HCP.

In your terminal, set an environment variable for the client ID.

$ export HCP_CLIENT_ID=

Then, set an environment variable for the client secret.

$ export HCP_CLIENT_SECRET=

Login to Terraform Cloud

In this tutorial, you will use the Terraform CLI to create the Terraform Cloud workspace and trigger remote plan and apply runs.

Log in to your Terraform Cloud account in your terminal.

$ terraform login
Terraform will request an API token for app.terraform.io using your browser.

If login is successful, Terraform will store the token in plain text in
the following file for use by subsequent commands:
    /Users/<USER>/.terraform.d/credentials.tfrc.json

Do you want to proceed?
  Only 'yes' will be accepted to confirm.

  Enter a value:

Confirm with a yes and follow the workflow in the browser window that automatically opens. Paste the generated API key into your Terminal when prompted. For more detailed instructions on logging in, review the Authenticate the CLI with Terraform Cloud tutorial.

Clone repository

In your terminal, clone the example repository. This repository contains a Packer template that defines an Ubuntu AMI and two directories with configuration that you will use to test the run task.

$ git clone https://github.com/hashicorp/learn-hcp-packer-run-tasks

Navigate to the cloned repository.

$ cd learn-hcp-packer-run-tasks

Create image iteration in HCP Packer

Open ubuntu-focal.pkr.hcl to review the template. This template will build an Ubuntu 20.04 AMI in the us-east-2 region. It will also push the metadata to the learn-packer-run-tasks bucket in HCP Packer.

build {
  hcp_packer_registry {
    bucket_name = "learn-packer-run-tasks"
    ## ...
  }
  sources = [
    "source.amazon-ebs.basic-example-east"
  ]
}

Initialize your Packer template.

$ packer init .

Now, build your image.

$ packer build ubuntu-focal.pkr.hcl
amazon-ebs.basic-example-east: output will be in this color.

==> amazon-ebs.basic-example-east: Publishing build details for amazon-ebs.basic-example-east to the HCP Packer registry
==> amazon-ebs.basic-example-east: Prevalidating any provided VPC information
==> amazon-ebs.basic-example-east: Prevalidating AMI Name: packer_AWS_1646215104_v1.0.0
    amazon-ebs.basic-example-east: Found Image ID: ami-05be...
## ...
==> Wait completed after 4 minutes 41 seconds
==> Builds finished. The artifacts of successful builds are:
--> amazon-ebs.basic-example-east: AMIs were created:
us-east-2: ami-05be...
--> amazon-ebs.basic-example-east: Published metadata to HCP Packer registry packer/learn-packer-run-tasks/iterations/01FX9WDZPYN3YBFTTVJQFBGQVE

In your HCP dashboard, go to the learn-packer-run-tasks bucket to confirm Packer pushed the build metadata to HCP Packer.

Create channel and schedule revocation

On the Channels page, create a channel named production and set it to the first iteration.

Next, go to the Iterations page. Schedule a revocation date for the first iteration by clicking on ..., then Revoke iteration.

Select Revoke at a future date and enter the time for 1 minute from your current time. The time is in UTC (current time in UTC). For example, if it is currently 10:00, enter 10:01. Then, enter Assign image channel to revoked iteration for the revocation reason, then click Revoke Iteration to revoke the iteration.

You are setting a short revocation window so that your image channel uses a revoked image to test validation workflows. This is for the educational purposes of the tutorial.

Set up Terraform Cloud workspace

Go to the tf-data-source-validation directory. This directory contains Terraform configuration that you will use to create a Terraform Cloud workspace to test the data source image validation run task.

$ cd tf-data-source-validation

Open main.tf. This configuration defines two data sources that retrieve an AMI ID from the production channel of the learn-packer-run-tasks HCP Packer image bucket, and an EC2 instance that uses the image ID returned by the HCP Packer data sources.

provider "hcp" {}

provider "aws" {
  region = var.region
}

data "hcp_packer_iteration" "ubuntu" {
  bucket_name = "learn-packer-ubuntu"
  channel     = "production"
}

data "hcp_packer_image" "ubuntu_us_east_2" {
  bucket_name    = "learn-packer-ubuntu"
  cloud_provider = "aws"
  iteration_id   = data.hcp_packer_iteration.ubuntu.ulid
  region         = "us-east-2"
}

resource "aws_instance" "app_server" {
  ami           = data.hcp_packer_image.ubuntu_us_east_2.cloud_image_id
  instance_type = "t2.micro"
  tags = {
    Name = "Learn-HCP-Packer"
  }
}

Update configuration

Open terraform.tf. In the cloud block, update the organization to point to your Terraform Cloud organization.

terraform {
  ## ...

  cloud {
    organization = "hashicorp-training"
    hostname     = "app.terraform.io"

    workspaces {
      name = "learn-hcp-packer-run-tasks-data-source-validation"
    }
  }
}

Create Terraform Cloud workspace

Initialize your Terraform configuration. This will create a Terraform Cloud workspace named learn-hcp-packer-run-tasks-data-source-validation in your Terraform Cloud organization.

$ terraform init

Initializing Terraform Cloud...

Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Installing hashicorp/aws v4.2.0...
- Installed hashicorp/aws v4.2.0 (signed by HashiCorp)

Terraform Cloud has been successfully initialized!

You may now begin working with Terraform Cloud. Try running "terraform plan" to
see any changes that are required for your infrastructure.

If you ever set or change modules or Terraform Settings, run "terraform init"
again to reinitialize your working directory.

In Terraform Cloud, open the learn-hcp-packer-run-tasks-data-source-validation workspace.

Add AWS and HCP credentials to workspace variables

Go to the Variables page.

Under Workspace variables, add your AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, HCP_CLIENT_ID, and HCP_CLIENT_SECRET as environment variables. You generated the HCP client ID and secret in the prerequisites. Alternatively, you can create variable sets with these environment variables and reuse them across multiple workspaces.

Enable run tasks in workspace

Click on Settings, then Run Tasks.

Under Available Run Tasks, click on HCP-Packer.

Terraform Cloud run tasks have two enforcement levels.

1. Advisory: If this run task fails, the run will proceed with a warning in the UI.
2. Mandatory: If this run task fails, the run will return an error and stop.

Select the Mandatory enforcement level, then click Create.

The Run Task page will now display the run task for HCP Packer. This run task will parse resources for hard-coded machine image IDs and check if they are tracked and unrevoked in HCP Packer. If the run task detects an machine image ID that is associated with a revoked iteration, both the run task and the Terraform Cloud run will fail.

Trigger Terraform Cloud run

In your terminal, apply your configuration. After Terraform creates the plan, the run will return an error because the run task failed.

$ terraform apply
Running apply in Terraform Cloud. Output will stream here. Pressing Ctrl-C
will cancel the remote apply if it's still pending. If the apply started it
will stop streaming the logs, but will not stop the apply running remotely.

Preparing the remote apply...

To view this run in a browser, visit:
https://app.terraform.io/app/hashicorp-training/learn-hcp-packer-run-tasks-resource-validation/runs/run-REDACTED

In Terraform Cloud, open the latest run. Notice that Terraform was able to build an execution plan.

The hcp_packer_image data source will return the image satisfying the data source parameters regardless of its revocation status. If the data source references a revoked image or an image that is scheduled to be revoked, the revoke_at attribute is set to the revocation timestamp.

The data source image validation run task automatically checks and warns for image iterations that are revoked or scheduled for revocation.

Click the Tasks failed box.

The run task failed with the following message:

Data source image validation results: 1 resource scanned. 1 new resource using revoked images. No newer version was found for the revoked images. Use Packer to build compliant images and send information to HCP Packer. When using channels, the channel must be re-assigned to a valid iteration.

The run task detected that the aws_instance resource references the hcp_packer_image data source. Since the data source references a revoked iteration and the resource was being created, the run task failed and blocked the deployment of revoked images.

If the run task determines that a newer iteration version is available, it will suggest that you use it. If you are the image maintainer, you can assign the channel to the newer iteration.

The Details link in the run task output will take you to the HCP Packer dashboard in case you wish to make any changes.

Restore image iteration

In the HCP Packer dashboard, go to the learn-packer-run-tasks bucket and select the revoked iteration. Click Manage, then Restore iteration to restore the revoked iteration.

Confirm the action by clicking on Restore iteration.

Re-trigger Terraform Cloud run

Apply your configuration. When prompted to confirm the apply, press Enter to discard the run.

$ terraform apply
Running apply in Terraform Cloud. Output will stream here. Pressing Ctrl-C
will cancel the remote apply if it's still pending. If the apply started it
will stop streaming the logs, but will not stop the apply running remotely.

Preparing the remote apply...

To view this run in a browser, visit:
https://app.terraform.io/app/hashicorp-training/learn-hcp-packer-run-tasks-data-source-validation/runs/run-REDACTED

Waiting for the plan to start...

Terraform v1.1.6
on linux_amd64
Configuring remote state backend...
Initializing Terraform configuration...

## ...

Plan: 1 to add, 0 to change, 0 to destroy.

## ...

Do you want to perform these actions in workspace "learn-hcp-packer-run-tasks-data-source-validation"?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: 

╷
│ Error: Apply discarded.
│ 
│ 

Verify image validation

In Terraform Cloud, open the latest run and expand the Tasks passed box.

The run task passed with the following message:

Data source image validation: 1 resource scanned. All resources are compliant.

The run task parsed the aws_instance resource and again detected the reference to the HCP Packer data source. Since you restored the iteration, your configuration is now valid and the run check passes.

The data source image validation only validates resources that reference the hcp_packer_image data source. The Plus tier resource image validation run task validates all types of image ID references (for example, HCP data source, hard-coded, or external source).

Next steps

In this tutorial, you used the Terraform Cloud run task for HCP Packer to prevent your Terraform configuration from referencing revoked image iterations.

For more information on topics covered in this tutorial, check out the following resources:

• Complete the resource image validation run task feature tutorial to learn how to ensure your Terraform configuration uses compliant machine images (even if you hard-code machine image IDs).
• Read more about the Terraform Cloud run task integration in the HCP Packer documentation.