Skip to content

README.md

Latest commit

 

History

History
254 lines (204 loc) · 15.8 KB

README.md

File metadata and controls

254 lines (204 loc) · 15.8 KB

Contributors Forks Stargazers Issues Unlicense License


Logo

AWS Security Groups Module

PSA-compliant 3-tier security group architecture with mandatory rule descriptions and zero-egress database defaults.
Explore the docs »

View Demo · Report Bug · Request Feature

Documentation

Full auto-generated documentation of inputs, outputs, and resources: TERRAFORM-DOCS.md

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Security Features
  5. PSA Compliance Features
  6. Outputs
  7. Troubleshooting
  8. License

About The Project

This module implements a hardened 3-tier network security architecture (Web, App, Database) plus a dedicated Management tier. It enforces mandatory descriptions for all firewall rules to ensure auditability and PSA compliance.

Features

  • 3-Tier Isolation: Pre-configured flows between tiers (Web -> App -> DB).
  • Mandatory Descriptions: Every ingress/egress rule must have a human-readable description.
  • Zero-Egress Database: The database tier is configured with NO outbound rules by default.
  • HTTPS Enforcement: Web tier defaults to port 443 with optional port 80.
  • Management Tier: Dedicated SG for restricted SSH/RDP access.
  • Custom Rules: Support for injecting project-specific rules while maintaining the base security posture.

(back to top)

Usage

Basic Usage

module "security_groups" {
  source = "./terraform-aws-security-groups"

  project_name = "myapp"
  environment  = "prod"
  vpc_id       = "vpc-12345678"
  name_prefix  = "myapp-prod"

  allowed_web_cidrs        = ["0.0.0.0/0"]
  allowed_management_cidrs = ["203.0.113.0/24"]
  app_port                 = 8080
  db_port                  = 5432
}

Advanced Usage with Custom Rules

module "sg" {
  source = "./terraform-aws-security-groups"

  project_name             = "complex-app"
  environment              = "prod"
  vpc_id                   = module.vpc.vpc_id
  name_prefix              = "complex-app"
  allowed_management_cidrs = ["203.0.113.0/24"]

  web_custom_ingress = [
    {
      from_port   = 8443
      to_port     = 8443
      protocol    = "tcp"
      cidr_blocks = ["1.2.3.4/32"]
      description = "Custom management webhook"
    }
  ]
}

(back to top)

Security Features

  • Description Enforcement: Prevents the creation of "blind" firewall rules.
  • Lateral Movement Protection: Rules are strictly limited to the necessary target security groups.
  • No Wide-Open Egress: All tiers have scoped egress; DB tier has NONE.
  • Management Lockdown: SSH/RDP access is disabled by default and requires explicit CIDR whitelisting.
  • ICMP Disabled: Standard ping/discovery is disabled by default to reduce the attack surface.

(back to top)

PSA Compliance Features

This module implements the following PSA compliance features (referencing 10-Strukturierte_PSA_Anforderungen_Netzwerk_LLM.pdf):

Security Controls

  • Req 6 (Access Control): Strict ACL-like protection for management interfaces.
  • Req 14 (L7 Inspection): Designed to sit behind ALB/WAF for deep inspection.
  • Req 3.66-04 (Isolation): Consistent naming and tagging for multi-tenant isolation.
  • Auditability: Mandatory descriptions ensure every rule is traceable to a requirement.

(back to top)

Troubleshooting

Connection Refused between Tiers

  • Verify the app_port or db_port matches your application configuration.
  • Check that the resources (e.g., EC2, RDS) are actually assigned to the correct security group IDs output by this module.

SSH/RDP Not Working

  • Ensure your IP is included in allowed_management_cidrs.
  • Verify the create_management_sg = true.

(back to top)

Requirements

Name Version
terraform >=1.3

Providers

Name Version
aws n/a

Modules

No modules.

Resources

Name Type
aws_security_group.app_tier resource
aws_security_group.db_tier resource
aws_security_group.management resource
aws_security_group.web_tier resource
aws_security_group_rule.app_custom resource
aws_security_group_rule.app_from_web_ingress resource
aws_security_group_rule.app_https_egress resource
aws_security_group_rule.app_to_db_egress resource
aws_security_group_rule.db_from_app_ingress resource
aws_security_group_rule.mgmt_https_egress resource
aws_security_group_rule.mgmt_rdp_ingress resource
aws_security_group_rule.mgmt_ssh_egress resource
aws_security_group_rule.mgmt_ssh_ingress resource
aws_security_group_rule.web_custom resource
aws_security_group_rule.web_http_ingress resource
aws_security_group_rule.web_https_egress resource
aws_security_group_rule.web_https_ingress resource
aws_security_group_rule.web_to_app_egress resource

Inputs

Name Description Type Default Required
allow_http Allow HTTP (port 80) traffic - HTTPS (443) is always enabled bool false no
allow_rdp Allow RDP (port 3389) for Windows management bool false no
allowed_https_egress_cidrs CIDR blocks allowed for HTTPS egress from managed security groups list(string) 
[
  "0.0.0.0/0"
]
 no
allowed_management_cidrs CIDR blocks allowed for management access list(string) n/a yes
allowed_web_cidrs CIDR blocks allowed to access the web tier list(string) 
[
  "0.0.0.0/0"
]
 no
app_custom_ingress List of custom ingress rules for app tier 
list(object({
    from_port   = number
    to_port     = optional(number)
    protocol    = optional(string, "tcp")
    cidr_blocks = list(string)
    description = optional(string, "Custom application ingress rule")
  }))
 [] no
app_port Port for application tier communication number 8080 no
app_tier_sg_ids List of application tier security group IDs (if not creating app tier SG) list(string) [] no
create_app_tier_sg Create security group for application tier bool true no
create_db_tier_sg Create security group for database tier bool true no
create_management_sg Create security group for management/bastion access bool true no
create_web_tier_sg Create security group for web tier bool true no
db_port Port for database communication number 5432 no
db_tier_sg_ids List of database tier security group IDs (if not creating db tier SG) list(string) [] no
environment Environment (e.g., prod, dev, test) string n/a yes
internal_cidrs Internal CIDR blocks for management access list(string) 
[
  "10.0.0.0/16"
]
 no
name_prefix Prefix for resource names (if not provided, will use project-environment pattern) string "" no
project_name Name of the project string n/a yes
tags Additional tags for all resources map(string) {} no
vpc_id ID of the VPC where security groups will be created string n/a yes
web_custom_ingress List of custom ingress rules for web tier 
list(object({
    from_port   = number
    to_port     = optional(number)
    protocol    = optional(string, "tcp")
    cidr_blocks = list(string)
    description = optional(string, "Custom web ingress rule")
  }))
 [] no
web_tier_sg_ids List of web tier security group IDs (if not creating web tier SG) list(string) [] no

Outputs

Name Description
app_tier_sg_arn The ARN of the application tier security group
app_tier_sg_id The ID of the application tier security group
app_tier_sg_name The name of the application tier security group
db_tier_sg_arn The ARN of the database tier security group
db_tier_sg_id The ID of the database tier security group
db_tier_sg_name The name of the database tier security group
management_sg_arn The ARN of the management security group
management_sg_id The ID of the management security group
management_sg_name The name of the management security group
security_group_ids Map of managed security group IDs
security_group_names Map of managed security group names
web_tier_sg_arn The ARN of the web tier security group
web_tier_sg_id The ID of the web tier security group
web_tier_sg_name The name of the web tier security group