Thanks to visit codestin.com
Credit goes to github.com

Skip to content

appvia/terraform-aws-compliance

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

99 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Appvia Banner

Terraform Registry Latest Release Slack Community Contributors

Github Actions

Terraform AWS Compliance Module

Overview

The Terraform AWS Compliance module provides a comprehensive, opinionated solution for implementing enterprise-grade security and compliance controls across AWS Organizations. This module orchestrates multiple AWS security services to create a unified compliance framework that ensures consistent security posture, automated monitoring, and regulatory adherence across all organizational units and accounts.

Purpose & Intent

Problem Statement

Large organizations face significant challenges in maintaining security and compliance across their AWS infrastructure:

  • Fragmented Security Posture: Multiple accounts and organizational units often have inconsistent security configurations
  • Compliance Complexity: Meeting regulatory requirements (SOC 2, PCI DSS, HIPAA, etc.) across distributed infrastructure
  • Manual Security Management: Time-consuming and error-prone manual configuration of security services
  • Lack of Centralized Visibility: Difficulty in monitoring security posture across the entire organization
  • Inconsistent Standards: Different teams implementing security controls differently
  • Audit Preparation: Complex and time-consuming compliance reporting and evidence collection

Solution

This module provides a centralized, automated approach to security and compliance that:

  • Centralizes Security Management: Implements Security Hub as the central security command center
  • Automates Compliance Monitoring: Deploys AWS Config rules across organizational units via StackSets
  • Enables Continuous Monitoring: Provides real-time security findings and compliance status
  • Standardizes Security Controls: Applies consistent security policies across all accounts
  • Facilitates Audit Preparation: Generates comprehensive compliance reports and evidence
  • Reduces Operational Overhead: Automates security service configuration and management

Key Features

đź”’ Comprehensive Security Services

  • AWS Security Hub: Centralized security findings aggregation and management
  • AWS Config: Configuration compliance monitoring and drift detection
  • AWS Access Analyzer: Unused access identification and IAM policy analysis
  • AWS Inspector: Vulnerability assessment for EC2, ECR, and Lambda workloads
  • AWS Macie: Sensitive data discovery and protection
  • AWS GuardDuty: Threat detection and security monitoring

📊 Advanced Compliance Management

  • Multi-Standard Support: CIS, NIST, PCI DSS, AWS Foundational Security Best Practices
  • Custom Security Policies: Configurable security controls with custom parameters
  • Organizational Unit Targeting: Granular policy application across OUs and accounts
  • Rule Group Management: Organized configuration rules for different environments
  • Compliance Reporting: Automated compliance status reporting and evidence collection

đź”” Intelligent Notifications

  • Multi-Channel Alerts: Slack, Microsoft Teams, and email notifications
  • Severity-Based Filtering: Configurable alert thresholds (CRITICAL, HIGH, MEDIUM, LOW)
  • Real-Time Monitoring: EventBridge-driven instant security finding notifications
  • Customizable Templates: Tailored notification formats for different audiences
  • Escalation Workflows: Automated escalation based on finding severity

🏗️ Enterprise Architecture

  • StackSet Distribution: Automated deployment across organizational units
  • Regional Flexibility: Multi-region support with centralized management
  • Account Exclusion: Granular control over which accounts receive specific policies
  • Resource Tagging: Comprehensive tagging for governance and cost management
  • Dependency Management: Proper resource dependencies and lifecycle management

🛡️ Security & Governance

  • Least Privilege Access: Minimal IAM permissions for all operations
  • Encryption Support: KMS integration for sensitive data protection
  • Audit Trail: Comprehensive logging and monitoring capabilities
  • Policy Customization: Fine-tuned security controls based on organizational needs
  • Compliance Mapping: Direct mapping to regulatory frameworks and standards

⚙️ Operational Excellence

  • Terraform State Management: Full Terraform state management for all resources
  • Resource Tagging: Consistent tagging across all created resources
  • Output Management: Comprehensive outputs for integration with other modules
  • Dependency Management: Proper resource dependencies and lifecycle management
  • Rollback Capabilities: Safe rollback mechanisms for policy changes

