cloudandthings / terraform-aws-clickops-notifier

Get notified when actions are taken in the AWS Console.
https://registry.terraform.io/modules/cloudandthings/clickops-notifier/aws/latest
MIT License
207 stars 17 forks source link
aws clickops terraform terraform-modules

Tests

AWS ClickOps Notifier

Get notified when users are taking actions in the AWS Console. More here

🏗️ Module Usage

It is not strictly a requirement, that you use this with AWS ControlTower. The module has only been tested in the Log Archive account that ships with AWS ControlTower. Setup your AWS credentails such that aws sts get-caller-identity | grep Account gives you your ControlTower Log Archive account id.

Organizational Mode vs Standalone Mode

If your account is part of an AWS Organization that does not use centralized CloudTrail logging or that does not want to monitor ClickOps at an organizational level, you can deploy ClickOps in standalone mode in a single account. For standalone mode you need CloudTrail enabled in your account, have it configured to write logs to a CloudWatch Log Group and have sufficient permission to create a subscription filter on the log group.

Excluded scoped actions

The following actions will not be alerted, these are either:

This functionality can be overriden with the excluded_scoped_actions and excluded_scoped_actions_effect variables. The list of excluded actions is available in the terraform docs below.

Contributing

Report issues/questions/feature requests on in the issues section.

Full contributing guidelines are covered here.


Documentation


Inputs

Name Description Type Default Required
additional_iam_policy_statements Map of dynamic policy statements to attach to Lambda Function role any {} no
allowed_aws_principals_for_sns_subscribe List of AWS principals allowed to subscribe to the SNS topic (only applicable to org deployments). list(string) [] no
cloudtrail_bucket_name Bucket containing the Cloudtrail logs that you want to process. ControlTower bucket name follows this naming convention aws-controltower-logs-{{account_id}}-{{region}} string "" no
cloudtrail_bucket_notifications_sns_arn SNS topic ARN for bucket notifications. If not provided, a new SNS topic will be created along with the bucket notifications configuration. string null no
cloudtrail_log_group CloudWatch Log group for CloudTrail events. string "" no
create_iam_role Determines whether a an IAM role is created or to use an existing IAM role bool true no
event_batch_size Batch events into chunks of event_batch_size number 100 no
event_maximum_batching_window Maximum batching window in seconds. number 300 no
event_processing_timeout Maximum number of seconds the lambda is allowed to run and number of seconds events should be hidden in SQS after being picked up my Lambda. number 60 no
excluded_accounts List of accounts that be excluded for scans on manual actions. These take precidence over included_accounts list(string) [] no
excluded_scoped_actions A list of service scoped actions that will not be alerted on. Format {{service}}.amazonaws.com:{{action}} list(string) [] no
excluded_scoped_actions_effect Should the existing exluded actions be replaces or appended to. By default it will append to the list, valid values: APPEND, REPLACE string "APPEND" no
excluded_users List of email addresses will not be reported on when practicing ClickOps. list(string) [] no
firehose_delivery_stream_name Kinesis Firehose delivery stream name to output ClickOps events to. string null no
iam_role_arn Existing IAM role ARN for the lambda. Required if create_iam_role is set to false string null no
included_accounts List of accounts that be scanned to manual actions. If empty will scan all accounts. list(string) [] no
included_users List of emails that be scanned to manual actions. If empty will scan all emails. list(string) [] no
kms_key_id_for_sns_topic KMS key ID for encrypting the sns_topic (only applicable to org deployments). string null no
lambda_deployment_s3_bucket S3 bucket for lambda deployment package. string null no
lambda_deployment_s3_key S3 object key for lambda deployment package. Otherwise, defaults to var.naming_prefix/local.deployment_filename. string null no
lambda_deployment_upload_to_s3_enabled If true, the lambda deployment package within this module repo will be copied to S3. If false then the S3 object must be uploaded separately. Ignored if lambda_deployment_s3_bucket is null. bool true no
lambda_log_level Lambda logging level. One of: ["DEBUG", "INFO", "WARN", "ERROR"]. string "WARN" no
lambda_memory_size The amount of memory for Lambda to use number "128" no
lambda_runtime The lambda runtime to use. One of: ["python3.9", "python3.8", "python3.7"] string "python3.8" no
log_retention_in_days Number of days to keep CloudWatch logs number 14 no
naming_prefix Resources will be prefixed with this string "clickops-notifier" no
standalone Deploy ClickOps in a standalone account instead of into an entire AWS Organization. Ideal for teams who want to monitor ClickOps in only their accounts where it is not instrumented at an Organizational level. bool false no
subcription_filter_distribution The method used to distribute log data to the destination. By default log data is grouped by log stream, but the grouping can be set to random for a more even distribution. This property is only applicable when the destination is an Amazon Kinesis stream. Valid values are "Random" and "ByLogStream". string "Random" no
tags Tags to add to resources in addition to the default_tags for the provider map(string) {} no
webhooks_for_msteams_notifications Map of custom_name => webhook URLs for MS Teams notifications. https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=dotnet map(string) {} no
webhooks_for_slack_notifications Map of custom_name => webhook URLs for Slack notifications. https://api.slack.com/messaging/webhooks map(string) {} no

