From 2d53f2e59900b29c762915857ed1fd7e47bd59f3 Mon Sep 17 00:00:00 2001 From: Cody Bruno Date: Thu, 11 Sep 2025 13:56:47 -0400 Subject: [PATCH 1/4] Update workspace FAQ and policy values concepts with control/policy creation updates from materialization --- docs/concepts/policies/values-settings.md | 6 +- docs/faq/workspace-faq/index.md | 72 ++++++++++++++++++- .../7-minute-labs/set-policy/index.md | 13 ++-- 3 files changed, 81 insertions(+), 10 deletions(-) diff --git a/docs/concepts/policies/values-settings.md b/docs/concepts/policies/values-settings.md index b51e702d..21778d90 100644 --- a/docs/concepts/policies/values-settings.md +++ b/docs/concepts/policies/values-settings.md @@ -9,13 +9,13 @@ sidebar_label: Values & Settings Each policy type may have many settings for different resources. -
The policy type AWS > S3 > Bucket > Approved may be set to `Enforce: Delete unapproved if new & empty` for development accounts, but deliberately limited to `Check: Approved` for production accounts. +
The policy type AWS > S3 > Bucket > Approved may be set to Enforce: Delete unapproved if new & empty for development accounts, but deliberately limited to Check: Approved for production accounts.
**Policy Settings** are inherited down through the hierarchy of resources.
AWS > S3 > Bucket > Approved may be set -to `Enforce: Delete unapproved if new & empty` at Turbot level - ensuring all buckets are deleted if they don't meet the approval criteria (e.g. in approved region). +to Enforce: Delete unapproved if new & empty at Turbot level - ensuring all buckets are deleted if they don't meet the approval criteria (e.g. in approved region).
Policy settings are only valid for target resources and their ancestors. @@ -44,7 +44,7 @@ policy values exist only on the target. AWS > S3 > Bucket > Approved
diff --git a/docs/faq/workspace-faq/index.md b/docs/faq/workspace-faq/index.md index ae868e22..485a501a 100644 --- a/docs/faq/workspace-faq/index.md +++ b/docs/faq/workspace-faq/index.md @@ -12,10 +12,16 @@ sidebar_label: "Workspace FAQ" * [When do Guardrails API keys expire?](#when-do-guardrails-api-keys-expire) * [Is it possible to get an event stream out of Guardrails?](#is-it-possible-to-get-an-event-stream-out-of-guardrails) * [Can I make mods available for only part of the workspace?](#can-i-make-mods-available-for-only-part-of-the-workspace) +* [When are policy values created in Guardrails?](#when-are-policy-values-created-in-guardrails) +* [Why don't I see policy values for all my resources?](#why-dont-i-see-policy-values-for-all-my-resources) +* [When are control instances created for my resources?](#when-are-control-instances-created-for-my-resources) +* [How can I view all installed control types and policy types?](#how-can-i-view-all-installed-control-types-and-policy-types) +* [What's the difference between a policy having no value vs. being set to 'Skip'?](#whats-the-difference-between-a-policy-having-no-value-vs-being-set-to-skip) --- ## Can I rotate the keys embedded in Guardrails' event handlers? + Sure! Regular key rotation is a part of any strong security stance. Configuration and troubleshooting instructions can be found on the [key rotation](workspace-faq/key_rotation) page. ## The Guardrails console session expires at 12 hours. Can it be shorter? @@ -23,12 +29,76 @@ Sure! Regular key rotation is a part of any strong security stance. Configurati The Guardrails console session timeout period can be adjusted with the [Turbot > Workspace > Console Session Timeout](mods/turbot/turbot-iam/policy#turbot--workspace--console-session-timeout) to as little as 15 minutes. Keep in mind that this is a global change that affects all users in the Guardrails console. Guardrails API keys are not affected by this change. ## When do Guardrails API keys expire? + By default, Guardrails API keys do not expire. Guardrails admins can set the [Turbot > IAM > Access Key > Expiration](mods/turbot/turbot-iam/policy#turbot--iam--access-key--expiration) policy to deactivate or delete Guardrails API keys to a range of expiration periods ranging up to 90 days. Ensure that Guardrails console access can be recovered if access keys expire for any break-glass users. A calculated policy could be written for the `Turbot > IAM > Access Key > Expiration` policy to identify and preserve the API keys for break-glass users but deactivate/destroy keys for other users. Note that this policy does not affect AWS IAM Access Keys. ## Is it possible to get an event stream out of Guardrails? + The Guardrails Firehose provides a user configurable event stream of cloud environment change, Guardrails control state, and Guardrails permission assignments. Full details on how to configure the Firehose can be found in the [Firehose guide](guides/firehose). ## Can I make mods available for only part of the workspace? -Installing a Guardrails mod makes the resource types, controls and policies available to the entire workspace. \ No newline at end of file + +Installing a Guardrails mod makes the resource types, controls and policies available to the entire workspace. + +## When are policy values created in Guardrails? + +Policy value creation depends on the type of policy: + +**Configuration and account-level policies**: These policy values are created automatically when resources are discovered, using default values from the installed mods. These include settings like regions, budgets, and account notification CC configurations. + +**Control-specific policies**: These policy values are only created when you set a policy setting somewhere in the resource hierarchy. These are typically policies that drive specific controls like `AWS > S3 > Bucket > Approved` or `AWS > EC2 > Instance > Active`. + +For example, if you set the `AWS > S3 > Bucket > Approved` policy at the AWS account level, Guardrails will create policy values for this policy type and all of its sub-policies, like `AWS > S3 > Bucket > Approved > Regions` for all S3 buckets in that account. Without a policy setting somewhere in the hierarchy, no policy value exists for control-specific policy types. + +## Why don't I see policy values for all my resources? + +There are two main reasons you might not see certain policy values: + +**For control-specific policies**: If you don't see a policy value for policies that drive specific controls (like `AWS > S3 > Bucket > Approved`), it means no policy setting has been created anywhere in the resource hierarchy for that policy type. This is by design - Guardrails only creates these policy values when policy settings exist. + +**For configuration policies**: These should appear automatically with default values. If they're missing, it may indicate the relevant mod isn't installed or the resource discovery hasn't completed. + +## When are control instances created for my resources? + +Control instances are only created when policy settings exist for the primary policy that drives that control. + +For example, the `AWS > S3 > Bucket > Approved` control will only appear on your S3 buckets when you have policy settings for the `AWS > S3 > Bucket > Approved` policy type. + +This means different resources may show different sets of controls based on which policies have been configured in their hierarchy. Configuration and account-level controls may appear automatically with their related policy values. + +## How can I view all installed control types and policy types? + +There are several ways to explore what control types and policy types are available in your Guardrails workspace: + +**For a specific resource type:** +1. **Navigate to any resource** of the type you're interested in +2. **View available control types**: Go to the **Controls** tab and select **Self** from the level dropdown to see all control types that apply to this resource type +3. **View available policy types**: Go to the **Policies** tab and select **Self** from the level dropdown to see all policy types that apply to this resource type + +**For browsing all control and policy types:** +1. **Navigate to the main Controls section** in Guardrails +2. **Use the Explore tab** to browse control types by hierarchy and search for specific control types +3. **Navigate to the main Policies section** in Guardrails +4. **Use the Explore tab** to browse policy types by hierarchy and search for specific policy types + +## What's the difference between a policy having no value vs. being set to 'Skip'? + +This distinction is important for control-driving policies: + +**No policy value (no policy setting exists)**: +- No policy setting has been created anywhere in the hierarchy for this control-driving policy +- No policy value exists for this policy type on the resource +- No control instance is created +- The policy type is essentially "inactive" for this resource + +**Policy value set to "Skip" (policy setting exists)**: +- A policy setting exists and is explicitly set to "Skip" +- A policy value exists on the resource with the value "Skip" +- A control instance is created but is in the "Skipped" state +- The policy type is "active" but the control takes no action + +**Note**: Configuration and account-level policies typically always have values (even if using defaults), so this distinction mainly applies to control-driving policies like "Approved", "Active", and "Versioning" policies. + +Setting a control-driving policy to "Skip" is useful when you want the control to exist (for reporting, future changes, etc.) but don't want it to take any enforcement action. \ No newline at end of file diff --git a/docs/getting-started/7-minute-labs/set-policy/index.md b/docs/getting-started/7-minute-labs/set-policy/index.md index 4c7ba220..d80cf1ee 100644 --- a/docs/getting-started/7-minute-labs/set-policy/index.md +++ b/docs/getting-started/7-minute-labs/set-policy/index.md @@ -33,20 +33,21 @@ values in the Turbot Guardrails Console. ## View a Policy Value -1. In the Turbot Guardrails Console, navigate to the test bucket that you created in the - [prerequisite step](set-policy#prerequisites). Our test bucket name is - _turbot-bucket-version_, which we can search for at the main Turbot Guardrails screen. - Click on the bucket once it is found. +1. In the Turbot Guardrails Console, search for the test bucket called _turbot-bucket-version_ that you created in the [prerequisite step](set-policy#prerequisites). ![](/images/docs/guardrails/search-bucket-step1.png) + +2. Click on the bucket once it is found. ![](/images/docs/guardrails/search-bucket-step2.png) + +3. Next, you'll see the bucket's details. ![](/images/docs/guardrails/search-bucket-step3.png) -2. Click the **Policies** tab. It shows both +4. Click the **Policies** tab. It shows both [Policy Settings](concepts/policies/values-settings#policy-settings) and [Policy Values](concepts/policies/values-settings#policy-values). ![](/images/docs/guardrails/settings-values.png) -3. From the list of Policy Values for this bucket, click on the **Template +5. From the list of Policy Values for this bucket, click on the **Template (Bucket > Tags > Template)** item to bring up the policy value. ![](/images/docs/guardrails/default-policy-value.png) From a72816c72c3435b422ec6cd1f36762c72332ee91 Mon Sep 17 00:00:00 2001 From: cbruno10 Date: Thu, 11 Sep 2025 14:09:05 -0400 Subject: [PATCH 2/4] Update docs/concepts/policies/values-settings.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/concepts/policies/values-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/policies/values-settings.md b/docs/concepts/policies/values-settings.md index 21778d90..8daea48f 100644 --- a/docs/concepts/policies/values-settings.md +++ b/docs/concepts/policies/values-settings.md @@ -44,7 +44,7 @@ policy values exist only on the target. AWS > S3 > Bucket > Approved From 93e71a801f069bd641462c89a33faccbd0928bae Mon Sep 17 00:00:00 2001 From: Cody Bruno Date: Thu, 11 Sep 2025 14:50:46 -0400 Subject: [PATCH 3/4] Minor updates and cleanup in FAQ --- docs/faq/workspace-faq/index.md | 68 ++++++--------------------------- 1 file changed, 11 insertions(+), 57 deletions(-) diff --git a/docs/faq/workspace-faq/index.md b/docs/faq/workspace-faq/index.md index 485a501a..404cef3a 100644 --- a/docs/faq/workspace-faq/index.md +++ b/docs/faq/workspace-faq/index.md @@ -12,11 +12,8 @@ sidebar_label: "Workspace FAQ" * [When do Guardrails API keys expire?](#when-do-guardrails-api-keys-expire) * [Is it possible to get an event stream out of Guardrails?](#is-it-possible-to-get-an-event-stream-out-of-guardrails) * [Can I make mods available for only part of the workspace?](#can-i-make-mods-available-for-only-part-of-the-workspace) -* [When are policy values created in Guardrails?](#when-are-policy-values-created-in-guardrails) -* [Why don't I see policy values for all my resources?](#why-dont-i-see-policy-values-for-all-my-resources) -* [When are control instances created for my resources?](#when-are-control-instances-created-for-my-resources) -* [How can I view all installed control types and policy types?](#how-can-i-view-all-installed-control-types-and-policy-types) -* [What's the difference between a policy having no value vs. being set to 'Skip'?](#whats-the-difference-between-a-policy-having-no-value-vs-being-set-to-skip) +* [Why don't I see all controls for my resources?](#why-dont-i-see-all-controls-for-my-resources) +* [Why do some policy types have no values?](#why-do-some-policy-types-have-no-values) --- @@ -42,63 +39,20 @@ The Guardrails Firehose provides a user configurable event stream of cloud envir Installing a Guardrails mod makes the resource types, controls and policies available to the entire workspace. -## When are policy values created in Guardrails? +## Why don't I see all controls for my resources? -Policy value creation depends on the type of policy: +Most controls are only created when policy settings exist for the primary policy that drives that control. -**Configuration and account-level policies**: These policy values are created automatically when resources are discovered, using default values from the installed mods. These include settings like regions, budgets, and account notification CC configurations. +For example, the `AWS > S3 > Bucket > Approved` control will only appear on your S3 buckets when you have policy settings for the `AWS > S3 > Bucket > Approved` policy type. If you only create policy settings for sub-policies, like `AWS > S3 > Bucket > Approved > Regions`, the control will **not** be created. -**Control-specific policies**: These policy values are only created when you set a policy setting somewhere in the resource hierarchy. These are typically policies that drive specific controls like `AWS > S3 > Bucket > Approved` or `AWS > EC2 > Instance > Active`. +CMDB and configuration controls, like `AWS > EC2 > Instance > Discovery` and `AWS > Turbot > Event Handlers`, are always created with their related policy values. -For example, if you set the `AWS > S3 > Bucket > Approved` policy at the AWS account level, Guardrails will create policy values for this policy type and all of its sub-policies, like `AWS > S3 > Bucket > Approved > Regions` for all S3 buckets in that account. Without a policy setting somewhere in the hierarchy, no policy value exists for control-specific policy types. +You can view all available control types for a resource by navigating to a specific resource, and then selecting the `Controls` tab. -## Why don't I see policy values for all my resources? +## Why do some policy types have no values? -There are two main reasons you might not see certain policy values: +Most policy types only create policy values when you explicitly set a policy setting somewhere in the resource hierarchy. These are typically policies that drive specific controls like `AWS > S3 > Bucket > Approved` or `AWS > EC2 > Instance > Active`. -**For control-specific policies**: If you don't see a policy value for policies that drive specific controls (like `AWS > S3 > Bucket > Approved`), it means no policy setting has been created anywhere in the resource hierarchy for that policy type. This is by design - Guardrails only creates these policy values when policy settings exist. +For example, if you set the `AWS > S3 > Bucket > Approved` policy at the AWS account level, Guardrails will create policy values for this policy type and all of its sub-policies, like `AWS > S3 > Bucket > Approved > Regions` for all S3 buckets in that account. Without a policy setting somewhere in the hierarchy, no policy value exists for these policy types. -**For configuration policies**: These should appear automatically with default values. If they're missing, it may indicate the relevant mod isn't installed or the resource discovery hasn't completed. - -## When are control instances created for my resources? - -Control instances are only created when policy settings exist for the primary policy that drives that control. - -For example, the `AWS > S3 > Bucket > Approved` control will only appear on your S3 buckets when you have policy settings for the `AWS > S3 > Bucket > Approved` policy type. - -This means different resources may show different sets of controls based on which policies have been configured in their hierarchy. Configuration and account-level controls may appear automatically with their related policy values. - -## How can I view all installed control types and policy types? - -There are several ways to explore what control types and policy types are available in your Guardrails workspace: - -**For a specific resource type:** -1. **Navigate to any resource** of the type you're interested in -2. **View available control types**: Go to the **Controls** tab and select **Self** from the level dropdown to see all control types that apply to this resource type -3. **View available policy types**: Go to the **Policies** tab and select **Self** from the level dropdown to see all policy types that apply to this resource type - -**For browsing all control and policy types:** -1. **Navigate to the main Controls section** in Guardrails -2. **Use the Explore tab** to browse control types by hierarchy and search for specific control types -3. **Navigate to the main Policies section** in Guardrails -4. **Use the Explore tab** to browse policy types by hierarchy and search for specific policy types - -## What's the difference between a policy having no value vs. being set to 'Skip'? - -This distinction is important for control-driving policies: - -**No policy value (no policy setting exists)**: -- No policy setting has been created anywhere in the hierarchy for this control-driving policy -- No policy value exists for this policy type on the resource -- No control instance is created -- The policy type is essentially "inactive" for this resource - -**Policy value set to "Skip" (policy setting exists)**: -- A policy setting exists and is explicitly set to "Skip" -- A policy value exists on the resource with the value "Skip" -- A control instance is created but is in the "Skipped" state -- The policy type is "active" but the control takes no action - -**Note**: Configuration and account-level policies typically always have values (even if using defaults), so this distinction mainly applies to control-driving policies like "Approved", "Active", and "Versioning" policies. - -Setting a control-driving policy to "Skip" is useful when you want the control to exist (for reporting, future changes, etc.) but don't want it to take any enforcement action. \ No newline at end of file +Some policy types always have values created automatically when resources are discovered, using default values. These CMDB and configuration policies include settings like CMDB, event handlers, and account notification recipients. \ No newline at end of file From 1274b039ab013fbe839126c52783fc560cc5e11f Mon Sep 17 00:00:00 2001 From: Cody Bruno Date: Fri, 12 Sep 2025 11:15:10 -0400 Subject: [PATCH 4/4] Add notes on materialization policy --- docs/faq/workspace-faq/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/faq/workspace-faq/index.md b/docs/faq/workspace-faq/index.md index 404cef3a..153daea7 100644 --- a/docs/faq/workspace-faq/index.md +++ b/docs/faq/workspace-faq/index.md @@ -41,6 +41,8 @@ Installing a Guardrails mod makes the resource types, controls and policies avai ## Why don't I see all controls for my resources? +**Note**: This applies when the `Turbot > Materialization` policy is set to `Automatic`. If set to `Always`, all controls will appear regardless of policy settings. + Most controls are only created when policy settings exist for the primary policy that drives that control. For example, the `AWS > S3 > Bucket > Approved` control will only appear on your S3 buckets when you have policy settings for the `AWS > S3 > Bucket > Approved` policy type. If you only create policy settings for sub-policies, like `AWS > S3 > Bucket > Approved > Regions`, the control will **not** be created. @@ -51,6 +53,8 @@ You can view all available control types for a resource by navigating to a speci ## Why do some policy types have no values? +**Note**: This applies when the `Turbot > Materialization` policy is set to `Automatic`. If set to `Always`, all policy values will be created regardless of whether policy settings exist. + Most policy types only create policy values when you explicitly set a policy setting somewhere in the resource hierarchy. These are typically policies that drive specific controls like `AWS > S3 > Bucket > Approved` or `AWS > EC2 > Instance > Active`. For example, if you set the `AWS > S3 > Bucket > Approved` policy at the AWS account level, Guardrails will create policy values for this policy type and all of its sub-policies, like `AWS > S3 > Bucket > Approved > Regions` for all S3 buckets in that account. Without a policy setting somewhere in the hierarchy, no policy value exists for these policy types.