feat: Add implementation for root module combining firewall and policy

Author: bryantbiggs

README.md

@@ -6,10 +6,12 @@ Terraform module which creates AWS network firewall resources.
 
 See [`examples`](https://github.com/clowdhaus/terraform-aws-network-firewall/tree/main/examples) directory for working examples to reference:
 
+### Firewall & Firewall Policy
 ```hcl
 module "network_firewall" {
   source = "clowdhaus/network-firewall/aws"
 
+
   tags = {
     Terraform   = "true"
     Environment = "dev"
@@ -37,19 +39,64 @@ No providers.
 
 ## Modules
 
-No modules.
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_firewall"></a> [firewall](#module\_firewall) | ./modules/firewall | n/a |
+| <a name="module_policy"></a> [policy](#module\_policy) | ./modules/policy | n/a |
 
 ## Resources
 
 No resources.
 
 ## Inputs
 
-No inputs.
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_create"></a> [create](#input\_create) | Controls if resources should be created | `bool` | `true` | no |
+| <a name="input_create_logging_configuration"></a> [create\_logging\_configuration](#input\_create\_logging\_configuration) | Controls if a Logging Configuration should be created | `bool` | `false` | no |
+| <a name="input_create_policy"></a> [create\_policy](#input\_create\_policy) | Controls if policy should be created | `bool` | `true` | no |
+| <a name="input_create_policy_resource_policy"></a> [create\_policy\_resource\_policy](#input\_create\_policy\_resource\_policy) | Controls if a resource policy should be created | `bool` | `false` | no |
+| <a name="input_delete_protection"></a> [delete\_protection](#input\_delete\_protection) | A boolean flag indicating whether it is possible to delete the firewall. Defaults to `true` | `bool` | `true` | no |
+| <a name="input_description"></a> [description](#input\_description) | A friendly description of the firewall | `string` | `""` | no |
+| <a name="input_encryption_configuration"></a> [encryption\_configuration](#input\_encryption\_configuration) | KMS encryption configuration settings | `any` | `{}` | no |
+| <a name="input_firewall_policy_arn"></a> [firewall\_policy\_arn](#input\_firewall\_policy\_arn) | The ARN of the Firewall Policy to use | `string` | `""` | no |
+| <a name="input_firewall_policy_change_protection"></a> [firewall\_policy\_change\_protection](#input\_firewall\_policy\_change\_protection) | A boolean flag indicating whether it is possible to change the associated firewall policy. Defaults to `false` | `bool` | `null` | no |
+| <a name="input_logging_configuration_destination_config"></a> [logging\_configuration\_destination\_config](#input\_logging\_configuration\_destination\_config) | A list of min 1, max 2 configuration blocks describing the destination for the logging configuration | `any` | `[]` | no |
+| <a name="input_name"></a> [name](#input\_name) | A friendly name of the firewall | `string` | `""` | no |
+| <a name="input_policy_attach_resource_policy"></a> [policy\_attach\_resource\_policy](#input\_policy\_attach\_resource\_policy) | Controls if a resource policy should be attached to the firewall policy | `bool` | `false` | no |
+| <a name="input_policy_description"></a> [policy\_description](#input\_policy\_description) | A friendly description of the firewall policy | `string` | `null` | no |
+| <a name="input_policy_encryption_configuration"></a> [policy\_encryption\_configuration](#input\_policy\_encryption\_configuration) | KMS encryption configuration settings | `any` | `{}` | no |
+| <a name="input_policy_name"></a> [policy\_name](#input\_policy\_name) | A friendly name of the firewall policy | `string` | `""` | no |
+| <a name="input_policy_ram_resource_associations"></a> [policy\_ram\_resource\_associations](#input\_policy\_ram\_resource\_associations) | A map of RAM resource associations for the created firewall policy | `map(string)` | `{}` | no |
+| <a name="input_policy_resource_policy"></a> [policy\_resource\_policy](#input\_policy\_resource\_policy) | The policy JSON to use for the resource policy; required when `create_resource_policy` is `false` | `string` | `""` | no |
+| <a name="input_policy_resource_policy_actions"></a> [policy\_resource\_policy\_actions](#input\_policy\_resource\_policy\_actions) | A list of IAM actions allowed in the resource policy | `list(string)` | `[]` | no |
+| <a name="input_policy_resource_policy_principals"></a> [policy\_resource\_policy\_principals](#input\_policy\_resource\_policy\_principals) | A list of IAM principals allowed in the resource policy | `list(string)` | `[]` | no |
+| <a name="input_policy_stateful_default_actions"></a> [policy\_stateful\_default\_actions](#input\_policy\_stateful\_default\_actions) | Set of actions to take on a packet if it does not match any stateful rules in the policy. This can only be specified if the policy has a `stateful_engine_options` block with a rule\_order value of `STRICT_ORDER`. You can specify one of either or neither values of `aws:drop_strict` or `aws:drop_established`, as well as any combination of `aws:alert_strict` and `aws:alert_established` | `list(string)` | `[]` | no |
+| <a name="input_policy_stateful_engine_options"></a> [policy\_stateful\_engine\_options](#input\_policy\_stateful\_engine\_options) | A configuration block that defines options on how the policy handles stateful rules. See [Stateful Engine Options](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/networkfirewall_firewall_policy#stateful-engine-options) for details | `any` | `{}` | no |
+| <a name="input_policy_stateful_rule_group_reference"></a> [policy\_stateful\_rule\_group\_reference](#input\_policy\_stateful\_rule\_group\_reference) | Set of configuration blocks containing references to the stateful rule groups that are used in the policy. See [Stateful Rule Group Reference](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/networkfirewall_firewall_policy#stateful-rule-group-reference) for details | `any` | `{}` | no |
+| <a name="input_policy_stateless_custom_action"></a> [policy\_stateless\_custom\_action](#input\_policy\_stateless\_custom\_action) | Set of configuration blocks describing the custom action definitions that are available for use in the firewall policy's `stateless_default_actions` | `any` | `{}` | no |
+| <a name="input_policy_stateless_default_actions"></a> [policy\_stateless\_default\_actions](#input\_policy\_stateless\_default\_actions) | Set of actions to take on a packet if it does not match any of the stateless rules in the policy. You must specify one of the standard actions including: `aws:drop`, `aws:pass`, or `aws:forward_to_sfe` | `list(string)` | <pre>[<br>  "aws:pass"<br>]</pre> | no |
+| <a name="input_policy_stateless_fragment_default_actions"></a> [policy\_stateless\_fragment\_default\_actions](#input\_policy\_stateless\_fragment\_default\_actions) | Set of actions to take on a fragmented packet if it does not match any of the stateless rules in the policy. You must specify one of the standard actions including: `aws:drop`, `aws:pass`, or `aws:forward_to_sfe` | `list(string)` | <pre>[<br>  "aws:pass"<br>]</pre> | no |
+| <a name="input_policy_stateless_rule_group_reference"></a> [policy\_stateless\_rule\_group\_reference](#input\_policy\_stateless\_rule\_group\_reference) | Set of configuration blocks containing references to the stateless rule groups that are used in the policy. See [Stateless Rule Group Reference](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/networkfirewall_firewall_policy#stateless-rule-group-reference) for details | `any` | `{}` | no |
+| <a name="input_policy_tags"></a> [policy\_tags](#input\_policy\_tags) | A map of tags to add to all resources | `map(string)` | `{}` | no |
+| <a name="input_subnet_change_protection"></a> [subnet\_change\_protection](#input\_subnet\_change\_protection) | A boolean flag indicating whether it is possible to change the associated subnet(s). Defaults to `true` | `bool` | `true` | no |
+| <a name="input_subnet_mapping"></a> [subnet\_mapping](#input\_subnet\_mapping) | Set of configuration blocks describing the public subnets. Each subnet must belong to a different Availability Zone in the VPC. AWS Network Firewall creates a firewall endpoint in each subnet | `any` | `{}` | no |
+| <a name="input_tags"></a> [tags](#input\_tags) | A map of tags to add to all resources | `map(string)` | `{}` | no |
+| <a name="input_vpc_id"></a> [vpc\_id](#input\_vpc\_id) | The unique identifier of the VPC where AWS Network Firewall should create the firewall | `string` | `""` | no |
 
 ## Outputs
 
-No outputs.
+| Name | Description |
+|------|-------------|
+| <a name="output_arn"></a> [arn](#output\_arn) | The Amazon Resource Name (ARN) that identifies the firewall |
+| <a name="output_id"></a> [id](#output\_id) | The Amazon Resource Name (ARN) that identifies the firewall |
+| <a name="output_logging_configuration_id"></a> [logging\_configuration\_id](#output\_logging\_configuration\_id) | The Amazon Resource Name (ARN) of the associated firewall |
+| <a name="output_policy_arn"></a> [policy\_arn](#output\_policy\_arn) | The Amazon Resource Name (ARN) that identifies the firewall policy |
+| <a name="output_policy_id"></a> [policy\_id](#output\_policy\_id) | The Amazon Resource Name (ARN) that identifies the firewall policy |
+| <a name="output_policy_resource_policy_id"></a> [policy\_resource\_policy\_id](#output\_policy\_resource\_policy\_id) | The Amazon Resource Name (ARN) of the firewall policy associated with the resource policy |
+| <a name="output_policy_update_token"></a> [policy\_update\_token](#output\_policy\_update\_token) | A string token used when updating a firewall policy |
+| <a name="output_status"></a> [status](#output\_status) | Nested list of information about the current status of the firewall |
+| <a name="output_update_token"></a> [update\_token](#output\_update\_token) | A string token used when updating a firewall |
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 
 ## License

examples/complete/README.md

@@ -1,8 +1,9 @@
 # Complete AWS Network Firewall Example
 
-Configuration in this directory creates:
+Configuration in this directory creates the following as separate module definitions:
 
-- <XXX>
+- AWS Network Firewall & Firewall Policy
+- AWS Network Firewall Rule Group
 
 ## Usage
 
@@ -34,13 +35,21 @@ Note that this example may create resources which will incur monetary charges on
 
 | Name | Source | Version |
 |------|--------|---------|
+| <a name="module_network_firewall"></a> [network\_firewall](#module\_network\_firewall) | ../.. | n/a |
+| <a name="module_network_firewall_disabled"></a> [network\_firewall\_disabled](#module\_network\_firewall\_disabled) | ../.. | n/a |
+| <a name="module_network_firewall_rule_group_stateful"></a> [network\_firewall\_rule\_group\_stateful](#module\_network\_firewall\_rule\_group\_stateful) | ../../modules/rule-group | n/a |
+| <a name="module_network_firewall_rule_group_stateless"></a> [network\_firewall\_rule\_group\_stateless](#module\_network\_firewall\_rule\_group\_stateless) | ../../modules/rule-group | n/a |
 | <a name="module_vpc"></a> [vpc](#module\_vpc) | terraform-aws-modules/vpc/aws | ~> 5.0 |
 
 ## Resources
 
 | Name | Type |
 |------|------|
+| [aws_cloudwatch_log_group.logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group) | resource |
+| [aws_s3_bucket.network_firewall_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket) | resource |
+| [aws_s3_bucket_policy.network_firewall_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_policy) | resource |
 | [aws_availability_zones.available](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/availability_zones) | data source |
+| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
 
 ## Inputs
 

examples/complete/main.tf

@@ -2,14 +2,17 @@ provider "aws" {
   region = local.region
 }
 
+data "aws_caller_identity" "current" {}
 data "aws_availability_zones" "available" {}
 
 locals {
-  region = "us-east-1"
-  name   = "network-firewall-ex-${basename(path.cwd)}"
+  region     = "us-east-1"
+  name       = "network-firewall-ex-${basename(path.cwd)}"
+  account_id = data.aws_caller_identity.current.account_id
 
   vpc_cidr = "10.0.0.0/16"
-  azs      = slice(data.aws_availability_zones.available.names, 0, 3)
+  num_azs  = 3
+  azs      = slice(data.aws_availability_zones.available.names, 0, local.num_azs)
 
   tags = {
     Name       = local.name
@@ -22,19 +25,161 @@ locals {
 # network firewall Module
 ################################################################################
 
-# module "network_firewall" {
-#   source = "../.."
+module "network_firewall" {
+  source = "../.."
 
-#   create = false
+  # Firewall
+  name        = local.name
+  description = "Example network firewall"
 
-#   tags = local.tags
-# }
+  # Only for example
+  delete_protection                 = false
+  firewall_policy_change_protection = false
+  subnet_change_protection          = false
 
-# module "network_firewall_disabled" {
-#   source = "../.."
+  vpc_id = module.vpc.vpc_id
+  subnet_mapping = { for i in range(0, local.num_azs) :
+    "subnet-${i}" => {
+      subnet_id       = element(module.vpc.public_subnets, i)
+      ip_address_type = "IPV4"
+    }
+  }
+
+  # Logging configuration
+  create_logging_configuration = true
+  logging_configuration_destination_config = [
+    {
+      log_destination = {
+        logGroup = aws_cloudwatch_log_group.logs.name
+      }
+      log_destination_type = "CloudWatchLogs"
+      log_type             = "ALERT"
+    },
+    {
+      log_destination = {
+        bucketName = aws_s3_bucket.network_firewall_logs.id
+        prefix     = local.name
+      }
+      log_destination_type = "S3"
+      log_type             = "FLOW"
+    }
+  ]
+
+  # Policy
+  policy_name        = local.name
+  policy_description = "Example network firewall policy"
 
-#   create = false
-# }
+  policy_stateful_rule_group_reference = {
+    one = { resource_arn = module.network_firewall_rule_group_stateful.arn }
+  }
+
+  policy_stateless_default_actions          = ["aws:pass"]
+  policy_stateless_fragment_default_actions = ["aws:drop"]
+  policy_stateless_rule_group_reference = {
+    one = {
+      priority     = 1
+      resource_arn = module.network_firewall_rule_group_stateless.arn
+    }
+  }
+
+  tags = local.tags
+}
+
+module "network_firewall_disabled" {
+  source = "../.."
+
+  create = false
+}
+
+################################################################################
+# Network Firewall Rule Group
+################################################################################
+
+module "network_firewall_rule_group_stateful" {
+  source = "../../modules/rule-group"
+
+  name        = "${local.name}-stateful"
+  description = "Stateful Inspection for denying access to a domain"
+  type        = "STATEFUL"
+  capacity    = 100
+
+  rule_group = {
+    rules_source = {
+      rules_source_list = {
+        generated_rules_type = "DENYLIST"
+        target_types         = ["HTTP_HOST"]
+        targets              = ["test.example.com"]
+      }
+    }
+  }
+
+  # Resource Policy
+  create_resource_policy     = true
+  attach_resource_policy     = true
+  resource_policy_principals = ["arn:aws:iam::${local.account_id}:root"]
+
+  tags = local.tags
+}
+
+module "network_firewall_rule_group_stateless" {
+  source = "../../modules/rule-group"
+
+  name        = "${local.name}-stateless"
+  description = "Stateless Inspection with a Custom Action"
+  type        = "STATELESS"
+  capacity    = 100
+
+  rule_group = {
+    rules_source = {
+      stateless_rules_and_custom_actions = {
+        custom_action = [{
+          action_definition = {
+            publish_metric_action = {
+              dimension = [{
+                value = "2"
+              }]
+            }
+          }
+          action_name = "ExampleMetricsAction"
+        }]
+        stateless_rule = [{
+          priority = 1
+          rule_definition = {
+            actions = ["aws:pass", "ExampleMetricsAction"]
+            match_attributes = {
+              source = [{
+                address_definition = "1.2.3.4/32"
+              }]
+              source_port = [{
+                from_port = 443
+                to_port   = 443
+              }]
+              destination = [{
+                address_definition = "124.1.1.5/32"
+              }]
+              destination_port = [{
+                from_port = 443
+                to_port   = 443
+              }]
+              protocols = [6]
+              tcp_flag = [{
+                flags = ["SYN"]
+                masks = ["SYN", "ACK"]
+              }]
+            }
+          }
+        }]
+      }
+    }
+  }
+
+  # Resource Policy
+  create_resource_policy     = true
+  attach_resource_policy     = true
+  resource_policy_principals = ["arn:aws:iam::${local.account_id}:root"]
+
+  tags = local.tags
+}
 
 ################################################################################
 # Supporting Resources
@@ -56,3 +201,62 @@ module "vpc" {
 
   tags = local.tags
 }
+
+resource "aws_cloudwatch_log_group" "logs" {
+  name              = "${local.name}-logs"
+  retention_in_days = 7
+
+  tags = local.tags
+}
+
+resource "aws_s3_bucket" "network_firewall_logs" {
+  bucket        = "${local.name}-network-firewall-logs-${local.account_id}"
+  force_destroy = true
+
+  tags = local.tags
+}
+
+# Logging configuration automatically adds this policy if not present
+resource "aws_s3_bucket_policy" "network_firewall_logs" {
+  bucket = aws_s3_bucket.network_firewall_logs.id
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Action = "s3:PutObject"
+        Condition = {
+          ArnLike = {
+            "aws:SourceArn" = "arn:aws:logs:${local.region}:${local.account_id}:*"
+          }
+          StringEquals = {
+            "aws:SourceAccount" = local.account_id
+            "s3:x-amz-acl"      = "bucket-owner-full-control"
+          }
+        }
+        Effect = "Allow"
+        Principal = {
+          Service = "delivery.logs.amazonaws.com"
+        }
+        Resource = "${aws_s3_bucket.network_firewall_logs.arn}/${local.name}/AWSLogs/${local.account_id}/*"
+        Sid      = "AWSLogDeliveryWrite"
+      },
+      {
+        Action = "s3:GetBucketAcl"
+        Condition = {
+          ArnLike = {
+            "aws:SourceArn" = "arn:aws:logs:${local.region}:${local.account_id}:*"
+          }
+          StringEquals = {
+            "aws:SourceAccount" = local.account_id
+          }
+        }
+        Effect = "Allow"
+        Principal = {
+          Service = "delivery.logs.amazonaws.com"
+        }
+        Resource = aws_s3_bucket.network_firewall_logs.arn
+        Sid      = "AWSLogDeliveryAclCheck"
+      },
+    ]
+  })
+}

examples/separate/main.tf

@@ -32,12 +32,12 @@ module "network_firewall" {
   description = "Example network firewall"
 
   # Only for example
-  delete_protection = false
-
-  firewall_policy_arn               = module.network_firewall_policy.arn
+  delete_protection                 = false
   firewall_policy_change_protection = false
   subnet_change_protection          = false
 
+  firewall_policy_arn = module.network_firewall_policy.arn
+
   vpc_id = module.vpc.vpc_id
   subnet_mapping = { for i in range(0, local.num_azs) :
     "subnet-${i}" => {