add complete set of aws getting started images/docs

docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account.md

@@ -110,14 +110,14 @@ When the control is green, Turbot has successfully connected to your account.
 
 ## Runbook Progress Tracker
 
-1 **Connect a readonly AWS account to Guardrails**
+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](/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. [Set a Guardrails policy for AWS resources](/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)
+4. [Create a static exception to a Guardrails AWS policy](/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)
+5. [Create a calculated exception to a Guardrails AWS policy](/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)
+6. [Set an alert on an AWS Guardrails control](/docs/integrations/aws/getting-started-readonly/set_alert_on_control)

docs/integrations/aws/getting-started-readonly/create_calculated_exception.md

@@ -0,0 +1,162 @@
+---
+title: "Create a calculated exception to a Guardrails AWS policy"
+template: Documentation
+nav:
+  title: "Create a calculated exception"
+---
+
+
+# Create a calculated exception to a Guardrails AWS policy
+
+## Introduction
+
+**Purpose**: This runbook shows a Guardrails administrator how to create a calculated policy exception for a set of AWS resources.
+
+**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]().
+
+## Procedure
+
+### Step 1: Delete the previously-created static exception
+
+In [Create a static exception]() we overrode the global default for bucket versioning (`Skip`) with a Sandbox-level setting (`Check: Enabled`). 
+<p><img alt="aws_start_4_bucket_versioning_policy_hierarchy" src="/images/docs/guardrails/runbook/aws_start_4_bucket_versioning_policy_hierarchy.png"/></p>
+
+Now we’ll delete that static exception and create a new calculated exception. 
+
+To delete the execution, find it using `Reports -> Policy Setting Exceptions`
+<p><img alt="aws_start_4_report_policy_setting_exceptions" src="/images/docs/guardrails/runbook/aws_start_4_report_policy_setting_exceptions.png"/></p>
+
+Click into the policy setting and click `Delete`.
+<p><img alt="aws_start_4_delete_policy_setting" src="/images/docs/guardrails/runbook/aws_start_4_delete_policy_setting.png"/></p>
+
+Now click the account id (or alias) in the breadcrumb trail.
+<p><img alt="aws_start_4_breadcrumb_account" src="/images/docs/guardrails/runbook/aws_start_4_breadcrumb_account.png"/></p>
+
+### Step 2: Launch the calculated policy builder
+
+We’ve already overridden the default policy (`Skip`) with a Sandbox-level policy (`Check: Enabled`). And we’ve seen how to refine that Sandbox-level policy with an exception for a single bucket. Now we’ll create a calculated policy to apply that exception to a set of buckets in this account.   
+
+Click into the account, select the `Policies` tab, search for `s3 bucket versioning`, and click `Descendant`. 
+<p><img alt="aws_start_4_find_versioning_policy_at_account_level" src="/images/docs/guardrails/runbook/aws_start_4_find_versioning_policy_at_account_level.png"/></p>
+
+Click into it, and click `New Policy Setting`.  The policy type is `AWS > S3 > Bucket > Versioning`. Under `Resource` navigate to the account you imported in [Connect a readonly AWS Account to Guardrails]().
+<p><img alt="aws_start_4_ready_for_calc_policy" src="/images/docs/guardrails/runbook/aws_start_4_ready_for_calc_policy.png"/></p>
+
+Now click `Enable calculated mode` and then `Launch calculated policy builder`.
+<p><img alt="aws_start_4_ready_to_launch_calc_policy_builder" src="/images/docs/guardrails/runbook/aws_start_4_ready_to_launch_calc_policy_builder.png"/></p>
+
+Here’s the initial state of the policy builder.
+<p><img alt="aws_start_4_initial_calc_policy_builder" src="/images/docs/guardrails/runbook/aws_start_4_initial_calc_policy_builder.png"/></p>
+
+### Step 3: Tag your test bucket
+
+We want this policy to act on buckets in your imported account that are tagged with `SkipVersioning`. So, in the AWS console, apply that tag to your test bucket. Use  `SkipVersioning` as the key, and leave the value empty.
+<p><img alt="aws_start_4_tag_the_test_bucket" src="/images/docs/guardrails/runbook/aws_start_4_tag_the_test_bucket.png"/></p>
+
+### Step 4: Query for the tag
+
+Back in the policy builder, under `Test Resource`, choose your test bucket and, in the `Input [GraphQL]` dropdown, choose `Get bucket`. Guardrails inserts a GraphQL query that, by default, looks for tags on the test resource. Verify that the output matches the tag you assigned. 
+<p><img alt="aws_start_4_calc_policy_graphql_default_query_for_bucket" src="/images/docs/guardrails/runbook/aws_start_4_calc_policy_graphql_default_query_for_bucket.png"/></p>
+
+### Step 5: Configure the template to check for the existence of the tag
+
+
+Paste this code into the Nunjucks template.  
+
+```
+nunjucks
+{% set tag_exists = false %}
+{% if 'SkipVersioning' in $.bucket.turbot.tags %}
+  {% set tag_exists = true %}
+{% endif %}
+"{{ tag_exists }}"
+```
+
+
+Our ultimate goal here is to return a valid value for the `AWS > S3 > Bucket > Versioning` policy type. But first, we’ll verify that the template can detect the existence of the tag. Here we can see that it does: the output value is `true`. The `Result` is in error because `true` isn’t one of the allowed values for this policy type, we’ll take care of that in the next step.
+<p><img alt="aws_start_4_template_check_for_tag" src="/images/docs/guardrails/runbook/aws_start_4_template_check_for_tag.png"/></p>
+
+### Step 6: Configure the template to return a valid value
+
+Paste this code into the template.  
+
+```
+nunjucks
+{% set result = 'Check: Enabled' %}
+{% if 'SkipVersioning' in $.bucket.turbot.tags %}
+  {% set result = 'Skip' %}
+{% endif %}
+"{{ result }}"
+```  
+
+Now the output is `Skip`, which is valid for this policy type.
+<p><img alt="aws_start_4_template_use_skip_versioning_tag" src="/images/docs/guardrails/runbook/aws_start_4_template_use_skip_versioning_tag.png"/></p>
+
+To verify that the calculated policy only applies to buckets with the `SkipVersioning` tag, set the test resource to another bucket under your account that lacks the tag. Verify that the ancestor Sandbox-level setting, `Check: Enabled`, is the result.  
+
+Click `Update` to return the `Create Policy Setting` page.
+
+### Step 7: Create the calculated policy
+
+Click `Create` to create the policy.
+
+Note: To enable the `Create` button you may need to switch `Precedence` from `Required` to `Recommended` and then back to `Required`.
+<p><img alt="aws_start_4_create_policy_setting" src="/images/docs/guardrails/runbook/aws_start_4_create_policy_setting.png"/></p>
+
+You’ll land on the `Policy Setting` page. Select the `Hierarchy` tab to review the situation. The Turbot default is `Skip`, we have overridden it to `Check: Enabled` at the Sandbox level, and refined it at the account level with our calculated policy.
+<p><img alt="aws_start_4_review_calc_policy_in_hierarchy" src="/images/docs/guardrails/runbook/aws_start_4_review_calc_policy_in_hierarchy.png"/></p>
+
+
+
+
+### Step 8: Observe the effect of the calculated policy
+
+Go to `Reports > Controls by State` and search for `s3 bucket versioning`.
+
+Your test bucket should be in the `Skipped` state. Other buckets that don’t enable versioning should be in `Alarm` per the ancestor Sandbox-level policy. 
+<p><img alt="aws_start_4_observe_effect_of_calc_policy_1" src="/images/docs/guardrails/runbook/aws_start_4_observe_effect_of_calc_policy_1.png"/></p>  
+
+
+
+To verify that the new calculated policy applies to all buckets in the account, tag another bucket with `SkipVersioning`,  and go back to `Reports > Controls by State` and search for `s3 bucket versioning`. This time, set the `State` filter to `Skipped`.
+
+The report initially reports only your original test bucket which was the only one exempted from the ancestor `Check: Enabled` policy for bucket versioning. Wait for Guardrails to notice that you assigned `SkipVersioning` to a second bucket. 
+
+
+Both tagged buckets are now in the `Skipped` state.  
+<p><img alt="aws_start_4_observe_effect_of_calc_policy_2" src="/images/docs/guardrails/runbook/aws_start_4_observe_effect_of_calc_policy_2.png"/></p>
+
+Click into your test control, and observe that it’s in the `Skipped` state.  
+<p><img alt="aws_start_4_observe_effect_of_calc_policy_3" src="/images/docs/guardrails/runbook/aws_start_4_observe_effect_of_calc_policy_3.png"/></p>
+
+### Step 9: Find the policies you created
+
+On the Guardrails home page, click `POLICY SETTINGS` (🔧).
+
+Search for `s3 bucket versioning`. 
+<p><img alt="aws_start_4_find_my_policies" src="/images/docs/guardrails/runbook/aws_start_4_find_my_policies.png"/></p>
+
+This view shows the static Sandbox-level exception you created in [this runbook](/guardrails/docs/integrations/aws/getting-started-readonly/create_static_exception) along with the calculated exception you created here. 
+
+
+
+
+
+
+
+
+## Runbook Progress Tracker
+
+1. [Connect a readonly AWS account to Guardrails](/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account)
+
+2. [Review and test a Guardrails AWS control](/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)
+
+4. [Create a static exception to a Guardrails AWS policy](/docs/integrations/aws/getting-started-readonly/create_static_exception)
+
+5. **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)

