diff --git a/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account.md b/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account.md index 3740cdfd..67398167 100644 --- a/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account.md +++ b/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account.md @@ -27,7 +27,7 @@ To import your AWS account into Guardrails you will: ### Step 1: Create an AWS IAM role for Guardrails -Follow these steps to create the role in the AWS Management Console. (You can alternatively use [CloudFormation]() or [Terraform().) +Follow these steps to create the role in the AWS Management Console. (You can alternatively use [CloudFormation]() or [Terraform]().) Log in to the AWS Management Console. @@ -57,7 +57,7 @@ Note: There are many policies matching `ReadOnlyAccess`, reverse-sorting the lis Click `Next`. -Name the role appropriately (e.g. `turbot-readonly-role`) +Name the role appropriately (e.g. `turbot-role`) Review the trust policy and permissions @@ -112,12 +112,14 @@ When the control is green, Turbot has successfully connected to your account. 1. **Connect a readonly AWS account to Guardrails** -2. [Review and test a Guardrails AWS control](/docs/integrations/aws/getting-started-readonly/review_and_test_control) +2. [Review and test a Guardrails AWS control](/guardrails/docs/integrations/aws/getting-started-readonly/review_and_test_control) -3. [Set a Guardrails policy for AWS resources](/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) +3. [Enable event handlers for fast change detection](/guardrails/docs/integrations/aws/getting-started-readonly/enable_event_handlers) -4. [Create a static exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_static_exception) +4. [Set a Guardrails policy for AWS resources](/guardrails/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) -5. [Create a calculated exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_calculated_exception) +5. [Create a static exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_static_exception) -6. [Set an alert on an AWS Guardrails control](/docs/integrations/aws/getting-started-readonly/set_alert_on_control) +6. [Create a calculated exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_calculated_exception) + +7. [Set an alert on an AWS Guardrails control](/guardrails/docs/integrations/aws/getting-started-readonly/set_alert_on_control) diff --git a/docs/integrations/aws/getting-started-readonly/create_calculated_exception.md b/docs/integrations/aws/getting-started-readonly/create_calculated_exception.md index 58a9345a..1c962425 100644 --- a/docs/integrations/aws/getting-started-readonly/create_calculated_exception.md +++ b/docs/integrations/aws/getting-started-readonly/create_calculated_exception.md @@ -14,7 +14,17 @@ nav: **Prerequisites**: -- Completion of [Connect an AWS account to Guardrails with readonly permissions](),  [Review and test a Guardrails AWS control](),  [Set a Guardrails policy for AWS resources](), and [Create a static exception](). +- [Connect an AWS account to Guardrails with readonly permissions]() + +- [Review and test a Guardrails AWS control]() + +- [Enable event handlers for fast change detection]() + +  + +- [Set a Guardrails policy for AWS resources]() + +- [Create a static exception to a Guardrails AWS policy]() ## Procedure @@ -149,14 +159,16 @@ This view shows the static Sandbox-level exception you created in [this runbook] ## Runbook Progress Tracker -1. [Connect a readonly AWS account to Guardrails](/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) +1. [Connect a readonly AWS account to Guardrails](/guardrails/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) + +2. [Review and test a Guardrails AWS control](/guardrails/docs/integrations/aws/getting-started-readonly/review_and_test_control) -2. [Review and test a Guardrails AWS control](/docs/integrations/aws/getting-started-readonly/review_and_test_control) +3. [Enable event handlers for fast change detection](/guardrails/docs/integrations/aws/getting-started-readonly/enable_event_handlers) -3. [Set a Guardrails policy for AWS resources](/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) +4. [Set a Guardrails policy for AWS resources](/guardrails/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) -4. [Create a static exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_static_exception) +5. [Create a static exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_static_exception) -5. **Create a calculated exception to a Guardrails AWS policy** +6. **Create a calculated exception to a Guardrails AWS policy** -6. [Set an alert on an AWS Guardrails control](/docs/integrations/aws/getting-started-readonly/set_alert_on_control) +7. [Set an alert on an AWS Guardrails control](/guardrails/docs/integrations/aws/getting-started-readonly/set_alert_on_control) diff --git a/docs/integrations/aws/getting-started-readonly/create_static_exception.md b/docs/integrations/aws/getting-started-readonly/create_static_exception.md index 1c19ef70..14ca7ce5 100644 --- a/docs/integrations/aws/getting-started-readonly/create_static_exception.md +++ b/docs/integrations/aws/getting-started-readonly/create_static_exception.md @@ -14,7 +14,15 @@ nav: **Prerequisites**: -- Completion of [Connect an AWS account to Guardrails with readonly permissions](),  [Review and test a Guardrails AWS control](), and [Set a Guardrails policy for AWS resources](). +- [Connect an AWS account to Guardrails with readonly permissions]() + +- [Review and test a Guardrails AWS control]() + +- [Enable event handlers for fast change detection]() + +  + +- [Set a Guardrails policy for AWS resources]() ## Procedure @@ -62,14 +70,16 @@ Note that only one control (for your test bucket) is skipped; all others are sub ## Runbook Progress Tracker -1. [Connect a readonly AWS account to Guardrails](/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) +1. [Connect a readonly AWS account to Guardrails](/guardrails/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) + +2. [Review and test a Guardrails AWS control](/guardrails/docs/integrations/aws/getting-started-readonly/review_and_test_control) -2. [Review and test a Guardrails AWS control](/docs/integrations/aws/getting-started-readonly/review_and_test_control) +3. [Enable event handlers for fast change detection](/guardrails/docs/integrations/aws/getting-started-readonly/enable_event_handlers) -3. [Set a Guardrails policy for AWS resources](/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) +4. [Set a Guardrails policy for AWS resources](/guardrails/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) -4. **Create a static exception to a Guardrails AWS policy** +5. **Create a static exception to a Guardrails AWS policy** -5. [Create a calculated exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_calculated_exception) +6. [Create a calculated exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_calculated_exception) -6. [Set an alert on an AWS Guardrails control](/docs/integrations/aws/getting-started-readonly/set_alert_on_control) +7. [Set an alert on an AWS Guardrails control](/guardrails/docs/integrations/aws/getting-started-readonly/set_alert_on_control) diff --git a/docs/integrations/aws/getting-started-readonly/enable_event_handlers.md b/docs/integrations/aws/getting-started-readonly/enable_event_handlers.md new file mode 100755 index 00000000..f393c266 --- /dev/null +++ b/docs/integrations/aws/getting-started-readonly/enable_event_handlers.md @@ -0,0 +1,66 @@ +--- +title: "Enable event handlers for fast change detection" +template: Documentation +nav: +  title: "Enable event handlers" +--- + + + + +# Enable event handlers for fast change detection + +## Introduction + +**Purpose**: This runbook shows a Guardrails administrator how to enable event handlers to speed up change detection. + + +**Prerequisites**: + +-  [Connect an AWS account to Guardrails with readonly permissions]() + +-  [Review and test a Guardrails AWS control]() + +## Procedure + +### Step 1: Update the Turbot IAM role + + +When you [imported your account](), the IAM role you created for Guardrails only attached only the policy `arn:aws:iam::aws:policy/ReadOnlyAccess`.  With that level of access, Guardrails must poll AWS to detect changes. As you’ve now seen, it can take a few minutes for Guardrails to notice a change. Polling also entails heavy and thus costly use of AWS APIs. + +Switching from polling to event handlers enables Guardrails to detect changes almost instantly, and lightens the API load. This requires a slight elevation of privilege. Along with `ReadOnlyAccess`, attach `AmazonSNSFullAccess` and `CloudWatchEventsFullAccess`. +