Architecture

System Components

graph TB
    subgraph "Central Compliance Account"
        A[Security Hub Aggregator]
        B[Security Hub Organization Config]
        C[Config Rules StackSets]
        D[Access Analyzer]
        E[Inspector Organization Config]
        F[Macie StackSet]
        G[Notification System]
    end
    
    subgraph "Security Hub Policies"
        H[Foundational Best Practices]
        I[CIS Benchmarks]
        J[NIST 800-53]
        K[PCI DSS]
        L[Custom Policies]
    end
    
    subgraph "Organizational Units"
        M[Production OU]
        N[Development OU]
        O[Security OU]
        P[Compliance OU]
    end
    
    subgraph "Member Accounts"
        Q[Account 1]
        R[Account 2]
        S[Account N]
    end
    
    A --> H
    A --> I
    A --> J
    A --> K
    A --> L
    C --> M
    C --> N
    C --> O
    C --> P
    M --> Q
    N --> R
    O --> S
    G --> A
    D --> A
    E --> A
    F --> A
Loading

Data Flow

  1. Policy Definition: Security policies are defined in the central compliance account
  2. StackSet Distribution: Policies are distributed to organizational units via AWS StackSets
  3. Continuous Monitoring: AWS Config and Security Hub continuously monitor compliance
  4. Finding Generation: Security findings are generated and aggregated in Security Hub
  5. Notification Processing: Findings are processed and sent via configured notification channels
  6. Compliance Reporting: Automated reports are generated for audit and compliance purposes

Security Services Integration

  • Security Hub: Central aggregation point for all security findings
  • AWS Config: Configuration compliance monitoring and drift detection
  • Access Analyzer: IAM policy analysis and unused access identification
  • Inspector: Vulnerability assessment across compute workloads
  • Macie: Sensitive data discovery and classification
  • GuardDuty: Threat detection and security monitoring

Usage

Basic Usage - Foundational Security

module "compliance" {
  source = "appvia/compliance/aws"
  version = "0.1.0"

  region = "us-east-1"
  
  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
    Purpose     = "compliance"
  }

  securityhub = {
    aggregator = {
      create            = true
      linking_mode      = "ALL_REGIONS"
      specified_regions = ["us-east-1", "us-west-2"]
    }

    configuration = {
      auto_enable           = true
      auto_enable_standards = "DEFAULT"
      organization_configuration = {
        configuration_type = "CENTRAL"
      }
    }

    policies = {
      "foundational-security" = {
        enable      = true
        description = "AWS Foundational Security Best Practices for all accounts"
        
        associations = [
          { organization_unit = "ou-1234567890" }
        ]

        policy = {
          standard_arns = ["aws_foundational_best_practices"]
          controls = {
            disabled = [
              "Account.1",  # Security contact details
              "CloudTrail.1" # CloudTrail enabled (handled by org trail)
            ]
          }
        }
      }
    }
  }
}

Advanced Usage - Multi-Standard Compliance

module "compliance" {
  source = "appvia/compliance/aws"
  version = "0.1.0"

  region = "us-east-1"
  
  tags = {
    Environment     = "production"
    ComplianceLevel = "high"
    ManagedBy       = "terraform"
  }

  # Access Analyzer Configuration
  access_analyzer = {
    enable_unused_analyzer = true
    unused_analyzer_name   = "enterprise-unused-access"
    unused_access_age      = 90
  }

  # Inspector Configuration
  inspector = {
    enable              = true
    account_id          = "123456789012"
    enable_ec2_scan     = true
    enable_ecr_scan     = true
    enable_lambda_scan  = true
    enable_lambda_code_scan = true
  }

  # Macie Configuration
  macie = {
    enable                = true
    frequency             = "FIFTEEN_MINUTES"
    organizational_units  = ["ou-1234567890", "ou-0987654321"]
    excluded_accounts     = ["111111111111"] # Sandbox accounts
    stackset_name         = "enterprise-macie-config"
  }

