Policy Management

Safe Zone policies determine which values are detected, ignored, blocked, or evaluated by a guardrail. Manage policies as reviewed operational configuration rather than ad hoc production edits.

Policy Building Blocks

Resource	Purpose	Example
Pattern	Detect a value that matches a regular expression.	Internal project IDs or account formats.
Allowlist	Ignore an exact value that is known and approved.	A public support email address.
Blocklist	Reject an exact forbidden value.	A restricted keyword or leaked secret marker.
Validator	Evaluate a format or AI-based rule.	Toxic language or an expected JSON structure.
Template	Import a reviewed set of policy resources together.	A policy pack for a business unit.

Add a Pattern

POST /patterns
Authorization: Bearer policy-admin
Content-Type: application/json

{
  "name": "PROJECT_CODE",
  "regex": "PROJ-[0-9]{4}",
  "category": "SECRET",
  "description": "Internal project code"
}

This pattern lets Safe Zone recognize an organization-specific identifier that the built-in rules do not cover. Test the expression against valid, invalid, and near-match values before enabling it in production. Avoid expressions with pathological backtracking.

Add an Allowlist Entry

POST /allowlist
Authorization: Bearer policy-admin
Content-Type: application/json

{
  "value": "support@example.com",
  "description": "Published support address"
}

Use the allowlist only when a detected value is intentionally public and safe in the relevant context. Do not allowlist broad domains, partial secrets, or common patterns merely to reduce false positives.

Add a Blocklist Entry

POST /blacklist
Authorization: Bearer policy-admin
Content-Type: application/json

{
  "value": "CONFIDENTIAL-PROJECT-NAME",
  "description": "Restricted program identifier"
}

A blocklist is appropriate for exact values that must stop the request even if a general detector does not assign a high confidence score.

Add a Validator

POST /validators
Authorization: Bearer policy-admin
Content-Type: application/json

{
  "name": "TOXIC_LANGUAGE",
  "type": "AI_PROMPT",
  "rule": "Does this text contain abusive or toxic language? Answer YES or NO.",
  "expected": "NO"
}

The validator name is then passed in the guardrails array of /detect or in X-TSZ-Guardrails for gateway calls. Validator instructions should produce a narrow, deterministic decision that can be tested.

Import a Policy Template

tsz templates import --file ./customer-support-policy.json

Templates are useful for promoting the same reviewed policy pack across environments. Keep template files in version control, review changes, and record the imported version in the deployment change.

Safe Change Process

1. Define the business risk and intended decision.
2. Add positive, negative, and boundary test cases.
3. Apply the candidate policy in a non-production environment.
4. Run detection and gateway regression tests.
5. Review false positives, false negatives, and latency.
6. Promote the same policy definition to production.
7. Monitor block rate and validator failures after release.

When removing a policy, first identify applications that reference its validator name or expect its placeholder. A removed validator can silently reduce coverage if clients continue sending the old name.

Troubleshooting

Symptom	Check
A known value is not detected	Pattern status, regular expression boundaries, category, and cache state.
A public value is still masked	Exact allowlist value and normalization differences such as whitespace or case.
Too many requests are blocked	Confidence thresholds, explicit block rules, and validator decision quality.
A guardrail does not run	Validator name in the request and the client's token permission.
Policy changed but behavior did not	Hot reload result, instance consistency, and supported cache administration.

See the API Reference for complete endpoint payloads and the CLI Guide for equivalent operator commands.