breaking: move variables to objects and improve settings

.gitignore

@@ -7,3 +7,6 @@
 
 # .tfvars files
 *.tfvars
+
+# CheckOv pre-commit external modules path
+**/.external_modules/*

README.md

@@ -83,9 +83,49 @@ Once the event is delivered, the function `securityhub-events-suppressor` will b
 
 * Commit your changes, push and merge. The pipeline will automatically maintain the set of suppressions and store them in DynamoDB. If all above steps succeed, the finding is suppressed.
 
+### Examples
+
+Suppress a finding in all accounts:
+
+```yaml
+Suppressions:
+  "1.13":
+    - action: SUPPRESSED
+      rules:
+        - ^AWS::::Account:[0-9]{12}$
+      notes: A note about this suppression
+```
+
+Suppress a finding in some accounts (with comments):
+
+```yaml
+Suppressions:
+  EC2.17:
+    - action: SUPPRESSED
+      rules:
+        - ^arn:aws:ec2:eu-west-1:111111111111:instance/i-[0-9a-z]$ # can add comments here like
+        - ^arn:aws:ec2:eu-west-1:222222222222:instance/i-[0-9a-z]$ # the friendly IAM alias to more
+        - ^arn:aws:ec2:eu-west-1:333333333333:instance/i-[0-9a-z]$ # easily identify matches resources
+      notes: A note about this suppression
+```
+
+Suppress finding for specific resources:
+
+```yaml
+   EC2.18:
+     - action: SUPPRESSED
+       rules:
+         - arn:aws:ec2:eu-west-1:111111111111:security-group/sg-0ae8d23e1d28b1437
+         - arn:aws:ec2:eu-west-1:222222222222:security-group/sg-01f1aa5f8407c98b9
+       notes: A note about this suppression
+```
+
+> **Note**
+> There is no leading `^` or trailing `$` as we don't use a regex for specific resources.
+
 # Usage
 
-<!--- BEGIN_TF_DOCS --->
+<!-- BEGIN_TF_DOCS -->
 ## Requirements
 
 | Name | Version |
@@ -137,4 +177,4 @@ Once the event is delivered, the function `securityhub-events-suppressor` will b
 | lambda\_securityhub\_events\_suppressor\_sg\_id | This will output the security group id attached to the securityhub\_events\_suppressor Lambda. This can be used to tune ingress and egress rules. |
 | lambda\_securityhub\_streams\_suppressor\_sg\_id | This will output the security group id attached to the securityhub\_streams\_suppressor Lambda. This can be used to tune ingress and egress rules. |
 
-<!--- END_TF_DOCS --->
+<!-- END_TF_DOCS -->

UPGRADING.md

@@ -0,0 +1,41 @@
+# Upgrading Notes
+
+This document captures required refactoring on your part when upgrading to a module version that contains breaking changes.
+
+## Upgrading to v1.0.0
+
+### Behaviour
+
+- Timeouts of the suppressor lambdas have been increased to 120 seconds. The current timeout of 60 seconds is not always enough to process 100 records of findings.
+- The `create_servicenow_access_keys` variable, now called `servicenow_integration.create_access_keys` was not used in the code and therefore the default behaviour was that access keys would be created. This issue has been resolved.
+- The `create_allow_all_egress_rule` variable has been set to `false`.
+- The `tags` variable is now optional.
+
+### Variables
+
+The following variables have been replaced by a new variable `jira_integration`:
+
+- `jira_exclude_account_filter` -> `jira_integration.exclude_account_ids`
+- `jira_finding_severity_normalized` -> `jira_integration.finding_severity_normalized_threshold`
+- `jira_integration` -> `jira_integration.enabled`
+- `jira_issue_type` -> `jira_integration.issue_type`
+- `jira_project_key` -> `jira_integration.project_key`
+- `jira_secret_arn` -> `jira_integration.credentials_secret_arn`
+- `lambda_jira_name` -> `jira_integration.lambda_settings.name`
+- `lambda_jira_iam_role_name` -> `jira_integration.lambda_settings.iam_role_name`
+- Additionally you are now able to specify the `log_level`, `memory_size,` and `timeout` of the lambda.
+
+The following variables have been replaced by a new variable `servicenow_integration`:
+
+- `servicenow_integration` -> `servicenow_integration.enabled`
+- `create_servicenow_access_keys` -> `servicenow_integration.create_access_keys`
+
+The following variables have been replaced by a new variable `lambda_events_suppressor`:
+
+- `lambda_events_suppressor_name` -> `lambda_events_suppressor.name`
+- Additionally you are now able to specify the `log_level`, `memory_size,` and `timeout` of the lambda.
+
+The following variables have been replaced by a new variable `lambda_streams_suppressor`:
+
+- `lambda_streams_suppressor_name` -> `lambda_streams_suppressor.name`
+- Additionally you are now able to specify the `log_level`, `memory_size,` and `timeout` of the lambda.

examples/basic/main.tf

@@ -0,0 +1,20 @@
+provider "aws" {
+  region = "eu-west-1"
+}
+
+resource "aws_kms_key" "default" {
+  enable_key_rotation = true
+}
+
+resource "random_pet" "default" {
+  length = 8
+}
+
+module "security_hub_manager" {
+  providers = { aws = aws }
+  source    = "../../"
+
+  kms_key_arn    = aws_kms_key.default
+  s3_bucket_name = "securityhub-suppressor-artifacts-${random_pet.default.id}"
+  tags           = { Terraform = true }
+}

examples/basic/versions.tf

@@ -0,0 +1,22 @@
+terraform {
+  required_version = ">= 1.3.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 4.9"
+    }
+    local = {
+      source  = "hashicorp/local"
+      version = ">= 1.0"
+    }
+    null = {
+      source  = "hashicorp/null"
+      version = ">= 2.0"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 3.0"
+    }
+  }
+}

examples/jira-integration/main.tf

@@ -0,0 +1,52 @@
+provider "aws" {
+  region = "eu-west-1"
+}
+
+resource "aws_kms_key" "default" {
+  enable_key_rotation = true
+}
+
+resource "random_pet" "default" {
+  length = 8
+}
+
+resource "aws_secretsmanager_secret" "jira_credentials" {
+  description = "Security Hub Findings Manager Jira Credentials Secret"
+  kms_key_id  = aws_kms_key.default
+  name        = "lambda/jira_credentials_secret"
+}
+
+// tfsec:ignore:GEN003
+resource "aws_secretsmanager_secret_version" "jira_credentials" {
+  secret_id = aws_secretsmanager_secret.jira_credentials.id
+  secret_string = jsonencode({
+    "url"     = "https://jira.mycompany.com"
+    "apiuser" = "username"
+    "apikey"  = "apikey"
+  })
+}
+
+module "security_hub_manager" {
+  providers = { aws = aws }
+  source    = "../../"
+
+  kms_key_arn    = aws_kms_key.default
+  s3_bucket_name = "securityhub-suppressor-artifacts-${random_pet.default.id}"
+  tags           = { Terraform = true }
+
+  jira_integration = {
+    enabled                = true
+    credentials_secret_arn = aws_secretsmanager_secret.jira_credentials.arn
+    project_key            = "PROJECT"
+  }
+}
+
+resource "aws_security_group_rule" "lambda_jira_security_hub_to_jira" {
+  type              = "egress"
+  description       = "Allow access from lambda_jira_security_hub to Jira"
+  from_port         = 443
+  to_port           = 443
+  protocol          = "tcp"
+  cidr_blocks       = ["1.1.1.1/32"]
+  security_group_id = module.security_hub_manager.lambda_jira_security_hub_sg_id[0]
+}

examples/jira-integration/versions.tf

@@ -0,0 +1,22 @@
+terraform {
+  required_version = ">= 1.3.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 4.9"
+    }
+    local = {
+      source  = "hashicorp/local"
+      version = ">= 1.0"
+    }
+    null = {
+      source  = "hashicorp/null"
+      version = ">= 2.0"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 3.0"
+    }
+  }
+}

examples/servicenow-integration/main.tf

@@ -0,0 +1,24 @@
+provider "aws" {
+  region = "eu-west-1"
+}
+
+resource "aws_kms_key" "default" {
+  enable_key_rotation = true
+}
+
+resource "random_pet" "default" {
+  length = 8
+}
+
+module "security_hub_manager" {
+  providers = { aws = aws }
+  source    = "../../"
+
+  kms_key_arn    = aws_kms_key.default
+  s3_bucket_name = "securityhub-suppressor-artifacts-${random_pet.default.id}"
+  tags           = { Terraform = true }
+
+  servicenow_integration = {
+    enabled = true
+  }
+}

examples/servicenow-integration/versions.tf

@@ -0,0 +1,22 @@
+terraform {
+  required_version = ">= 1.3.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 4.9"
+    }
+    local = {
+      source  = "hashicorp/local"
+      version = ">= 1.0"
+    }
+    null = {
+      source  = "hashicorp/null"
+      version = ">= 2.0"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 3.0"
+    }
+  }
+}

jira.tf

@@ -1,8 +1,8 @@
 # IAM role to be assumed by Lambda Function
 module "lambda_jira_security_hub_role" {
-  count                 = var.jira_integration ? 1 : 0
+  count                 = var.jira_integration.enabled ? 1 : 0
   source                = "github.com/schubergphilis/terraform-aws-mcaf-role?ref=v0.3.2"
-  name                  = var.lambda_jira_iam_role_name
+  name                  = var.jira_integration.lambda_settings.iam_role_name
   create_policy         = true
   postfix               = false
   principal_identifiers = ["lambda.amazonaws.com"]
@@ -12,7 +12,7 @@ module "lambda_jira_security_hub_role" {
 }
 
 data "aws_iam_policy_document" "lambda_jira_security_hub" {
-  count = var.jira_integration ? 1 : 0
+  count = var.jira_integration.enabled ? 1 : 0
   statement {
     sid = "TrustEventsToStoreLogEvent"
     actions = [
@@ -32,7 +32,7 @@ data "aws_iam_policy_document" "lambda_jira_security_hub" {
       "secretsmanager:GetSecretValue"
     ]
     resources = [
-      var.jira_secret_arn
+      var.jira_integration.credentials_secret_arn
     ]
   }
 
@@ -70,14 +70,14 @@ data "aws_iam_policy_document" "lambda_jira_security_hub" {
 
 # Lambda VPC Execution role policy attachment
 resource "aws_iam_role_policy_attachment" "lambda_jira_security_hub_role_vpc_policy" {
-  count      = var.jira_integration && var.subnet_ids != null ? 1 : 0
+  count      = var.jira_integration.enabled && var.subnet_ids != null ? 1 : 0
   role       = module.lambda_jira_security_hub_role[0].id
   policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole"
 }
 
 # Create a Lambda zip deployment package with code and dependencies
 module "lambda_jira_deployment_package" {
-  count                    = var.jira_integration ? 1 : 0
+  count                    = var.jira_integration.enabled ? 1 : 0
   source                   = "terraform-aws-modules/lambda/aws"
   version                  = "~> 3.3.0"
   create_function          = false
@@ -92,10 +92,10 @@ module "lambda_jira_deployment_package" {
 # Lambda function to create Jira ticket for Security Hub findings and set the workflow state to NOTIFIED
 module "lambda_jira_security_hub" {
   #checkov:skip=CKV_AWS_272:Code signing not used for now
-  count                        = var.jira_integration ? 1 : 0
+  count                        = var.jira_integration.enabled ? 1 : 0
   providers                    = { aws.lambda = aws }
   source                       = "github.com/schubergphilis/terraform-aws-mcaf-lambda?ref=v0.3.3"
-  name                         = var.lambda_jira_name
+  name                         = var.jira_integration.lambda_settings.name
   create_allow_all_egress_rule = var.create_allow_all_egress_rule
   create_policy                = false
   create_s3_dummy_object       = false
@@ -104,22 +104,22 @@ module "lambda_jira_security_hub" {
   handler                      = "securityhub_jira.lambda_handler"
   kms_key_arn                  = var.kms_key_arn
   log_retention                = 365
-  memory_size                  = 256
+  memory_size                  = var.jira_integration.lambda_settings.memory_size
   role_arn                     = module.lambda_jira_security_hub_role[0].arn
   runtime                      = "python3.8"
   s3_bucket                    = var.s3_bucket_name
   s3_key                       = module.lambda_jira_deployment_package[0].s3_object.key
   s3_object_version            = module.lambda_jira_deployment_package[0].s3_object.version_id
   subnet_ids                   = var.subnet_ids
   tags                         = var.tags
-  timeout                      = 60
+  timeout                      = var.jira_integration.lambda_settings.timeout
 
   environment = {
-    EXCLUDE_ACCOUNT_FILTER      = jsonencode(var.jira_exclude_account_filter)
-    JIRA_ISSUE_TYPE             = var.jira_issue_type
-    JIRA_PROJECT_KEY            = var.jira_project_key
-    JIRA_SECRET_ARN             = var.jira_secret_arn
-    LOG_LEVEL                   = var.lambda_log_level
+    EXCLUDE_ACCOUNT_FILTER      = jsonencode(var.jira_integration.exclude_account_ids)
+    JIRA_ISSUE_TYPE             = var.jira_integration.issue_type
+    JIRA_PROJECT_KEY            = var.jira_integration.project_key
+    JIRA_SECRET_ARN             = var.jira_integration.credentials_secret_arn
+    LOG_LEVEL                   = var.jira_integration.lambda_settings.log_level
     POWERTOOLS_LOGGER_LOG_EVENT = "false"
     POWERTOOLS_SERVICE_NAME     = "jira-securityhub"
   }

modules/servicenow/README.md

@@ -1,5 +1,5 @@
 # Usage
-<!--- BEGIN_TF_DOCS --->
+<!-- BEGIN_TF_DOCS -->
 ## Requirements
 
 | Name | Version |
@@ -26,4 +26,4 @@
 
 No output.
 
-<!--- END_TF_DOCS --->
+<!-- END_TF_DOCS -->

modules/servicenow/iam.tf

@@ -1,11 +1,12 @@
 module "sync-user" {
   #checkov:skip=CKV_AWS_273:We really need a user for this setup
-  name          = "SCSyncUser"
-  source        = "github.com/schubergphilis/terraform-aws-mcaf-user?ref=v0.1.13"
-  create_policy = true
-  policy        = aws_iam_policy.sqs_policy.policy
-  kms_key_id    = var.kms_key_arn
-  tags          = var.tags
+  name                  = "SCSyncUser"
+  source                = "github.com/schubergphilis/terraform-aws-mcaf-user?ref=v0.4.0"
+  create_iam_access_key = var.create_access_keys
+  create_policy         = true
+  kms_key_id            = var.kms_key_arn
+  policy                = aws_iam_policy.sqs_policy.policy
+  tags                  = var.tags
 
   policy_arns = [
     "arn:aws:iam::aws:policy/service-role/AWSConfigRoleForOrganizations",