  # Config Rules
  config = {
    stackset_name_prefix = "enterprise-config-"
    
    rule_groups = {
      "production-security" = {
        description = "Production security rules for critical workloads"
        associations = ["ou-prod-1234567890"]
        enabled_regions = ["us-east-1", "us-west-2"]
        
        rules = {
          "required-tags" = {
            description = "Validate required resource tags"
            identifier  = "REQUIRED_TAGS"
            resource_types = [
              "AWS::EC2::Instance",
              "AWS::S3::Bucket",
              "AWS::RDS::DBInstance"
            ]
            inputParameters = {
              tag1Key = "Environment"
              tag2Key = "Owner"
              tag3Key = "CostCenter"
            }
            max_execution_frequency = "TwentyFour_Hours"
          }
          
          "s3-bucket-encryption" = {
            description = "Ensure S3 buckets have encryption enabled"
            identifier  = "S3_BUCKET_SERVER_SIDE_ENCRYPTION_ENABLED"
            resource_types = ["AWS::S3::Bucket"]
            max_execution_frequency = "TwentyFour_Hours"
          }
        }
      }
    }
  }

  # Security Hub Configuration
  securityhub = {
    aggregator = {
      create            = true
      linking_mode      = "SPECIFIED_REGIONS"
      specified_regions = ["us-east-1", "us-west-2", "eu-west-1"]
    }

    configuration = {
      auto_enable           = true
      auto_enable_standards = "DEFAULT"
      organization_configuration = {
        configuration_type = "CENTRAL"
      }
    }

    notifications = {
      enable                = true
      eventbridge_rule_name = "enterprise-security-findings"
      severities            = ["CRITICAL", "HIGH"]
      sns_topic_queue_name  = "enterprise-security-alerts"
    }

    policies = {
      "cis-benchmark" = {
        enable      = true
        description = "CIS AWS Foundations Benchmark v1.4.0"
        
        associations = [
          { organization_unit = "ou-1234567890" }
        ]

        policy = {
          standard_arns = ["cis_v140"]
          controls = {
            disabled = [
              "CIS.1.1",  # Disable specific controls as needed
              "CIS.1.2"
            ]
          }
        }
      }

      "nist-800-53" = {
        enable      = true
        description = "NIST 800-53 Rev 5 compliance framework"
        
        associations = [
          { organization_unit = "ou-compliance-0987654321" }
        ]

        policy = {
          standard_arns = ["nist_sp_800_53_rev5"]
          controls = {
            custom_parameter = [
              {
                security_control_id = "AC.1"
                parameter = {
                  name       = "maxAccessKeyAge"
                  value_type = "NUMBER"
                  enum = {
                    value = "90"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }

  # Notification Configuration
  notifications = {
    slack = {
      webhook_url = "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
    }
    
    teams = {
      webhook_url = "https://outlook.office.com/webhook/YOUR/TEAMS/WEBHOOK"
    }
    
    email = {
      addresses = [
        "[email protected]",
        "[email protected]"
      ]
    }
  }
}

Use Cases

1. Enterprise Security Program

# For large enterprises with comprehensive security requirements
module "enterprise_compliance" {
  source = "appvia/compliance/aws"
  
  region = "us-east-1"
  
  securityhub = {
    aggregator = {
      create = true
      linking_mode = "ALL_REGIONS"
    }
    
    policies = {
      "enterprise-foundational" = {
        enable = true
        description = "Enterprise-wide foundational security controls"
        associations = [
          { organization_unit = "ou-all-accounts" }
        ]
        policy = {
          standard_arns = ["aws_foundational_best_practices"]
          controls = {
            disabled = [
              # Customize based on enterprise requirements
            ]
          }
        }
      }
    }
  }
  
  config = {
    rule_groups = {
      "enterprise-tagging" = {
        description = "Enterprise resource tagging standards"
        associations = ["ou-all-accounts"]
        rules = {
          "required-tags" = {
            description = "Validate enterprise tagging standards"
            identifier = "REQUIRED_TAGS"
            resource_types = ["AWS::EC2::Instance", "AWS::S3::Bucket"]
            inputParameters = {
              tag1Key = "Environment"
              tag2Key = "Owner"
              tag3Key = "CostCenter"
              tag4Key = "DataClassification"
            }
          }
        }
      }
    }
  }
  
  tags = {
    Environment = "production"
    BusinessUnit = "Security"
    Compliance = "required"
  }
}

2. Compliance-Focused Setup

# For organizations with strict regulatory requirements
module "compliance_focused" {
  source = "appvia/compliance/aws"
  
  region = "us-east-1"
  
  # Enable all security services
  access_analyzer = {
    enable_unused_analyzer = true
    unused_access_age = 30  # Stricter than default
  }
  
  inspector = {
    enable = true
    enable_ec2_scan = true
    enable_ecr_scan = true
    enable_lambda_scan = true
  }
  
  macie = {
    enable = true
    frequency = "FIFTEEN_MINUTES"
    organizational_units = ["ou-sensitive-data"]
  }
  
  securityhub = {
    policies = {
      "pci-dss-compliance" = {
        enable = true
        description = "PCI DSS v3.2.1 compliance controls"
        associations = [
          { organization_unit = "ou-payment-systems" }
        ]
        policy = {
          standard_arns = ["pci_dss"]
        }
      }
    }
  }
  
  notifications = {
    email = {
      addresses = [
        "[email protected]",
        "[email protected]",
        "[email protected]"
      ]
    }
  }
  
  tags = {
    Environment = "production"
    Compliance = "pci-dss"
    DataClassification = "confidential"
  }
}

3. Development Environment

# For development and testing environments
module "dev_compliance" {
  source = "appvia/compliance/aws"
  
  region = "us-east-1"
  
  securityhub = {
    configuration = {
      auto_enable = false  # Manual enablement for dev
      auto_enable_standards = "NONE"
    }
    
    policies = {
      "dev-foundational" = {
        enable = true
        description = "Basic security controls for development"
        associations = [
          { organization_unit = "ou-development" }
        ]
        policy = {
          standard_arns = ["aws_foundational_best_practices"]
          controls = {
            disabled = [
              # Disable controls that are too restrictive for dev
              "EC2.10",  # VPC endpoints
              "RDS.5",   # Multi-AZ
              "RDS.6"    # Enhanced monitoring
            ]
          }
        }
      }
    }
  }
  
  config = {
    rule_groups = {
      "dev-tagging" = {
        description = "Basic tagging requirements for dev"
        associations = ["ou-development"]
        rules = {
          "required-tags" = {
            description = "Validate basic resource tags"
            identifier = "REQUIRED_TAGS"
            resource_types = ["AWS::EC2::Instance", "AWS::S3::Bucket"]
            inputParameters = {
              tag1Key = "Environment"
              tag2Key = "Owner"
            }
          }
        }
      }
    }
  }
  
  tags = {
    Environment = "development"
    Purpose = "compliance"
  }
}

Monitoring & Troubleshooting

CloudWatch Logs and Metrics

The module creates comprehensive monitoring capabilities:

# View Security Hub findings
aws securityhub get-findings --filters '{"ComplianceStatus": [{"Value": "FAILED", "Comparison": "EQUALS"}]}'

# Monitor Config compliance
aws config get-compliance-summary-by-config-rule

# Check Access Analyzer findings
aws accessanalyzer list-findings --analyzer-arn arn:aws:access-analyzer:region:account:analyzer/analyzer-name

Key Monitoring Metrics

Service Metric Description Use Case
Security Hub Findings Number of security findings Monitor security posture
Config ComplianceByConfigRule Compliance status by rule Track configuration compliance
Access Analyzer UnusedAccessFindings Unused access findings Monitor IAM hygiene
Inspector VulnerabilityFindings Vulnerability findings Track security vulnerabilities

Common Issues & Solutions

1. StackSet Deployment Failures

Error: StackSet deployment failed for organizational unit

Solutions:

  • Verify organizational unit ARNs are correct
  • Check StackSet execution role permissions
  • Ensure target accounts have proper permissions
  • Review CloudFormation stack events for specific errors

2. Security Hub Policy Association Issues

Error: Security Hub policy association failed

Solutions:

  • Verify policy ID and target ID are correct
  • Check Security Hub organization configuration
  • Ensure proper IAM permissions for policy association
  • Verify target accounts are part of the organization

3. Notification Delivery Issues

Error: Notifications not being delivered

Solutions:

  • Verify webhook URLs are correct and accessible
  • Check EventBridge rule configuration
  • Ensure SNS topic permissions are correct
  • Verify Lambda function execution permissions

Operational Best Practices

  1. Regular Compliance Reviews: Schedule monthly compliance posture reviews
  2. Policy Updates: Keep security policies updated with latest standards
  3. Exception Management: Implement proper exception handling for disabled controls
  4. Training and Awareness: Provide training on compliance requirements
  5. Incident Response: Establish procedures for handling security findings

Requirements

Prerequisites

  • AWS Organizations enabled
  • Appropriate IAM permissions for Security Hub, Config, and StackSets
  • Organizational units properly configured
  • Notification channels (Slack, Teams, email) configured

AWS Services Used

  • AWS Security Hub
  • AWS Config
  • AWS Access Analyzer
  • AWS Inspector
  • AWS Macie
  • AWS GuardDuty (via separate module)
  • AWS StackSets
  • AWS EventBridge
  • Amazon SNS

Permissions Required

  • Security Hub organization administrator
  • Config organization administrator
  • StackSets administrator
  • IAM permissions for service configuration
  • CloudFormation permissions for StackSet templates

Update Documentation

The terraform-docs utility is used to generate this README. Follow the below steps to update:

  1. Make changes to the .terraform-docs.yml file
  2. Fetch the terraform-docs binary (https://terraform-docs.io/user-guide/installation/)
  3. Run terraform-docs markdown table --output-file ${PWD}/README.md --output-mode inject .

Providers

Name Version
aws >= 5.0.0

Inputs

Name Description Type Default Required
region The region to deploy the resources string n/a yes
tags A map of tags to add to the resources map(string) n/a yes
access_analyzer Configuration for the AWS Access Analyzer service
object({
enable_unused_analyzer = optional(bool, true)
# Indicates whether to enable the unused AWS Access Analyzer service
unused_analyzer_name = optional(string, "lza-unused-access-analyzer")
# The name of the unused AWS Access Analyzer service
unused_access_age = optional(number, 90)
})
null no
config Configuration for the securityhub organization managed rules
object({
stackset_name_prefix = optional(string, "lza-config-")

# The prefix added to the stacksets
rule_groups = optional(map(object({
associations = list(string)
# List of organizational units to deploy the managed rules
description = string
# Description for the rule group
enabled_regions = optional(list(string), null)
# List of regions to enable these rules
exclude_accounts = optional(list(string), null)
# The list of accounts to exclude from the organization managed rule
rules = map(object({
description = string
# The description of the organization managed rules
identifier = string
# The identifier of the organization managed rule
inputs = optional(map(string), {})
# The identifier of the organization managed rule scope
resource_types = list(string)
# The list of resource types to scope the organization managed rule
max_execution_frequency = optional(string, null)
# The max_execution_frequency of the rule
}))
})), {})
# The configuration for the securityhub organization managed rules
})
{
"rule_groups": {}
}
no
inspector Organizational configuration for the AWS Inspector service
object({
account_id = optional(string, null)
# The delegated administrator account ID for the AWS Inspector service
enable = optional(bool, false)
# Indicates whether to enable the AWS Inspector service
enable_ec2_scan = optional(bool, false)
# Indicates whether to enable the AWS Inspector service for EC2 instances
enable_ecr_scan = optional(bool, false)
# Indicates whether to enable the AWS Inspector service for ECR repositories
enable_lambda_scan = optional(bool, false)
# Indicates whether to enable the AWS Inspector service for Lambda functions
enable_lambda_code_scan = optional(bool, false)
# Indicates whether to enable the AWS Inspector service for Lambda code
})
{
"enable": false
}
no
macie Configuration for the AWS Macie service
object({
enable = optional(bool, false)
# Indicates whether to enable the AWS Macie service should be enabled in all accounts
excluded_accounts = optional(list(string), null)
# The list of accounts to exclude from the AWS Macie service
frequency = optional(string, "FIFTEEN_MINUTES")
# The frequency at which the AWS Macie service should be enabled
organizational_units = optional(list(string), null)
# The list of member accounts to associate with the AWS Macie service
stackset_name = optional(string, "lza-macie-configuration")
})
null no
notifications Configuration for the notifications
object({
email = optional(object({
addresses = optional(list(string), [])
}), null)
slack = optional(object({
lamdba_name = optional(string, "lz-securityhub-all-notifications-slack")
webhook_url = string
}), null)
teams = optional(object({
lamdba_name = optional(string, "lz-securityhub-all-notifications-teams")
webhook_url = string
}), null)
})
{
"email": {
"addresses": []
},
"slack": null,
"teams": null
}
no
securityhub Configuration for the securityhub
object({
aggregator = optional(object({
create = optional(bool, false)
# Indicates whether to create the securityhub
# Indicates whether to create the aggregator
linking_mode = optional(string, "ALL_REGIONS")
# Indicates whether to aggregate findings from all of the available regions
specified_regions = optional(list(string), null)
# A list of regions to aggregate findings from when using SPECIFIED_REGIONS linking mode
}), {
create = false
linking_mode = "ALL_REGIONS"
specified_regions = null
}
)
# The configuration for the aggregator
configuration = optional(object({
auto_enable = optional(bool, true)
# Indicates whether to automatically enable Security Hub
auto_enable_standards = optional(string, "DEFAULT")
# Indicates whether to automatically enable new controls and standards
organization_configuration = object({
configuration_type = optional(string, "CENTRAL")
# Indicates whether to enable Security Hub as a standalone service or as an organization master
})
# The configuration for the organization
}), {
auto_enable = false
auto_enable_standards = "DEFAULT"
organization_configuration = {
configuration_type = "CENTRAL"
}
})
# The configuration for the securityhub
notifications = optional(object({
enable = optional(bool, false)
# Indicates whether to enable the securityhub notifications
eventbridge_rule_name = optional(string, "lza-securityhub-all-notifications")
# The name of the event bridge rule
severities = optional(list(string), ["CRITICAL", "HIGH"])
# The list of severities to enable the notifications
sns_topic_queue_name = optional(string, "lza-securityhub-all-notifications")
# Name of the SNS topic to send the notifications
}), {
enable = false
eventbridge_rule_name = "lza-securityhub-all-notifications"
severities = []
sns_topic_queue_name = "lza-securityhub-all-notifications"
})
# The configuration for the notifications
policies = optional(map(object({
enable = optional(bool, true)
# Indicates whether the configuration policy is enabled
description = string
# The description of the configuration policy
associations = optional(list(object({
account_id = optional(string, null)
# The account ID to associate with the policy
organization_unit = optional(string, null)
# The organization unit to associate with the policy
})), [])
# The list of associations for the configuration policy
policy = object({
enable = optional(bool, true)
# Indicates whether the configuration policy is enabled
standard_arns = list(string)
# The ARNs of the standards to enable
controls = object({
disabled = optional(list(string), null)
# The list of control identifiers to disable
custom_parameter = optional(list(object({
security_control_id = string
# The ID of the security control
parameter = object({
name = string
# The name of the parameter
value_type = string
# The type of the parameter
enum = optional(object({
value = string
# The value of the parameter (if the type is ENUM)
}), null)
})
# The parameter for the security control
})), null)
})
# The parameter for the security control
})
# The configuration policy
})), {})
})
{
"aggregator": {
"create": false,
"linking_mode": "ALL_REGIONS",
"specified_regions": null
},
"configuration": {
"auto_enable": false,
"auto_enable_standards": "NONE",
"organization_configuration": {
"configuration_type": "CENTRAL"
}
},
"policies": {}
}
no

Outputs

Name Description
inspector_resource_types A list of resources type to enable for inspector
securityhub_policy_associations A map of policy associations by policy name
securityhub_policy_configurations A map of all the policies to the central configuration arns

About

Terraform module used to provision and configure opinionated security compliance

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Packages

No packages published

Contributors 7