diff --git a/docs/developers/developers-sidebar.json b/docs/developers/developers-sidebar.json new file mode 100644 index 00000000..ff6e4c38 --- /dev/null +++ b/docs/developers/developers-sidebar.json @@ -0,0 +1,12 @@ +{ + "type": "category", + "id": "developers", + "link": "developers", + "items": [ + "developers/install-mcp", + "developers/policy-pack-development", + "developers/graphql", + "developers/nunjucks", + "developers/fix-calc-policy-evaluation-errors" + ] +} diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/calc-policy-builder-page.png b/docs/developers/fix-calc-policy-evaluation-errors/calc-policy-builder-page.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/calc-policy-builder-page.png rename to docs/developers/fix-calc-policy-evaluation-errors/calc-policy-builder-page.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-control-ok-state.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-control-ok-state.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-control-ok-state.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-control-ok-state.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-launch-policy-builder.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-launch-policy-builder.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-launch-policy-builder.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-launch-policy-builder.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-policy-value-ok.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-policy-value-ok.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-policy-value-ok.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-policy-value-ok.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-resolve-cal-policy.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-resolve-cal-policy.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-resolve-cal-policy.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-resolve-cal-policy.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-calc-policy-in-error.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-calc-policy-in-error.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-calc-policy-in-error.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-calc-policy-in-error.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-edit.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-edit.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-edit.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-edit.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-effective-calc-policy.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-effective-calc-policy.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-effective-calc-policy.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-effective-calc-policy.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-policies.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-policies.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-policies.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-select-policies.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-update-policy.png b/docs/developers/fix-calc-policy-evaluation-errors/guardrails-update-policy.png similarity index 100% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-update-policy.png rename to docs/developers/fix-calc-policy-evaluation-errors/guardrails-update-policy.png diff --git a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/index.md b/docs/developers/fix-calc-policy-evaluation-errors/index.md similarity index 70% rename from docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/index.md rename to docs/developers/fix-calc-policy-evaluation-errors/index.md index 589be481..d98e10e2 100644 --- a/docs/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/index.md +++ b/docs/developers/fix-calc-policy-evaluation-errors/index.md @@ -22,7 +22,7 @@ However, calculated policies can sometimes encounter errors due to misconfigurat Log into the Guardrails console with provided local credentials or by using any SAML based login and Select **Policies** from the top navigation menu. -![Navigate to Reports](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-policies.png) +![Navigate to Reports](./guardrails-select-policies.png) ## Step 2: Select Policy Value @@ -30,47 +30,47 @@ Select the calculated policy in an error state that needs to be resolved. This r Here, the error occurs due to `TypeError: Cannot read properties of undefined (reading 'toString')`, indicating that the referenced property is undefined and cannot be converted to a string. -![Select Calculated Policy](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-calc-policy-in-error.png) +![Select Calculated Policy](./guardrails-select-calc-policy-in-error.png) ## Step 3: Select Calculated Policy Select the **Calculated** policy, with an ✅ `EFFECTIVE SETTING`. -![Effective Setting](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-effective-calc-policy.png) +![Effective Setting](./guardrails-select-effective-calc-policy.png) ## Step 4: Edit Policy Setting Select **Edit** from the top right corner. -![Select Edit](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-select-edit.png) +![Select Edit](./guardrails-select-edit.png) Choose **Launch calculated policy builder**. -![Launch Calculated Policy Builder](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-launch-policy-builder.png) +![Launch Calculated Policy Builder](./guardrails-launch-policy-builder.png) This displays the `GraphQL` query and `Jinja2/Nunjucks` template used in the calculated policy, providing insight into how the policy value is generated. -![Calculated Policy Builder Page](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/calc-policy-builder-page.png) +![Calculated Policy Builder Page](./calc-policy-builder-page.png) ## Step 5: Resolve Calculated Policy Select the `Test Resource`, update the corrected Jinja2/Nunjucks template, and view the real-time output to verify if the fix is successful. Choose **Update**. -![Resolve Error](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-resolve-cal-policy.png) +![Resolve Error](./guardrails-resolve-cal-policy.png) Select **Update** from the Update Policy Setting page. -![Select Update](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-update-policy.png) +![Select Update](./guardrails-update-policy.png) ## Step 6: Review - [ ] Verify that the policy value transitions to an `OK` state, confirming the issue has been resolved successfully. -![Policy Value State](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-policy-value-ok.png) +![Policy Value State](./guardrails-policy-value-ok.png) - [ ] Verify that the affected control transitions to an `OK` state. -![Control State](/images/docs/guardrails/guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors/guardrails-control-ok-state.png) +![Control State](./guardrails-control-ok-state.png) ## Troubleshooting diff --git a/docs/guides/using-guardrails/graphql/index.md b/docs/developers/graphql/index.md similarity index 100% rename from docs/guides/using-guardrails/graphql/index.md rename to docs/developers/graphql/index.md diff --git a/docs/developers/index.md b/docs/developers/index.md new file mode 100644 index 00000000..b135770e --- /dev/null +++ b/docs/developers/index.md @@ -0,0 +1,16 @@ +--- +title: Developers +sidebar_label: Developers +--- + +# Developing guardrails for Guardrails + +This section covers the various AI-powered features available in Guardrails. + +| Section | Description +| - | - +| [Install Guardrails MCP](/guardrails/docs/developers/install-mcp) | Learn how Guardrails Model Context Protocol (MCP) server is enabled. +| [Policy Pack Development](/guardrails/docs/developers/policy-pack-development) | Learn how to use AI to develop and validate policy packs. +| [GraphQL](/guardrails/docs/developers/graphql) | Tips and Tricks for GraphQL +| [Nunjucks](/guardrails/docs/developers/nunjucks) | Tips and tricks for using Nunjucks, including troubleshooting +| [Resolve Calculated Policy Errors](/guardrails/docs/developers/fix-calc-policy-evaluation-errors) | Troubleshooting calc policy errors \ No newline at end of file diff --git a/docs/guides/using-guardrails/ai-tools/index.md b/docs/developers/install-mcp/index.md similarity index 98% rename from docs/guides/using-guardrails/ai-tools/index.md rename to docs/developers/install-mcp/index.md index c377f9ca..7f1fbd36 100644 --- a/docs/guides/using-guardrails/ai-tools/index.md +++ b/docs/developers/install-mcp/index.md @@ -1,9 +1,9 @@ --- -title: AI Tools (MCP) -sidebar_label: AI Tools (MCP) +title: Install Guardrails MCP +sidebar_label: Install MCP for AI --- -# Configure Guardrails MCP Server +# Install the Guardrails' MCP Server for AI Assisted Development In this guide, you will: diff --git a/docs/guides/using-guardrails/nunjucks/approve.png b/docs/developers/nunjucks/approve.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/approve.png rename to docs/developers/nunjucks/approve.png diff --git a/docs/guides/using-guardrails/nunjucks/error1.png b/docs/developers/nunjucks/error1.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error1.png rename to docs/developers/nunjucks/error1.png diff --git a/docs/guides/using-guardrails/nunjucks/error2.png b/docs/developers/nunjucks/error2.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error2.png rename to docs/developers/nunjucks/error2.png diff --git a/docs/guides/using-guardrails/nunjucks/error3.png b/docs/developers/nunjucks/error3.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error3.png rename to docs/developers/nunjucks/error3.png diff --git a/docs/guides/using-guardrails/nunjucks/error4.png b/docs/developers/nunjucks/error4.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error4.png rename to docs/developers/nunjucks/error4.png diff --git a/docs/guides/using-guardrails/nunjucks/error5.png b/docs/developers/nunjucks/error5.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error5.png rename to docs/developers/nunjucks/error5.png diff --git a/docs/guides/using-guardrails/nunjucks/error6.png b/docs/developers/nunjucks/error6.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/error6.png rename to docs/developers/nunjucks/error6.png diff --git a/docs/guides/using-guardrails/nunjucks/index.md b/docs/developers/nunjucks/index.md similarity index 100% rename from docs/guides/using-guardrails/nunjucks/index.md rename to docs/developers/nunjucks/index.md diff --git a/docs/guides/using-guardrails/nunjucks/multi-tag.png b/docs/developers/nunjucks/multi-tag.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/multi-tag.png rename to docs/developers/nunjucks/multi-tag.png diff --git a/docs/guides/using-guardrails/nunjucks/object-object.png b/docs/developers/nunjucks/object-object.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/object-object.png rename to docs/developers/nunjucks/object-object.png diff --git a/docs/guides/using-guardrails/nunjucks/regex1.png b/docs/developers/nunjucks/regex1.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/regex1.png rename to docs/developers/nunjucks/regex1.png diff --git a/docs/guides/using-guardrails/nunjucks/regex2.png b/docs/developers/nunjucks/regex2.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/regex2.png rename to docs/developers/nunjucks/regex2.png diff --git a/docs/guides/using-guardrails/nunjucks/regex3.png b/docs/developers/nunjucks/regex3.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/regex3.png rename to docs/developers/nunjucks/regex3.png diff --git a/docs/guides/using-guardrails/nunjucks/tag-value.png b/docs/developers/nunjucks/tag-value.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/tag-value.png rename to docs/developers/nunjucks/tag-value.png diff --git a/docs/guides/using-guardrails/nunjucks/tag1.png b/docs/developers/nunjucks/tag1.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/tag1.png rename to docs/developers/nunjucks/tag1.png diff --git a/docs/guides/using-guardrails/nunjucks/tags.png b/docs/developers/nunjucks/tags.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/tags.png rename to docs/developers/nunjucks/tags.png diff --git a/docs/guides/using-guardrails/nunjucks/test-tag-hyphen.png b/docs/developers/nunjucks/test-tag-hyphen.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/test-tag-hyphen.png rename to docs/developers/nunjucks/test-tag-hyphen.png diff --git a/docs/guides/using-guardrails/nunjucks/turbot-tag.png b/docs/developers/nunjucks/turbot-tag.png similarity index 100% rename from docs/guides/using-guardrails/nunjucks/turbot-tag.png rename to docs/developers/nunjucks/turbot-tag.png diff --git a/docs/developers/policy-pack-development/index.md b/docs/developers/policy-pack-development/index.md new file mode 100644 index 00000000..7ba25887 --- /dev/null +++ b/docs/developers/policy-pack-development/index.md @@ -0,0 +1,205 @@ +--- +title: Policy Pack Development with AI Tools +sidebar_label: Using AI for Policy Pack Development +--- + +# Policy Pack Development with AI Tools + +In this guide, you will learn how to: + +- Use the MCP server's AI assistant to generate a production-ready Turbot policy pack +- Configure Terraform files, policy settings, and README according to Turbot best practices +- Test and validate your policy pack before deploying to production + +This step-by-step guide will help you streamline policy pack development using AI, ensuring all required components are created and validated efficiently. + +## Prerequisites + +Before you begin, ensure you have the following: + +- Guardrails MCP server installed and configured. + Follow the [Install Guardrails MCP guide](/guardrails/docs/guides/using-guardrails/ai/install-mcp) to set up the Model Context Protocol (MCP) server. +- Access to your Guardrails workspace URL (e.g., `https://your-workspace.cloud.turbot.com`). +- Familiarity with the [Guardrails console](https://turbot.com/guardrails/docs/getting-started/). +- A clear policy objective (for example, `Enforce EKS Public Endpoint Access`). +- Resource IDs available for testing your policy pack. + +## Step 1: Clone *guardrails-samples* Repository + +Before starting, clone the [guardrails-samples](https://github.com/turbot/guardrails-samples) repository locally. This repository contains example policy packs, recommended directory structure, and a README template. Use this as your working directory for creating and testing your new policy pack. + +```bash +git clone https://github.com/turbot/guardrails-samples.git +cd guardrails-samples/policy_packs +``` +>[!NOTE] +> Create a new branch to make sure you use this branch to raise PR against the main branch. + +Let AI create your new policy pack as a subdirectory here, following the structure and examples provided. + +## Step 2: Define Goal + +Clearly state the policy objective. For example: + +- Enforce EKS endpoint access security: + - Public access is disabled by default. + - If public access is enabled, restrict to specific CIDRs (e.g., `203.0.113.0/24`, `10.0.0.0/8`). + - Private access must always be enabled. + +### Identify Policies + +List the relevant Turbot policies to include in your policy pack. You can explore the [Guardrails Hub](https://hub.guardrails.turbot.com/) to find policies specific to your chosen cloud provider's mod. + +For example, consider the following policies: + +- [AWS > EKS > Cluster > Endpoint Access](https://hub.guardrails.turbot.com/mods/aws/policies/aws-eks/clusterEndpointAccess) +- [AWS > EKS > Cluster > Endpoint Access > CIDR Ranges](https://hub.guardrails.turbot.com/mods/aws/policies/aws-eks/clusterEndpointAccessCidrRanges) + +## Step 3: Prepare LLM Prompt + +Use the template below to guide the LLM when working in your new branch within the Cursor AI IDE or any AI-assisted development environment. + +``` +Goal: +- Enforce EKS endpoint access security: + - Public access should be disabled by default. + - If public access is enabled, restrict it to specific CIDRs (e.g., 203.0.113.0/24, 10.0.0.0/8). + - Private access must always be enabled. +- Policies must be visible in the Guardrails UI as part of the policy pack. +- Support a production workflow where customers attach the policy pack manually. + +Instructions: +1. Create a policy pack (Terraform) for AWS EKS endpoint access, following Turbot best practices and directory structure. +2. Define the policies as part of the policy pack (not as standalone policy settings). Use `turbot_policy_setting` resources with `resource = turbot_policy_pack..id`. +3. For testing: + - Add a `turbot_policy_pack_attachment` resource to attach the policy pack to a real resource (provide a test resource ID). + - After a successful test, prompt the user to validate in the Guardrails console that the policies are visible and correct. + - Once the user confirms, remove the `turbot_policy_pack_attachment` resource for production readiness. +4. For production: + - The policy pack should NOT include any `turbot_policy_pack_attachment` resource. + - Customers will attach the policy pack to their desired resources manually via the Guardrails console. +5. README: + - Generate a README for the policy pack following the rules in https://github.com/turbot/guardrails-samples/blob/main/policy_packs/README.md (categories, primary_category, type, usage, etc.). + - Validate the README and policy pack structure against all best practices. If any rule fails, revise and revalidate until all are green/OK. +6. Test: + - Initialize and apply the policy pack using Terraform, attaching it to the provided test resource. + - Confirm that the policies are visible in the Guardrails UI under the policy pack and that the resource is compliant. + - After user validation, remove the attachment for production. + +Configuration Input: +- Approved CIDR ranges: `["203.0.113.0/24", "10.0.0.0/8"]` +- Test Resource ID: (provide your real resource ID, e.g., `355421285155896`) + +Example Terraform Structure: +- `main.tf`: Defines the `turbot_policy_pack` (and, for testing only, the `turbot_policy_pack_attachment`). +- `policies.tf`: Defines `turbot_policy_setting` resources with `resource = turbot_policy_pack..id`. +- `providers.tf`: Provider block. +- `variables.tf`: Variable for the target resource. +- `README.md`: As per best practices. + +Do not proceed if no real resource is available. +Do not use standalone policy settings attached directly to the resource. +All policies must be visible in the UI as part of the policy pack. + +Workflow: +1. Develop and test with the attachment. +2. Prompt user to validate in the Guardrails console. +3. After confirmation, remove the attachment for production readiness. +``` + +## Step 4: Optimize the Feedback Loop + +Work collaboratively with the AI assistant to review, validate, and improve your policy pack. Use an iterative approach: check the generated files, provide clear feedback, and request specific changes until the policy pack meets your requirements and best practices. + +### Review the generated files + +- `README.md` +- `main.tf` +- `policies.tf` +- `providers.tf` +- `variables.tf` + +### Checklist + +- Do the policy settings match your objectives? +- Are all required files present and following the recommended structure? +- Is the documentation clear and complete? +- Are there any errors or missing configurations? + +### How to provide feedback + +You can use prompts like: + +``` +Please update the following: +- Add more detail to the usage section in README.md +- Change the approved CIDR ranges in variables.tf to ["198.51.100.0/24"] +- Add tags to the policy pack in main.tf +- Ensure all policies are visible in the Guardrails UI +- Fix the resource reference in policies.tf to use the correct variable +``` +### Iterate as needed +Repeat the review and feedback process until you are satisfied with the results. Don't hesitate to ask the AI assistant for clarifications, best practice checks, or additional examples. + +## Step 5: Actionable Execution + +Take your validated policy pack and apply it in a test environment to ensure everything works as expected. + +### Apply the Policy Pack + +1. **Plan the Deployment:** + + Let's initialize and run terraform plan. + + - Example prompt: + ``` + - Initialize the Terraform configuration + - Run terraform plan and wait for me to confirm terraform apply + ``` + +2. **Apply to a Test Resource:** + - Run `terraform apply` to deploy the policy pack, attaching it to your test resource (e.g., `355421285155896`). + - Example prompt: + ``` + - Apply the policy pack to resource 355421285155896 + ``` +#### Example Prompts + +In case any error or further validation use below + +``` +- Help me troubleshoot a Terraform apply error +- Confirm that the policy pack is visible in the Guardrails UI +- Check if the resource is compliant after applying the policy pack +``` + +### Review + +Manually review to make sure execution is successful + +- [ ] Terraform apply completed without errors. +- [ ] The policy pack and its policies are visible in the Guardrails Console. +- [ ] Resource compliance status is as expected. +- [ ] No unexpected alarms or errors. + +## Step 6: Finalize for Production + +After you have successfully tested your policy pack and validated the results, it's important to prepare your configuration for release by removing any test-specific resources or attachments. + +### Remove Test Attachments + +- Instruct the AI assistant (or manually update your Terraform files) to remove the `turbot_policy_pack_attachment` resource used for testing. +- Ensure your policy pack is now ready for release, where customers will attach it to their own resources via the Guardrails Console. + +#### Example Prompts + +``` +- Remove the test attachment for the generated policy pack. +- Update documentation for production use. +- Verify final structure matches existing policy pack structure +``` +### Review + +- [ ] All test attachments have been removed from your Terraform configuration. +- [ ] The policy pack structure matches the recommended format and best practices. +- [ ] Documentation is updated for release. diff --git a/docs/guides/using-guardrails/ai/ai-configuration/index.md b/docs/guides/using-guardrails/ai/ai-configuration/index.md new file mode 100644 index 00000000..8d865cfe --- /dev/null +++ b/docs/guides/using-guardrails/ai/ai-configuration/index.md @@ -0,0 +1,124 @@ +--- +title: AI Configuration +sidebar_label: AI Configuration +--- + +# Turbot AI Configuration + +In this guide, you will learn how to: + +- Configure various parameters in `Turbot > AI > Configuration` policy + +This guide is the starting point for all AI-powered features, including `Intelligent Assessment Control`, `Intelligent Fixes`, and `Policy Pack Summary`. Before using any AI capabilities in Guardrails, ensure you have completed the steps outlined in this guide. + +## Prerequisites + +- *Turbot/Admin* permissions at the Turbot resource level. +- Familiarity with the [Guardrails console](https://turbot.com/guardrails/docs/getting-started/). +- Access credentials for the AI model. + + +## Step 1: Find Turbot > AI Policy + +Log in to the Guardrails console using your local credentials or via a SAML-based login. From the **Policies** tab, navigate to *Turbot > AI* in the Guardrails console. + +This section provides AI-related policies that allow Guardrails to govern the use of AI for various configurations and settings. Select **Configurations**. + +![Turbot > AI > Configurations](./turbot-ai-configuration.png) + +## Step 2: Configure AI Provider + +Select **Turbot > AI > Configuration > Provider [Default]** to configure the AI service provider. The default value is set to `openai`. + +In this example, `anthropic` is selected. + +![Turbot > AI > Provider](./turbot-ai-provider.png) + +## Step 3: Configure API Key + +Select **Turbot > AI > Configuration > API Key [Default]** policy under the `Turbot > AI > Configuration` main policy. + +Enter the API key for the provider chosen in Step 2. Guardrails will use this key to authenticate with your AI service provider. + +![Turbot > AI > Configuration > API Key Policy Setting](./turbot-ai-api-key.png) + +> [!IMPORTANT] +> - The API key is a sensitive credential used for authentication with your chosen AI service provider. Ensure it is stored and handled securely. +> - For OpenAI: +> - Obtain the API key from the [OpenAI platform](https://platform.openai.com/api-keys) +> - The key should start with "sk-" +> - For Anthropic: +> - Get the API key from the [Anthropic console](https://console.anthropic.com/settings/keys) +> - The key should start with "sk-ant-" +> - Store the API key securely and rotate it periodically according to your organization's security policies. +> - Never share or expose the API key in logs, code repositories, or public forums. + +## Step 4: Configure AI Model + +Select **Turbot > AI > Configuration > Model [Default]** policy under the `Turbot > AI > Configuration` main policy. + +Choose the model to use with the selected AI provider for processing requests. + +![Choose the AI Model](./turbot-ai-model.png) + +> [!NOTE] +> Supported and tested models include: +> - [OpenAI models](https://platform.openai.com/docs/pricing#latest-models): `gpt-4.1`, `gpt-4.1-mini`, `gpt-4o` +> - [Anthropic models](https://docs.anthropic.com/en/docs/about-claude/models/overview#model-names): `claude-sonnet-4-20250514`, `claude-3-7-sonnet-20250219`, `claude-3-5-haiku-20241022`, `claude-3-5-sonnet-20241022` +> +> For optimal results: +> - Use the latest model versions when possible. +> - Higher-tier models (like GPT-4 series and Claude Sonnet/Haiku series) provide more accurate and detailed assessments. +> - Lower-tier models may produce different or less consistent results. +> - Model availability may vary based on your AI provider subscription. +> - For more information about the models, see the documentation for [OpenAI](https://platform.openai.com/docs/models) and [Anthropic](https://docs.anthropic.com/en/docs/models-overview). + +## Step 5: Configure Max Tokens + +Select **Turbot > AI > Configuration > Max Tokens [Default]** under the `Turbot > AI > Configuration` main policy. The default value is set to `1000` as a best practice. + +> [!TIP] +> - Configure the maximum number of tokens to use for the AI API calls. This setting controls the length of the AI's response by limiting the number of tokens (words, subwords, or characters) that can be generated. +> - A higher value allows for longer, more detailed responses but may increase API costs and response time. +> - A lower value produces more concise responses. +> - The default value of 1000 tokens provides a good balance for most use cases, but you can adjust this based on your specific needs and the complexity of the tasks you want the AI to perform. + +You can adjust this based on your specific needs and the complexity of the tasks you want the AI to perform. + +## Step 6: Configure Temperature + +The policy **Turbot > AI > Configuration > Temperature [Default]** allows you to configure the temperature parameter for AI API calls. Temperature controls the randomness or creativity of the AI's responses. + +A lower value (closer to 0) makes responses more focused, deterministic, and consistent, while a higher value (closer to 1) makes responses more diverse and creative. The default value of 0.2 provides a good balance between consistency and creativity, suitable for most business and technical use cases. + +The default value is set to `0.2`. You may choose to update it based on your needs. + +## Step 7: Enable Configuration + +The **Turbot > AI > Configuration > Enabled [Default]** policy under `Turbot > AI > Configuration` plays an important role if you wish to apply configurations to all features under `Turbot > AI`. You may choose to continue with the default value `Disabled` and enable it in respective features separately. + +To enable it, select **New Policy Settings**, set **Resource** to `Turbot`, and choose `Enabled`. + +![Enable AI Configuration](./turbot-ai-configuration-enabled.png) + +## Review + +- [ ] Validate that all the required settings are in place. + +![Review AI Configuration](./turbot-ai-configuration-review.png) + +## Next Steps + +After completing this configuration, continue with the following guides to leverage AI features in Guardrails: + +- [Enable Intelligent Assessment](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-assessment) +- [Enable Intelligent Fixes](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-fixes/) +- [Enable Policy Pack Summary](/guardrails/docs/guides/using-guardrails/ai/enable-policy-pack-summary/) +- [Developing guardrails for Guardrails](/guardrails/docs/developers/) + + +## Troubleshooting + +| Issue | Description | Guide | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| Further Assistance | If issues persist, please open a support ticket and attach relevant information to help us assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-api-key.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-api-key.png new file mode 100644 index 00000000..49ea5142 Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-api-key.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-enabled.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-enabled.png new file mode 100644 index 00000000..52c67cb0 Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-enabled.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-review.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-review.png new file mode 100644 index 00000000..161da03c Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration-review.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration.png new file mode 100644 index 00000000..c1984382 Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-configuration.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-model.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-model.png new file mode 100644 index 00000000..0794643a Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-model.png differ diff --git a/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-provider.png b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-provider.png new file mode 100644 index 00000000..380e06d9 Binary files /dev/null and b/docs/guides/using-guardrails/ai/ai-configuration/turbot-ai-provider.png differ diff --git a/docs/guides/using-guardrails/ai/ai-sidebar.json b/docs/guides/using-guardrails/ai/ai-sidebar.json new file mode 100644 index 00000000..91b754a1 --- /dev/null +++ b/docs/guides/using-guardrails/ai/ai-sidebar.json @@ -0,0 +1,11 @@ +{ + "type": "category", + "id": "ai", + "link": "guides/using-guardrails/ai", + "items": [ + "guides/using-guardrails/ai/ai-configuration", + "guides/using-guardrails/ai/enable-intelligent-assessment", + "guides/using-guardrails/ai/enable-intelligent-fixes", + "guides/using-guardrails/ai/enable-policy-pack-summary" + ] +} diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-create-setting.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-create-setting.png new file mode 100644 index 00000000..bff11e0d Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-create-setting.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-ia-context.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-ia-context.png new file mode 100644 index 00000000..577943a4 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-ia-context.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-intelligent-assessment-response.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-intelligent-assessment-response.png new file mode 100644 index 00000000..16eb7e9c Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-bucket-intelligent-assessment-response.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-intelligent-assessment-check-mode.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-intelligent-assessment-check-mode.png new file mode 100644 index 00000000..99745c2c Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/aws-s3-intelligent-assessment-check-mode.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/index.md b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/index.md new file mode 100644 index 00000000..7c5246f4 --- /dev/null +++ b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/index.md @@ -0,0 +1,129 @@ +--- +title: Enable Intelligent Assessment +sidebar_label: Enable Intelligent Assessment +--- + +# Enable Intelligent Assessment + +In this guide, you will learn how to: + +- Set up custom user prompts and context for resource evaluation. +- Enable Intelligent Assessment for a specific S3 bucket control as an example. + +The [Intelligent Assessment](/guardrails/docs/concepts/guardrails/intelligent-assessment) [control](/guardrails/docs/reference/glossary#control) 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 evaluate it. + +## Prerequisites + +- *Turbot/Admin* permissions at the Turbot resource level. +- Familiarity with the [Guardrails console](https://turbot.com/guardrails/docs/getting-started/). +- Ensure that [Turbot > AI > Configuration](/guardrails/docs/guides/using-guardrails/ai/ai-configuration) is set up. + +## Step 1: Enable Intelligent Assessment Control + +Log in to the Guardrails console using your local credentials or via a SAML-based login. + +Enable the following policy at the Turbot level: **Turbot > AI > Control > Intelligent Assessment > Enabled**. This enables AI capabilities for Intelligent Assessment controls. + +> [!NOTE] +> - The default value is `Disabled`. You can enable it based on your requirements. +> - If enabled at the Turbot level in [Turbot AI Configuration > Step 7](/guardrails/docs/guides/using-guardrails/ai/ai-configuration#step-7-enable-configuration), the Intelligent Assessment control becomes available for use. + +For this guide, the `Turbot > AI > Control > Intelligent Assessment > Enabled` policy is set to `Enabled`. + +![Enable Intelligent Assessment Control](./turbot-ai-intelligent-assessment-enabled.png) + +## Step 2: Find Targeted S3 Bucket + +Navigate to the **Resources** tab and search for the S3 bucket you want to assess. You can filter by: + +- Resource type: `AWS > S3 > Bucket` +- Bucket name in the search bar + +![Find S3 Bucket](./locate-aws-s3-bucket.png) + +Select the bucket to view its details and controls. This will be the target resource for setting up `Intelligent Assessment`. + +> [!TIP] +> You can also find the required bucket using **Reports** > **AWS S3 Buckets**. + +## Step 3: Add User Prompt + +While in `AWS > S3 > Bucket`, select the **Policies** tab and choose the `AWS > S3 > Bucket > Intelligent Assessment > User Prompt` policy. + +Select **New Policy Setting** to add a new prompt. + +![Locate User Prompt Policy](./locate-user-prompt-policy.png) + +Here you can define the prompt that will be sent to the AI provider for resource assessment. Ensure your instructions are clear and specific. + +![Set the User Prompt Value for Assessment](./set-user-prompt-value.png) + +> [!NOTE] +> You can set this policy at the resource, account, or folder level. +> For more information, see [Guardrails Policy Hierarchy](/guardrails/docs/concepts/policies/hierarchy). + +**Example Prompt:** +``` +- Confirm that logging is enabled and logs are sent to a secure location. +- Check if versioning is enabled and multi-factor delete is configured when the bucket has a tag "Environment":"Non-Compliant Tag". If it doesn't have the tag, only check if versioning is enabled. +- Ensure that the S3 bucket is not publicly accessible and all access is restricted to specific IAM roles or users. +- Verify that server-side encryption is enabled using AWS KMS for all objects in the bucket. +- Check if the bucket policy denies unencrypted uploads and enforces HTTPS-only access. +- Confirm that lifecycle rules are configured to transition objects to Glacier storage after 30 days and delete them after 365 days. +- Ensure that the bucket has a policy to block all public ACLs and public bucket policies. +- Validate that only specific IP address ranges (e.g., 10.0.0.0/8) are allowed to access the bucket. +- Check if object lock is enabled for regulatory compliance and retention. +- Confirm that the bucket has a tag \"Owner\" with a valid email address. +- Ensure that cross-region replication is enabled to a backup bucket in another AWS region. +- Verify that access logging is enabled and logs are sent to a dedicated logging bucket with restricted access. +``` +## Step 4: Set up Context + +The sub-policy `AWS > S3 > Bucket > Intelligent Assessment > Context` defines the context information in JSON format that will be provided to the configured AI provider for the intelligent assessment of the S3 bucket. + +By default, the context includes the resource's attributes and metadata required for accurate evaluation. In this example, we will use the `default context`. + +![Intelligent Assessment Context](./aws-s3-bucket-ia-context.png) + +> [!NOTE] +> You may customize this context to include additional information relevant to your assessment needs. + +## Step 5: Set Primary Policy to Check Mode + +Now that the user prompt is set with the default context, let's set up the primary policy `AWS > S3 > Bucket > Intelligent Assessment` for this S3 bucket. + +To access the main policy, while in the `AWS > S3 > Bucket > Intelligent Assessment` **Controls**, select the **Policies** tab. If not set earlier, you may find `Intelligent Assessment` is set to `Skip`. + +![Create Settings](./aws-s3-bucket-create-setting.png) + +Select **CREATE SETTING** and set the option to `Check: User prompt`. This policy activates Intelligent Assessment for the S3 bucket based on your user prompt and context. + +> [!NOTE] +> You can set this policy at the resource, account, or folder level. +> For more information, see [Guardrails Policy Hierarchy](/guardrails/docs/concepts/policies/hierarchy). + +![Set the Intelligent Assessment Policy for S3 Bucket](./aws-s3-intelligent-assessment-check-mode.png) + +## Step 6: Check Control Status + +The control will assess the S3 bucket using the configured user prompt and evaluate the control. + +![Example Output from S3 Bucket Intelligent Assessment](./aws-s3-bucket-intelligent-assessment-response.png) + +> [!NOTE] +> The output is generated by the AI provider and may vary based on the model's capabilities and input details. + +## Next Steps + +To explore more Guardrails features: + +- [Intelligent Fixes](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-fixes) +- [Policy Pack Summary](/guardrails/docs/guides/using-guardrails/ai/enable-policy-pack-summary) +- [Configure Guardrails MCP Server](/guardrails/docs/guides/using-guardrails/ai/install-mcp) +- [Developing guardrails for Guardrails](/guardrails/docs/developers/) + +## Troubleshooting + +| Issue | Description | Guide | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| Further Assistance | If issues persist, please open a support ticket and attach relevant information to help us assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-aws-s3-bucket.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-aws-s3-bucket.png new file mode 100644 index 00000000..2e58d97c Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-aws-s3-bucket.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-user-prompt-policy.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-user-prompt-policy.png new file mode 100644 index 00000000..763b76a7 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/locate-user-prompt-policy.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/set-user-prompt-value.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/set-user-prompt-value.png new file mode 100644 index 00000000..31124791 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/set-user-prompt-value.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-assessment/turbot-ai-intelligent-assessment-enabled.png b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/turbot-ai-intelligent-assessment-enabled.png new file mode 100644 index 00000000..96056c25 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-assessment/turbot-ai-intelligent-assessment-enabled.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-cli-outcome.png b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-cli-outcome.png new file mode 100644 index 00000000..e847a917 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-cli-outcome.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-quick-action.png b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-quick-action.png new file mode 100644 index 00000000..6bd18455 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-quick-action.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-steps-tf.png b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-steps-tf.png new file mode 100644 index 00000000..7561b5a1 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-steps-tf.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-tf-outcome.png b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-tf-outcome.png new file mode 100644 index 00000000..47e17ab9 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/aws-s3-bucket-tags-remediation-tf-outcome.png differ diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/index.md b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/index.md new file mode 100644 index 00000000..c6712a65 --- /dev/null +++ b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/index.md @@ -0,0 +1,87 @@ +--- +title: Enable Intelligent Fixes +sidebar_label: Enable Intelligent Fixes +--- + +# Enable Intelligent Fixes + +In this guide, you will learn how to: + +- Get AI-generated remediation steps for non-compliant resources. +- Review and implement recommended fixes for security and compliance issues. +- Understand the context and impact of suggested remediation actions. + +When a resource is found to be non-compliant i.e. enters an alarm state, Intelligent Fixes analyzes: + +- **Alert Summary:** Clear explanation of why the control is in alarm and what needs to be addressed. +- **Guardrails Actions:** Available `Quick Actions` and policy changes within the platform. +- **Cloud Provider CLI:** Direct commands for AWS, Azure, gcloud, kubectl, and gh CLIs to fix the misconfiguration. +- **Infrastructure-as-Code:** Terraform plans to remediate the issue via code. + +## Prerequisites + +- *Turbot/Admin* permissions at the Turbot resource level. +- Familiarity with the [Guardrails console](https://turbot.com/guardrails/docs/getting-started/). +- Ensure that [Turbot > AI > Configuration](/guardrails/docs/guides/using-guardrails/ai/ai-configuration) is set up. + +## Step 1: Enable Intelligent Fixes + +In the **Policies** tab, navigate to `Turbot > AI > Control > Intelligent Fixes` and select the **Enabled** option. Create a new setting by selecting **New Policy Setting**. + +![Enable Intelligent Fixes Control](./turbot-ai-intelligent-fixes-enabled.png) + +> [!NOTE] +> - The default value is `Disabled`. You can enable it based on your requirements. +> - If enabled at the Turbot level in [Turbot AI Configuration > Step 7](/guardrails/docs/guides/using-guardrails/ai/ai-configuration#step-7-enable-configuration), the Intelligent Assessment control becomes available for use. + +For this guide, the `Turbot > AI > Control > Intelligent Fixes > Enabled` policy is set to `Enabled`. + +## Step 2: Check Remediation + +Navigate to any control in the `ALARM` state. The remediation steps will automatically begin to load, and you will see an initial message: "Generating remediation steps…". + +For example, let's consider `AWS > S3 > Bucket > Tags`. + +![Generate Intelligent Fixes](./aws-s3-bucket-tags-remediation-steps-tf.png) + +The AI will analyze the non-compliant resource and generate remediation steps in multiple options such as CLI, Terraform, and CloudFormation. + +**Remediation in Terraform** + +![AWS > S3 > Bucket > Tag > CLI Remediation](./aws-s3-bucket-tags-remediation-tf-outcome.png) + +**Remediation in CLI** + +You can select the *CLI* option from the **Remediation Steps** dropdown to view the required CLI commands. + +![AWS > S3 > Bucket > Tag > CLI Remediation](./aws-s3-bucket-tags-remediation-cli-outcome.png) + +> [!NOTE] +> The output is generated by the AI provider and may vary based on the model's capabilities and input details. + +## Step 3: Check Quick Action + +`Quick Actions` provide an option to perform one-time control enforcements directly within your cloud environment. When enabled for any control, these actions appear in the remediation panel alongside the detailed remediation steps. + +Check [Quick Actions](/guardrails/docs/guides/using-guardrails/quick-actions#enabling-quick-actions) for more details on enabling it. + +![Quick Action for S3 Bucket Tags Remediation](./aws-s3-bucket-tags-remediation-quick-action.png) + +> [!NOTE] +> [Quick Actions](/guardrails/docs/guides/using-guardrails/quick-actions#enabling-quick-actions) are available for select controls and provide a fast, automated way to remediate common issues. Always review each action before applying it to ensure it aligns with your compliance requirements. + +## Next Steps + +To explore more Guardrails features: + +- [Intelligent Assessment Control](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-assessment) +- [Policy Pack Summary](/guardrails/docs/guides/using-guardrails/ai/enable-policy-pack-summary) +- [Configure Guardrails MCP Server](/guardrails/docs/guides/using-guardrails/ai/install-mcp) +- [Developing guardrails for Guardrails](/guardrails/docs/developers/) + + +## Troubleshooting + +| Issue | Description | Guide | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| Further Assistance | If issues persist, please open a support ticket and attach relevant information to help us assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/using-guardrails/ai/enable-intelligent-fixes/turbot-ai-intelligent-fixes-enabled.png b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/turbot-ai-intelligent-fixes-enabled.png new file mode 100644 index 00000000..fed04743 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-intelligent-fixes/turbot-ai-intelligent-fixes-enabled.png differ diff --git a/docs/guides/using-guardrails/ai/enable-policy-pack-summary/index.md b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/index.md new file mode 100644 index 00000000..8b7dcdf8 --- /dev/null +++ b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/index.md @@ -0,0 +1,66 @@ +--- +title: Enable Policy Pack Summary +sidebar_label: Enable Policy Pack Summary +--- + +# Enable Policy Pack Summary + +In this guide, you will learn how to: + +- Enable and configure the Policy Pack Summary feature. +- View AI-generated summaries of policy pack configurations and purposes. + +The AI-powered `Policy Pack Summary` feature provides contextual insights by analyzing policy pack configurations to generate meaningful summaries. These summaries help teams understand the intent and impact of policies, including key policy settings, dependencies, and their business context. + +> [!TIP] +> Use the policy pack summary to: +> - Validate policy pack configurations. +> - Document your governance approach. +> - Understand how to use these summaries for better policy management and team collaboration. + +## Prerequisites + +- *Turbot/Admin* permissions at the Turbot resource level. +- Familiarity with the [Guardrails console](https://turbot.com/guardrails/docs/getting-started/). +- Ensure that [Turbot > AI > Configuration](/guardrails/docs/guides/using-guardrails/ai/ai-configuration) is set up. + +## Step 1: Enable Policy Pack Summary + +In the **Policies** tab, navigate to `Turbot > AI > Policy Pack` and select **Summary**. + +![Navigate to Policy Pack Summary](./turbot-ai-policy-pack-summary.png) + +Select **Enabled** and create a new setting by selecting **New Policy Setting**. + +![Policy Pack Summary Enabled](./turbot-ai-policy-pack-summary-enabled.png) + +> [!NOTE] +> - The default value is `Disabled`. You can enable it based on your requirements. +> - If enabled at the Turbot level in [Turbot AI Configuration > Step 7](/guardrails/docs/guides/using-guardrails/ai/ai-configuration#step-7-enable-configuration), the Intelligent Assessment control becomes available for use. + +For this guide, the `Turbot > AI > Policy Pack > Summary > Enabled` policy is set to `Enabled`. + +## Step 2: Check Policy Pack Summary + +To check the policy pack summary, navigate to the **Policy Packs** section of the **Policies** tab. Select any policy pack to view its summary. + +![Policy Pack Summary](./turbot-ai-policy-pack-summary-response.png) + +> [!NOTE] +> The output is generated by the AI provider and may vary based on the model's capabilities and input details. + +## Next Steps + +To explore more Guardrails features: + +- [Intelligent Assessment Control](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-assessment) +- [Intelligent Fixes](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-fixes) +- [Configure Guardrails MCP Server](/guardrails/docs/guides/using-guardrails/ai/install-mcp) +- [Developing guardrails for Guardrails](/guardrails/docs/developers/) + + +## Troubleshooting + +| Issue | Description | Guide | +|------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| +| Further Assistance | If issues persist, please open a support ticket and attach relevant information to help us assist you more efficiently. | [Open Support Ticket](https://support.turbot.com) | \ No newline at end of file diff --git a/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-enabled.png b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-enabled.png new file mode 100644 index 00000000..e7e2ca50 Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-enabled.png differ diff --git a/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-response.png b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-response.png new file mode 100644 index 00000000..a7010ddf Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary-response.png differ diff --git a/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary.png b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary.png new file mode 100644 index 00000000..1f9ac28c Binary files /dev/null and b/docs/guides/using-guardrails/ai/enable-policy-pack-summary/turbot-ai-policy-pack-summary.png differ diff --git a/docs/guides/using-guardrails/ai/index.md b/docs/guides/using-guardrails/ai/index.md new file mode 100644 index 00000000..2cf1f199 --- /dev/null +++ b/docs/guides/using-guardrails/ai/index.md @@ -0,0 +1,15 @@ +--- +title: AI Features +sidebar_label: AI Features +--- + +# Guardrail AI + +This section covers the various AI-powered features available in Guardrails. + +| Section | Description +| - | - +| [AI API Integration](/guardrails/docs/guides/using-guardrails/ai/ai-configuration) | How to configure AI settings and preferences within Guardrails. +| [Enable Intelligent Assessment](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-assessment) | Learn about AI-powered controls using natural language prompts to evaluate cloud resource compliances. +| [Enable Intelligent Fixes](/guardrails/docs/guides/using-guardrails/ai/enable-intelligent-fixes) | Learn about AI-assisted remediation recommendations. +| [Enable Policy Pack Summary](/guardrails/docs/guides/using-guardrails/ai/enable-policy-pack-summary) | Learn about AI-generated summaries of policy packs. diff --git a/docs/guides/using-guardrails/index.md b/docs/guides/using-guardrails/index.md index 2dd76510..4d6c7908 100644 --- a/docs/guides/using-guardrails/index.md +++ b/docs/guides/using-guardrails/index.md @@ -8,14 +8,12 @@ This section provides how-to guides for common tasks. | Section | Description | - | - -| [AI Tools](guides/using-guardrails/ai-tools) | Learn how to use different AI integration tools and prompts +| [AI](guides/using-guardrails/ai) | Learn AI-powered capabilities like intelligent assessment, fixes, policy pack summaries of cloud resources | [Console](guides/console) | Navigate the Guardrails Console user interface -| [GraphQL](guides/graphql) | Tips and Tricks for GraphQL | [IAM](guides/iam) | Manage directories, users, and permissions | [Stacks](guides/using-guardrails/stacks) | Manage resource configurations using OpenTofu, an open-source implementation of Terraform | [Notifications](guides/using-guardrails/notifications) | Manage real-time alerts to be sent about events that occur in your cloud infrastructure | [Scheduling](guides/using-guardrails/scheduling) | Manage resource start and stop using custom tags -| [Nunjucks](guides/nunjucks) | Tips and tricks for using Nunjucks, including troubleshooting | [Quick Actions](guides/quick-actions) | Configuration options for Quick Actions | [Searching and Filtering](guides/searching-filtering) | Getting started with Filters in Guardrails | [Troubleshooting](/guardrails/docs/guides/using-guardrails/troubleshooting) | Learn how to troubleshoot and resolve common issues when using Guardrails. diff --git a/docs/index.md b/docs/index.md index 389e21bd..0c35512d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,3 +16,6 @@ Turbot Guardrails is a full-stack governance platform that automates discovery a | [Reference](/guardrails/docs/reference/) | Reference documentation for the API, CLI, Terraform provider, and more. | [Guides](/guardrails/docs/guides/) | Step-by-step guides for using, configuring, and hosting Guardrails. | [Frequently Asked Questions](/guardrails/docs/faq/) | Answers to our most common questions. +| [Developer Guide](/guardrails/docs/developers/) | Learn how to develop guardrails for Guardrails. + + diff --git a/docs/sidebar.json b/docs/sidebar.json index db1c8dc8..88f4a197 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -296,7 +296,10 @@ "id": "using-guardrails", "link": "guides/using-guardrails", "items": [ - "guides/using-guardrails/ai-tools", + { + "type": "placeholder", + "file": "guides/using-guardrails/ai/ai-sidebar.json" + }, { "type": "category", "id": "console", @@ -314,7 +317,6 @@ "guides/using-guardrails/console/detail-pages" ] }, - "guides/using-guardrails/graphql", { "type": "category", "id": "iam", @@ -348,7 +350,6 @@ "guides/using-guardrails/scheduling/db-scheduling-using-custom-tag" ] }, - "guides/using-guardrails/nunjucks", "guides/using-guardrails/quick-actions", "guides/using-guardrails/searching-filtering", { @@ -358,7 +359,6 @@ "items": [ "guides/using-guardrails/troubleshooting/fix-invalid-controls", "guides/using-guardrails/troubleshooting/access-control-logs", - "guides/using-guardrails/troubleshooting/fix-calc-policy-evaluation-errors", "guides/using-guardrails/troubleshooting/run-controls-using-scripts" ] } @@ -427,6 +427,7 @@ ] }, "guides/hosting-guardrails/FAQ", + { "type": "category", "id": "troubleshooting", @@ -491,6 +492,10 @@ "faq/guardrails-and-aws-scps" ] }, + { + "type": "placeholder", + "file": "developers/developers-sidebar.json" + }, { "type": "category", "id": "reference",