diff --git a/docs/my-website/docs/proxy/guardrails/policy_templates.md b/docs/my-website/docs/proxy/guardrails/policy_templates.md new file mode 100644 index 00000000000..6c2da70560a --- /dev/null +++ b/docs/my-website/docs/proxy/guardrails/policy_templates.md @@ -0,0 +1,298 @@ +# Policy Templates + +Policy templates provide pre-configured guardrail policies that you can use as a starting point for your organization. Instead of manually creating policies and guardrails, you can select a template that matches your use case and deploy it with one click. + +## Using Policy Templates + +### In the UI + +1. Navigate to **Policies → Templates** tab in the LiteLLM Admin UI +2. Browse available templates (e.g., "PII Protection", "Cost Control", "HR Compliance") +3. Click **"Use Template"** on any template +4. Review the guardrails that will be created: + - Existing guardrails are marked with a green checkmark + - New guardrails can be selected/deselected +5. Click **"Create X Guardrails & Use Template"** +6. Review and customize the pre-filled policy form +7. Click **"Create Policy"** to save + +![Policy Templates UI](/img/policy_templates_ui.png) + +### Workflow + +``` +Select Template → Review Guardrails → Create Selected → Edit Policy → Save +``` + +The system automatically: +- ✅ Detects which guardrails already exist +- ✅ Creates only the missing guardrails you select +- ✅ Pre-fills the policy form with template data +- ✅ Lets you customize before saving + +## Available Templates + +Templates are fetched from [GitHub](https://raw.githubusercontent.com/BerriAI/litellm/main/policy_templates.json) with automatic fallback to local backup. + +### Current Templates + +#### 1. Advanced PII Protection (Australia) +- **Complexity:** High +- **Use Case:** Comprehensive PII detection for Australian organizations +- **Guardrails:** + - Australian tax identifiers (TFN, ABN, Medicare) + - Australian passports + - International PII (SSN, passports, national IDs) + - Contact information (email, phone, address) + - Financial data (credit cards, IBAN) + - API credentials (AWS, GitHub, Slack) - **BLOCKS** requests + - Network infrastructure (IP addresses) + - Protected class information (gender, race, religion, disability, etc.) + +#### 2. Baseline PII Protection +- **Complexity:** Low +- **Use Case:** Basic protection for internal tools and testing +- **Guardrails:** + - Australian tax identifiers + - API credentials + - Financial data + +## Creating Your Own Policy Templates + +You can contribute policy templates for the entire LiteLLM community to use. + +### Template Structure + +Templates are defined in JSON format with the following structure: + +```json +{ + "id": "unique-template-id", + "title": "Display Title", + "description": "Detailed description of what this template protects", + "icon": "ShieldCheckIcon", + "iconColor": "text-purple-500", + "iconBg": "bg-purple-50", + "guardrails": [ + "guardrail-name-1", + "guardrail-name-2" + ], + "complexity": "Low|Medium|High", + "guardrailDefinitions": [ + { + "guardrail_name": "example-guardrail", + "litellm_params": { + "guardrail": "litellm_content_filter", + "mode": "pre_call", + "patterns": [ + { + "pattern_type": "prebuilt", + "pattern_name": "email", + "action": "MASK" + } + ], + "pattern_redaction_format": "[{pattern_name}_REDACTED]" + }, + "guardrail_info": { + "description": "What this guardrail does" + } + } + ], + "templateData": { + "policy_name": "policy-name", + "description": "Policy description", + "guardrails_add": ["guardrail-name-1", "guardrail-name-2"], + "guardrails_remove": [] + } +} +``` + +### Field Descriptions + +#### Display Fields +- **id**: Unique identifier (lowercase with hyphens) +- **title**: User-facing name shown in UI +- **description**: Detailed explanation of what the template protects +- **icon**: Icon name (must be available in UI icon map) +- **iconColor**: Tailwind CSS text color class +- **iconBg**: Tailwind CSS background color class +- **guardrails**: Array of guardrail names (for display only) +- **complexity**: Badge showing difficulty ("Low", "Medium", or "High") + +#### Guardrail Definitions +- **guardrailDefinitions**: Array of complete guardrail configurations + - Each must be a valid guardrail object that can be sent to `/guardrails` POST endpoint + - If a guardrail already exists, it will be skipped + - Can be empty `[]` if template uses only existing guardrails + +#### Policy Configuration +- **templateData**: Object that pre-fills the policy form + - **policy_name**: Suggested name (user can edit) + - **description**: Policy description + - **guardrails_add**: Array of guardrail names to include + - **guardrails_remove**: Array to remove (usually `[]` for templates) + - **inherit**: (Optional) Parent policy name for inheritance + +### Example Template + +Here's a complete example for a HIPAA compliance template: + +```json +{ + "id": "hipaa-compliance", + "title": "HIPAA Compliance Policy", + "description": "Healthcare compliance policy that masks PHI and enforces HIPAA regulations for healthcare applications.", + "icon": "ShieldCheckIcon", + "iconColor": "text-red-500", + "iconBg": "bg-red-50", + "guardrails": [ + "phi-detector", + "medical-record-blocker", + "patient-id-masker" + ], + "complexity": "High", + "guardrailDefinitions": [ + { + "guardrail_name": "phi-detector", + "litellm_params": { + "guardrail": "litellm_content_filter", + "mode": "pre_call", + "patterns": [ + { + "pattern_type": "prebuilt", + "pattern_name": "us_ssn", + "action": "MASK" + }, + { + "pattern_type": "prebuilt", + "pattern_name": "email", + "action": "MASK" + }, + { + "pattern_type": "prebuilt", + "pattern_name": "us_phone", + "action": "MASK" + } + ], + "pattern_redaction_format": "[PHI_REDACTED]" + }, + "guardrail_info": { + "description": "Detects and masks Protected Health Information (PHI)" + } + } + ], + "templateData": { + "policy_name": "hipaa-compliance-policy", + "description": "HIPAA compliance policy for healthcare applications", + "guardrails_add": [ + "phi-detector", + "medical-record-blocker", + "patient-id-masker" + ], + "guardrails_remove": [] + } +} +``` + +## Contributing Templates + +To contribute a policy template for everyone to use: + +### Step 1: Create Your Template JSON + +1. Create a JSON file following the structure above +2. Test it locally by adding it to your local `policy_templates.json` +3. Verify all guardrails work correctly +4. Ensure descriptions are clear and helpful + +### Step 2: Submit a Pull Request + +1. Fork the [LiteLLM repository](https://github.com/BerriAI/litellm) +2. Add your template to `policy_templates.json` at the root +3. Add your template to `litellm/policy_templates_backup.json` (keep both in sync) +4. Create a pull request with: + - Clear description of what the template protects + - Use case examples + - Any relevant compliance frameworks (HIPAA, GDPR, SOC 2, etc.) + +### Guidelines + +**DO:** +- ✅ Use clear, descriptive names +- ✅ Include comprehensive descriptions +- ✅ Test all guardrails thoroughly +- ✅ Document pattern sources (e.g., "Based on NIST guidelines") +- ✅ Group related guardrails logically +- ✅ Consider different complexity levels + +**DON'T:** +- ❌ Include credentials or secrets +- ❌ Use overly broad patterns that may have false positives +- ❌ Duplicate existing templates +- ❌ Use custom code without thorough testing + +## Using Templates Offline + +For air-gapped or offline deployments, set the environment variable: + +```bash +export LITELLM_LOCAL_POLICY_TEMPLATES=true +``` + +This forces the system to use the local backup (`litellm/policy_templates_backup.json`) instead of fetching from GitHub. + +## Template Sources + +- **GitHub (default):** https://raw.githubusercontent.com/BerriAI/litellm/main/policy_templates.json +- **Local backup:** `litellm/policy_templates_backup.json` + +Templates are automatically fetched from GitHub on each request, with fallback to local backup on any failure. + +## Available Pattern Types + +When creating guardrails for templates, you can use these prebuilt patterns: + +### Identity Documents +- `passport_australia`, `passport_us`, `passport_uk`, `passport_germany`, etc. +- `us_ssn`, `us_ssn_no_dash` +- `au_tfn`, `au_abn`, `au_medicare` +- `nl_bsn_contextual` +- `br_cpf`, `br_rg`, `br_cnpj` + +### Financial +- `visa`, `mastercard`, `amex`, `discover`, `credit_card` +- `iban` + +### Contact Information +- `email` +- `us_phone`, `br_phone_landline`, `br_phone_mobile` +- `street_address` +- `br_cep` (Brazilian postal code) + +### Credentials +- `aws_access_key`, `aws_secret_key` +- `github_token` +- `slack_token` +- `generic_api_key` + +### Network +- `ipv4`, `ipv6` + +### Protected Class +- `gender_sexual_orientation` +- `race_ethnicity_national_origin` +- `religion` +- `age_discrimination` +- `disability` +- `marital_family_status` +- `military_status` +- `public_assistance` + +See the [full patterns list](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/patterns.json) for all available patterns. + +## Related Docs + +- [Guardrail Policies](./guardrail_policies) +- [Policy Tags](./policy_tags) +- [Content Filter Patterns](../hooks/content_filter) +- [Custom Code Guardrails](../hooks/custom_code) diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index 579b5699101..60c87ddc458 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -97,6 +97,7 @@ const sidebars = { label: "Policies", items: [ "proxy/guardrails/guardrail_policies", + "proxy/guardrails/policy_templates", "proxy/guardrails/policy_tags", ], }, diff --git a/litellm/proxy/management_endpoints/policy_endpoints.py b/litellm/proxy/management_endpoints/policy_endpoints.py index ad8d0643d0c..a7e2bae3268 100644 --- a/litellm/proxy/management_endpoints/policy_endpoints.py +++ b/litellm/proxy/management_endpoints/policy_endpoints.py @@ -60,11 +60,18 @@ def fetch_remote_policy_templates(url: str, timeout: int = 5) -> List[Any]: """ Fetch policy templates from a remote URL. - Returns the parsed JSON list. Raises on network/parse errors. + Returns the parsed JSON list. Falls back to local backup on any error. """ - response = httpx.get(url, timeout=timeout) - response.raise_for_status() - return response.json() + try: + response = httpx.get(url, timeout=timeout) + response.raise_for_status() + return response.json() + except Exception as e: + verbose_proxy_logger.warning( + f"Failed to fetch policy templates from {url}: {e}. " + "Falling back to local backup." + ) + return load_local_policy_templates() def get_policy_templates_list() -> List[Any]: @@ -86,36 +93,24 @@ def get_policy_templates_list() -> List[Any]: ) return load_local_policy_templates() - # Try to fetch from GitHub - try: - templates = fetch_remote_policy_templates(POLICY_TEMPLATES_GITHUB_URL) + # Fetch from GitHub (automatically falls back to local on any error) + templates = fetch_remote_policy_templates(POLICY_TEMPLATES_GITHUB_URL) - # Validate it's a non-empty list - if not isinstance(templates, list): - verbose_proxy_logger.warning( - f"Fetched policy templates is not a list (type={type(templates).__name__}). " - "Falling back to local backup." - ) - return load_local_policy_templates() - - if len(templates) == 0: - verbose_proxy_logger.warning( - "Fetched policy templates is empty. Falling back to local backup." - ) - return load_local_policy_templates() - - verbose_proxy_logger.debug( - f"Successfully fetched {len(templates)} policy templates from GitHub" - ) - return templates - - except Exception as e: + # Validate it's a non-empty list + if not isinstance(templates, list): verbose_proxy_logger.warning( - f"Failed to fetch policy templates from {POLICY_TEMPLATES_GITHUB_URL}: {e}. " - "Falling back to local backup." + f"Policy templates is not a list (type={type(templates).__name__}). " + "Using local backup." ) return load_local_policy_templates() + if len(templates) == 0: + verbose_proxy_logger.warning("Policy templates is empty. Using local backup.") + return load_local_policy_templates() + + verbose_proxy_logger.debug(f"Successfully loaded {len(templates)} policy templates") + return templates + @router.post( "/policy/validate",