tf_threatstack_control_plane_monitoring_integration
Setup Threat Stack <-> Control Plane Monitoring integration module
This module provides the ability to define the Threat Stack integration infrastructure via Terraform. Currently only AWS Cloudtrail is supported, and it automates the AWS Manual Integration Setup
This module will create and manage the following:
- AWS CloudTrail
- multi-region trail
- records global service events
- S3 bucket to store events
- enables log file validation
- CloudTrail to Cloudwatch logging
- AWS SNS topic to forward CloudTrail events to
- AWS SQS queue Threat Stack will check for events
- Cross account IAM role for Threat Stack
Dependencies
This Terraform module currently depends on the following providers as dependencies:
template
~> 2.1aws
~> 2.0
Usage
This version of the module is compatible with Terraform 0.12+. Terraform 0.11 and earlier are not supported, and this module will not work. For a pre-0.12-compatible version of this module, see v1.0.0 of this module.
To use, a user-created module should be defined that imports this module (via the source
parameter on the module
setting. Terraform will download and use the source module with the terraform init
command, so there is no need to download it separately for use. The minimum configuration for the user would look as follows (Be sure to adjust the git ref in the source value appropriately):
module "threatstack_aws_integration" { # THe name of the module here is arbitrary and can be whatever makes it easily identifiable to the end-user
source = "github.com/threatstack/threatstack-terraform?ref=<integration_version>"
threatstack = {
account_id = "<THREATSTACK_AWS_ACCOUNT_ID>"
external_id = "<THREATSTACK_AWS_EXTERNAL_ID>"
}
aws_account_info = {
account_id = "<AWS_ACCOUNT_ID>"
region = "us-east-1"
}
}
Threat Stack Setup
In Threat Stack click Add Account
under AWS Accounts fill in the relevant output values on the Integrations page under Settings and get the Threat Stack Account ID and External ID. Use these values for the threatstack.account_id
and threatstack.external_id
input variables (see below). Run Terraform and get the outputs from it.
Record the Terraform output values, and use them to complete the configuration of the Threat Stack platform's side integration. See sections 3 & 6 of the AWS Manual Integration Setup page for details.
Variables
The module's input variables are defined in their own Terraform variable objects. They are as follows:
-
threatstack: (REQUIRED) Threat Stack-specific settings to deploy the integration. The defaults are null, so the integration will fail if not set.
-
aws_account_info: (REQUIRED) AWS account specifics to deploy the integration. The defaults are null, so the integration will fail if not set.
-
aws_flags: (Optional) The flags have defaults, so the module can work without these explicitly set.
-
aws_optional_conf: (Optional) The settings have defaults, so the module can work without these explicitly set.
Threat Stack configuration
All of the Threat Stack configuration is required. Not explicitly defining these values when using this module will cause the integration to not work as expected.
The Threat Stack configuration is defined as follows:
module "threatstack_aws_integration" {
source = "github.com/threatstack/threatstack-terraform?ref=<integration_version>"
# Strings generated from the Threat Stack Add Account page
threatstack = {
account_id = string
external_id = string
}
}
-
threatstack.account_id: Threat Stack account ID associated with the Threat Stack org. Used to find remote state information and is prepended to bucket names.
-
threatstack.external_id: Account ID, used for CloudTrail integration.
AWS configuration
This Terraform input variable is split into 3 sections: required settings, flag settings, and optional settings
Required settings
module "threatstack_aws_integration" {
source = "github.com/threatstack/threatstack-terraform?ref=<integration_version>"
aws_account_info = {
# ...
account_id = string
region = string
#...
}
}
-
aws_account_info.account_id: Account ID, used for CloudTrail integration.
-
aws_account_info.region: AWS region. Used to find remote state.
Flag settings
module "threatstack_aws_integration" {
source = "github.com/threatstack/threatstack-terraform?ref=<integration_version>"
aws_flags = {
# ...
enable_logging = bool # Defaults to `true`
enable_log_file_validation = bool # Defaults to `true`
include_global_service_events = bool # Defaults to `true`
is_multi_region_trail = bool # Defaults to `true`
s3_force_destroy = bool # Defaults to `false`
#...
}
}
-
aws_flags.enable_logging (optional): Enable logging, set to 'false' to pause logging.
-
aws_flags.enable_log_file_validation (optional): Create signed digest file to validated contents of logs.
-
aws_flags.include_global_service_events (optional): Include evnets from global services such as IAM.
-
aws_flags.is_multi_region_trail (optional): Whether the trail is created in all regions or just the current region.
-
aws_flags.s3_force_destroy (optional): Bucket destroy will fail if the bucket is not empty. Set to
"true"
if you REALLY want to destroy logs on teardown.
Optional settings
module "threatstack_aws_integration" {
source = "github.com/threatstack/threatstack-terraform?ref=<integration_version>"
aws_optional_conf = {
# ...
cloudtrail_name = string # Defaults to "ThreatStackIntegration"
iam_role_name = string # Defaults to "ThreatStackIntegration"
sns_topic_name = string # Defaults to "ThreatStackIntegration"
sns_topic_display_name = string # Defaults to "Threat Stack integration topic."
sqs_queue_name = string # Defaults to "ThreatStackIntegration"
s3_bucket_name = string # Defaults to "threatstack-integration"
s3_force_destroy = string # Defaults to "/"
#...
}
}
-
aws_optional_conf.cloudtrail_name (optional): Name of CloudTrail trail.
-
aws_optional_conf.iam_role_name (optional): Name of cross account IAM role gating access for Threat Stack to AWS environment.
-
aws_optional_conf.sns_topic_name (optional): Name of SNS topic used by CloudTrail.
-
aws_optional_conf.sns_topic_display_name (optional): SNS topic display name.
-
aws_optional_conf.sqs_queue_name (optional): Name of SQS queue to forward events to.
-
aws_optional_conf.s3_bucket_name (optional): Name of bucket to create to store logs. Pay attention to the fact that account name will be prepended to the provided bucket name to help prevent name collisions.
-
aws_optional_conf.s3_bucket_prefix (optional): S3 prefix path for logs. Useful is using a bucket used by other services. (Not recommended)
Outputs
Exposing this module's outputs to the rest of your terraform definitions
As of Terraform 0.12, there is a known change in the structure of the terraform state file format that makes child module outputs inaccessible to tools like terraform show
, terraform output
, or via remote state data sources. A child module is any resource defined with the module "<name>" { ... }
resource directive.
In order to refer to any of the outputs of this module outside of the implementing module, they must be wrapped as new outputs defined in the implementing module itself.
One way to do this (see below) is to define your infrastructure in your main.tf
, and define your wrapper outputs in an outputs.tf
file.
Example implementation
This is the file that implements the threatstack-terraform module with your account-specific information:
<your_module_directory>/main.tf:
module "threatstack_aws_integration" {
source = "github.com/threatstack/threatstack-terraform?ref=<integration_version>"
aws_account_info = {
# ...
}
aws_flags = {
# ...
}
aws_optional_conf = {
# ...
}
}
Using the name you gave to the instance of the threatstack-terraform module above, the output is defined as:
<your_module_directory>/outputs.tf:
output "threatstack-aws-integration-cloudtrail-arn" {
value = "${module.threatstack_aws_integration.cloudtrail_arn}"
}
You can wrap any of the threatstack-terraform module outputs listed below in the same way.
Important outputs to expose to complete the integration
There are three output values that are needed to complete the integration by defining them in the Threat Stack Platform administrative settings (see the official documentation for more information), once the terraform module has been applid in the customer infrastructure. They are:
- iam_role_arn
- s3_bucket_id
- sqs_queue_source
It is recommended that these outputs be rewrapped in outputs defined in your implementing module (as seen in the previous example), at a minimum. This will allow you to use the terraform output
CLI command to get the value generated by this module.
List of all outputs from this module
NOTE: You can also see this list in this module's
outputs.tf
file.
-
cloudtrail_arn: ARN of CloudTrail.
-
cloudtrail_home_region: Home region for CloudTrail
-
cloudtrail_id: CloudTrail ID. Name of CloudTrail without full ARN string.
-
cloudwatch_log_group_arn: ARN of CloudWatch log group for cloudTrail events.
-
iam_role_arn: ARN of cross account IAM role granting Threat Stack access to environment. (Enter this value into Threat Stack when setting up.)
-
iam_role_name: Name of cross account IAM role granting Threat Stack access to environment.
-
iam_role_cloudtrail_arn: ARN of IAM role allowing events to be logged to CloudWatch.
-
iam_role_cloudtrail_name: Name of IAM role allowing events to be logged to CloudWatch.
-
s3_bucket_arn: ARN of bucket for CloudTrail events.
-
s3_bucket_id: Name of bucket for CloudTrail events. (Enter this value into Threat Stack when setting up.)
-
sns_topic_arn: ARN of SNS topic where CloudTrail events are forwarded to.
-
sqs_queue_arn: ARN of SQS queue Threat Stack reads events from.
-
sqs_queue_id: SQS queue ID / endpoint.
-
sqs_queue_source: Name of SQS queue Threat Stack reads events from. (Enter this value into Threat Stack when setting up.)