Policy Simulations

Changing governance policies in production carries risk. A poorly tuned rule can block legitimate agent actions or allow unwanted ones. MITRITY's policy simulation system lets you test proposed policy changes against historical audit events before deploying them — giving you a clear picture of exactly how many decisions would change.

Overview

A policy simulation takes a proposed policy configuration and replays it against your actual audit history. The result tells you:

• How many decisions would change compared to the current policy set
• How many actions would shift from allow to block (new denials)
• How many actions would shift from block to allow (relaxed restrictions)
• How many actions would shift from immediate decision to hold (new approval requirements)
• Which specific events would be affected, with full context

Simulations are read-only. They never modify your live policies, affect running agents, or create audit events.

Creating a Simulation

Via the Dashboard

1. Navigate to Policies > Simulations.
2. Click New Simulation.
3. Choose the simulation source:
   • Modified policy set: Start from your current policies and make changes
   • Custom policy set: Upload a complete policy configuration
4. Select the time range to simulate against (e.g., last 7 days, last 30 days, custom range).
5. Optionally filter by agent or environment.
6. Click Run Simulation.

The simulation runs asynchronously. Depending on the volume of historical events, it may take a few seconds to several minutes. The dashboard polls for completion automatically.

Via the API

Create a simulation by posting a policy configuration and time range:

curl -X POST https://api.mitrity.com/api/v1/simulations \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test stricter CRM policies",
    "description": "Evaluate impact of denying all CRM write operations for sales-bot",
    "days": 7,
    "environment_id": "env_production",
    "policies": [
      {
        "name": "deny-crm-writes",
        "policy_type": "deny",
        "action_pattern": "write_crm_*",
        "priority": 300
      },
      {
        "name": "allow-crm-reads",
        "policy_type": "allow",
        "action_pattern": "read_crm_*",
        "priority": 100
      },
      {
        "name": "deny-all-default",
        "policy_type": "deny",
        "action_pattern": "*",
        "priority": 1
      }
    ]
  }'

Response:

{
  "data": {
    "id": "sim_4k2m8n",
    "name": "Test stricter CRM policies",
    "description": "Evaluate impact of denying all CRM write operations for sales-bot",
    "status": "running",
    "days": 7,
    "environment_id": "env_production",
    "policy_count": 3,
    "created_at": "2026-03-01T14:00:00Z"
  },
  "meta": {
    "request_id": "req_sim001",
    "timestamp": "2026-03-01T14:00:00Z"
  }
}

Simulation Parameters

Parameter	Type	Required	Description
name	string	Yes	A descriptive name for the simulation
description	string	No	Additional context about the purpose of the simulation
days	integer	Yes (if no start_date/end_date)	Number of days of history to simulate against (1-90)
start_date	datetime	No	Custom start date (ISO 8601)
end_date	datetime	No	Custom end date (ISO 8601)
environment_id	string	No	Limit simulation to a specific environment
agent_ids	array	No	Limit simulation to specific agents
policies	array	Yes	The complete policy set to simulate

Polling for Completion

Simulations run asynchronously. Poll the simulation status:

curl https://api.mitrity.com/api/v1/simulations/sim_4k2m8n \
  -H "Authorization: Bearer mk_live_your-api-key"

Response (running):

{
  "data": {
    "id": "sim_4k2m8n",
    "name": "Test stricter CRM policies",
    "status": "running",
    "progress": {
      "events_processed": 12500,
      "events_total": 34200,
      "percent_complete": 36
    },
    "created_at": "2026-03-01T14:00:00Z"
  },
  "meta": {
    "request_id": "req_sim002",
    "timestamp": "2026-03-01T14:00:30Z"
  }
}

Response (completed):

{
  "data": {
    "id": "sim_4k2m8n",
    "name": "Test stricter CRM policies",
    "status": "completed",
    "days": 7,
    "environment_id": "env_production",
    "policy_count": 3,
    "results": {
      "events_analyzed": 34200,
      "decisions_changed": 1847,
      "allow_to_block": 1823,
      "block_to_allow": 24,
      "allow_to_hold": 0,
      "hold_to_allow": 0,
      "hold_to_block": 0,
      "block_to_hold": 0,
      "unchanged": 32353
    },
    "created_at": "2026-03-01T14:00:00Z",
    "completed_at": "2026-03-01T14:02:15Z"
  },
  "meta": {
    "request_id": "req_sim003",
    "timestamp": "2026-03-01T14:02:30Z"
  }
}

Simulation Statuses

Status	Description
pending	Simulation is queued and waiting to start
running	Simulation is actively processing historical events
completed	Simulation finished successfully; results are available
failed	Simulation encountered an error (see error field)

Interpreting Results

Summary Metrics

The results object provides high-level impact metrics:

Metric	Description	Impact
events_analyzed	Total number of historical audit events replayed	Volume context
decisions_changed	Total decisions that would differ under the new policies	Overall impact
allow_to_block	Actions currently allowed that would be denied	Potential disruption
block_to_allow	Actions currently denied that would be allowed	Relaxed restrictions
allow_to_hold	Actions currently allowed that would require approval	New review burden
hold_to_allow	Actions currently held that would be auto-allowed	Reduced review burden
hold_to_block	Actions currently held that would be auto-denied	Stricter enforcement
block_to_hold	Actions currently denied that would move to approval	Added human review
unchanged	Actions where the decision would remain the same	Stability indicator

Affected Events

Get the list of events where decisions would change:

