Terraform Module Datadog Agentless Scanner Module

This Terraform module provides a simple and reusable configuration for installing a Datadog agentless scanner.

Prerequisites

Before using this module, make sure you have the following:

1. Terraform installed on your local machine.
2. AWS credentials configured with the necessary permissions.

Usage

To use this module in your Terraform configuration, add the following code in your existing Terraform code:

# First we need to define the proper roles for our scanners. It consists of two different modules.

# 1. The "scanning delegate role" defines all the policies and IAM roles necessary for the scanner to interact and scan some specific account resources.
# It shall be created for every account that the agentless scanner will be able scan. These roles are meant to be assumed by the "agentless scanner role".
module "delegate_role" {
  source = "git::https://github.com/DataDog/terraform-module-datadog-agentless-scanner//modules/scanning-delegate-role"

  scanner_roles = [module.scanner_role.role.arn]
}

# 2. The "agentless scanner role" creates an EC2 instance profile along with an IAM role allowing the EC2 instance scanner to assume the scanning delegate role(s).
# It shall be created in the same account as the agentless scanner instance.
module "scanner_role" {
  source = "git::https://github.com/DataDog/terraform-module-datadog-agentless-scanner//modules/agentless-scanner-role"

  api_key_secret_arns = [module.agentless_scanner.api_key_secret_arn]
}

# Finally we can create the agentless scanner instance. It requires the instance profile name that was created by the scanner_role.
# This module will define the VPC, subnets, network and compute resources required for the agentless scanner.
# See the documentation of each module for more information or our examples for a complete setup.
module "agentless_scanner" {
  source = "git::https://github.com/DataDog/terraform-module-datadog-agentless-scanner"

  api_key               = var.datadog-api-key
  instance_profile_name = module.scanner_role.instance_profile.name
}

variable "datadog-api-key" {

}

And run:

terraform init
terraform apply -var="datadog-api-key=$DD_API_KEY"

Important

Datadog strongly recommends pinning the version of the module to keep repeatable deployment and to avoid unexpected changes.

Uninstall

To uninstall, remove the Agentless scanner module from your Terraform code. Removing this module deletes all resources associated with the Agentless scanner. Alternatively, if you used a separate Terraform state for this setup, you can uninstall the Agentless scanner by executing terraform destroy.

Warning

Exercise caution when deleting Terraform resources. Review the plan carefully to ensure everything is in order.

Architecture

The Agentless Scanner deployment is split into different modules to allow for more flexibility and customization. The following modules are available:

• scanning-delegate-role: Creates the necessary IAM role and policies for the scanning delegate. It creates an IAM role in a specific account that the scanner can then assume to scan the account. This role allows read access to many different resources (EBS snapshots, Lambdas etc.) in the account to be able to scan them.
• agentless-scanner-role: Creates the necessary IAM role and policies for the agentless scanner instance. It creates an IAM role that allows the scanner to assume the role of the scanning delegate.
• instance: Creates the EC2 instance that runs the agentless scanner. This instance is launched as part of an Auto Scaling group to ensure high availability.
• user_data: Creates the user data script that installs and configures the agentless scanner on the EC2 instance.
• vpc: Creates the VPC, subnets and all network resources required for the agentless scanner.

The main module provided at the root of this repository is a thin wrapper around the vpc, user_data and instance modules, with simplified inputs. The scanning-delegate-role and agentless-scanner-role modules are intended to be used in conjunction with this module, as they define the proper IAM permissions for the scanner.

flowchart TD
    subgraph "Account A"
      subgraph "Main module"
          UD[user_data]
          VPC[vpc]
          I[instance]
          UD-->I
          VPC-->I
        end

        SR[agentless-scanner-role]
        SR-->I

        DRA[scanning-delegate-role A]
        DRA-- trusts -->SR
        SR-- assumes -->DRA
    end

    subgraph "Account B"
      DRB[scanning-delegate-role B]
      DRB-- trusts -->SR
      SR-- assumes -->DRB
    end

Loading

Examples

For complete examples, refer to the examples directory in this repository.

Development

Install pre-commit checks:

pre-commit install

Automatically generate documentation for the Terraform modules:

pre-commit run terraform-docs-go -a

Lint Terraform code:

pre-commit run terraform_fmt -a
pre-commit run terraform_tflint -a

Run all checks:

pre-commit run -a

Changelog

See changelog.

Requirements

Name	Version
terraform	>= 1.0
aws	>= 5.0

Providers

No providers.

Modules

Name	Source	Version
instance	./modules/instance	n/a
user_data	./modules/user_data	n/a
vpc	./modules/vpc	n/a

Resources

No resources.

Inputs

Name	Description	Type	Default	Required
agent_configuration	Specifies a custom configuration for the Datadog Agent. The specified object is passed directly as a configuration input for the Datadog Agent. For more details: https://docs.datadoghq.com/agent/configuration/agent-configuration-files/. Warning: this is an advanced feature and can break the Datadog Agent if not used correctly.	any	{}	no
api_key	Specifies the API keys required by the Datadog Agent to submit vulnerabilities to Datadog	string	null	no
api_key_secret_arn	ARN of the secret holding the Datadog API key. Takes precedence over api_key variable	string	null	no
enable_ssm	Whether to enable AWS SSM to facilitate executing troubleshooting commands on the instance	bool	false	no
enable_ssm_vpc_endpoint	Whether to enable AWS SSM VPC endpoint (only applicable if enable_ssm is true)	bool	true	no
instance_count	Size of the autoscaling group the instance is in (i.e. number of instances with scanners to run)	number	1	no
instance_profile_name	Name of the instance profile to attach to the instance	string	n/a	yes
instance_type	The type of instance running the scanner	string	"t4g.large"	no
scanner_channel	Channel of the scanner to install from (stable or beta).	string	"stable"	no
scanner_configuration	Specifies a custom configuration for the scanner. The specified object is passed directly as a configuration input for the scanner. Warning: this is an advanced feature and can break the scanner if not used correctly.	any	{}	no
scanner_repository	Repository URL to install the scanner from.	string	"https://apt.datadoghq.com/"	no
scanner_version	Version of the scanner to install	string	"0.11"	no
site	By default the Agent sends its data to Datadog US site. If your organization is on another site, you must update it. See https://docs.datadoghq.com/getting_started/site/	string	null	no
tags	A map of additional tags to add to the IAM role/profile created	map(string)	{}	no

Outputs

Name	Description
api_key_secret_arn	The ARN of the secret containing the Datadog API key
vpc	The VPC created for the Datadog agentless scanner