diff --git a/docs/concepts/controls/index.md b/docs/concepts/controls/index.md index f075c02d..1db75461 100644 --- a/docs/concepts/controls/index.md +++ b/docs/concepts/controls/index.md @@ -17,6 +17,15 @@ Resource State + Policy Setting = Control State As a concrete example: A cloud storage resource does not have encryption at rest configured. In Guardrails, the encryption at rest policy asserts that storage should be encrypted at rest. The encryption at rest control evaluates resource state against the policy then acts. In this case, the control will go into an `alarm` state. If the policy is set to check mode then the control will only go into `alarm`. If in enforce mode, the control will go into `alarm` and Guardrails will act to remediate the resource. When the remediation is successful, the control will rerun then go into `ok`. +## Control Creation + +Control creation is controlled by the `Turbot > Materialization` policy, which supports two modes: + +- **Always**: Controls are created for all resources regardless of whether policy settings exist. This provides comprehensive coverage but may impact performance in large environments. +- **Automatic**: Controls are only created when you explicitly set the primary policy in the resource hierarchy. For example, the `AWS > S3 > Bucket > Approved` control will only appear on your S3 buckets when you have a policy setting for the `AWS > S3 > Bucket > Approved` policy type. However, if you only create policy settings for its sub-policies, like `AWS > S3 > Bucket > Approved > Regions`, the control will **not** be created. + +Note that some controls, such as those used to discover resources and configure accounts (like `AWS > EC2 > Instance > Discovery` and `AWS > Turbot > Event Handlers`), are always created regardless of the materialization mode. + ## Control Types A **Control Type** is a definition for a particular control. Each different control type is a blueprint that can be configured for resources, such the **Approved** control type for AWS S3 buckets. In this case, the control `AWS > S3 > Bucket > Approved` evaluates policy settings to determine what it means for an S3 bucket to be "Approved," and will take the action defined in the associated, identically named policy (`AWS > S3 > Bucket > Approved`). diff --git a/docs/concepts/policies/values-settings.md b/docs/concepts/policies/values-settings.md index b51e702d..346e8a72 100644 --- a/docs/concepts/policies/values-settings.md +++ b/docs/concepts/policies/values-settings.md @@ -5,17 +5,17 @@ sidebar_label: Values & Settings # Policy Values & Settings -### Policy Settings +## Policy 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. @@ -25,11 +25,11 @@ Policy settings are only valid for target resources and their ancestors. down to the specific S3 Bucket such as Turbot > Folder A > AWS 1111 > us-east-1 > my-bucket.
-### Policy Values +## Policy Values A **Policy Value** is the effective policy setting on an instance of a resource -type. Every resource that is targeted by a given policy setting will have its -own value for that policy, which will be the resultant calculated policy for the +type. Resources that are targeted by a given policy setting will have their own +values for that policy, which will be the resultant calculated policy for the "winning" policy in the hierarchy. Policy settings are inherited through the resource hierarchy, and values for a @@ -40,11 +40,18 @@ inherited by all resources below. While policy settings can exist above the target in the resource hierarchy, policy values exist only on the target. +Policy value creation is controlled by the `Turbot > Materialization` policy, which supports two modes: + +- **Always**: Policy values are created for all resources regardless of whether policy settings exist. This provides comprehensive coverage but may impact performance in large environments. +- **Automatic**: Primary policy values are only created when you explicitly set a primary policy in the resource hierarchy. For sub-policy types, their values are also created when a related primary policy setting is created. For example, if no policy setting exists for `AWS > S3 > Bucket > Approved` at the AWS account level, then S3 buckets in that account will not have policy values for `AWS > S3 > Bucket > Approved` or its sub-policies. + +Note that some policy types, such as those related to CMDB and event handler configuration, always create values when resources are discovered, regardless of the materialization mode. +
AWS > S3 > Bucket > Approved
diff --git a/docs/faq/workspace-faq/index.md b/docs/faq/workspace-faq/index.md index ae868e22..1aa2a661 100644 --- a/docs/faq/workspace-faq/index.md +++ b/docs/faq/workspace-faq/index.md @@ -12,10 +12,13 @@ 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) +* [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) --- ## 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 +26,35 @@ 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. + +## Why don't I see all controls for my resources? + +**Note**: If the `Turbot > Materialization` policy is set to `Always` or your workspace doesn't have the `Turbot > Materialization` policy type installed, 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 a policy setting for the `AWS > S3 > Bucket > Approved` policy type. However, if you only create policy settings for its sub-policies, like `AWS > S3 > Bucket > Approved > Regions`, the control will **not** be created. + +Controls used to discover resources and configure accounts, like `AWS > EC2 > Instance > Discovery` and `AWS > Turbot > Event Handlers`, are always created with their related policy values. + +## Why do some policy types have no values? + +**Note**: If the `Turbot > Materialization` policy is set to `Always` or your workspace doesn't have the `Turbot > Materialization` policy type installed, all policy values will be created regardless of policy settings. + +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 create a policy setting for the `AWS > S3 > Bucket > Approved` policy type 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. + +Some policy types, like those related to CMDB and event handler configuration, always have values created when resources are discovered. 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)