Skip to content

Commit

Permalink
Merge pull request #1 from pablo19sc/main
Browse files Browse the repository at this point in the history 
First Commit - AWS Network Firewall Module
  • Loading branch information
@drewmullen
drewmullen authored Aug 17, 2022
2 parents 83f3dc6 + a6dbb16 commit b7345eb
Show file tree
Hide file tree
Showing 123 changed files with 4,794 additions and 199 deletions.
4 changes: 4 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,3 +40,7 @@ terraform.rc

go.mod
go.sum

# DS_Store

.DS_Store
221 changes: 164 additions & 57 deletions .header.md
View file
Original file line number Diff line number Diff line change
@@ -1,57 +1,164 @@
# Creating modules for AWS I&A Organization

This repo template is used to seed Terraform Module templates for the [AWS I&A GitHub organization](https://github.com/aws-ia). Usage of this template is allowed per included license. PRs to this template will be considered but are not guaranteed to be included. Consider creating an issue to discuss a feature you want to include before taking the time to create a PR.
### TL;DR

1. [install pre-commit](https://pre-commit.com/)
2. configure pre-commit: `pre-commit install`
3. install required tools
- [tflint](https://github.com/terraform-linters/tflint)
- [tfsec](https://aquasecurity.github.io/tfsec/v1.0.11/)
- [terraform-docs](https://github.com/terraform-docs/terraform-docs)
- [golang](https://go.dev/doc/install) (for macos you can use `brew`)
- [coreutils](https://www.gnu.org/software/coreutils/)

Write code according to [I&A module standards](https://aws-ia.github.io/standards-terraform/)

## Module Documentation

**Do not manually update README.md**. `terraform-docs` is used to generate README files. For any instructions an content, please update [.header.md](./.header.md) then simply run `terraform-docs ./` or allow the `pre-commit` to do so.

## Terratest

Please include tests to validate your examples/<> root modules, at a minimum. This can be accomplished with usually only slight modifications to the [boilerplate test provided in this template](./test/examples_basic_test.go)

### Configure and run Terratest

1. Install

[golang](https://go.dev/doc/install) (for macos you can use `brew`)
2. Change directory into the test folder.

`cd test`
3. Initialize your test

go mod init github.com/[github org]/[repository]

`go mod init github.com/aws-ia/terraform-aws-vpc`
4. Run tidy

`git mod tidy`
5. Install Terratest

`go get github.com/gruntwork-io/terratest/modules/terraform`
6. Run test (You can have multiple test files).
- Run all tests

`go test`
- Run a specific test with a timeout

`go test -run examples_basic_test.go -timeout 45m`
## Module Standards

For best practices and information on developing with Terraform, see the [I&A Module Standards](https://aws-ia.github.io/standards-terraform/)

## Continuous Integration

The I&A team uses AWS CodeBuild to perform continuous integration (CI) within the organization. Our CI uses the a repo's `.pre-commit-config.yaml` file as well as some other checks. All PRs with other CI will be rejected. See our [FAQ](https://aws-ia.github.io/standards-terraform/faq/#are-modules-protected-by-ci-automation) for more details.
# AWS Network Firewall Module

AWS Network Firewall is a stateful, managed, network firewall and intrusion detection and prevention service for Amazon Virtual Private Clouds (Amazon VPCs). This module can be used to deploy an AWS Network Firewall resource in the desired VPC, automating all the routing and logging configuration when the resource is deployed.

This module only handles the creation of the infrastructure, leaving full freedom to the user to define the firewall rules (which should be done outside the module). Same applies to IAM roles and KMS keys when you define the logging of the firewall - rememeber that it is a best practice to encryt at rest your firewall logs.

## Usage

To create AWS Network Firewall in your VPC, you need to provide the following information:

- `network_firewall_name`= (Required|string) Name to provide the AWS Network Firewall resource.
- `network_firewall_policy`= (Required|string) ARN of the firewall policy to apply in the AWS Network Firewall resource. Check the definition of [AWS Network Firewall Policies](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/networkfirewall_firewall_policy) and [AWS Network Firewall Rule Groups](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/networkfirewall_rule_group) to see how you can create firewall policies.
- `network_firewall_policy_change_protection` = (Optional|bool) To indicate whether it is possible to change the associated firewall policy after creation. Defaults to `false`.
- `network_firewall_subnet_change_protection` = (Optional|bool) To indicate whether it is possible to change the associated subnet(s) after creation. Defaults to `false`.
- `vpc_id` = (Required|string) ID of the VPC where the AWS Network Firewall resource should be placed.
- `vpc_subnets` = (Required|map(string)) Map of subnet IDs to place the Network Firewall endpoints. Example:

```hcl
vpc_subnets = {
us-east-1a = subnet-IDa
us-east-1b = subnet-IDb
us-east-1c = subnet-IDc
}
```

- `routing_configuration` = (Required|any) Configuration of the routing desired in the VPC. Depending the type of VPC, the information to provide is different. The type of VPCs supported are: `single_vpc`, `intra_vpc_inspection`, `centralized_inspection_without_egress`, and `centralized_inspection_with_egress`. **Only one key (option) can be defined**. More information about the differences between each of the VPC types (and examples) can be checked in the section below.
- `tags`= (Optional|map(string)) List of tags to apply to the AWS Network Firewall resource.

## Routing configuration

Once the AWS Network Firewall resource is created, the routing to the firewall endpoints need to be created. However, depending the VPC and how we want to inspect the traffic, this routing configuration is going to be different. The module supports the routing configuration of 4 different types of VPCs, covering the most common [Inspection Deployment models with with AWS Network Firewall](https://d1.awsstatic.com/architecture-diagrams/ArchitectureDiagrams/inspection-deployment-models-with-AWS-network-firewall-ra.pdf).

### Single VPC

The first use case is when the firewall endpoints are located in the VPC to inspect the traffic from/to workloads in that same VPC - distributed inspection model. If using this routing configuration (`simple_vpc`) it is expected to place the firewall endpoints in subnets between the Internet gateway (IGW) and the public subnets (where you can place the Elastic Load Balancers and NAT gateways). The image below shows an example of the architecture, routing configuration, and traffic flow.

<p align="center">
<img src="./images/single_vpc.png" alt="Single VPC - Architecture diagram" width="100%">
</p>

An example of the definition of this routing configuration is the following one:

```hcl
routing_configuration = {
single_vpc = {
igw_route_table = rtb-ID
protected_subnet_route_tables = {
us-east-1a = rtb-IDa
us-east-1b = rtb-IDb
us-east-1c = rtb-IDc
}
protected_subnet_cidr_blocks = {
us-east-1a = "10.0.0.0/24"
us-east-1b = "10.0.1.0/24"
us-east-1c = "10.0.2.0/24"
}
}
}
```

### Intra-VPC Inspection

When placing firewall endpoints to inspect traffic between workloads inside the same VPC (between your EC2 instances and the database layer, for example) you can take advantage of the VPC routing enhacement - which allows you to include more specific routing than the local one (`intra_vpc_inspection`). The image below shows an example of the architecture, routing configuration, and traffic flow.

<p align="center">
<img src="./images/single_vpc_intra_subnet.png" alt="Intra-VPC Inspection - Architecture diagram" width="100%">
</p>

The module expects in this variable two variables:

- `number_routes` = (Required|number) Number of configured items in the `routes` variable.
- `routes` = (Required|list(map(string))) List of intra-VPC route configurations. Each item of the list expects a map of strings with two values: `source_subnet_route_tables` and `destination_subnet_cidr_blocks`. These two values indicate the route table of the source subnet and the CIDR block of the destination subnet in which the firewall endpoint is going to be placed in between (several Availability Zones can be added). Remember that only one direction is configured per item, so in most situations you will need two items per group of subnets to inspect.

An example of the definition of this routing configuration is the following one.

```hcl
routing_configuration = {
intra_vpc_inspection = {
number_routes = 2
routes = {
{
source_subnet_route_tables = {
us-east-1a = rtb-IDa
us-east-1b = rtb-IDb
us-east-1c = rtb-IDc
}
destination_subnet_cidr_blocks = {
us-east-1a = "10.0.0.0/24"
us-east-1b = "10.0.1.0/24"
us-east-1c = "10.0.2.0/24"
}
},
{
source_subnet_route_tables = {
us-east-1a = rtb-IDaa
us-east-1b = rtb-IDbb
us-east-1c = rtb-IDcc
}
destination_subnet_cidr_blocks = {
us-east-1a = "10.0.3.0/24"
us-east-1b = "10.0.4.0/24"
us-east-1c = "10.0.5.0/24"
}
}
}
}
}
```

### Hub and Spoke with Inspection VPC

The use case covers the creation of a centralized Inspection VPC in a Hub and Spoke architecture with AWS Transit Gateway, with the idea of managing the traffic inspection at scale. When using the key `centralized_inspection_without_egress` it is supposed that the Inspection VPC created is only used to place the AWS Transit Gateway ENIs and the firewall endpoints. The image below shows an example of the architecture, routing configuration, and traffic flow.

<p align="center">
<img src="./images/centralized_vpc.png" alt="Central Inspection VPC - Architecture diagram" width="100%">
</p>

An example of the definition of this routing configuration is the following one:

```hcl
routing_configuration = {
centralized_inspection_without_egress = {
tgw_subnet_route_tables = {
us-east-1a = rtb-IDa
us-east-1b = rtb-IDb
us-east-1c = rtb-IDc
}
}
}
```

### Hub and Spoke with Inspection VPC (with egress traffic)

The use case covers the creation of a centralized Inspection VPC in a Hub and Spoke architecture with AWS Transit Gateway, with the idea of managing the traffic inspection at scale. When using the key `centralized_inspection_with_egress` it is supposed that the Inspection VPC also has access to the Internet, to centralize inspection and egress traffic at the same time. The image below shows an example of the architecture, routing configuration, and traffic flow.

<p align="center">
<img src="./images/centralized_vpc_with_egress.png" alt="Central Inspection VPC with Egress traffic - Architecture diagram" width="100%">
</p>

An example of the definition of this routing configuration is the following one:

```hcl
routing_configuration = {
centralized_inspection_with_egress = {
tgw_subnet_route_tables = {
us-east-1a = rtb-IDa
us-east-1b = rtb-IDb
us-east-1c = rtb-IDc
}
public_subnet_route_tables = {
us-east-1a = rtb-IDaa
us-east-1b = rtb-IDbb
us-east-1c = rtb-IDcc
}
network_cidr_blocks = ["10.0.0.0/8", "192.168.0.0/24"]
}
}
```

## References

- Reference Architecture: [Inspection Deployment models with with AWS Network Firewall](https://d1.awsstatic.com/architecture-diagrams/ArchitectureDiagrams/inspection-deployment-models-with-AWS-network-firewall-ra.pdf)
- Blog post: [Deployment models for AWS Network Firewall](https://aws.amazon.com/blogs/networking-and-content-delivery/deployment-models-for-aws-network-firewall/)
- Blog post: [Deployment models for AWS Network Firewall with VPC routing enhancements](https://aws.amazon.com/blogs/networking-and-content-delivery/deployment-models-for-aws-network-firewall-with-vpc-routing-enhancements/)
Loading

0 comments on commit b7345eb

Please sign in to comment.