publish-egress-ip-terraform

This repository contains Terraform code to deploy cisagov/publish-egress-ip-lambda and related resources.

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.

• A valid Lambda deployment file must be present in the root directory and have the same name as var.lambda_zip_filename (e.g. "lambda_build.zip").

• A Terraform variables file customized for your assessment environment, for example:

  bucket_name         = "s3-cdn.egress-info.my.domain.gov"
  domain              = "egress-info.my.domain.gov"
  deployment_role_arn = "arn:aws:iam::123456789012:role/deployment-role"
  file_configs        = [
        {
            "filename": "all.txt",
            "app_regex": ".*",
            "static_ips": [],
            "description": "This file contains a list of all public IP addresses."
        },
        {
            "filename": "vs.txt",
            "app_regex": "^Vulnerability Scanning$",
            "static_ips": [
                "192.168.1.1/32",
                "192.168.2.2/32"
            ],
            "description": "This file contains a list of all IPs used for Vulnerability Scanning."
        }
    ]
  route53_role_arn    = "arn:aws:iam::123456789012:role/route53-role"
  
  tags = {
    Team        = "VM Fusion - Development"
    Application = "Publish Egress IP"
    Workspace   = "production"
  }

Building the Terraform-based infrastructure

1. Create a Terraform workspace (if you haven't already done so) for your assessment by running terraform workspace new <workspace_name>.

2. Create a <workspace_name>.tfvars file with all of the required variables (see Inputs below for details).

3. Run the command terraform init.

4. Create all Terraform infrastructure by running the command:

   terraform apply -var-file=<workspace_name>.tfvars

After the Terraform code has been deployed and the Lambda has run successfully, you will be able to see your published egress IP address information at: https://<var.domain>

If you defined additional files via var.file_configs, they can be accessed at: https://<var.domain>/<var.file_configs.filename>

Requirements

Name	Version
terraform	~> 1.1
aws	~> 4.9

Providers

Name	Version
aws	~> 4.9
aws.deploy	~> 4.9
aws.organizationsreadonly	~> 4.9
aws.route53resourcechange	~> 4.9
terraform	n/a

Modules

Name	Source	Version
security_header_lambda	transcend-io/lambda-at-edge/aws	0.5.0

Resources

Name	Type
aws_cloudfront_distribution.egress_info	resource
aws_cloudfront_origin_access_control.egress_info	resource
aws_cloudwatch_event_rule.lambda_schedule	resource
aws_cloudwatch_event_target.lambda_schedule	resource
aws_cloudwatch_log_group.lambda_logs	resource
aws_iam_policy.lambdaexecution_policy	resource
aws_iam_role.lambdaexecution_role	resource
aws_iam_role_policy_attachment.lambdaexecution_policy_attachment	resource
aws_lambda_function.publish_egress_ip	resource
aws_lambda_permission.allow_cloudwatch	resource
aws_route53_record.rules_vm_A	resource
aws_route53_record.rules_vm_AAAA	resource
aws_s3_bucket.egress_info	resource
aws_s3_bucket.lambda_at_edge	resource
aws_s3_bucket_ownership_controls.egress_info	resource
aws_s3_bucket_policy.egress_info	resource
aws_s3_bucket_public_access_block.egress_info	resource
aws_s3_bucket_public_access_block.lambda_artifact_bucket	resource
aws_s3_bucket_server_side_encryption_configuration.egress_info	resource
aws_s3_bucket_server_side_encryption_configuration.lambda_at_edge	resource
aws_s3_bucket_versioning.lambda_at_edge	resource
aws_acm_certificate.rules_cert	data source
aws_caller_identity.current	data source
aws_caller_identity.deploy	data source
aws_iam_policy_document.egress_info	data source
aws_iam_policy_document.lambda_assume_role_doc	data source
aws_iam_policy_document.lambdaexecution_doc	data source
aws_organizations_organization.org	data source
terraform_remote_state.dns	data source
terraform_remote_state.dns_cyber_dhs_gov	data source
terraform_remote_state.master	data source
terraform_remote_state.terraform	data source

Inputs

Name	Description	Type	Default	Required
account_name_regex	A regular expression that will be applied against the names of all non-master accounts in the AWS organization. If the name of an account matches the regular expression, that account will be queried for egress IP addresses to publish. The default value should not match any valid account name.	string	"^$"	no
application_tag	The name of the AWS tag whose value represents the application associated with an IP address.	string	"Application"	no
aws_region	The AWS region to deploy into (e.g. us-east-1).	string	"us-east-1"	no
bucket_name	The name of the S3 bucket to publish egress IP address information to.	string	n/a	yes
cloudfront_distribution_oac_description	The description to apply to the CloudFront Origin Access Control.	string	"Allow CloudFront to securely read from an S3 bucket."	no
cloudfront_distribution_oac_name	The name for the CloudFront Origin Access Control.	string	"publish-egress-ip-s3-distribution"	no
deployment_role_arn	The ARN of the IAM role to use to deploy the Lambda and all related resources.	string	n/a	yes
domain	The domain hosting the published file(s) containing egress IPs. Also used for the CloudFront distribution and certificate.	string	n/a	yes
domain_aliases	A list of domain aliases to associate with the CloudFront distribution. These domains must be included (as subject alternative names) in the certificate used by the distribution.	list(string)	[]	no
ec2_read_role_name	The name of the IAM role that allows read access to the necessary EC2 attributes. Note that this role must exist in each account that you want to query.	string	"EC2ReadOnly"	no
extraorg_account_ids	A list of AWS account IDs corresponding to "extra" accounts that you want to query for egress IPs to publish.	list(string)	[]	no
file_configs	A list of objects that define the files to be published. "app_regex" specifies a regular expression matching the application name (based on the variable var.application_tag). "description" is the description of the published file. "filename" is the name to assign the published file. "static_ips" is a list of CIDR blocks that will always be included in the published file. An example file configuration looks like this: [{"app_regex": ".*", "description": "This file contains a list of all public IP addresses to be published.", "filename": "all.txt", "static_ips": []}, {"app_regex": "^Vulnerability Scanning$", "description": "This file contains a list of all IPs used for Vulnerability Scanning.", "filename": "vs.txt", "static_ips": ["192.168.1.1/32", "192.168.2.2/32"]}]	list(object({ app_regex = string, description = string, filename = string, static_ips = list(string) }))	[]	no
file_header	The header template for each published file. When the file is published, newline characters are automatically added between each item in the list. The following variables are available within the template: {domain} - the domain where the published files are located, {filename} - the name of the published file, {timestamp} - the timestamp when the file was published, {description} - the description of the published file	list(string)	[ "###", "# https://{domain}/{filename}", "# {timestamp}", "# {description}", "###" ]	no
lambda_function_description	The description of the Lambda function.	string	"Lambda function to publish egress IP addresses to an S3 bucket configured with a CloudFront distribution for HTTPS access."	no
lambda_function_name	The name of the Lambda function to publish egress IP addresses.	string	"publish-egress-ip"	no
lambda_schedule_interval	The number of minutes between scheduled runs of the Lambda function to publish egress IP addresses. This value must be an integer greater than 0.	number	60	no
lambda_zip_filename	The name of the ZIP file containing the Lambda function deployment package to publish egress IP addresses. The file must be located in the root directory of this project.	string	"lambda_build.zip"	no
lambdaexecution_role_description	The description to associate with the IAM role (and policy) that allows the publish-egress-ip Lambda to query other accounts for public EC2 IP information, publish objects to the S3 bucket, and write CloudWatch logs.	string	"Allows the publish-egress-ip Lambda to query other accounts for public EC2 IP information, publish objects to the S3 bucket, and write CloudWatch logs."	no
lambdaexecution_role_name	The name to assign the IAM role (and policy) that allows the publish-egress-ip Lambda to query other accounts for public EC2 IP information, publish objects to the S3 bucket, and write CloudWatch logs.	string	"PublishEgressIPLambda"	no
publish_egress_tag	The name of the AWS resource tag whose value represents whether the EC2 instance or elastic IP should have its public IP address published.	string	"Publish Egress"	no
region_filters	A list of AWS EC2 region filters to use when querying for IP addresses to publish. If a filter is not specified, the query will be performed in all regions. An example filter to restrict to US regions looks like this: [{ "Name" : "endpoint", "Values" : ["*.us-*"] }]. For more information, refer to https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-regions.html.	list(object({ Name = string, Values = list(string) }))	[]	no
root_object	The root object in the S3 bucket to serve when no path is provided or an error occurs.	string	"all.txt"	no
route53_role_arn	The ARN of the IAM role to use to modify Route53 DNS resources.	string	n/a	yes
tags	Tags to apply to all AWS resources created.	map(string)	{}	no

Outputs

Name	Description
bucket	The S3 bucket where egress IP address information is published.

Notes

Running pre-commit requires running terraform init in every directory that contains Terraform code. In this repository, these are the main directory and every directory under examples/.

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.