From da2941460a17cd39902ca44d3b18ea03e09552f7 Mon Sep 17 00:00:00 2001 From: SumitPopat Date: Wed, 25 Jun 2025 18:46:06 +0530 Subject: [PATCH 1/6] Add concepts doc for Intelligent Assessment. --- docs/concepts/guardrails/index.md | 1 + .../guardrails/intelligent-assessment.md | 65 +++++++++++++++++++ docs/sidebar.json | 1 + 3 files changed, 67 insertions(+) create mode 100644 docs/concepts/guardrails/intelligent-assessment.md diff --git a/docs/concepts/guardrails/index.md b/docs/concepts/guardrails/index.md index 507f4c72..d981ca1f 100644 --- a/docs/concepts/guardrails/index.md +++ b/docs/concepts/guardrails/index.md @@ -21,6 +21,7 @@ there are many guardrails that are common and consistent across resources. | [Discovery](concepts/guardrails/discovery) | Mechanism by which Guardrails initially adds a resource to the CMDB. | | [Encryption at Rest](concepts/guardrails/encryption-at-rest) | A mechanism to manage data encryption at rest (i.e. AWS S3 Buckets). | | [Encryption in Transit](concepts/guardrails/encryption-in-transit) | A mechanism to manage data encryption in transit (i.e. AWS S3 Buckets). | +| [Intelligent Assessment](concepts/guardrails/intelligent-assessment) | AI-powered resource assessment to evaluate compliance using natural language. | [Public Access](concepts/guardrails/public-access) | Configure public access settings on cloud resources. | | [Scheduling](concepts/guardrails/scheduling) | Define schedules to control cloud resource usage. | | [Stacks/ Configured](concepts/guardrails/configured) | [DEPRECATED] Manage resource configuration using Terraform. | diff --git a/docs/concepts/guardrails/intelligent-assessment.md b/docs/concepts/guardrails/intelligent-assessment.md new file mode 100644 index 00000000..2d43db72 --- /dev/null +++ b/docs/concepts/guardrails/intelligent-assessment.md @@ -0,0 +1,65 @@ +--- +title: Intelligent Assessment Guardrails +sidebar_label: Intelligent Assessment +--- + +# Approved Guardrails + +## Overview + +**Intelligent Assessment** introduces an AI-powered way to define and evaluate governance policies in Turbot Guardrails. +Instead of crafting complex calculated policies, you can describe the check you want — in plain natural language — and let Guardrails interpret and check it. +This unlocks flexible, free-form compliance use cases that would otherwise require significant coding or multiple traditional guardrails. + +Intelligent Assessment is complementary to existing controls (e.g., **Approved** and **Active**). +Where those controls rely on structured sub-policies, Intelligent Assessment excels when you need bespoke logic, conditional checks, or multi-step reasoning. + +The primary Intelligent Assessment policy has a consistent form: +`{provider} > {service} > {resource} > Intelligent Assessment` + +
+ +
+ +The Intelligent Assessment guardrail and policy have a number of sub-settings to determine the +attributes of the assessment. The format of these policy types is +`{provider} > {service} > {resource} > Intelligent Assessment > {Items}`: + +``` + {service} > {resource} > Intelligent Assessment > Context + {service} > {resource} > Intelligent Assessment > User Prompt +``` + +The `Context` sub-policy includes the resource metadata by default but can be updated to include additional data. +The `User Prompt` sub-policy is where you would define a prompt to assess the resource. + +### Example Guardrail: AWS > S3 > Bucket > Intelligent Assessment + +The `AWS > S3 > Bucket > Intelligent Assessment` policy determines the action to take on a resource. You can set the policy to skip (don't run at all), or to check whether the resource is compliant per the user prompt. + +The Intelligent Assessment sub-policies allow you to set the context and the user prompt: + +
+ +
+ +Let's assume that an S3 bucket has tags `"Environment": "Non-Compliant Tag"`, and has versioning disabled. + +```yaml +Tags: + - Key: Environment + Value: Non-Compliant Tag +Versioning: + MFADelete: Disabled + Status: Suspended +``` + +To check if the bucket has the correct `Environment` Tag value and has versioning enabled, you could set the `AWS > S3 > Bucket > Intelligent Assessment > User Prompt` policy to `The bucket must have an Environment tag value of staging and versioning must be enabled`. +The control will then evaluate the result using AI, and go to alarm with the response `The current tag Environment has a value of Non-Compliant Tag which is incorrect. Versioning is not enabled and set to Suspended`. diff --git a/docs/sidebar.json b/docs/sidebar.json index 965c00b8..db1c8dc8 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -124,6 +124,7 @@ "concepts/guardrails/discovery", "concepts/guardrails/encryption-at-rest", "concepts/guardrails/encryption-in-transit", + "concepts/guardrails/intelligent-assessment", "concepts/guardrails/public-access", "concepts/guardrails/scheduling", "concepts/guardrails/stacks", From 77e8fc7426eac951ff7cea806959d7cf5cca4adc Mon Sep 17 00:00:00 2001 From: Sumit Popat Date: Wed, 25 Jun 2025 18:49:21 +0530 Subject: [PATCH 2/6] Update docs/concepts/guardrails/index.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/concepts/guardrails/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/guardrails/index.md b/docs/concepts/guardrails/index.md index d981ca1f..f4214f5e 100644 --- a/docs/concepts/guardrails/index.md +++ b/docs/concepts/guardrails/index.md @@ -21,7 +21,7 @@ there are many guardrails that are common and consistent across resources. | [Discovery](concepts/guardrails/discovery) | Mechanism by which Guardrails initially adds a resource to the CMDB. | | [Encryption at Rest](concepts/guardrails/encryption-at-rest) | A mechanism to manage data encryption at rest (i.e. AWS S3 Buckets). | | [Encryption in Transit](concepts/guardrails/encryption-in-transit) | A mechanism to manage data encryption in transit (i.e. AWS S3 Buckets). | -| [Intelligent Assessment](concepts/guardrails/intelligent-assessment) | AI-powered resource assessment to evaluate compliance using natural language. +| [Intelligent Assessment](concepts/guardrails/intelligent-assessment) | AI-powered resource assessment to evaluate compliance using natural language. | [Public Access](concepts/guardrails/public-access) | Configure public access settings on cloud resources. | | [Scheduling](concepts/guardrails/scheduling) | Define schedules to control cloud resource usage. | | [Stacks/ Configured](concepts/guardrails/configured) | [DEPRECATED] Manage resource configuration using Terraform. | From 69c71658e3b3ed21330c7846d9b4a092c033df74 Mon Sep 17 00:00:00 2001 From: SumitPopat Date: Wed, 25 Jun 2025 19:00:11 +0530 Subject: [PATCH 3/6] Update header --- docs/concepts/guardrails/intelligent-assessment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/guardrails/intelligent-assessment.md b/docs/concepts/guardrails/intelligent-assessment.md index 2d43db72..7d917b70 100644 --- a/docs/concepts/guardrails/intelligent-assessment.md +++ b/docs/concepts/guardrails/intelligent-assessment.md @@ -3,7 +3,7 @@ title: Intelligent Assessment Guardrails sidebar_label: Intelligent Assessment --- -# Approved Guardrails +# Intelligent Assessment Guardrails ## Overview From e2d2883a58172012a6e9e506bfe3f718f7ddcbe7 Mon Sep 17 00:00:00 2001 From: Sumit Popat Date: Fri, 27 Jun 2025 14:35:40 +0530 Subject: [PATCH 4/6] Update docs/concepts/guardrails/intelligent-assessment.md Co-authored-by: cbruno10 --- docs/concepts/guardrails/intelligent-assessment.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/concepts/guardrails/intelligent-assessment.md b/docs/concepts/guardrails/intelligent-assessment.md index 7d917b70..c0e9d783 100644 --- a/docs/concepts/guardrails/intelligent-assessment.md +++ b/docs/concepts/guardrails/intelligent-assessment.md @@ -8,10 +8,13 @@ sidebar_label: Intelligent Assessment ## Overview **Intelligent Assessment** introduces an AI-powered way to define and evaluate governance policies in Turbot Guardrails. + Instead of crafting complex calculated policies, you can describe the check you want — in plain natural language — and let Guardrails interpret and check it. + This unlocks flexible, free-form compliance use cases that would otherwise require significant coding or multiple traditional guardrails. Intelligent Assessment is complementary to existing controls (e.g., **Approved** and **Active**). + Where those controls rely on structured sub-policies, Intelligent Assessment excels when you need bespoke logic, conditional checks, or multi-step reasoning. The primary Intelligent Assessment policy has a consistent form: From 53a3ecc89e1f1dd760856dd1b5086973e1f3c2d0 Mon Sep 17 00:00:00 2001 From: SumitPopat Date: Fri, 27 Jun 2025 14:54:00 +0530 Subject: [PATCH 5/6] Addressed review comments. --- .../guardrails/intelligent-assessment.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/concepts/guardrails/intelligent-assessment.md b/docs/concepts/guardrails/intelligent-assessment.md index c0e9d783..ac822e94 100644 --- a/docs/concepts/guardrails/intelligent-assessment.md +++ b/docs/concepts/guardrails/intelligent-assessment.md @@ -33,13 +33,20 @@ attributes of the assessment. The format of these policy types is `{provider} > {service} > {resource} > Intelligent Assessment > {Items}`: ``` - {service} > {resource} > Intelligent Assessment > Context - {service} > {resource} > Intelligent Assessment > User Prompt +{provider} > {service} > {resource} > Intelligent Assessment > Context +{provider} > {service} > {resource} > Intelligent Assessment > User Prompt ``` The `Context` sub-policy includes the resource metadata by default but can be updated to include additional data. The `User Prompt` sub-policy is where you would define a prompt to assess the resource. +As part of the evaluation, the AI provider will respond with `State` and `Reason`. +The `State` attribute is either + +- `OK`: Evaluation matches the given user prompt +- `Alarm`: Evaluation does not match the given user prompt +- `Error`: User prompt is empty or AI cannot determine the outcome based on the user prompt and context + ### Example Guardrail: AWS > S3 > Bucket > Intelligent Assessment The `AWS > S3 > Bucket > Intelligent Assessment` policy determines the action to take on a resource. You can set the policy to skip (don't run at all), or to check whether the resource is compliant per the user prompt. @@ -64,5 +71,8 @@ Versioning: Status: Suspended ``` -To check if the bucket has the correct `Environment` Tag value and has versioning enabled, you could set the `AWS > S3 > Bucket > Intelligent Assessment > User Prompt` policy to `The bucket must have an Environment tag value of staging and versioning must be enabled`. +To check if the bucket has the correct `Environment` tag value and has versioning enabled: + +- Set `AWS > S3 > Bucket > Intelligent Assessment > User Prompt` policy to: `The bucket must have an Environment tag value of staging and versioning must be enabled` + The control will then evaluate the result using AI, and go to alarm with the response `The current tag Environment has a value of Non-Compliant Tag which is incorrect. Versioning is not enabled and set to Suspended`. From 712bdac0b195b685f86c9aed4b95b85cc8f64b47 Mon Sep 17 00:00:00 2001 From: SumitPopat Date: Fri, 27 Jun 2025 15:11:55 +0530 Subject: [PATCH 6/6] minor fixes. --- docs/concepts/guardrails/intelligent-assessment.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/concepts/guardrails/intelligent-assessment.md b/docs/concepts/guardrails/intelligent-assessment.md index ac822e94..1416dfa6 100644 --- a/docs/concepts/guardrails/intelligent-assessment.md +++ b/docs/concepts/guardrails/intelligent-assessment.md @@ -41,11 +41,12 @@ The `Context` sub-policy includes the resource metadata by default but can be up The `User Prompt` sub-policy is where you would define a prompt to assess the resource. As part of the evaluation, the AI provider will respond with `State` and `Reason`. -The `State` attribute is either -- `OK`: Evaluation matches the given user prompt -- `Alarm`: Evaluation does not match the given user prompt -- `Error`: User prompt is empty or AI cannot determine the outcome based on the user prompt and context +The `State` attribute is either: + +- `OK` - Evaluation matches the given user prompt +- `Alarm` - Evaluation does not match the given user prompt +- `Error` - User prompt is empty or AI cannot determine the outcome based on the user prompt and context ### Example Guardrail: AWS > S3 > Bucket > Intelligent Assessment @@ -73,6 +74,6 @@ Versioning: To check if the bucket has the correct `Environment` tag value and has versioning enabled: -- Set `AWS > S3 > Bucket > Intelligent Assessment > User Prompt` policy to: `The bucket must have an Environment tag value of staging and versioning must be enabled` +- Set `AWS > S3 > Bucket > Intelligent Assessment > User Prompt`: `The bucket must have an Environment tag value of staging and versioning must be enabled` The control will then evaluate the result using AI, and go to alarm with the response `The current tag Environment has a value of Non-Compliant Tag which is incorrect. Versioning is not enabled and set to Suspended`.