Troubleshooting Policy Evaluation Failures

When a policy evaluation does not produce the expected result, the issue is almost always in the policy definition, not the engine. Authensor's policy engine is deterministic: given the same policy and the same input, it always produces the same output. This makes debugging straightforward if you approach it systematically.

Step 1: Reproduce the Issue

Extract the exact envelope (the action request) that produced the unexpected result. You can find this in the audit trail receipt. Then evaluate it locally:

npx authensor evaluate --policy ./policy.yaml --envelope ./envelope.json

This runs the policy engine in isolation, outside the control plane, and shows the full evaluation trace.

Step 2: Check Rule Ordering

Rules are evaluated in order. The first matching rule determines the outcome. If a broad deny rule appears before a specific allow rule, the deny rule wins.

# This denies everything because the deny rule matches first
rules:
  - name: "deny-all"
    match:
      tool: "*"
    action: deny
  - name: "allow-reads"
    match:
      tool: "database_read"
    action: allow

Move more specific rules before broader ones.

Step 3: Verify Pattern Matching

Regex patterns are the most common source of policy bugs. Test your patterns against the actual tool names and parameter values:

• ^SELECT matches "SELECT * FROM users" but not "select * from users" (case sensitive by default)
• file_* as a glob matches "file_read" and "file_write" but not "read_file"
• \\.env$ matches ".env" but not ".environment"

Step 4: Check Parameter Matching

If a rule matches on parameters, verify that the envelope contains those parameters in the expected structure. A rule matching parameters.query.pattern will not match if the envelope has the query under parameters.sql instead.

Step 5: Inspect the Default Action

If no rule matches, the default action applies. Verify that defaults.action is set to what you expect. If it is missing, the engine defaults to deny.

Step 6: Validate the Policy Schema

Run the schema validator to catch structural errors:

npx authensor validate --policy ./policy.yaml

This catches missing required fields, invalid action values, and malformed patterns before they cause runtime surprises.

When you identify the issue, add a test case for it. Over time, your test suite becomes a regression safety net for policy changes.