Static Policy API

Manage static policies for pattern-based enforcement through the Agent API. Static policies define rules that are evaluated against every request for SQL injection prevention, PII detection, and custom patterns.

Overview

Static policies are evaluated synchronously on every request. They are pattern-based rules that:

• Detect SQL injection attempts
• Identify PII (credit cards, SSNs, emails, phone numbers)
• Block or warn on custom patterns
• Support tenant-specific overrides (Enterprise)

Base URL: http://localhost:8080 (Agent)

---

Endpoints

GET /api/v1/static-policies

List all static policies with optional filtering.

Request:

curl "http://localhost:8080/api/v1/static-policies?enabled=true&category=security" \
  -H "X-Tenant-ID: my-tenant"

Query Parameters:

Parameter	Type	Description
enabled	boolean	Filter by enabled status
category	string	Filter by category (security, compliance, custom)
page	integer	Page number (default: 1)
page_size	integer	Items per page (default: 50, max: 100)

Response (200 OK):

{
  "policies": [
    {
      "id": "sys_sqli_union",
      "name": "SQL Injection - UNION",
      "description": "Detects UNION-based SQL injection attempts",
      "category": "security",
      "pattern": "(?i)union\\s+(all\\s+)?select",
      "action": "block",
      "severity": "critical",
      "enabled": true,
      "system": true,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": "sys_pii_credit_card",
      "name": "PII - Credit Card Detection",
      "description": "Detects credit card numbers using Luhn validation",
      "category": "compliance",
      "pattern": "\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14})\\b",
      "action": "warn",
      "severity": "high",
      "enabled": true,
      "system": true,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_count": 24,
    "total_pages": 1
  }
}

---

POST /api/v1/static-policies

Create a new static policy.

Request:

curl -X POST http://localhost:8080/api/v1/static-policies \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: my-tenant" \
  -d '{
    "name": "Block Competitor Mentions",
    "description": "Block queries mentioning competitor products",
    "category": "custom",
    "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
    "action": "block",
    "severity": "medium",
    "enabled": true,
    "message": "Queries about competitor products are not allowed"
  }'

Request Body:

Field	Type	Required	Description
name	string	Yes	Policy display name
description	string	No	Policy description
category	string	Yes	Category: security, compliance, custom
pattern	string	Yes	Regex pattern to match
action	string	Yes	Action: block, warn, log
severity	string	No	Severity: critical, high, medium, low
enabled	boolean	No	Whether policy is active (default: true)
message	string	No	Custom message when policy triggers

Response (201 Created):

{
  "success": true,
  "policy": {
    "id": "pol_abc123",
    "name": "Block Competitor Mentions",
    "description": "Block queries mentioning competitor products",
    "category": "custom",
    "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
    "action": "block",
    "severity": "medium",
    "enabled": true,
    "message": "Queries about competitor products are not allowed",
    "system": false,
    "version": 1,
    "created_at": "2025-01-02T10:00:00Z",
    "updated_at": "2025-01-02T10:00:00Z"
  }
}

---

GET /api/v1/static-policies/{id}

Get a specific policy by ID.

Request:

curl http://localhost:8080/api/v1/static-policies/pol_abc123 \
  -H "X-Tenant-ID: my-tenant"

Response (200 OK):

{
  "id": "pol_abc123",
  "name": "Block Competitor Mentions",
  "description": "Block queries mentioning competitor products",
  "category": "custom",
  "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
  "action": "block",
  "severity": "medium",
  "enabled": true,
  "message": "Queries about competitor products are not allowed",
  "system": false,
  "version": 3,
  "created_at": "2025-01-02T10:00:00Z",
  "updated_at": "2025-01-02T12:00:00Z"
}

---

PUT /api/v1/static-policies/{id}

Update an existing policy.

Request:

curl -X PUT http://localhost:8080/api/v1/static-policies/pol_abc123 \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: my-tenant" \
  -d '{
    "pattern": "(?i)(competitor-a|competitor-b|competitor-c|rival-product)",
    "enabled": true
  }'

Response (200 OK):

{
  "success": true,
  "policy": {
    "id": "pol_abc123",
    "name": "Block Competitor Mentions",
    "pattern": "(?i)(competitor-a|competitor-b|competitor-c|rival-product)",
    "enabled": true,
    "version": 4,
    "updated_at": "2025-01-02T14:00:00Z"
  }
}

note

System policies (where system: true) cannot be modified or deleted. Create an override instead.

---

DELETE /api/v1/static-policies/{id}

Soft-delete a policy. The policy is disabled but retained for audit purposes.

Request:

curl -X DELETE http://localhost:8080/api/v1/static-policies/pol_abc123 \
  -H "X-Tenant-ID: my-tenant"

Response (200 OK):

{
  "success": true,
  "message": "Policy soft-deleted",
  "policy_id": "pol_abc123"
}

---

PATCH /api/v1/static-policies/{id}

Toggle the enabled status of a policy.

Request:

curl -X PATCH http://localhost:8080/api/v1/static-policies/pol_abc123 \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: my-tenant" \
  -d '{
    "enabled": false
  }'

Response (200 OK):

{
  "success": true,
  "policy": {
    "id": "pol_abc123",
    "enabled": false,
    "updated_at": "2025-01-02T15:00:00Z"
  }
}

