From 6b398bd067518d82865f6504018a4b85de861140 Mon Sep 17 00:00:00 2001 From: badra001 Date: Fri, 26 Nov 2021 10:51:06 -0500 Subject: [PATCH] update readme --- CHANGELOG.md | 4 +- README.md | 19 ++- cloudtrail-key/README.md | 7 +- cloudtrail-key/versions.tf | 14 +++ cloudtrail/README.md | 113 +++++++++++++++--- cloudtrail/main.tf | 119 ++++++++++++++++--- cloudtrail/versions.tf | 14 +++ examples/cloudtrail/cloudtrail_full.tf | 38 ++++++ examples/cloudtrail/cloudtrail_simple.tf | 18 +++ examples/cloudtrail/org_cloudtrail_simple.tf | 23 ++++ 10 files changed, 329 insertions(+), 40 deletions(-) create mode 100644 cloudtrail-key/versions.tf create mode 100644 cloudtrail/versions.tf create mode 100644 examples/cloudtrail/cloudtrail_full.tf create mode 100644 examples/cloudtrail/cloudtrail_simple.tf create mode 100644 examples/cloudtrail/org_cloudtrail_simple.tf diff --git a/CHANGELOG.md b/CHANGELOG.md index b17f01c..a72b45a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -129,4 +129,6 @@ * v1.14.0 -- 20211115 - cloudtrail-key - - create module to setup a KMS ke per region for cloudtrail + - create module to setup a KMS key per region for cloudtrail + - cloudtrail + - create module to setup needed resources for cloudtrail, cloudwatch logs, sns, sqs, and splunk diff --git a/README.md b/README.md index dccaf0b..f852f84 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,23 @@ This sets the SES domain of the form `{account_id}.aws.mail.census.gov`. At this so be sure run it in the west region for govcloud. ### object-logging -### cloudtrail -### config + +This is in its own module [aws-setup-s3-object-logging](https://github.e.it.census.gov/terraform-modules/aws-setup-s3-object-logging). + +### [cloudtrail-key](cloudtrail-key) + +This creates a KMS key (region specific) for use by CloudTrail and all its resources (Cloudwatch Log, SNS, SQS, S3). + +### [cloudtrail](cloudtrail) + +This creates a CloudTrail (region specific) and supporing resources Cloudwatch Log, SNS, SQS, S3. It requires a KMS +key created specifically for this, from [cloudtrail-key](cloudtrail-key) above. It also creates Splunk input +configuration files. + +### [config](config) + +This creates the Config setup, a few Config Rules, SNS and SQS and Splunk input configurations files. + ### gpg-key ## Submodules :: Common diff --git a/cloudtrail-key/README.md b/cloudtrail-key/README.md index 176d26d..61a86d0 100644 --- a/cloudtrail-key/README.md +++ b/cloudtrail-key/README.md @@ -47,13 +47,16 @@ module "cloudtrail_key_full" { ## Requirements -No requirements. +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 0.12 | +| [aws](#requirement\_aws) | >= 3.66.0 | ## Providers | Name | Version | |------|---------| -| [aws](#provider\_aws) | n/a | +| [aws](#provider\_aws) | >= 3.66.0 | ## Modules diff --git a/cloudtrail-key/versions.tf b/cloudtrail-key/versions.tf new file mode 100644 index 0000000..3d116e6 --- /dev/null +++ b/cloudtrail-key/versions.tf @@ -0,0 +1,14 @@ +terraform { + required_providers { + aws = { + source = "hashicorp/aws" + version = ">= 3.66.0" + } + # ldap = { + # source = "trevex/ldap" + # version = ">= 0.5.4" + # } + } + required_version = ">= 0.12" + # required_version = ">= 0.13" +} diff --git a/cloudtrail/README.md b/cloudtrail/README.md index 7beb7af..a3af4b0 100644 --- a/cloudtrail/README.md +++ b/cloudtrail/README.md @@ -5,48 +5,129 @@ cloudwatch log groups, and associated permissions. It also generates a splunk c for pulling cloudtrail events. * S3 bucket -* S3 bucket policy +* SNS Topic +* SQS Queue (and Deadletter queue) +* Cloudwatch Log +* setup/*.conf files for Splunk + * inputs.{name}.{account}.{region}.conf -# Usage -Here is a simple example, the one most commonly expected to be used. +Once setup, the gnerated Splunk configuration files can be provided to the Splunk team for ingesting +as CloudTrail. + +## Usage: Simple + +This siomple configuration is how it will typically be deployed. ```hcl +module "cloudtrail_key" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail-key" + + tags = local.common_tags +} + module "cloudtrail" { source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail" - # account_alias = "do2-govcloud" - name = "mycloudtrail" - access_log_bucket = "myaccesslogbucket" - kms_key_management_identifiers = [ "arn:aws:iam::079788916859:role/r-inf-cloud-admin" ] + account_alias = var.account_alias + access_log_bucket = module.logs.bucket_id + kms_key_arn = module.cloudtrail_key.kms_key_arn + + enable_sns = true + enable_sqs = true + + tags = local.common_tags } ``` -This one can be used if you need to customize stuff, though really, the defaults are all built -for a reason, and deployment code (i.e., Ansible) will expect these defaults to be used in -variable file generation. +## Usage: Extended + +This shows the creation of a key with additional variables, along with a policy for key access (currently +just a placholder), and the cloudtrail with more variables offered. ```hcl -module "cloudtrail_full" { +module "cloudtrail_key" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail-key" + + name = "mycloudtrail" + kms_admin_roles = ["arn:aws:iam::079788916859:role/r-inf-cloud-admin"] + kms_policy_document = data.aws_iam_policy_document.myct_policy.json - # logs is generally not needed and not recommended - component_tags = { - "s3" = { + tags = { + Environment = "csvd:infrastructure" + } + + component_tags = { + "kms" = { "SpecialTag1" = "something" "SpecialTag2" = "somethingElse" } } } + +data "aws_iam_policy_document" "myct_policy" {} + +module "cloudtrail" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail" + + name = "mycloudtrail" + account_alias = var.account_alias + access_log_bucket = module.logs.bucket_id + kms_key_arn = module.cloudtrail_key.kms_key_arn + + enable_organization = false + enable_sns = true + enable_sqs = true + + tags = merge( + local.common_tags, + tomap({ Environment = "csvd:infrastructure" }), + ) +} +```hcl + +## Usage: Organization Cloudtrail + +This can be used for creation of an organization cloud trail. It is only applicable to the master +account of the organization, so you won't see this one used very often. + +```hcl +data "aws_organizations_organization" "org" {} + +module "org_cloudtrail_key" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail-key" + + name = "org-cloudtrail" + tags = local.common_tags +} + +module "org_cloudtrail" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail" + + account_alias = var.account_alias + enable_organization = true + access_log_bucket = module.logs.bucket_id + kms_key_arn = module.org_cloudtrail_key.kms_key_arn + organization_id = data.aws_organizations_organization.org.id + + enable_sns = true + enable_sqs = true + + tags = local.common_tags +} ``` ## Requirements -No requirements. +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 0.12 | +| [aws](#requirement\_aws) | >= 3.66.0 | ## Providers | Name | Version | |------|---------| -| [aws](#provider\_aws) | n/a | +| [aws](#provider\_aws) | >= 3.66.0 | | [null](#provider\_null) | n/a | | [random](#provider\_random) | n/a | | [template](#provider\_template) | n/a | diff --git a/cloudtrail/main.tf b/cloudtrail/main.tf index be9b9af..31682eb 100644 --- a/cloudtrail/main.tf +++ b/cloudtrail/main.tf @@ -4,39 +4,118 @@ * This set up the needed components for cloudtrail in a region: S3, KMS key, SNS, SQS, cloudtrail, * cloudwatch log groups, and associated permissions. It also generates a splunk configuration to be used * for pulling cloudtrail events. -* +* * * S3 bucket -* * S3 bucket policy +* * SNS Topic +* * SQS Queue (and Deadletter queue) +* * Cloudwatch Log +* * setup/*.conf files for Splunk +* * inputs.{name}.{account}.{region}.conf * -* # Usage -* Here is a simple example, the one most commonly expected to be used. +* Once setup, the gnerated Splunk configuration files can be provided to the Splunk team for ingesting +* as CloudTrail. * +* ## Usage: Simple +* +* This siomple configuration is how it will typically be deployed. +* * ```hcl +* module "cloudtrail_key" { +* source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail-key" +* +* tags = local.common_tags +* } +* * module "cloudtrail" { * source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail" -* -* # account_alias = "do2-govcloud" -* name = "mycloudtrail" -* access_log_bucket = "myaccesslogbucket" -* kms_key_management_identifiers = [ "arn:aws:iam::079788916859:role/r-inf-cloud-admin" ] +* +* account_alias = var.account_alias +* access_log_bucket = module.logs.bucket_id +* kms_key_arn = module.cloudtrail_key.kms_key_arn +* +* enable_sns = true +* enable_sqs = true +* +* tags = local.common_tags * } * ``` -* -* This one can be used if you need to customize stuff, though really, the defaults are all built -* for a reason, and deployment code (i.e., Ansible) will expect these defaults to be used in -* variable file generation. -* +* +* ## Usage: Extended +* +* This shows the creation of a key with additional variables, along with a policy for key access (currently +* just a placholder), and the cloudtrail with more variables offered. +* * ```hcl -* module "cloudtrail_full" { -* -* # logs is generally not needed and not recommended -* component_tags = { -* "s3" = { +* module "cloudtrail_key" { +* source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail-key" +* +* name = "mycloudtrail" +* kms_admin_roles = ["arn:aws:iam::079788916859:role/r-inf-cloud-admin"] +* kms_policy_document = data.aws_iam_policy_document.myct_policy.json +* +* tags = { +* Environment = "csvd:infrastructure" +* } +* +* component_tags = { +* "kms" = { * "SpecialTag1" = "something" * "SpecialTag2" = "somethingElse" * } * } * } +* +* data "aws_iam_policy_document" "myct_policy" {} +* +* module "cloudtrail" { +* source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail" +* +* name = "mycloudtrail" +* account_alias = var.account_alias +* access_log_bucket = module.logs.bucket_id +* kms_key_arn = module.cloudtrail_key.kms_key_arn +* +* enable_organization = false +* enable_sns = true +* enable_sqs = true +* +* tags = merge( +* local.common_tags, +* tomap({ Environment = "csvd:infrastructure" }), +* ) +* } +* ```hcl +* +* +* ## Usage: Organization Cloudtrail +* +* This can be used for creation of an organization cloud trail. It is only applicable to the master +* account of the organization, so you won't see this one used very often. +* +* ```hcl +* data "aws_organizations_organization" "org" {} +* +* module "org_cloudtrail_key" { +* source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail-key" +* +* name = "org-cloudtrail" +* tags = local.common_tags +* } +* +* module "org_cloudtrail" { +* source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail" +* +* account_alias = var.account_alias +* enable_organization = true +* access_log_bucket = module.logs.bucket_id +* kms_key_arn = module.org_cloudtrail_key.kms_key_arn +* organization_id = data.aws_organizations_organization.org.id +* +* enable_sns = true +* enable_sqs = true +* +* tags = local.common_tags +* } * ``` */ @@ -77,3 +156,5 @@ data "aws_kms_key" "incoming_key" { # data "aws_organizations_organization" "org" {} + + diff --git a/cloudtrail/versions.tf b/cloudtrail/versions.tf new file mode 100644 index 0000000..3d116e6 --- /dev/null +++ b/cloudtrail/versions.tf @@ -0,0 +1,14 @@ +terraform { + required_providers { + aws = { + source = "hashicorp/aws" + version = ">= 3.66.0" + } + # ldap = { + # source = "trevex/ldap" + # version = ">= 0.5.4" + # } + } + required_version = ">= 0.12" + # required_version = ">= 0.13" +} diff --git a/examples/cloudtrail/cloudtrail_full.tf b/examples/cloudtrail/cloudtrail_full.tf new file mode 100644 index 0000000..d70f5c0 --- /dev/null +++ b/examples/cloudtrail/cloudtrail_full.tf @@ -0,0 +1,38 @@ +module "cloudtrail_key" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail-key" + + name = "mycloudtrail" + kms_admin_roles = ["arn:aws:iam::079788916859:role/r-inf-cloud-admin"] + kms_policy_document = data.aws_iam_policy_document.myct_policy.json + + tags = { + Environment = "csvd:infrastructure" + } + + component_tags = { + "kms" = { + "SpecialTag1" = "something" + "SpecialTag2" = "somethingElse" + } + } +} + +data "aws_iam_policy_document" "myct_policy" {} + +module "cloudtrail" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail" + + name = "mycloudtrail" + account_alias = var.account_alias + access_log_bucket = module.logs.bucket_id + kms_key_arn = module.cloudtrail_key.kms_key_arn + + enable_organization = false + enable_sns = true + enable_sqs = true + + tags = merge( + local.common_tags, + tomap({ Environment = "csvd:infrastructure" }), + ) +} diff --git a/examples/cloudtrail/cloudtrail_simple.tf b/examples/cloudtrail/cloudtrail_simple.tf new file mode 100644 index 0000000..329599a --- /dev/null +++ b/examples/cloudtrail/cloudtrail_simple.tf @@ -0,0 +1,18 @@ +module "cloudtrail_key" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail-key" + + tags = local.common_tags +} + +module "cloudtrail" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail" + + account_alias = var.account_alias + access_log_bucket = module.logs.bucket_id + kms_key_arn = module.cloudtrail_key.kms_key_arn + + enable_sns = true + enable_sqs = true + + tags = local.common_tags +} diff --git a/examples/cloudtrail/org_cloudtrail_simple.tf b/examples/cloudtrail/org_cloudtrail_simple.tf new file mode 100644 index 0000000..409f0ef --- /dev/null +++ b/examples/cloudtrail/org_cloudtrail_simple.tf @@ -0,0 +1,23 @@ +data "aws_organizations_organization" "org" {} + +module "org_cloudtrail_key" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail-key" + + name = "org-cloudtrail" + tags = local.common_tags +} + +module "org_cloudtrail" { + source = "git@github.e.it.census.gov:terraform-modules/aws-inf-setup.git//cloudtrail" + + account_alias = var.account_alias + enable_organization = true + access_log_bucket = module.logs.bucket_id + kms_key_arn = module.org_cloudtrail_key.kms_key_arn + organization_id = data.aws_organizations_organization.org.id + + enable_sns = true + enable_sqs = true + + tags = local.common_tags +}