Policy Modes - TealTiger Docs

Policy modes let you test policies in production without breaking anything. Think of them as a safety switch that separates “what would happen” from “what actually happens.”

Why policy modes matter

Imagine deploying a new security policy that accidentally blocks legitimate user requests. Without policy modes, you’d have to:

Deploy the policy
Hope it works correctly
Deal with angry users if it doesn’t
Roll back and start over

With policy modes, you can:

Deploy in MONITOR mode
See what would be blocked (without actually blocking)
Tune the policy based on real traffic
Switch to ENFORCE mode with confidence

The three modes

TealTiger supports three policy modes:

MONITOR mode (recommended for new policies)

Policies are evaluated and violations are logged, but nothing is blocked.

const engine = new TealEngine({
  policies: {
    tools: {
      file_delete: {
        condition: { field: 'tool.name', operator: 'eq', value: 'file_delete' },
        action: 'DENY'
      }
    }
  },
  mode: {
    defaultMode: PolicyMode.MONITOR
  }
});

// In MONITOR mode:
const decision = await engine.evaluate(request);
// decision.action === 'DENY', but request still proceeds
// Violation is logged for analysis

Use MONITOR mode when:

Testing new policies in production
Measuring impact before enforcement
Tuning policy thresholds
Validating policy logic

What happens:

✅ Policies are evaluated
✅ Decisions are recorded
✅ Audit logs are created
❌ Actions are NOT blocked

ENFORCE mode (production enforcement)

Policies are evaluated and violations are blocked.

const engine = new TealEngine({
  policies: {
    tools: {
      file_delete: {
        condition: { field: 'tool.name', operator: 'eq', value: 'file_delete' },
        action: 'DENY'
      }
    }
  },
  mode: {
    defaultMode: PolicyMode.ENFORCE
  }
});

// In ENFORCE mode:
const decision = await engine.evaluate(request);
if (decision.action === 'DENY') {
  throw new Error('Request blocked by policy');
}

Use ENFORCE mode when:

Policies have been validated in MONITOR mode
You’re confident in policy behavior
Ready for production enforcement

What happens:

✅ Policies are evaluated
✅ Decisions are recorded
✅ Audit logs are created
✅ Actions ARE blocked

REPORT_ONLY mode (visibility only)

Similar to MONITOR, but with minimal logging overhead.

const engine = new TealEngine({
  mode: {
    defaultMode: PolicyMode.REPORT_ONLY
  }
});

Use REPORT_ONLY mode when:

You want visibility without enforcement
Minimizing performance impact
Initial policy exploration

Per-policy mode overrides

You can set different modes for different policies:

const engine = new TealEngine({
  policies: {
    tools: {
      file_delete: {
        condition: { field: 'tool.name', operator: 'eq', value: 'file_delete' },
        action: 'DENY'
      },
      file_write: {
        condition: { field: 'tool.name', operator: 'eq', value: 'file_write' },
        action: 'DENY'
      },
      customer_data_read: {
        condition: { field: 'tool.name', operator: 'eq', value: 'customer_data_read' },
        action: 'ALLOW'
      }
    }
  },
  mode: {
    // Default: monitor everything
    defaultMode: PolicyMode.MONITOR,
    
    // Override: enforce critical policies
    policyModes: {
      'tools.file_delete': PolicyMode.ENFORCE,  // Always block deletes
      'tools.file_write': PolicyMode.MONITOR    // Monitor writes
    }
  }
});

This lets you:

Enforce critical policies immediately
Monitor less critical policies
Roll out enforcement incrementally

Recommended rollout sequence

Follow this sequence for safe policy deployment:

Phase 1: MONITOR mode (1-2 weeks)

Deploy new policies in MONITOR mode to measure impact.

// Week 1-2: Monitor mode
mode: {
  defaultMode: PolicyMode.MONITOR
}

What to watch:

How many requests would be blocked?
Are there false positives?
What’s the violation rate?

Example metrics:

Total requests: 10,000
Would be blocked: 150 (1.5%)
False positives: 5 (0.05%)

Phase 2: Tune policies (1 week)

Adjust policies based on MONITOR mode data.

// Adjust thresholds based on real traffic
policies: {
  budget: {
    maxCostPerRequest: 0.50  // Was 0.25, too strict
  }
}

Phase 3: Selective ENFORCE (1 week)

Enforce critical policies, keep others in MONITOR.

// Week 4: Enforce critical policies only
mode: {
  defaultMode: PolicyMode.MONITOR,
  policyModes: {
    'tools.file_delete': PolicyMode.ENFORCE,
    'budget.daily_limit': PolicyMode.ENFORCE
  }
}

Phase 4: Full ENFORCE (ongoing)

Switch all policies to ENFORCE mode.

// Week 5+: Full enforcement
mode: {
  defaultMode: PolicyMode.ENFORCE
}

Monitoring policy impact

Track these metrics during rollout:

Violation rate

const metrics = await teal.getMetrics();

console.log({
  totalRequests: metrics.totalRequests,
  violations: metrics.violations,
  violationRate: (metrics.violations / metrics.totalRequests) * 100
});

// Output:
// {
//   totalRequests: 10000,
//   violations: 150,
//   violationRate: 1.5
// }

False positive rate

// Track user complaints or manual reviews
const falsePositives = await getFalsePositiveCount();
const falsePositiveRate = (falsePositives / metrics.violations) * 100;

console.log(`False positive rate: ${falsePositiveRate}%`);
// Target: under 5%

Policy effectiveness

// Compare before/after metrics
const beforeMetrics = {
  unauthorizedRefunds: 10,
  budgetOverruns: 5,
  dataLeaks: 2
};

const afterMetrics = {
  unauthorizedRefunds: 0,  // 100% reduction
  budgetOverruns: 0,       // 100% reduction
  dataLeaks: 0             // 100% reduction
};

Mode behavior comparison

Feature	REPORT_ONLY	MONITOR	ENFORCE
Evaluate policies	✅	✅	✅
Record decisions	✅	✅	✅
Create audit logs	✅	✅	✅
Block violations	❌	❌	✅
Log violations	✅	✅	✅
Performance impact	Minimal	Low	Low

What doesn’t change between modes

Policy modes only affect enforcement. These stay the same:

✅ Policy evaluation logic
✅ Condition matching
✅ Risk score calculation
✅ Reason code generation
✅ Audit event structure
✅ Decision determinism

Complete example

Here’s a complete example showing mode-aware handling:

import { TealEngine, PolicyMode, DecisionAction } from 'tealtiger';

const engine = new TealEngine({
  policies: {
    tools: {
      file_delete: {
        condition: { field: 'tool.name', operator: 'eq', value: 'file_delete' },
        action: 'DENY'
      }
    }
  },
  mode: {
    defaultMode: PolicyMode.MONITOR,
    policyModes: {
      'tools.file_delete': PolicyMode.ENFORCE
    }
  }
});

async function executeAction(action: string) {
  const decision = await engine.evaluate({
    action: 'tool.execute',
    tool: action
  });
  
  // Check if we should enforce
  const shouldEnforce = decision.mode === 'ENFORCE';
  
  if (decision.action === DecisionAction.DENY) {
    if (shouldEnforce) {
      // ENFORCE mode: actually block
      throw new Error(`Action blocked: ${decision.reason_codes.join(', ')}`);
    } else {
      // MONITOR mode: log but allow
      console.warn(`Would block: ${decision.reason_codes.join(', ')}`);
      await logViolation(decision);
      // Continue execution
    }
  }
  
  // Execute the action
  return await performAction(action);
}

// Example 1: file_delete (ENFORCE mode)
try {
  await executeAction('file_delete');
} catch (error) {
  console.error('Blocked:', error.message);
  // Output: "Blocked: Action blocked: TOOL_NOT_ALLOWED"
}