curl "https://api.mitrity.com/api/v1/simulations/sim_4k2m8n/events?change_type=allow_to_block&limit=25" \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": [
    {
      "event_id": "evt_abc123",
      "agent_id": "agt_sales-bot",
      "agent_name": "sales-bot",
      "action_type": "write_crm_contact",
      "current_decision": "allow",
      "simulated_decision": "deny",
      "current_policy": "allow-crm-all",
      "simulated_policy": "deny-crm-writes",
      "timestamp": "2026-02-28T15:30:00Z"
    },
    {
      "event_id": "evt_def456",
      "agent_id": "agt_sales-bot",
      "agent_name": "sales-bot",
      "action_type": "write_crm_deal",
      "current_decision": "allow",
      "simulated_decision": "deny",
      "current_policy": "allow-crm-all",
      "simulated_policy": "deny-crm-writes",
      "timestamp": "2026-02-28T16:45:00Z"
    }
  ],
  "meta": {
    "request_id": "req_sim004",
    "timestamp": "2026-03-01T14:05:00Z",
    "next_cursor": "eyJpZCI6MjV9",
    "total": 1823
  }
}

Change Type Filters

Filter affected events by the type of decision change:

Filter	Value	Description
change_type	allow_to_block	Show only events that would shift from allow to deny
change_type	block_to_allow	Show only events that would shift from deny to allow
change_type	allow_to_hold	Show only events that would shift from allow to hold
change_type	any	Show all events where the decision would change
agent_id	agent ID	Filter by specific agent

Use Cases

Testing Before Deployment

The most common use case: you have drafted a new policy or modified an existing one, and you want to understand the impact before deploying to production.

Workflow:

1. Draft your policy changes.
2. Run a simulation against the last 7-30 days.
3. Review the allow_to_block count — these are actions that your agents are currently performing that would be blocked.
4. Examine the affected events to confirm they should indeed be blocked.
5. If the impact is expected, deploy the policy. If not, refine and re-simulate.

Compliance Impact Analysis

Before a compliance audit, validate that your policy set meets the required controls:

1. Define the required policy set for your compliance framework (SOC 2, GDPR, ISO 27001).
2. Run a simulation to identify any gaps — actions that should be blocked but are currently allowed.
3. Quantify the allow_to_block count as "actions that would be brought into compliance."
4. Include the simulation results in your compliance documentation.

Policy Regression Testing

When updating policies, ensure you do not accidentally relax restrictions:

1. Export your current policy set.
2. Make changes.
3. Run a simulation.
4. Check the block_to_allow count — if it is greater than zero, some previously blocked actions would now be allowed. Verify each one is intentional.

Comparing Policy Strategies

Run multiple simulations with different policy sets to compare approaches:

1. Simulation A: Strict deny-all with explicit allows.
2. Simulation B: Allow-all with explicit denies.
3. Compare decisions_changed and allow_to_block counts.
4. Choose the strategy with the best balance of security and operational impact.

Agent Onboarding

When onboarding a new agent, simulate your policy set against sample actions to predict governance behavior:

1. Create test events for the new agent's expected action types.
2. Run a simulation scoped to that agent.
3. Verify that all expected actions are allowed and unexpected ones are blocked.
4. Adjust policies before the agent goes live.

Managing Simulations

List All Simulations

curl https://api.mitrity.com/api/v1/simulations \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": [
    {
      "id": "sim_4k2m8n",
      "name": "Test stricter CRM policies",
      "status": "completed",
      "days": 7,
      "results": {
        "events_analyzed": 34200,
        "decisions_changed": 1847
      },
      "created_at": "2026-03-01T14:00:00Z",
      "completed_at": "2026-03-01T14:02:15Z"
    },
    {
      "id": "sim_7j3n9p",
      "name": "Relax dev environment policies",
      "status": "completed",
      "days": 14,
      "results": {
        "events_analyzed": 8500,
        "decisions_changed": 312
      },
      "created_at": "2026-02-28T09:00:00Z",
      "completed_at": "2026-02-28T09:01:45Z"
    }
  ],
  "meta": {
    "request_id": "req_sim005",
    "timestamp": "2026-03-01T15:00:00Z",
    "next_cursor": null,
    "total": 2
  }
}

Delete a Simulation

Simulations are retained for 90 days by default. To delete a simulation manually:

curl -X DELETE https://api.mitrity.com/api/v1/simulations/sim_4k2m8n \
  -H "Authorization: Bearer mk_live_your-api-key"

Limitations

• Maximum simulation range: 90 days of historical data.
• Concurrent simulations: Up to 3 simulations can run simultaneously per tenant.
• Policy set size: Simulations support up to 500 policies per set.
• Event volume: Simulations processing more than 1 million events may take several minutes to complete.
• Hold policy simulation: Hold policies are evaluated for decision changes, but the actual approval workflow (timeouts, human decisions) is not simulated. The simulation reports what would be held, not what would ultimately be approved or denied.

Best Practices

Simulate Before Every Policy Change

Make simulations a standard part of your policy change workflow. Even a small change to a glob pattern can affect thousands of decisions.

Use Descriptive Names

Name simulations clearly so you can reference them later: "Test deny-all-writes for sales-bot (March 2026)" is more useful than "Simulation 5."

Review allow_to_block Carefully

The allow_to_block metric is the most critical. These are actions your agents are currently performing successfully that would be disrupted. Examine each affected event to confirm the block is intentional.

Run Simulations Across Multiple Time Ranges

Agent behavior may vary by day of week, time of day, or business cycle. Run simulations across different time ranges to catch edge cases.

Archive Results for Compliance

Download or bookmark simulation results before major policy deployments. These serve as evidence of due diligence for compliance audits.

Related Documentation

• Writing Policies — Policy structure and pattern matching
• Enforcement Modes — Monitor, Alert, and Enforce modes
• Approval Workflows — Hold policies and human-in-the-loop governance
• Compliance Reports — Generate compliance reports from governance data
• API Overview — Full API reference for simulation endpoints