diff --git a/docs/my-website/docs/proxy/guardrails/guardrail_policies.md b/docs/my-website/docs/proxy/guardrails/guardrail_policies.md
index 56be11c85a7..e2cb839203e 100644
--- a/docs/my-website/docs/proxy/guardrails/guardrail_policies.md
+++ b/docs/my-website/docs/proxy/guardrails/guardrail_policies.md
@@ -1,3 +1,7 @@
+import Image from '@theme/IdealImage';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# [Beta] Guardrail Policies
Use policies to group guardrails and control which ones run for specific teams, keys, or models.
@@ -10,6 +14,9 @@ Use policies to group guardrails and control which ones run for specific teams,
## Quick Start
+
+
+
```yaml showLineNumbers title="config.yaml"
model_list:
- model_name: gpt-4
@@ -43,6 +50,26 @@ policy_attachments:
scope: "*" # apply to all requests
```
+
+
+
+**Step 1: Create a Policy**
+
+Go to **Policies** tab and click **+ Create New Policy**. Fill in the policy name, description, and select guardrails to add.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Response headers show what ran:
```
@@ -58,6 +85,9 @@ x-litellm-applied-guardrails: pii_masking,prompt_injection
You have a global baseline, but want to add extra guardrails for a specific team.
+
+
+
```yaml showLineNumbers title="config.yaml"
policies:
global-baseline:
@@ -81,6 +111,30 @@ policy_attachments:
- finance # team alias from /team/new
```
+
+
+
+**Option 1: Create a team-scoped attachment**
+
+Go to **Policies** > **Attachments** tab and click **+ Create New Attachment**. Select the policy and the teams to scope it to.
+
+
+
+
+
+**Option 2: Attach from team settings**
+
+Go to **Teams** > click on a team > **Settings** tab > under **Policies**, select the policies to attach.
+
+
+
+
+
+
+
+
+
+
Now the `finance` team gets `pii_masking` + `strict_compliance_check` + `audit_logger`, while everyone else just gets `pii_masking`.
## Remove guardrails for a specific team
@@ -201,6 +255,60 @@ policy_attachments:
- "test-*" # key alias pattern
```
+**Tag-based** (matches keys/teams by metadata tags, wildcards supported):
+
+```yaml showLineNumbers title="config.yaml"
+policy_attachments:
+ - policy: hipaa-compliance
+ tags:
+ - "healthcare"
+ - "health-*" # wildcard - matches health-team, health-dev, etc.
+```
+
+Tags are read from key and team `metadata.tags`. For example, a key created with `metadata: {"tags": ["healthcare"]}` would match the attachment above.
+
+## Test Policy Matching
+
+Debug which policies and guardrails apply for a given context. Use this to verify your policy configuration before deploying.
+
+
+
+
+Go to **Policies** > **Test** tab. Enter a team alias, key alias, model, or tags and click **Test** to see which policies match and what guardrails would be applied.
+
+
+
+
+
+
+```bash
+curl -X POST "http://localhost:4000/policies/resolve" \
+ -H "Authorization: Bearer " \
+ -H "Content-Type: application/json" \
+ -d '{
+ "tags": ["healthcare"],
+ "model": "gpt-4"
+ }'
+```
+
+Response:
+
+```json
+{
+ "effective_guardrails": ["pii_masking"],
+ "matched_policies": [
+ {
+ "policy_name": "hipaa-compliance",
+ "matched_via": "tag:healthcare",
+ "guardrails_added": ["pii_masking"]
+ }
+ ]
+}
+```
+
+
+
+
## Config Reference
### `policies`
@@ -233,14 +341,18 @@ policy_attachments:
scope: ...
teams: [...]
keys: [...]
+ models: [...]
+ tags: [...]
```
| Field | Type | Description |
|-------|------|-------------|
| `policy` | `string` | **Required.** Name of the policy to attach. |
| `scope` | `string` | Use `"*"` to apply globally. |
-| `teams` | `list[string]` | Team aliases (from `/team/new`). |
+| `teams` | `list[string]` | Team aliases (from `/team/new`). Supports `*` wildcard. |
| `keys` | `list[string]` | Key aliases (from `/key/generate`). Supports `*` wildcard. |
+| `models` | `list[string]` | Model names. Supports `*` wildcard. |
+| `tags` | `list[string]` | Tag patterns (from key/team `metadata.tags`). Supports `*` wildcard. |
### Response Headers
@@ -248,6 +360,7 @@ policy_attachments:
|--------|-------------|
| `x-litellm-applied-policies` | Policies that matched this request |
| `x-litellm-applied-guardrails` | Guardrails that actually ran |
+| `x-litellm-policy-sources` | Why each policy matched (e.g., `hipaa=tag:healthcare; baseline=scope:*`) |
## How it works
diff --git a/docs/my-website/img/policy_team_attach.png b/docs/my-website/img/policy_team_attach.png
new file mode 100644
index 00000000000..4e337931ed8
Binary files /dev/null and b/docs/my-website/img/policy_team_attach.png differ
diff --git a/docs/my-website/img/policy_test_matching.png b/docs/my-website/img/policy_test_matching.png
new file mode 100644
index 00000000000..5d024ae78b4
Binary files /dev/null and b/docs/my-website/img/policy_test_matching.png differ