terraform-aws-securitycore

Description

This module creates the necessary resources to store your Terraform code remotely in AWS and is tied to the 'terraform-aws-account-setup' module; it should not be deployed separately.

FedRAMP Compliance: Moderate, High

Dependencies

• terraform-aws-account-setup (https://github.com/Coalfire-CF/terraform-aws-account-setup)

Resource List

• S3 for Terraform State
• IAM Policy document

S3 State File Locking

To utilize S3-native locking instead of DynamoDB you will remove the dynamodb_table line from your 'remote-data.tf' file and replace it with 'use_lockfile=true'. The lock file will now appear in the designated bucket assigned in the 'remote-data.tf' file. The name of the lock file will be the same as the state file with a .tflock extension added to the end. This can be tested by running a terraform plan and refreshing the tfstate S3 bucket; you should see the lock file appear and then disappear when the Terraform code is done running.

terraform {
  backend "s3" {
    bucket         = "<environment-name>>-us-gov-west-1-tf-state"
    region         = "us-gov-west-1"
    key            = "<environment-name>/us-gov-west-1/account-setup.tfstate"
    encrypt        = true
    use_lockfile   = true
  }
}

Usage

module "security-core" {
   source = "github.com/Coalfire-CF/terraform-aws-securitycore?ref=vX.X.X"

   application_account_numbers = var.application_account_numbers
   aws_region                  = var.aws_region
   resource_prefix             = var.resource_prefix

   # KMS Keys
   s3_kms_key_arn              = var.s3_kms_key_arn
}

Environment Setup

IAM user authentication:

- Download and install the AWS CLI (https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
- Log into the AWS Console and create AWS CLI Credentials (https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)
- Configure the named profile used for the project, such as 'aws configure --profile example-mgmt'

SSO-based authentication (via IAM Identity Center SSO):

- Login to the AWS IAM Identity Center console, select the permission set for MGMT, and select the 'Access Keys' link.
- Choose the 'IAM Identity Center credentials' method to get the SSO Start URL and SSO Region values.
- Run the setup command 'aws configure sso --profile example-mgmt' and follow the prompts.
- Verify you can run AWS commands successfully, for example 'aws s3 ls --profile example-mgmt'.
- Run 'export AWS_PROFILE=example-mgmt' in your terminal to use the specific profile and avoid having to use '--profile' option.

Deployment

1. Navigate to the Terraform project and create a parent directory in the upper level code, for example:

   ../{CLOUD}/terraform/{REGION}/management-account/example

   If multi-account management plane:

   ../{CLOUD}/terraform/{REGION}/{ACCOUNT_TYPE}-mgmt-account/example

2. Create a properly defined main.tf file via the template found under 'Usage' while adjusting tfvars as needed. Note that many provided variables are outputs from other modules. Example parent directory (modify this tree to reflect what the parent module should look like):

     ├── Example/
     │   ├── example.auto.tfvars   
     │   ├── main.tf
     │   ├── outputs.tf
     │   ├── providers.tf
     │   ├── required-providers.tf
     │   ├── remote-data.tf
     │   ├── variables.tf 
     │   ├── ...

3. Configure Terraform local backend and stage remote backend. For the first run, the entire contents of the 'remote-data.tf' file must be commented out with terraform local added to facilitate local state setup, like below:

   //terraform {
   //  backend "s3" {
   //    bucket         = "{resource_prefix}-{region}-tf-state"
   //    region         = "{region}"
   //    key            = "{resource_prefix}-{region}-security-core.tfstate"
   //    encrypt        = true
   //    use_lockfile   = true
   //  }
   //}
   terraform {
   backend "local"{}
   }

4. Initialize the Terraform working directory:

   terraform init

   Create an execution plan and verify the resources being created:

   terraform plan

   Apply the configuration:

   terraform apply

5. After the deployment has succeeded, uncomment the contents of 'remote-state.tf' and remove the terraform local code block.

6. Run 'terraform init -migrate-state' and follow the prompts to migrate the local state file to the appropriate S3 bucket in the management plane.

Requirements

Name	Version
terraform	>=1.5.0
aws	~> 5.0

Providers

Name	Version
aws	~> 5.0

Modules

Name	Source	Version
s3-tstate	github.com/Coalfire-CF/terraform-aws-s3	v1.0.4

Resources

Name	Type
aws_iam_policy_document.tfstate_bucket_policy	data source

Inputs

Name	Description	Type	Default	Required
application_account_numbers	Account IDs for application accounts to be used in IAM	list(string)	n/a	yes
aws_region	The AWS region to create things in	string	n/a	yes
resource_prefix	The prefix for the s3 bucket names	string	n/a	yes
s3_kms_key_arn	ARN for the CMK KMS key for S3	string	n/a	yes

Outputs

Name	Description
tstate_bucket_name	The name of the terraform state bucket

Contributing

Relative or absolute link to contributing.md

License

Coalfire Pages

Absolute link to any relevant Coalfire Pages

Copyright

Copyright © 2023 Coalfire Systems Inc.

Requirements

Name	Version
terraform	>=1.5.0
aws	~> 5.0

Providers

Name	Version
aws	~> 5.0

Modules

Name	Source	Version
s3-tstate	github.com/Coalfire-CF/terraform-aws-s3	v1.0.1

Resources

Name	Type
aws_dynamodb_table.dynamodb_	resource
aws_iam_policy_document.tfstate_bucket_policy	data source

Inputs

Name	Description	Type	Default	Required
application_account_numbers	Account IDs for application accounts to be used in IAM	list(string)	n/a	yes
aws_region	The AWS region to create things in	string	n/a	yes
dynamo_kms_key_arn	ARN for the CMK KMS key for DynamoDB	string	n/a	yes
resource_prefix	The prefix for the s3 bucket names	string	n/a	yes
s3_kms_key_arn	ARN for the CMK KMS key for S3	string	n/a	yes

Outputs

Name	Description
dynamo_key_arn	The arn of the dynamo kms key
dynamo_key_id	The id of the dynamo key
dynamodb_table_name	n/a
s3_key_arn	The arn of the s3 kms key
s3_key_iam	The name of the terraform state bucket
s3_key_id	The id of the s3 key
tstate_bucket_name	The name of the terraform state bucket