aws_start_role_permissions_for_event_handlers

+ + + +### Step 2: Enable event handlers + +Click the top-level `Policies`, search for `AWS Turbot Event Handlers`,  open the setting, and change the value to `Enforce: Configured`. +

aws_start_enable_event_handlers

+ +### Step 3: Observe immediate reaction to change! + + +Click the top-level `Resources` tab, navigate to the top (Turbot) level (if not already there), search for your test bucket, and click the `Activity` tab. + +Then, in the AWS console, toggle the `Block public setting` back and forth. Guardrails now detects the changes, and updates the control state immediately. +

aws_start_observe_event_handlers_in_action

+ +### + + +## Runbook Progress Tracker + +1. [Connect a readonly AWS account to Guardrails](/guardrails/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) + +2. [Review and test a Guardrails AWS control](/guardrails/docs/integrations/aws/getting-started-readonly/review_and_test_control) + +3. **Enable event handlers for fast change detection** + +4. [Set a Guardrails policy for AWS resources](/guardrails/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) + +5. [Create a static exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_static_exception) + +6. [Create a calculated exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_calculated_exception) + +7. [Set an alert on an AWS Guardrails control](/guardrails/docs/integrations/aws/getting-started-readonly/set_alert_on_control) diff --git a/docs/integrations/aws/getting-started-readonly/index.md b/docs/integrations/aws/getting-started-readonly/index.md index a775390c..61dc5197 100755 --- a/docs/integrations/aws/getting-started-readonly/index.md +++ b/docs/integrations/aws/getting-started-readonly/index.md @@ -1,11 +1,11 @@ --- -title: "Getting started with AWS: readonly" +title: "Getting started with AWS: ReadOnly" template: Documentation nav: - title: "Getting started: readonly" + title: "Getting started: ReadOnly" --- -# Getting started with AWS in Guardrails: readonly +# Getting started with AWS in Guardrails: ReadOnly In this series of runbooks you'll learn how to: @@ -13,6 +13,8 @@ In this series of runbooks you'll learn how to: - Review and test a control +- Enable event handlers for fast change detection + - Set a Guardrails policy - Create a static exception diff --git a/docs/integrations/aws/getting-started-readonly/review_and_test_control.md b/docs/integrations/aws/getting-started-readonly/review_and_test_control.md index a8540cb7..cd757d4b 100644 --- a/docs/integrations/aws/getting-started-readonly/review_and_test_control.md +++ b/docs/integrations/aws/getting-started-readonly/review_and_test_control.md @@ -14,9 +14,7 @@ nav: **Prerequisites**: -- Completion of the [Connect an AWS account to Guardrails with readonly permissions]() runbook. - -- Application of the S3 Bucket Public Access Block policy pack to the connected account. +-  [Connect an AWS account to Guardrails with readonly permissions]() ## Procedure @@ -66,14 +64,16 @@ As soon as Guardrails notices the change, the control is again green. ## Runbook Progress Tracker -1. [Connect a readonly AWS account to Guardrails](/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) +1. [Connect a readonly AWS account to Guardrails](/guardrails/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) 2. **Review and test a Guardrails AWS control** -3. [Set a Guardrails policy for AWS resources](/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) +3. [Enable event handlers for fast change detection](/guardrails/docs/integrations/aws/getting-started-readonly/enable_event_handlers) + +4. [Set a Guardrails policy for AWS resources](/guardrails/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) -4. [Create a static exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_static_exception) +5. [Create a static exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_static_exception) -5. [Create a calculated exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_calculated_exception) +6. [Create a calculated exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_calculated_exception) -6. [Set an alert on an AWS Guardrails control](/docs/integrations/aws/getting-started-readonly/set_alert_on_control) +7. [Set an alert on an AWS Guardrails control](/guardrails/docs/integrations/aws/getting-started-readonly/set_alert_on_control) diff --git a/docs/integrations/aws/getting-started-readonly/set_alert_on_control.md b/docs/integrations/aws/getting-started-readonly/set_alert_on_control.md index b9661793..a8aefe2d 100644 --- a/docs/integrations/aws/getting-started-readonly/set_alert_on_control.md +++ b/docs/integrations/aws/getting-started-readonly/set_alert_on_control.md @@ -10,17 +10,21 @@ nav: ## Introduction -**Purpose**: This runbook shows a Guardrails administrator how to create a calculated policy exception for a set of AWS resources. +**Purpose**: This runbook shows a Guardrails administrator how to notify by email on an alert. -**Prerequisites**: Completion of: - --  [Connect an AWS account to Guardrails with readonly permissions]() +**Prerequisites**: --  [Review and test a Guardrails AWS control]() +- [Connect an AWS account to Guardrails with readonly permissions]() + +- [Review and test a Guardrails AWS control]() + +- [Enable event handlers for fast change detection]() --  [Set a Guardrails policy for AWS resources]() +- [Set a Guardrails policy for AWS resources]() -- [Create a calculated exception](). +- [Create a static exception to a Guardrails AWS policy]() + +- [Create a calculated exception to a Guardrails AWS policy]() ## Procedure @@ -84,14 +88,16 @@ Watch the control log, and wait for Guardrails to notice the change. ## Runbook Progress Tracker -1. [Connect a readonly AWS account to Guardrails](/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) +1. [Connect a readonly AWS account to Guardrails](/guardrails/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) + +2. [Review and test a Guardrails AWS control](/guardrails/docs/integrations/aws/getting-started-readonly/review_and_test_control) -2. [Review and test a Guardrails AWS control](/docs/integrations/aws/getting-started-readonly/review_and_test_control) +3. [Enable event handlers for fast change detection](/guardrails/docs/integrations/aws/getting-started-readonly/enable_event_handlers) -3. [Set a Guardrails policy for AWS resources](/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) +4. [Set a Guardrails policy for AWS resources](/guardrails/docs/integrations/aws/getting-started-readonly/set_an_aws_policy) -4. [Create a static exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_static_exception) +5. [Create a static exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_static_exception) -5. [Create a calculated exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_calculated_exception) +6. [Create a calculated exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_calculated_exception) -6. **Set an alert on an AWS Guardrails control** +7. **Set an alert on an AWS Guardrails control** diff --git a/docs/integrations/aws/getting-started-readonly/set_an_aws_policy.md b/docs/integrations/aws/getting-started-readonly/set_an_aws_policy.md index 0465bbff..24be41a8 100644 --- a/docs/integrations/aws/getting-started-readonly/set_an_aws_policy.md +++ b/docs/integrations/aws/getting-started-readonly/set_an_aws_policy.md @@ -14,7 +14,11 @@ nav: **Prerequisites**: -- Completion of [Connect an AWS account to Guardrails with readonly permissions]() and [Review and test a Guardrails AWS control]() +- [Connect an AWS account to Guardrails with readonly permissions]() + +-  [Review and test a Guardrails AWS control]() + +- [Enable event handlers for fast change detection]() ## Procedure @@ -61,14 +65,16 @@ Note two transitions, first from `Skipped` to `Alarm` (when you set the policy) ## Runbook Progress Tracker -1. [Connect a readonly AWS account to Guardrails](/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) +1. [Connect a readonly AWS account to Guardrails](/guardrails/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account) + +2. [Review and test a Guardrails AWS control](/guardrails/docs/integrations/aws/getting-started-readonly/review_and_test_control) -2. [Review and test a Guardrails AWS control](/docs/integrations/aws/getting-started-readonly/review_and_test_control) +3. [Enable event handlers for fast change detection](/guardrails/docs/integrations/aws/getting-started-readonly/enable_event_handlers) -3. **Set a Guardrails policy for AWS resources** +4. **Set a Guardrails policy for AWS resources** -4. [Create a static exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_static_exception) +5. [Create a static exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_static_exception) -5. [Create a calculated exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_calculated_exception) +6. [Create a calculated exception to a Guardrails AWS policy](/guardrails/docs/integrations/aws/getting-started-readonly/create_calculated_exception) -6. [Set an alert on an AWS Guardrails control](/docs/integrations/aws/getting-started-readonly/set_alert_on_control) +7. [Set an alert on an AWS Guardrails control](/guardrails/docs/integrations/aws/getting-started-readonly/set_alert_on_control) diff --git a/docs/integrations/aws/getting-started-remediation/connect_writeable_aws_account.md b/docs/integrations/aws/getting-started-remediation/connect_writeable_aws_account.md deleted file mode 100755 index c5231a52..00000000 --- a/docs/integrations/aws/getting-started-remediation/connect_writeable_aws_account.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Connect a writeable AWS account to Guardrails: remediation" -template: Documentation -nav: -  title: Connect a writeable AWS account" ---- - -# Connect a writeable AWS account to Guardrails - -## Introduction - -**Purpose**: This runbook shows a Guardrails administrator how to connect Guardrails to an account in the standard AWS partition and enable Guardrails to remediate misconfigurations. - - diff --git a/docs/integrations/aws/getting-started-remediation/index.md b/docs/integrations/aws/getting-started-remediation/index.md index f19d0028..ec556cb9 100755 --- a/docs/integrations/aws/getting-started-remediation/index.md +++ b/docs/integrations/aws/getting-started-remediation/index.md @@ -1,16 +1,13 @@ --- -title: "Getting started with AWS: remediation" +title: "Getting started with AWS: Remediation" template: Documentation nav: title: "Getting started: remediation" --- -# Getting started with AWS in Guardrails: remediation +# Getting started with AWS in Guardrails: Remediation In this series of runbooks you'll learn how to: -- Import an AWS account with write access +- ... -- Enable event handling - -Start [here](integrations/aws/getting-started-remediation/connect_writeable_aws_account). \ No newline at end of file diff --git a/docs/sidebar.json b/docs/sidebar.json index 2ba4cecb..ce18d4b7 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -196,6 +196,7 @@ "items": [ "integrations/aws/getting-started-readonly/connect_readonly_aws_account", "integrations/aws/getting-started-readonly/review_and_test_control", + "integrations/aws/getting-started-readonly/enable_event_handlers", "integrations/aws/getting-started-readonly/set_an_aws_policy", "integrations/aws/getting-started-readonly/create_static_exception", "integrations/aws/getting-started-readonly/create_calculated_exception", @@ -207,7 +208,6 @@ "id": "getting-started-remediation", "link": "integrations/aws/getting-started-remediation", "items": [ - "integrations/aws/getting-started-remediation/connect_writeable_aws_account" ] }, diff --git a/images/runbook/aws_start_enable_event_handlers.png b/images/runbook/aws_start_enable_event_handlers.png new file mode 100644 index 00000000..8b86b2a3 Binary files /dev/null and b/images/runbook/aws_start_enable_event_handlers.png differ diff --git a/images/runbook/aws_start_observe_event_handlers_in_action.png b/images/runbook/aws_start_observe_event_handlers_in_action.png new file mode 100644 index 00000000..c38d1be6 Binary files /dev/null and b/images/runbook/aws_start_observe_event_handlers_in_action.png differ diff --git a/images/runbook/aws_start_role_permissions_for_event_handlers.png b/images/runbook/aws_start_role_permissions_for_event_handlers.png new file mode 100644 index 00000000..bcf2f295 Binary files /dev/null and b/images/runbook/aws_start_role_permissions_for_event_handlers.png differ