---

Policy Testing

POST /api/v1/static-policies/test

Test a pattern against sample inputs without creating a policy.

Request:

curl -X POST http://localhost:8080/api/v1/static-policies/test \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "(?i)select.*from.*where",
    "test_inputs": [
      "SELECT * FROM users WHERE id = 1",
      "What is the weather today?",
      "Please select items from the menu where price is low"
    ]
  }'

Response (200 OK):

{
  "pattern": "(?i)select.*from.*where",
  "results": [
    {
      "input": "SELECT * FROM users WHERE id = 1",
      "matched": true,
      "match_positions": [{"start": 0, "end": 31}]
    },
    {
      "input": "What is the weather today?",
      "matched": false
    },
    {
      "input": "Please select items from the menu where price is low",
      "matched": true,
      "match_positions": [{"start": 7, "end": 52}]
    }
  ],
  "match_count": 2,
  "total_inputs": 3
}

---

GET /api/v1/static-policies/effective

Get effective policies for a tenant, including system policies and tenant overrides.

Request:

curl http://localhost:8080/api/v1/static-policies/effective \
  -H "X-Tenant-ID: my-tenant"

Response (200 OK):

{
  "tenant_id": "my-tenant",
  "effective_policies": [
    {
      "id": "sys_sqli_union",
      "name": "SQL Injection - UNION",
      "enabled": true,
      "action": "block",
      "source": "system",
      "override": null
    },
    {
      "id": "sys_pii_credit_card",
      "name": "PII - Credit Card Detection",
      "enabled": true,
      "action": "warn",
      "source": "system",
      "override": {
        "action": "block",
        "reason": "Tenant requires blocking credit card exposure"
      }
    },
    {
      "id": "pol_abc123",
      "name": "Block Competitor Mentions",
      "enabled": true,
      "action": "block",
      "source": "tenant"
    }
  ],
  "system_policies_count": 20,
  "tenant_policies_count": 3,
  "overrides_count": 1
}

---

Version History

GET /api/v1/static-policies/{id}/versions

Get version history for a policy.

Request:

curl http://localhost:8080/api/v1/static-policies/pol_abc123/versions \
  -H "X-Tenant-ID: my-tenant"

Response (200 OK):

{
  "policy_id": "pol_abc123",
  "versions": [
    {
      "version": 4,
      "pattern": "(?i)(competitor-a|competitor-b|competitor-c|rival-product)",
      "action": "block",
      "enabled": true,
      "changed_by": "[email protected]",
      "changed_at": "2025-01-02T14:00:00Z",
      "change_summary": "Added competitor-c to pattern"
    },
    {
      "version": 3,
      "pattern": "(?i)(competitor-a|competitor-b|rival-product)",
      "action": "block",
      "enabled": true,
      "changed_by": "[email protected]",
      "changed_at": "2025-01-02T12:00:00Z",
      "change_summary": "Updated pattern"
    }
  ],
  "current_version": 4
}

---

Policy Overrides (Enterprise)

Tenant-specific overrides allow customizing system policy behavior without modifying the base policy.

POST /api/v1/static-policies/{id}/override

Create an override for a system policy.

Request:

curl -X POST http://localhost:8080/api/v1/static-policies/sys_pii_credit_card/override \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: my-tenant" \
  -d '{
    "action": "block",
    "reason": "Financial services compliance requires blocking"
  }'

Response (201 Created):

{
  "success": true,
  "override": {
    "policy_id": "sys_pii_credit_card",
    "tenant_id": "my-tenant",
    "action": "block",
    "reason": "Financial services compliance requires blocking",
    "created_at": "2025-01-02T10:00:00Z"
  }
}

DELETE /api/v1/static-policies/{id}/override

Remove a policy override, reverting to system default.

Request:

curl -X DELETE http://localhost:8080/api/v1/static-policies/sys_pii_credit_card/override \
  -H "X-Tenant-ID: my-tenant"

Response (200 OK):

{
  "success": true,
  "message": "Override removed, policy reverted to system default"
}

GET /api/v1/static-policies/overrides

List all policy overrides for a tenant.

Request:

curl http://localhost:8080/api/v1/static-policies/overrides \
  -H "X-Tenant-ID: my-tenant"

Response (200 OK):

{
  "tenant_id": "my-tenant",
  "overrides": [
    {
      "policy_id": "sys_pii_credit_card",
      "policy_name": "PII - Credit Card Detection",
      "system_action": "warn",
      "override_action": "block",
      "reason": "Financial services compliance requires blocking",
      "created_at": "2025-01-02T10:00:00Z"
    }
  ],
  "count": 1
}

---

Policy Actions

Action	Description
block	Reject the request and return an error
warn	Allow the request but include a warning in the response
log	Allow the request and log the match silently

---

Error Responses

HTTP Status	Error Code	Description
400	INVALID_PATTERN	Regex pattern is invalid
400	INVALID_ACTION	Action must be block, warn, or log
403	SYSTEM_POLICY_READONLY	Cannot modify system policies
404	POLICY_NOT_FOUND	Policy does not exist
409	POLICY_NAME_EXISTS	Policy name already in use

---

Next Steps

• Agent Endpoints - Policy enforcement API
• Security - PII Detection - PII detection patterns
• Security - SQL Injection - SQLi prevention