docs: improve inline comments

config_baselines.tf

@@ -1,6 +1,6 @@
 # --------------------------------------------------------------------------------------------------
-# Create an IAM Role for publishing VPC Flow Logs into CloudWatch Logs group.
-# Reference: https://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/flow-logs.html#flow-logs-iam
+# Create an IAM Role for AWS Config recorder to publish results and send notifications.
+# Reference: https://docs.aws.amazon.com/config/latest/developerguide/gs-cli-prereq.html#gs-cli-create-iamrole
 # --------------------------------------------------------------------------------------------------
 
 resource "aws_iam_role" "recorder" {
@@ -26,23 +26,24 @@ POLICY
 # See https://docs.aws.amazon.com/config/latest/developerguide/iamrole-permissions.html
 data "aws_iam_policy_document" "recoder_publish_policy" {
   statement {
-    actions = ["s3:PutObject"]
+    actions   = ["s3:PutObject"]
     resources = ["${module.audit_log_bucket.this_bucket_arn}/config/AWSLogs/${var.aws_account_id}/*"]
 
     condition {
-      test = "StringLike"
+      test     = "StringLike"
       variable = "s3:x-amz-acl"
-      values = ["bucket-owner-full-control"]
+      values   = ["bucket-owner-full-control"]
     }
   }
 
   statement {
-    actions = ["s3:GetBucketAcl"]
+    actions   = ["s3:GetBucketAcl"]
     resources = ["${module.audit_log_bucket.this_bucket_arn}"]
   }
 
   statement {
     actions = ["sns:Publish"]
+
     resources = [
       "${module.config_baseline_ap-northeast-1.config_topic_arn}",
       "${module.config_baseline_ap-northeast-2.config_topic_arn}",
@@ -64,8 +65,8 @@ data "aws_iam_policy_document" "recoder_publish_policy" {
 }
 
 resource "aws_iam_role_policy" "recoder_publish_policy" {
-  name = "${var.config_iam_role_policy_name}"
-  role = "${aws_iam_role.recorder.id}"
+  name   = "${var.config_iam_role_policy_name}"
+  role   = "${aws_iam_role.recorder.id}"
   policy = "${data.aws_iam_policy_document.recoder_publish_policy.json}"
 }
 
@@ -75,7 +76,8 @@ resource "aws_iam_role_policy_attachment" "recoder_read_policy" {
 }
 
 # --------------------------------------------------------------------------------------------------
-# Apply VPC baseline for each region.
+# AWS Config Baseline
+# Needs to be set up in each region.
 # --------------------------------------------------------------------------------------------------
 
 module "config_baseline_ap-northeast-1" {
@@ -285,7 +287,7 @@ resource "aws_config_config_rule" "root_mfa" {
     source_identifier = "ROOT_ACCOUNT_MFA_ENABLED"
   }
 
-  # Ensure this rule is created after the configuration recorder.
+  # Ensure this rule is created after all configuration recorders.
   depends_on = [
     "module.config_baseline_ap-northeast-1",
     "module.config_baseline_ap-northeast-2",

examples/root-example/regions.tf

@@ -1,6 +1,6 @@
 # --------------------------------------------------------------------------------------------------
 # A list of providers for all AWS regions.
-# See also: https://docs.aws.amazon.com/general/latest/gr/rande.html
+# Reference: https://docs.aws.amazon.com/general/latest/gr/rande.html
 # --------------------------------------------------------------------------------------------------
 
 provider "aws" {

guardduty_baselines.tf

@@ -1,3 +1,9 @@
+# --------------------------------------------------------------------------------------------------
+# GuardDuty Baseline
+# Needs to be set up in each region.
+# This is an extra configuration which is not included in CIS benchmark.
+# --------------------------------------------------------------------------------------------------
+
 module "guardduty_baseline_ap-northeast-1" {
   source = "./modules/guardduty-baseline"
 

modules/alarm-baseline/main.tf

@@ -1,7 +1,15 @@
+# --------------------------------------------------------------------------------------------------
+# The SNS topic to which CloudWatch alarms send events.
+# --------------------------------------------------------------------------------------------------
+
 resource "aws_sns_topic" "alarms" {
   name = "${var.sns_topic_name}"
 }
 
+# --------------------------------------------------------------------------------------------------
+# CloudWatch metrics and alamrs defined in the CIS benchmark.
+# --------------------------------------------------------------------------------------------------
+
 resource "aws_cloudwatch_log_metric_filter" "unauthorized_api_calls" {
   name           = "UnauthorizedAPICalls"
   pattern        = "{ ($.errorCode = \"*UnauthorizedOperation\") || ($.errorCode = \"AccessDenied*\") }"

modules/config-baseline/README.md

@@ -20,4 +20,3 @@ Enable AWS Config in all regions to automatically take configuration snapshots.
 |------|-------------|
 | config_topic_arn | The ARN of the SNS topic that AWS Config delivers notifications to. |
 | configuration_recorder_id | The name of the configuration recorder. |
-

modules/config-baseline/main.tf

@@ -1,3 +1,7 @@
+# --------------------------------------------------------------------------------------------------
+# Set up AWS Config recorder and let it publish results and send notifications.
+# --------------------------------------------------------------------------------------------------
+
 resource "aws_sns_topic" "config" {
   name = "${var.sns_topic_name}"
 }
@@ -34,6 +38,10 @@ resource "aws_config_configuration_recorder_status" "recorder" {
   depends_on = ["aws_config_delivery_channel.bucket"]
 }
 
+# --------------------------------------------------------------------------------------------------
+# A config rule to monitor open known ports.
+# --------------------------------------------------------------------------------------------------
+
 resource "aws_config_config_rule" "restricted_ports" {
   name = "RestrictedIncomingTraffic"
 

modules/guardduty-baseline/README.md

@@ -7,4 +7,3 @@ Enable GuardDuty in all regions.
 | Name | Description |
 |------|-------------|
 | guardduty_detector_id | The ID of the GuardDuty detector. |
-

modules/guardduty-baseline/main.tf

@@ -1,3 +1,7 @@
+# --------------------------------------------------------------------------------------------------
+# Enables GuardDuty.
+# --------------------------------------------------------------------------------------------------
+
 resource "aws_guardduty_detector" "default" {
   enable = true
 }

modules/iam-baseline/README.md

@@ -36,4 +36,3 @@
 | master_iam_role_name | The name of the IAM role used for the master user. |
 | support_iam_role_arn | The ARN of the IAM role used for the support user. |
 | support_iam_role_name | The name of the IAM role used for the support user. |
-

modules/secure-bucket/README.md

@@ -17,4 +17,3 @@ Creates a S3 bucket with access logging enabled.
 | log_bucket_id | The ID of the S3 bucket used for storing access logs of this bucket. |
 | this_bucket_arn | The ARN of this S3 bucket. |
 | this_bucket_id | The ID of this S3 bucket. |
-

modules/vpc-baseline/README.md

@@ -1,6 +1,6 @@
 # vpc-baseline
 
-## Features 
+## Features
 
 - Enable VPC Flow Logs with the default VPC in all regions.
 - Remove all rules associated with default route tables, default network ACLs and default security groups in the default VPC in all regions.
@@ -20,4 +20,3 @@
 | default_route_table_id | The ID of the default route table. |
 | default_security_group_id | The ID of the default security group. |
 | default_vpc_id | The ID of the default VPC. |
-

modules/vpc-baseline/main.tf

@@ -1,5 +1,9 @@
 data "aws_availability_zones" "available" {}
 
+# --------------------------------------------------------------------------------------------------
+# Clears rules associated with default resources.
+# --------------------------------------------------------------------------------------------------
+
 resource "aws_default_vpc" "default" {
   tags {
     Name = "Default VPC"
@@ -43,6 +47,10 @@ resource "aws_default_security_group" "default" {
   }
 }
 
+# --------------------------------------------------------------------------------------------------
+# Enable VPC Flow Logs for the default VPC.
+# --------------------------------------------------------------------------------------------------
+
 resource "aws_flow_log" "default_vpc_flow_logs" {
   log_group_name = "${var.vpc_flow_logs_group_name}"
   iam_role_arn   = "${var.vpc_flow_logs_iam_role_arn}"

providers.tf

@@ -1,6 +1,6 @@
 # --------------------------------------------------------------------------------------------------
 # A list of providers for all AWS regions.
-# See also: https://docs.aws.amazon.com/general/latest/gr/rande.html
+# Reference: https://docs.aws.amazon.com/general/latest/gr/rande.html
 # --------------------------------------------------------------------------------------------------
 
 provider "aws" {}

vpc_baselines.tf

@@ -53,7 +53,8 @@ resource "aws_cloudwatch_log_group" "default_vpc_flow_logs" {
 }
 
 # --------------------------------------------------------------------------------------------------
-# Apply VPC baseline for each region.
+# VPC Baseline
+# Needs to be set up in each region.
 # --------------------------------------------------------------------------------------------------
 
 module "vpc_baseline_ap-northeast-1" {