Integrate with Terraform Cloud

Trigger a Sophos Factory Job from Terraform Cloud

Description

This tutorial will guide you through inserting a Run Task in your Terraform Cloud (TFC) workflow that runs a Sophos Factory job. The job will be triggered using a webhook, and will subsequently execute a Sophos factory pipeline. The pipeline can be configured to execute any number of tasks, such as an opa eval scan, Terrascan, or Checkov scan. The pipeline results will then be sent back to TFC’s calling Run Task.

This integration also supports Terraform Enterprise (TFE). To use TFE instead, change the TFC webhook URL to your TFE instance.

The flow looks like this:

  1. Terraform Cloud Run
  2. Terraform Cloud Run Task
  3. Sophos Factory Job (WebHook Trigger)
  4. Sophos Factory Pipeline
  5. Reply back to Terraform Cloud Run Task
  6. Finish Terraform Cloud Workflow

The inspiration for this example comes from the Open Policy Agent | Terraform use case. The files listed in the instructions above have been added to this repo.

Requirements

  • A Terraform Cloud account
  • A Sophos Factory account
  • An AWS user with
    • An Access Key
    • Permission to do a plan based on the Terraform configuration in this repo

Instructions

In AWS:

  1. If you don’t already have one, create an IAM user with programmatic access and have the access key id and secret access key available for later.
  2. Assign the user the appropriate permissions to deploy the Terraform configuration in this repo (you do not need to deploy any resources to AWS in order to prove the workflow was successful).

In Sophos Factory:

  1. Create a new Job using the following settings:
    • Trigger: Incoming WebHook
    • Webhook Type: Terraform Cloud Run Task
    • (Optional) Terraform Secret Token: (A Generic Secret credential with an HMAC value)
    • Variables Transform: {"data": body} | dump
    • Pipeline Options:
      • Catalogs: choose one of the following example pipelines
        • Terraform Cloud Run Task | OPA Eval
        • Terraform Cloud Run Task | Terrascan
        • Terraform Cloud Run Task | Checkov
    • Revision: latest
  2. Click Create.
  3. Copy the WebHook URL for use later.

In Terraform Cloud:

  1. Create a new Event Hook (YourOrg ➡ Settings ➡ Task event hooks ➡ Create event hook)
    • Name: Choose a descriptive name
    • Endpoint URL: Paste in the WebHook URL from the Sophos Factory job
    • HMAC (optional): Paste in the HMAC used earlier
    • Click Create run task.
  2. Create a new workspace (if one does not already exist) in Terraform Cloud using the following settings:
    • Version Control Workflow (the following values assume you want to use our supporting example repo opa-terraform-demo).
      • Provider: GitHub
      • ID: refactr/opa-terraform-demo
    • Add the new Event Hook (Your Workspace ➡ Settings ➡ Tasks)
      • Enforcement Level: choose either value
  3. Add the following Environment Variables (Your Workspace ➡ Variables ➡ Environment Variables)
    • AWS_ACCESS_KEY_ID: Paste in your AWS user’s access key id
    • AWS_SECRET_ACCESS_KEY: Paste in your AWS user’s secret access key
    • AWS_DEFAULT_REGION: choose an AWS region
  4. Start a new plan to confirm everything works (Your Workspace ➡ Actions ➡ Start a new plan)
    • Enter a reason for the new plan.
    • Click Start plan.
      • If you see a green check mark and Tasks Passed then you have successfully completed this integration!
      • Feel free to cancel the plan.

Back in Sophos Factory:

  1. Confirm the Job was executed:
    • Navigate to the Run History page and check that the Status shows success:
    • Click on the linked Run # to troubleshoot if needed.

Resources