Modules

Name Source Version
clickops_notifier_lambda terraform-aws-modules/lambda/aws 4.9.0

Outputs

Name Description
clickops_notifier_lambda Expose all the outputs from the lambda module
sns_topic Expose the bucket notification SNS details
sqs_queue Expose the bucket notification SQS details

Providers

Name Version
aws >= 4.9

Requirements

Name Version
terraform >= 0.15.0
aws >= 4.9

Resources

Name Type
aws_cloudwatch_log_subscription_filter.this resource
aws_s3_bucket_notification.bucket_notification resource
aws_s3_object.deployment resource
aws_sns_topic.bucket_notifications resource
aws_sns_topic_policy.bucket_notifications resource
aws_sns_topic_subscription.bucket_notifications resource
aws_sqs_queue.bucket_notifications resource
aws_sqs_queue_policy.bucket_notifications resource
aws_ssm_parameter.webhooks_for_msteams resource
aws_ssm_parameter.webhooks_for_slack resource
aws_caller_identity.current data source
aws_cloudwatch_log_group.this data source
aws_iam_policy_document.bucket_notifications data source
aws_iam_policy_document.lambda_permissions data source
aws_iam_policy_document.sns_topic_policy_bucket_notifications data source
aws_region.current data source

Default excluded scoped actions

locals {
  ignored_scoped_events_built_in = [
    "cognito-idp.amazonaws.com:InitiateAuth",
    "cognito-idp.amazonaws.com:RespondToAuthChallenge",

    "sso.amazonaws.com:Federate",
    "sso.amazonaws.com:Authenticate",
    "sso.amazonaws.com:Logout",
    "sso.amazonaws.com:SearchUsers",
    "sso.amazonaws.com:SearchGroups",
    "sso.amazonaws.com:CreateToken",

    "signin.amazonaws.com:UserAuthentication",
    "signin.amazonaws.com:SwitchRole",
    "signin.amazonaws.com:RenewRole",
    "signin.amazonaws.com:ExternalIdPDirectoryLogin",
    "signin.amazonaws.com:CredentialVerification",
    "signin.amazonaws.com:CredentialChallenge",
    "signin.amazonaws.com:CheckMfa",

    "logs.amazonaws.com:StartQuery",
    "cloudtrail.amazonaws.com:StartQuery",

    "iam.amazonaws.com:SimulatePrincipalPolicy",
    "iam.amazonaws.com:GenerateServiceLastAccessedDetails",

    "glue.amazonaws.com:BatchGetJobs",
    "glue.amazonaws.com:BatchGetCrawlers",
    "glue.amazonaws.com:StartJobRun",
    "glue.amazonaws.com:StartCrawler",

    "athena.amazonaws.com:StartQueryExecution",

    "servicecatalog.amazonaws.com:SearchProductsAsAdmin",
    "servicecatalog.amazonaws.com:SearchProducts",
    "servicecatalog.amazonaws.com:SearchProvisionedProducts",
    "servicecatalog.amazonaws.com:TerminateProvisionedProduct",

    "cloudshell.amazonaws.com:CreateSession",
    "cloudshell.amazonaws.com:PutCredentials",
    "cloudshell.amazonaws.com:SendHeartBeat",
    "cloudshell.amazonaws.com:CreateEnvironment",

    "kms.amazonaws.com:Decrypt",
    "kms.amazonaws.com:RetireGrant",

    "trustedadvisor.amazonaws.com:RefreshCheck",

    # Must CreateMultipartUpload before uploading any parts.
    "s3.amazonaws.com:UploadPart",
    "s3.amazonaws.com:UploadPartCopy",

    "route53domains:TransferDomain",

    "support.amazonaws.com:AddAttachmentsToSet",
    "support.amazonaws.com:AddCommunicationToCase",
    "support.amazonaws.com:CreateCase",
    "support.amazonaws.com:InitiateCallForCase",
    "support.amazonaws.com:InitiateChatForCase",
    "support.amazonaws.com:PutCaseAttributes",
    "support.amazonaws.com:RateCaseCommunication",
    "support.amazonaws.com:RefreshTrustedAdvisorCheck",
    "support.amazonaws.com:ResolveCase",

    "grafana.amazonaws.com:login_auth_sso",
  ]
}