Skip to content

Rules API

The Rules API allows you to manage detection and obfuscation policies that control how Shield processes sensitive data.

Overview

Rules in Shield define the core data protection policies:

  • Action: Detect, obfuscate, or block sensitive data
  • Applications: Which apps this rule applies to (via application UUIDs)
  • Obfuscations: How to mask detected data types
  • User/Group filters: Apply rules to specific users or directory groups
  • Time filters: Apply rules during specific time windows
  • ICAP mode: Request (REQMOD), Response (RESPMOD), or both

Rules are the heart of Shield's policy engine - they combine applications, data types, and obfuscations to enforce data protection policies based on context.

Authentication

Requires API Key with:

  • Read access: GET operations (all keys have read access)
  • Policy Definition permission: POST, PUT, PATCH, DELETE operations

Available Endpoints

The Rules API provides the following endpoints:

Core Operations

Special Operations

Key Concepts

Rule Actions

Rules can perform three types of actions:

Action Behavior Use Case
detect Log sensitive data detection without modifying content Audit and compliance monitoring
obfuscate Mask sensitive data using specified obfuscation patterns Data masking in logs or APIs
block Block the entire request/response if sensitive data is found Prevent data leakage to unauthorized destinations

Rule Evaluation Order

Rules are evaluated in order - the first matching rule determines the action. Use the Reorder Rules endpoint to adjust priority.

Example: 

1. Block SSNs to external APIs (most specific)
2. Obfuscate PII in all APIs (moderate)
3. Detect all sensitive data (catch-all)

ICAP Modes

Rules can apply to different traffic directions:

  • REQMOD - Apply to outbound requests (data leaving your network)
  • RESPMOD - Apply to inbound responses (data entering your network)
  • Both (empty icapMode) - Apply to both directions

User and Group Filters

Rules can be scoped to specific users or directory groups:

Response Format 
{
  "userFilters": [
    {
      "condition": "notequal",
      "filter": "admin"
    }
  ],
  "groupFilters": [
    {
      "condition": "contains",
      "filter": "Engineering",
      "provider": "AzureAD"
    }
  ]
}

Conditions: equal, notequal, contains, doesnotcontain

Time Filters

Apply rules during specific time windows:

{
  "timeFilterEnabled": true,
  "timeFilter": {
    "timeWindows": [
      {
        "startTime": "09:00",
        "endTime": "17:00"
      }
    ],
    "daysOfWeek": [1, 2, 3, 4, 5],
    "timezone": "America/New_York",
    "behavior": "match"
  }
}
  • behavior: "match" - Apply rule during specified times
  • behavior: "bypass" - Apply rule outside specified times

Common Use Cases

Detect All Sensitive Data

Create a detection-only rule to audit all sensitive data without blocking or masking:

{
  "name": "Audit All PII",
  "action": "detect",
  "enable": true,
  "apps": ["all-apps-uuid"],
  "icapMode": "REQMOD"
}

Block Data to External APIs

Prevent sensitive data from leaving your network:

{
  "name": "Block PII to External Services",
  "action": "block",
  "enable": true,
  "apps": ["external-apis-uuid"],
  "obfuscations": ["pii-obfuscation-uuid"],
  "icapMode": "REQMOD"
}

Mask Data for Non-Admins

Apply obfuscation based on user role:

{
  "name": "Mask SSNs for Non-Admins",
  "action": "obfuscate",
  "enable": true,
  "apps": ["hr-system-uuid"],
  "obfuscations": ["ssn-mask-uuid"],
  "userFilters": [
    {
      "condition": "notequal",
      "filter": "admin"
    }
  ]
}

Time-Based Protection

Apply stricter policies during business hours:

{
  "name": "Block PII During Business Hours",
  "action": "block",
  "enable": true,
  "apps": ["payment-apis-uuid"],
  "obfuscations": ["pii-obf-uuid"],
  "timeFilterEnabled": true,
  "timeFilter": {
    "timeWindows": [{"startTime": "08:00", "endTime": "18:00"}],
    "daysOfWeek": [1, 2, 3, 4, 5],
    "timezone": "America/Los_Angeles",
    "behavior": "match"
  }
}

Best Practices

  • Order matters - Place most specific rules first, general rules last
  • Use descriptive names - Clearly indicate what the rule does and why
  • Test before enabling - Create rules with "enable": false, test thoroughly, then enable
  • Combine filters sparingly - Too many filters make rules difficult to understand and maintain
  • Document time filters - Note timezone and business hours clearly in the description
  • Use soft delete - Deleted rules are retained for historical activity analysis