Skip to content

guardianproject-ops/terraform-aws-account-baseline-audit

BranchesTags

Repository files navigation

terraform-aws-account-baseline-audit

The Guardian

Terraform module for bringing an AWS Control Tower Audit account into governance.

It's 100% Open Source and licensed under the GNU General Public License.

Introduction

This module should be used on Audit accounts created by Control Tower. It sets up the following features:

  • Guard Duty for the entire AWS Org (You must run the corresponding root account baseline module first!)
  • Security Hub for the entire AWS Org
  • IAM user usage alerts
  • IAM Access Analyzer for the entire AWS Org

You must run our terraform-aws-account-baseline-root module first to setup administrator delegation for many of the services.

Usage

IMPORTANT: We do not pin modules to versions in our examples because of the difficulty of keeping the versions in the documentation in sync with the latest released versions. We highly recommend that in your code you pin the version to the exact version you are using so that your infrastructure remains stable, and update versions in a systematic way so that they do not catch you by surprise.

Also, because of a bug in the Terraform registry (hashicorp/terraform#21417), the registry shows many of our inputs as required when in fact they are optional. The table below correctly indicates which inputs are required.

To apply the account level baselines use:

module "audit" {
  source                   = "git::https://gitlab.com/guardianproject-ops/terraform-aws-account-baseline-audit?ref=main"
  guardduty_enabled        = var.guardduty_enabled
  governed_regions         = var.governed_regions
  aws_organization_root_id = var.aws_organization_root_id
  management_account_id    = var.management_account_id
  logging_account_id       = var.logging_account_id
  context                  = module.this.context
}

Then for each region where you want the IAM Access Analyzer to be enabled, run the following with a provider in each region:

module "audit_baseline_region" {
  source           = "git::https://gitlab.com/guardianproject-ops/terraform-aws-account-baseline-audit//modules/iam-access-analzyer-region?ref=main"
  context          = module.this.context
}

Requirements

Name Version
terraform >= 1.5.7
aws >= 5.78.0

Providers

Name Version
aws >= 5.78.0

Modules

Name Source Version
guardduty_org ./modules/guardduty-org n/a
kms_key_audit cloudposse/kms-key/aws 0.12.2
securityhub_org ./modules/securityhub-org n/a
this cloudposse/label/null 0.25.0

Resources

Name Type
aws_iam_role.sns_feedback resource
aws_iam_role_policy.sns_feedback_policy resource
aws_sns_topic.iam_activity resource
aws_sns_topic_policy.iam_activity resource
aws_sns_topic_subscription.iam_activity resource
aws_caller_identity.audit data source
aws_iam_policy_document.iam_activity_topic_policy data source
aws_iam_policy_document.kms_key_audit data source
aws_iam_policy_document.service_assume_role data source
aws_iam_policy_document.sns_feedback data source
aws_region.current data source

Inputs

Name Description Type Default Required
additional_tag_map Additional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration.		 map(string) {} no
attributes ID element. Additional attributes (e.g. workers or cluster) to add to id,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by the delimiter
and treated as a single ID element.		 list(string) [] no
aws_auditmanager AWS Audit Manager config settings 
object({
    enabled               = bool
    reports_bucket_prefix = string
  })
 
{
  "enabled": true,
  "reports_bucket_prefix": "audit-manager-reports"
}
 no
aws_organization_root_id The organization root id, this is NOT the root account id, this is a property of the AWS Organization resource it self.
Use: aws organizations list-roots --query "Roots[0].Id"		 string n/a yes
aws_security_hub AWS Security Hub settings 
object({
    aggregator_linking_mode      = optional(string, "SPECIFIED_REGIONS")
    auto_enable_controls         = optional(bool, true)
    control_finding_generator    = optional(string, "SECURITY_CONTROL")
    create_cis_metric_filters    = optional(bool, true)
    disabled_control_identifiers = optional(list(string), null)
    enabled_control_identifiers  = optional(list(string), null)
    product_arns                 = optional(list(string), [])
    standards_arns               = optional(list(string), null)
  })
 {} no
aws_security_hub_sns_subscription Subscription options for the LandingZone-SecurityHubFindings SNS topic 
map(object({
    endpoint = string
    protocol = string
  }))
 {} no
context Single object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables as null to use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged.		 any 
{
  "additional_tag_map": {},
  "attributes": [],
  "delimiter": null,
  "descriptor_formats": {},
  "enabled": true,
  "environment": null,
  "id_length_limit": null,
  "label_key_case": null,
  "label_order": [],
  "label_value_case": null,
  "labels_as_tags": [
    "unset"
  ],
  "name": null,
  "namespace": null,
  "regex_replace_chars": null,
  "stage": null,
  "tags": {},
  "tenant": null
}
 no
delimiter Delimiter to be used between ID elements.
Defaults to - (hyphen). Set to "" to use no delimiter at all.		 string null no
descriptor_formats Describe additional descriptors to be output in the descriptors output map.
Map of maps. Keys are names of descriptors. Values are maps of the form
{<br/> format = string<br/> labels = list(string)<br/>}
(Type is any so the map values can later be enhanced to provide additional options.)
format is a Terraform format string to be passed to the format() function.
labels is a list of labels, in order, to pass to format() function.
Label values will be normalized before being passed to format() so they will be
identical to how they appear in id.
Default is {} (descriptors output will be empty).		 any {} no
enabled Set to false to prevent the module from creating any resources bool null no
environment ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT' string null no
governed_regions List of AWS regions to enable LandingZone, GuardDuty, etc in list(string) n/a yes
guardduty_auto_enable_organization_members Indicates the auto-enablement configuration of GuardDuty for the member accounts in the organization. Valid values are ALL, NEW, NONE.

For more information, see:
https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_organization_configuration#auto_enable_organization_members		 string "ALL" no
guardduty_cloudwatch_enabled Flag to indicate whether CloudWatch logging should be enabled for GuardDuty bool false no
guardduty_cloudwatch_event_rule_pattern_detail_type The detail-type pattern used to match events that will be sent to SNS.

For more information, see:
https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/CloudWatchEventsandEventPatterns.html
https://docs.aws.amazon.com/eventbridge/latest/userguide/event-types.html
https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_findings_cloudwatch.html		 string "GuardDuty Finding" no
guardduty_create_sns_topic Flag to indicate whether an SNS topic should be created for notifications. If you want to send findings to a new SNS
topic, set this to true and provide a valid configuration for subscribers.		 bool false no
guardduty_detector_features A map of detector features for streaming foundational data sources to detect communication with known malicious domains and IP addresses and identify anomalous behavior.

For more information, see:
https://docs.aws.amazon.com/guardduty/latest/ug/guardduty-features-activation-model.html#guardduty-features

feature_name:
The name of the detector feature. Possible values include: S3_DATA_EVENTS, EKS_AUDIT_LOGS, EBS_MALWARE_PROTECTION, RDS_LOGIN_EVENTS, EKS_RUNTIME_MONITORING, LAMBDA_NETWORK_LOGS, RUNTIME_MONITORING. Specifying both EKS Runtime Monitoring (EKS_RUNTIME_MONITORING) and Runtime Monitoring (RUNTIME_MONITORING) will cause an error. You can add only one of these two features because Runtime Monitoring already includes the threat detection for Amazon EKS resources. For more information, see: https://docs.aws.amazon.com/guardduty/latest/APIReference/API_DetectorFeatureConfiguration.html.
status:
The status of the detector feature. Valid values include: ENABLED or DISABLED.
additional_configuration:
Optional information about the additional configuration for a feature in your GuardDuty account. For more information, see: https://docs.aws.amazon.com/guardduty/latest/APIReference/API_DetectorAdditionalConfiguration.html.
addon_name:
The name of the add-on for which the configuration applies. Possible values include: EKS_ADDON_MANAGEMENT, ECS_FARGATE_AGENT_MANAGEMENT, and EC2_AGENT_MANAGEMENT. For more information, see: https://docs.aws.amazon.com/guardduty/latest/APIReference/API_DetectorAdditionalConfiguration.html.
status:
The status of the add-on. Valid values include: ENABLED or DISABLED.		 
map(object({
    feature_name = string
    status       = string
    additional_configuration = optional(object({
      addon_name = string
      status     = string
    }), null)
  }))
 {} no
guardduty_enabled Whether to enable GuardDuty in the AWS Organization. bool true no
guardduty_finding_publishing_frequency The frequency of notifications sent for finding occurrences. If the detector is a GuardDuty member account, the value
is determined by the GuardDuty master account and cannot be modified, otherwise it defaults to SIX_HOURS.

For standalone and GuardDuty master accounts, it must be configured in Terraform to enable drift detection.
Valid values for standalone and master accounts: FIFTEEN_MINUTES, ONE_HOUR, SIX_HOURS."

For more information, see:
https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_findings_cloudwatch.html#guardduty_findings_cloudwatch_notification_frequency		 string null no
guardduty_findings_notification_arn The ARN for an SNS topic to send findings notifications to. This is only used if create_sns_topic is false.
If you want to send findings to an existing SNS topic, set this to the ARN of the existing topic and set
create_sns_topic to false.		 string null no
guardduty_kubernetes_audit_logs_enabled If true, enables Kubernetes audit logs as a data source for Kubernetes protection.

For more information, see:
https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_detector#audit_logs		 bool false no
guardduty_malware_protection_scan_ec2_ebs_volumes_enabled Configure whether Malware Protection is enabled as data source for EC2 instances EBS Volumes in GuardDuty.

For more information, see:
https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_detector#malware-protection		 bool false no
guardduty_s3_protection_enabled If true, enables S3 protection.

For more information, see:
https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/guardduty_detector#s3-logs		 bool true no
guardduty_subscribers A map of subscription configurations for SNS topics

For more information, see:
https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/sns_topic_subscription#argument-reference

protocol:
The protocol to use. The possible values for this are: sqs, sms, lambda, application. (http or https are partially
supported, see link) (email is an option but is unsupported in terraform, see link).
endpoint:
The endpoint to send data to, the contents will vary with the protocol. (see link for more information)
endpoint_auto_confirms:
Boolean indicating whether the end point is capable of auto confirming subscription e.g., PagerDuty. Default is
false.
raw_message_delivery:
Boolean indicating whether or not to enable raw message delivery (the original message is directly passed, not
wrapped in JSON with the original message in the message property). Default is false.		 
map(object({
    protocol               = string
    endpoint               = string
    endpoint_auto_confirms = bool
    raw_message_delivery   = bool
  }))
 {} no
id_length_limit Limit id to this many characters (minimum 6).
Set to 0 for unlimited length.
Set to null for keep the existing setting, which defaults to 0.
Does not affect id_full.		 number null no
kms_key_policy_audit A list of valid KMS key policy JSON document for use with audit KMS key list(string) [] no
label_key_case Controls the letter case of the tags keys (label names) for tags generated by this module.
Does not affect keys of tags passed in via the tags input.
Possible values: lower, title, upper.
Default value: title.		 string null no
label_order The order in which the labels (ID elements) appear in the id.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.		 list(string) null no
label_value_case Controls the letter case of ID elements (labels) as included in id,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via the tags input.
Possible values: lower, title, upper and none (no transformation).
Set this to title and set delimiter to "" to yield Pascal Case IDs.
Default value: lower.		 string null no
labels_as_tags Set of labels (ID elements) to include as tags in the tags output.
Default is to include all labels.
Tags with empty values will not be included in the tags output.
Set to [] to suppress all generated tags.
Notes:
The value of the name tag, if included, will be the id, not the name.
Unlike other null-label inputs, the initial setting of labels_as_tags cannot be
changed in later chained modules. Attempts to change it will be silently ignored.		 set(string) 
[
  "default"
]
 no
logging_account_id The account id for the AWS Control Tower Log archive account string n/a yes
management_account_id The account id for the AWS Organizations root account string n/a yes
monitor_iam_activity Whether IAM activity should be monitored bool true no
monitor_iam_activity_sns_subscription Subscription options for the LandingZone-IAMActivity SNS topic 
map(object({
    endpoint = string
    protocol = string
  }))
 {} no
name ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as a tag.
The "name" tag is set to the full id string. There is no tag with the value of the name input.		 string null no
namespace ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique string null no
path Optional path for all IAM users, user groups, roles, and customer managed policies created by this module string "/" no
regex_replace_chars Terraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.		 string null no
securityhub_enabled Whether to enable SecurityHub in the AWS Organization. bool true no
stage ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release' string null no
tags Additional tags (e.g. {'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.		 map(string) {} no
tenant ID element _(Rarely used, not included by default)_. A customer identifier, indicating who this instance of a resource is for string null no

Outputs

Name Description
guardduty_detector_arn The ARN of the GuardDuty detector.
guardduty_detector_id The ID of the GuardDuty detector.
guardduty_sns_topic_name The name of the SNS topic created by the component
guardduty_sns_topic_subscriptions The SNS topic subscriptions created by the component
kms_key_audit_arn The ARN of the KMS key used for audit logs.
kms_key_audit_id The ID of the KMS key used for audit logs.
sns_topic_monitor_iam_activity_arn ARN of the SNS Topic in the Audit account for IAM activity monitoring notifications
sns_topic_monitor_iam_activity_name NAME of the SNS Topic in the Audit account for IAM activity monitoring notifications
sns_topic_security_hub_findings_arn n/a
sns_topic_security_hub_findings_name n/a

Help

Got a question? We got answers.

File a GitLab issue, send us an email or join our Matrix Community.

Matrix Community

Matrix badge

Join our Open Source Community on Matrix. It's FREE for everyone! This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build on our open source code.

Contributing

Bug Reports & Feature Requests

Please use the issue tracker to report any bugs or file feature requests.

Developing

If you are interested in being a contributor and want to get involved in developing this project or help out with our other projects, we would love to hear from you! Shoot us an email.

In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

  1. Fork the repo on GitLab
  2. Clone the project to your own machine
  3. Commit changes to your own branch
  4. Push your work back up to your fork
  5. Submit a Pull Request so that we can review your changes

NOTE: Be sure to merge the latest changes from "upstream" before making a pull request!

Copyright

Copyright © 2021-2025 The Guardian Project

License

License: GPL v3

GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Trademarks

All other trademarks referenced herein are the property of their respective owners.

About

This project is maintained by The Guardian Project.

The Guardian Project

We're a collective of designers, developers, and ops folk focused on useable privacy and security with a focus on digital human rights and humanitarian projects.

Everything we do is 100% FOSS.

Follow us on Mastodon or twitter, apply for a job, or partner with us.

We offer paid support on all of our projects.

Check out our other DevOps projects or our entire other set of projects related to privacy and security related software, or hire us to get support with using our projects.

Contributors

Abel Luck
Abel Luck

About

Terraform module for bringing an AWS Control Tower audit account into governance (Mirror of https://gitlab.com/guardianproject-ops/terraform-aws-account-baseline-audit)

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

0 stars

Watchers

3 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages