Terraform Module Datadog Agentless Scanner

Terraform modules to set up Datadog Agentless Scanning on AWS, Azure and GCP.

This document covers AWS. For Azure and GCP instructions, please see their respective directories.

Examples

• AWS: see the examples directory.
• Azure: see the Azure module, or the ARM template.
• GCP: see the GCP examples directory.

Important

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

AWS Architecture

Datadog offers two ways to deploy Agentless Scanning on AWS: SaaS mode, where scanners run in Datadog's infrastructure, or self-hosted mode, where scanners run in your own AWS account.

SaaS mode

Scanners run in Datadog's infrastructure: nothing is deployed in your account. The agentless-scanning-policy module provides the scanning permissions, which are attached as a managed policy to the Datadog integration role. Datadog assumes this role to perform the scans.

flowchart LR
    subgraph "Datadog"
      S[Agentless scanners]
    end

    subgraph "Your AWS account"
      IR[Datadog integration role]
      P[agentless-scanning-policy]
      P-- attached to -->IR
    end

    S-- assumes -->IR

Loading

Self-hosted mode

Scanners run in your own AWS infrastructure. They require a Datadog API key with Remote Configuration enabled. The following modules are used:

• Main module: a thin wrapper around the vpc, user_data and instance modules, which create the network, the scanner install script and the Auto Scaling group running the scanners.
• agentless-scanner-role: IAM role and instance profile for the scanner instances, allowing them to assume the scanning delegate roles.
• scanning-delegate-role: IAM role created in each scanned account, holding the permissions to scan its resources (EBS snapshots, Lambdas, etc.).
• agentless-scanners-autoscaling: attaches the policy allowing Datadog to scale the scanners up or down based on load.
• agentless-s3-bucket: S3 bucket used to scan RDS snapshot exports (optional).

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

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.2.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 key required by the Agentless Scanner to submit vulnerabilities to Datadog - Make sure the API key is Remote Configuration enabled.	string	null	no
api_key_secret_arn	ARN of the secret holding the Datadog API key. Takes precedence over api_key variable - Make sure the API key is Remote Configuration enabled.	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	Default 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.medium"	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