// Example 2: file_write (MONITOR mode)
try {
  await executeAction('file_write');
  console.log('Executed (with warning)');
  // Output: "Would block: TOOL_NOT_ALLOWED"
  // Output: "Executed (with warning)"
} catch (error) {
  // Won't throw in MONITOR mode
}

from tealtiger import TealEngine, PolicyMode, DecisionAction

engine = TealEngine({
    "policies": {
        "tools": {
            "file_delete": {
                "condition": {"field": "tool.name", "operator": "eq", "value": "file_delete"},
                "action": "DENY"
            }
        }
    },
    "mode": {
        "defaultMode": PolicyMode.MONITOR,
        "policyModes": {
            "tools.file_delete": PolicyMode.ENFORCE
        }
    }
})

async def execute_action(action: str):
    decision = await engine.evaluate({
        "action": "tool.execute",
        "tool": action
    })
    
    # Check if we should enforce
    should_enforce = decision["mode"] == "ENFORCE"
    
    if decision["action"] == DecisionAction.DENY:
        if should_enforce:
            # ENFORCE mode: actually block
            raise Exception(f"Action blocked: {', '.join(decision['reason_codes'])}")
        else:
            # MONITOR mode: log but allow
            print(f"Would block: {', '.join(decision['reason_codes'])}")
            await log_violation(decision)
            # Continue execution
    
    # Execute the action
    return await perform_action(action)

# Example 1: file_delete (ENFORCE mode)
try:
    await execute_action("file_delete")
except Exception as error:
    print(f"Blocked: {str(error)}")
    # Output: "Blocked: Action blocked: TOOL_NOT_ALLOWED"

# Example 2: file_write (MONITOR mode)
try:
    await execute_action("file_write")
    print("Executed (with warning)")
    # Output: "Would block: TOOL_NOT_ALLOWED"
    # Output: "Executed (with warning)"
except Exception as error:
    # Won't throw in MONITOR mode
    pass

Best practices

Always start in MONITOR mode - Never deploy new policies directly to ENFORCE
Monitor for at least 1 week - Give yourself time to see patterns
Set violation rate targets - Aim for under 5% false positives
Enforce critical policies first - Start with high-risk operations
Document mode changes - Track when and why you changed modes
Alert on high violation rates - Get notified if violations spike

Common pitfalls

Pitfall 1: Skipping MONITOR mode

// ❌ Bad: Deploy directly to ENFORCE
mode: {
  defaultMode: PolicyMode.ENFORCE
}

// ✅ Good: Start with MONITOR
mode: {
  defaultMode: PolicyMode.MONITOR
}

Pitfall 2: Not monitoring long enough

// ❌ Bad: Switch to ENFORCE after 1 day
// Not enough data to validate

// ✅ Good: Monitor for 1-2 weeks
// See patterns across different times/days

Pitfall 3: Ignoring false positives

// ❌ Bad: Accept 20% false positive rate
// Users will be frustrated

// ✅ Good: Tune until under 5%
// Adjust thresholds based on real traffic

Next steps

Decision model

Understand how decisions are made

Policy authoring

Write custom policies

Audit schema

See what gets logged

Troubleshooting

Debug policy issues

​Why policy modes matter

​The three modes

​MONITOR mode (recommended for new policies)

​ENFORCE mode (production enforcement)

​REPORT_ONLY mode (visibility only)

​Per-policy mode overrides

​Recommended rollout sequence

​Phase 1: MONITOR mode (1-2 weeks)

​Phase 2: Tune policies (1 week)

​Phase 3: Selective ENFORCE (1 week)

​Phase 4: Full ENFORCE (ongoing)

​Monitoring policy impact

​Violation rate

​False positive rate

​Policy effectiveness

​Mode behavior comparison

​What doesn’t change between modes

​Complete example

​Best practices

​Common pitfalls

​Pitfall 1: Skipping MONITOR mode

​Pitfall 2: Not monitoring long enough

​Pitfall 3: Ignoring false positives

​Next steps