Terraform Cloud/Enterprise (TFC/E) Run Task Integration

InsightCloudSec provides Terraform Cloud (TFC) and Terraform Enterprise (TFE) support for the Infrastructure as Code (IaC) scanning via Run Tasks. In InsightCloudSec, you can generate a unique endpoint URL and HMAC Key that TFC/E will use to request scans. Using unique endpoint URLs and keys ensures the right InsightCloudSec policy is applied to the scan and that only TFC/E can use that endpoint. Any existing IaC Configuration can have TFC/E Run Tasks associated with it, and a TFC/E Workspace can use multiple IaC Configurations for analysis by using a Run Task per Configuration. This page provides instructions for configuring a Run Task within InsightCloudSec and TFC/E.

Prerequisites

You will need the following before getting started with configuring a Run Task:

  • An InsightCloudSec deployment that will accept traffic from the Terraform Cloud or Enterprise deployment from which you'll initiate scans
    • For security reasons, most InsightCloudSec deployments disallow most traffic, so you will need to work with your support team to enable this.
  • An IaC configuration within the InsightCloudSec user interface (UI)
  • Appropriate InsightCloudSec and Terraform Cloud/Enterprise permissions
    • At least the IaC Entitlement with Editor permissions in InsightCloudSec *Manage Run Tasks access in Terraform Cloud/Enterprise
  • A Terraform Cloud/Enterprise environment that uses Terraform version 0.12 or later

Managing Run Tasks in InsightCloudSec

Creating a Run Task in Terraform Cloud/Enterprise requires an InsightCloudSec endpoint URL and HMAC key to be generated first.

  1. Login to your InsightCloudSec platform and click Infrastructure as Code in the left-hand navigation menu.
    Click Configurations in the top menu.

  2. Click the TFC/E Run Task Integrations icon (gear) next to the desired configuration. A pane will slide in from the right side of the window.

  3. Create a new Run Task integration and generate the necessary values.

    • Click + New Run Task Integration.
    • Provide a name for the Run Task.
    • Click Generate.

  4. Copy the generated endpoint URL and HMAC key values to a safe location; you will need to use this value in the next section when you create a matching Run Task in Terraform Cloud/Enterprise. Ensure the key is only stored in TFC/E or is encrypted.

Copying the Endpoint URL and HMAC Key Values

This is the only opportunity you have to copy these values. If you close the popup or leave this page without copying the values, you will not be able to access the values and you'll need to delete the Run Task and create another one.

Managing Run Tasks in Terraform Cloud/Enterprise

Once you have the Endpoint URL and HMAC key in hand, you're able to create a matching Run Task in the Terraform Cloud/Enterprise user interface. InsightCloudSec recommends following Terraform's documentation for this setup; just remember to input your new Endpoint URL and HMAC key when appropriate!

After the Run Task has been successfully created, it will need to be associated with a workspace before you can return to InsightCloudSec and test out the integration. InsightCloudSec recommends following the Terraform documentation for this setup as well, but note that you should initially start with the Advisory enforcement level.

Troubleshooting

The two most common errors users experience while creating a Run Task in Terraform Cloud/Enterprise are associated with an incorrect endpoint URL and/or a missing or incorrect HMAC key. Upon trying to create a Run Task, Terraform will ping the provided URL using the HMAC key to ensure the source can accept the Run Task format; if this basic operation fails, the task cannot be created. We recommend you ensure the following:

  • All values are copy/pasted correctly from InsightCloudSec
  • All values are from the appropriate Run Task in InsightCloudSec
  • There are no space characters (" ") at the end of the endpoint URL/HMAC key (once pasted into Terraform Cloud/Enterprise)

Another common error occurs when your InsightCloudSec deployment's networking layer doesn't allow traffic from Terraform Cloud's/Enterprise's IP ranges. In this case, Run Task creation in Terraform Cloud/Enterprise may present a Bad Gateway error. In this case, work with your support team to allow traffic from Terraform Cloud/Enterprise.

For any questions or issues reach out to us through any of the options outlined under our Getting Support page.