docs/integrations/aws/getting-started-readonly/create_static_exception.md

@@ -0,0 +1,75 @@
+---
+title: "Create a static exception to a Guardrails AWS policy"
+template: Documentation
+nav:
+  title: "Create a static exception"
+---
+
+
+# Create a static exception to a Guardrails AWS policy
+
+## Introduction
+
+**Purpose**: This runbook shows a Guardrails administrator how to create a static policy exception for an individual AWS resource.
+
+**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]().
+
+## Procedure
+
+### Step 1: Suspend bucket versioning for your test bucket
+
+In [Set an AWS policy]() we attached a policy to your Sandbox that overrides the global default for bucket versioning, so that the effective setting for buckets in your Sandbox is `Check: Enabled`. You saw Guardrails react with `Alarm` when the bucket was in its default state (versioning disabled). You then saw Guardrails react with `OK` when you enabled versioning for the bucket.
+
+Now suspend versioning for that bucket and use top-level-search to find your test bucket.
+<p><img alt="aws_start_3_bucket_versioning_top_level_search_for_resource" src="/images/docs/guardrails/runbook/aws_start_3_bucket_versioning_top_level_search_for_resource.png"/></p>
+
+Click into the resource, select the `Activity` tab, and verify that the control for the bucket is in `Alarm` (or wait until it is).
+
+### Step 2: Create a bucket-level policy exception
+
+Select the `Policies` tab and click `New Policy Setting`.  
+<p><img alt="aws_start_3_begin_new_policy_setting_for_individual_bucket" src="/images/docs/guardrails/runbook/aws_start_3_begin_new_policy_setting_for_individual_bucket.png"/></p>
+
+
+
+Under `Policy Type` search for `aws s3 bucket versioning` and select that policy type.   
+
+Under `Setting` select `Skip`.  
+
+Click `Create`.
+<p><img alt="aws_start_3_create_policy_setting_for_individual_bucket" style="width:70%" src="/images/docs/guardrails/runbook/aws_start_3_create_policy_setting_for_individual_bucket.png"/></p>
+
+On the ensuing `Policy Setting` page, select the `Hierarchy` tab.
+<p><img alt="aws_start_3_new_policy_hierarchy_with_exception_for_individual_bucket" src="/images/docs/guardrails/runbook/aws_start_3_new_policy_hierarchy_with_exception_for_individual_bucket.png"/></p>
+
+### Step 3: Observe the effect of the exception.
+
+
+You’ve now overridden the Sandbox-level setting for this bucket. Select the `Activity` tab and wait for Guardrails to notice the change.
+<p><img alt="aws_start_3_aws_static_exception_in_effect" src="/images/docs/guardrails/runbook/aws_start_3_aws_static_exception_in_effect.png"/></p>
+
+The control for this bucket has transitioned from `Alarm` to `Skipped`.  
+
+Now search for `s3 bucket versioning`.
+<p><img alt="aws_start_3_verify_aws_static_exception" src="/images/docs/guardrails/runbook/aws_start_3_verify_aws_static_exception.png"/></p>
+
+Observe both policies: `Check: Enabled` at the Sandbox level, and `Skip` for the test bucket.  
+
+Note that only one control (for your test bucket) is skipped; all others are subject to the Sandbox-level policy and are in `Alarm`.
+
+
+## Runbook Progress Tracker
+
+1. [Connect a readonly AWS account to Guardrails](/docs/integrations/aws/getting-started-readonly/connect_readonly_aws_account)
+
+2. [Review and test a Guardrails AWS control](/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)
+
+4. **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. [Set an alert on an AWS Guardrails control](/docs/integrations/aws/getting-started-readonly/set_alert_on_control)

