cool-assessment-terraform
This project is used to create an operational assessment environment in the COOL environment.
Pre-requisites
-
Terraform installed on your system.
-
An accessible AWS S3 bucket to store Terraform state (specified in
backend.tf). -
An accessible AWS DynamoDB database to store the Terraform state lock (specified in
backend.tf). -
Access to all of the Terraform remote states specified in
remote_states.tf. -
Accept the terms for any AWS Marketplace subscriptions to be used by the operations instances in your assessment environment (must be done in the AWS account hosting the assessment environment):
-
Access to AWS AMIs for Guacamole and any other operations instance types used in your assessment.
-
OpenSSL server certificate and private key for the Guacamole instance in your assessment environment, stored in an accessible AWS S3 bucket; this can be easily created via certboto-docker or a similar tool.
-
A Terraform variables file customized for your assessment environment, for example:
assessment_account_name = "env0" private_domain = "env0" vpc_cidr_block = "10.224.0.0/21" operations_subnet_cidr_block = "10.224.0.0/24" private_subnet_cidr_blocks = ["10.224.1.0/24", "10.224.2.0/24"] tags = { Team = "VM Fusion - Development" Application = "COOL - env0 Account" Workspace = "env0" }
Building the Terraform-based infrastructure
-
Create a Terraform workspace (if you haven't already done so) for your assessment by running
terraform workspace new <workspace_name>. -
Create a
<workspace_name>.tfvarsfile with all of the required variables (see Inputs below for details). -
Run the command
terraform init. -
Add all necessary permissions by running the command:
terraform apply -var-file=<workspace_name>.tfvars --target=aws_iam_policy.provisionassessment_policy --target=aws_iam_role_policy_attachment.provisionassessment_policy_attachment -
Create all remaining Terraform infrastructure by running the command:
terraform apply -var-file=<workspace_name>.tfvars
Examples
Requirements
| Name | Version |
|---|---|
| terraform | ~> 1.0 |
| aws | ~> 3.38 |
| cloudinit | ~> 2.0 |
| null | ~> 3.0 |
Providers
| Name | Version |
|---|---|
| aws | ~> 3.38 |
| aws.dns_sharedservices | ~> 3.38 |
| aws.organizationsreadonly | ~> 3.38 |
| aws.provisionassessment | ~> 3.38 |
| aws.provisionparameterstorereadrole | ~> 3.38 |
| aws.provisionsharedservices | ~> 3.38 |
| cloudinit | ~> 2.0 |
| null | ~> 3.0 |
| terraform | n/a |
Modules
| Name | Source | Version |
|---|---|---|
| email_sending_domain_certreadrole | github.com/cisagov/cert-read-role-tf-module | n/a |
| guacamole_certreadrole | github.com/cisagov/cert-read-role-tf-module | n/a |
| read_terraform_state | github.com/cisagov/terraform-state-read-role-tf-module | n/a |
| run_shell_ssm_document | gazoakley/session-manager-settings/aws | n/a |
| vpc_flow_logs | trussworks/vpc-flow-logs/aws | ~>2.0 |
Resources
Inputs
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| assessment_account_name | The name of the AWS account for this assessment (e.g. "env0"). | string |
n/a | yes |
| assessor_account_role_arn | The ARN of an IAM role that can be assumed to create, delete, and modify AWS resources in a separate assessor-owned AWS account. | string |
"arn:aws:iam::123456789012:role/Allow_It" |
no |
| aws_availability_zone | The AWS availability zone to deploy into (e.g. a, b, c, etc.) | string |
"a" |
no |
| aws_region | The AWS region where the non-global resources for this assessment are to be provisioned (e.g. "us-east-1"). | string |
"us-east-1" |
no |
| cert_bucket_name | The name of the AWS S3 bucket where certificates are stored. | string |
"cisa-cool-certificates" |
no |
| cool_domain | The domain where the COOL resources reside (e.g. "cool.cyber.dhs.gov"). | string |
"cool.cyber.dhs.gov" |
no |
| dns_ttl | The TTL value to use for Route53 DNS records (e.g. 86400). A smaller value may be useful when the DNS records are changing often, for example when testing. | number |
60 |
no |
| email_sending_domain | The domain to send emails from within the assessment environment (e.g. "example.com"). | string |
"example.com" |
no |
| guac_connection_setup_path | The full path to the dbinit directory where initialization files must be stored in order to work properly. (e.g. "/var/guacamole/dbinit") | string |
"/var/guacamole/dbinit" |
no |
| inbound_ports_allowed | A map specifying the ports allowed inbound (from anywhere) to the various instance types (e.g. {"kali": [{"protocol": "tcp", "from_port": 443, "to_port": 443}, {"protocol": "tcp", "from_port": 9000, "to_port": 9009}]}). The currently-supported keys are: "assessorportal", "debiandesktop", "gophish", "kali", "nessus", "pentestportal", "samba", "teamserver", and "terraformer". | map(list(object({ protocol = string, from_port = number, to_port = number }))) |
{ "assessorportal": [], "debiandesktop": [], "gophish": [], "kali": [], "nessus": [], "pentestportal": [], "samba": [], "teamserver": [], "terraformer": [] } |
no |
| nessus_activation_codes | The list of Nessus activation codes (e.g. ["AAAA-BBBB-CCCC-DDDD"]). The number of codes in this list should match the number of Nessus instances defined in operations_instance_counts. | list(string) |
[] |
no |
| operations_instance_counts | A map specifying how many instances of each type should be created in the operations subnet (e.g. { "kali": 1 }). The currently-supported instance keys are: ["assessorportal", "debiandesktop", "gophish", "kali", "nessus", "pentestportal", "samba", "teamserver", "terraformer"]. | map(number) |
{ "kali": 1 } |
no |
| operations_subnet_cidr_block | The operations subnet CIDR block for this assessment (e.g. "10.10.0.0/24"). | string |
n/a | yes |
| private_domain | The local domain to use for this assessment (e.g. "env0"). If not provided, local.private_domain will be set to the base of the assessment account name. For example, if the account name is "env0 (Staging)", local.private_domain will default to "env0". Note that local.private_domain should be used in place of var.private_domain throughout this project. |
string |
"" |
no |
| private_subnet_cidr_blocks | The list of private subnet CIDR blocks for this assessment (e.g. ["10.10.1.0/24", "10.10.2.0/24"]). | list(string) |
n/a | yes |
| provisionaccount_role_name | The name of the IAM role that allows sufficient permissions to provision all AWS resources in the assessment account. | string |
"ProvisionAccount" |
no |
| provisionassessment_policy_description | The description to associate with the IAM policy that allows provisioning of the resources required in the assessment account. | string |
"Allows provisioning of the resources required in the assessment account." |
no |
| provisionassessment_policy_name | The name to assign the IAM policy that allows provisioning of the resources required in the assessment account. | string |
"ProvisionAssessment" |
no |
| read_terraform_state_role_name | The name to assign the IAM role (as well as the corresponding policy) that allows read-only access to the cool-assessment-terraform state in the S3 bucket where Terraform state is stored. The %s in this name will be replaced by the value of the assessment_account_name variable. | string |
"ReadCoolAssessmentTerraformTerraformState-%s" |
no |
| ssm_key_nessus_admin_password | The AWS SSM Parameter Store parameter that contains the password of the Nessus admin user (e.g. "/nessus/assessment/admin_password"). | string |
"/nessus/assessment/admin_password" |
no |
| ssm_key_nessus_admin_username | The AWS SSM Parameter Store parameter that contains the username of the Nessus admin user (e.g. "/nessus/assessment/admin_username"). | string |
"/nessus/assessment/admin_username" |
no |
| ssm_key_vnc_password | The AWS SSM Parameter Store parameter that contains the password needed to connect to the TBD instance via VNC (e.g. "/vnc/password") | string |
"/vnc/password" |
no |
| ssm_key_vnc_user_private_ssh_key | The AWS SSM Parameter Store parameter that contains the private SSH key of the VNC user on the TBD instance (e.g. "/vnc/ssh/rsa_private_key") | string |
"/vnc/ssh/rsa_private_key" |
no |
| ssm_key_vnc_username | The AWS SSM Parameter Store parameter that contains the username of the VNC user on the TBD instance (e.g. "/vnc/username") | string |
"/vnc/username" |
no |
| ssmsession_role_description | The description to associate with the IAM role (and policy) that allows creation of SSM SessionManager sessions to any EC2 instance in this account. | string |
"Allows creation of SSM SessionManager sessions to any EC2 instance in this account." |
no |
| ssmsession_role_name | The name to assign the IAM role (and policy) that allows creation of SSM SessionManager sessions to any EC2 instance in this account. | string |
"StartStopSSMSession" |
no |
| tags | Tags to apply to all AWS resources created | map(string) |
{} |
no |
| terraformer_role_description | The description to associate with the IAM role (and policy) that allows Terraformer instances to create appropriate AWS resources in this account. | string |
"Allows Terraformer instances to create appropriate AWS resources in this account." |
no |
| terraformer_role_name | The name to assign the IAM role (and policy) that allows Terraformer instances to create appropriate AWS resources in this account. | string |
"Terraformer" |
no |
| vpc_cidr_block | The CIDR block to use this assessment's VPC (e.g. "10.224.0.0/21"). | string |
n/a | yes |
Outputs
| Name | Description |
|---|---|
| assessment_private_zone | The private DNS zone for this assessment. |
| assessor_portal_instance_profile | The instance profile for the Assessor Portal instances. |
| assessor_portal_instances | The Assessor Portal instances. |
| assessor_portal_security_group | The security group for the Assessor Portal instances. |
| aws_region | The AWS region where this assessment environment lives. |
| certificate_bucket_name | The name of the S3 bucket where certificate information is stored for this assessment. |
| cloudwatch_and_ssm_agent_security_group | A security group for all instances. Allows access to the VPC endpoint resources necessary for the AWS CloudWatch agent and the AWS SSM agent. |
| debian_desktop_instance_profile | The instance profile for the Debian desktop instances. |
| debian_desktop_instances | The Debian desktop instances. |
| debian_desktop_security_group | The security group for the Debian desktop instances. |
| efs_client_security_group | A security group that should be applied to all instances that will mount the EFS file share. |
| efs_mount_targets | The mount targets for the EFS file share. |
| email_sending_domain_certreadrole | The IAM role that allows for reading the certificate for the email-sending domain. |
| gophish_instance_profile | The instance profile for the Gophish instances. |
| gophish_instances | The Gophish instances. |
| gophish_security_group | The security group for the Gophish instances. |
| guacamole_accessible_security_group | A security group that should be applied to all instances that are to be accessible from Guacamole. |
| guacamole_server | The AWS EC2 instance hosting Guacamole. |
| kali_instance_profile | The instance profile for the Kali instances. |
| kali_instances | The Kali instances. |
| kali_security_group | The security group for the Kali instances. |
| nessus_instance_profile | The instance profile for the Nessus instances. |
| nessus_instances | The Nessus instances. |
| nessus_security_group | The security group for the Nessus instances. |
| operations_subnet | The operations subnet. |
| operations_subnet_acl | The access control list (ACL) for the operations subnet. |
| pentest_portal_instance_profile | The instance profile for the Pentest Portal instances. |
| pentest_portal_instances | The Pentest Portal instances. |
| pentest_portal_security_group | The security group for the Pentest Portal instances. |
| private_subnet_acls | The access control lists (ACLs) for the private subnets. |
| private_subnet_cidr_blocks | The private subnet CIDR blocks. These are used to index into the private_subnets and efs_mount_targets outputs. |
| private_subnet_nat_gateway | The NAT gateway for the private subnets. |
| private_subnets | The private subnets. |
| read_terraform_state_module | The IAM policies and role that allow read-only access to the cool-assessment-terraform workspace-specific state in the Terraform state bucket. |
| remote_desktop_url | The URL of the remote desktop gateway (Guacamole) for this assessment. |
| samba_client_security_group | The security group that should be applied to all instance types that wish to mount the Samba file share being served by the Samba file share server instances. |
| samba_instance_profile | The instance profile for the Samba file share server instances. |
| samba_instances | The Samba file share server instances. |
| samba_server_security_group | The security group for the Samba file share server instances. |
| scanner_security_group | A security group that should be applied to all instance types that perform scanning. This security group allows egress to anywhere as well as ingress from anywhere via ICMP. |
| ssm_session_role | An IAM role that allows creation of SSM SessionManager sessions to any EC2 instance in this account. |
| teamserver_instance_profile | The instance profile for the Teamserver instances. |
| teamserver_instances | The Teamserver instances. |
| teamserver_security_group | The security group for the Teamserver instances. |
| terraformer_instances | The Terraformer instances. |
| terraformer_security_group | The security group for the Terraformer instances. |
| vpc | The VPC for this assessment environment. |
| vpn_server_cidr_block | The CIDR block for the COOL VPN. |
Notes
Running pre-commit requires running terraform init in every directory that
contains Terraform code. In this repository, this is only the main directory.
Contributing
We welcome contributions! Please see CONTRIBUTING.md for
details.
License
This project is in the worldwide public domain.
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.