docs/integrations/aws/getting-started-readonly/review_and_test_control.md

@@ -0,0 +1,79 @@
+---
+title: "Review and test a Guardrails AWS control"
+template: Documentation
+nav:
+  title: "Review and test a control"
+---
+
+
+# Review and test a Guardrails AWS control
+
+## Introduction
+
+**Purpose**: This runbook shows a cloud engineer or DevOps specialist how to review and test an AWS control and its associated  policies.
+
+**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. 
+
+## Procedure
+
+### Step 1: Observe a control in the OK state
+
+Create an AWS S3 bucket, and verify that `Block public access` is on.
+<p><img alt="aws_start_1_aws_bucket_default" src="/images/docs/guardrails/runbook/aws_start_1_aws_bucket_default.png"/></p>
+
+Go to the `Reports` tab at the top of the Guardrails console, then search for `Controls by Control Type`.
+
+Search for your bucket and  `public access`.
+<p><img alt="aws_start_1_aws_search_for_bucket" src="/images/docs/guardrails/runbook/aws_start_1_aws_search_for_bucket.png"/></p>  
+
+
+
+Click the bucket name to view the `Public Access Block` control for that bucket.
+<p><img alt="aws_start_1_public_access_block_control_initial_green" src="/images/docs/guardrails/runbook/aws_start_1_public_access_block_control_initial_green.png"/></p>
+
+Click the `Policies` tab to review the associated policy. The value is `Check` which means Guardrails will check that the bucket blocks public access and report `OK` if so. Otherwise, it will raise an `Alarm`. No actions will be taken on the bucket in `Check` mode.
+<p><img alt="aws_start_1_public_access_block_policy" src="/images/docs/guardrails/runbook/aws_start_1_public_access_block_policy.png"/></p>
+
+### Step 2: Put the control into Alarm
+
+Go back to the AWS console and turn off `Block all public access`  
+<p><img alt="aws_start_1_console_unblock_public_access" style="width:60%" src="/images/docs/guardrails/runbook/aws_start_1_console_unblock_public_access.png"/></p>
+
+In Guardrails, go back to the `Control` tab. In a few minutes, the control will go to `Alarm`.
+<p><img alt="aws_start_1_public_access_block_control_is_red" src="/images/docs/guardrails/runbook/aws_start_1_public_access_block_control_is_red.png"/></p>
+
+Why not immediately? In the [prerequisite runbook]() we connected Guardrails to your AWS account in readonly mode which means Guardrails can observe, but not act in, your account. In that ReadOnly configuration, Guardrails polls for changes at one minute intervals. Event Handlers offer lower latency but require write access into the account. To enable event-handling, so that Guardrails reacts immediately to changes, see  [this runbook]().  
+
+Click the `Activity` tab to see that Guardrails has logged the transition from `OK` to `Alarm`.
+<p><img alt="aws_start_1_public_access_block_notification_ok_to_alarm" src="/images/docs/guardrails/runbook/aws_start_1_public_access_block_notification_ok_to_alarm.png"/></p>  
+
+
+### Step 3: Restore the control to OK
+
+
+Now revisit the AWS console and enable `Block all public access` again for your bucket.  
+
+As soon as Guardrails notices the change, the control is again green.  
+<p><img alt="aws_start_1_public_access_block_notification_alarm_to_ok" src="/images/docs/guardrails/runbook/aws_start_1_public_access_block_notification_alarm_to_ok.png"/></p>
+
+
+
+
+
+## Runbook Progress Tracker
+
+1. [Connect a readonly AWS account to 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)
+
+4. [Create a static exception to a Guardrails AWS policy](/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. [Set an alert on an AWS Guardrails control](/docs/integrations/aws/getting-started-readonly/set_alert_on_control)