Control Impact Simulator — Admin Guide

Overview

The Control Impact Simulator (CIS) is Control Core's first-class control testing tool. It evaluates one control against one input payload per run, using the same OPA engine the Bouncer uses at runtime, and writes every run to policy_simulation_logs with a matching POLICY_SIMULATION_RUN audit event.

As an administrator, you can monitor team usage, review test history across the organization, and ensure testing workflows align with your compliance requirements.

Scope note: The simulator is a per-input decision tool, not a blast-radius, traffic-replay, or live-Bouncer introspection tool. Use it to validate stored control logic against explicit inputs before promotion.

Key Capabilities

Monitoring Team Usage

Accessing Simulation Audit Logs

All control simulations are logged to the central audit trail for compliance tracking.

To view simulation logs:

1. Navigate to Audit Logs from the Operations menu
2. Filter by event type: POLICY_SIMULATION_RUN (technical name)
3. View details including:
   • Control tested
   • User who ran the test
   • Decision result (ALLOW/DENY/MASK)
   • Input summary
   • Execution time
   • Environment (Sandbox/Production)

Audit events tracked:

• POLICY_SIMULATION_RUN: Every test execution
• POLICY_SIMULATION_EXPORTED: Result exports
• TEST_SCENARIO_CREATED: Saved test scenarios
• TEST_SCENARIO_UPDATED: Scenario modifications
• TEST_SCENARIO_DELETED: Scenario deletions

Test History Analytics

Monitor control testing activity:

• Total simulations per control: Understand which controls are being tested most
• Average execution time: Track control complexity and performance
• Decision breakdown: See ALLOW vs DENY ratios
• User activity: Identify which team members are testing controls

Best Practices for Admins

1. Review Production Tests Regularly

   • Production control tests are logged but read-only
   • Monitor for unusual testing patterns
   • Ensure tests align with change management processes

2. Encourage Scenario Saving

   • Saved scenarios enable regression testing
   • Build a library of test cases for critical controls
   • Share scenarios across teams for consistency

3. Monitor Export Activity

   • Exports are logged for compliance
   • Review who is exporting simulation data
   • Ensure sensitive data is handled appropriately

4. Environment Governance

   • Enforce Sandbox → Production promotion workflow
   • Require testing before production deployment
   • Use simulation history as approval evidence

Integration with Policy Lifecycle

Testing Workflow

Draft Control (Sandbox)
  ↓
Test with Control Simulator (Automated attribute extraction)
  ↓
Review trace and results
  ↓
Save test scenario for regression
  ↓
Enable in Sandbox
  ↓
Production testing (read-only)
  ↓
Promote to Production

Compliance and Governance

• All simulations are logged to policy_simulation_logs table
• Linked to main audit trail via POLICY_SIMULATION_RUN events
• Test history provides evidence of due diligence
• Exports can be attached to change requests

Troubleshooting

Common Issues

"No controls available for testing"

• Check environment filter (Sandbox vs Production)
• Ensure controls have logic defined
• Verify user permissions

"Failed to extract attributes"

• OPA is bundled with Control Core - check deployment
• Verify control logic is syntactically valid
• Check control-plane-api logs for details

"Simulation timed out"

• Complex controls may take longer to evaluate
• Review control logic for infinite loops or expensive operations
• Contact support if issue persists

Security Considerations

Data Protection

• Simulation inputs may contain sensitive test data
• Inputs are stored in policy_simulation_logs table
• Consider data retention policies for simulation history
• Use export carefully with compliance requirements

Access Control

• Only authenticated users can run simulations
• Production testing requires appropriate permissions
• Scenario saving is per-user (no sharing by default)
• Export actions are audit-logged

System Requirements

The Control Simulator requires:

• OPA: Bundled with control-plane-api Docker container
• Regal: Optional (for enhanced linting)
• Database: PostgreSQL or SQLite for simulation logs
• Browser: Modern browser with JavaScript enabled

All components are pre-installed in Control Core deployments.

Support and Feedback

For issues or enhancement requests related to the Control Simulator:

1. Check the Troubleshooting section above
2. Review test history and audit logs for error details
3. Contact Control Core support with simulation ID for faster resolution
4. Use the Feedback dialog in the PAP interface

Access Control Summary

The API enforces per-user ownership on simulation history and exports:

• Non-admin users see only their own runs in GET /v1/pis/policies/{policy_id}/test-history.
• Admins (roles admin and builtin_admin) see every run on controls they can access.
• Exports of another user's run by a non-admin return 403 Forbidden.

Admins should audit export activity via the POLICY_SIMULATION_EXPORTED event.

Related Documentation

• Control Manager Guide - End-user testing guide
• API Reference - Developer documentation
• Quick Start: Testing Controls - 5-minute intro
• Audit Log Guide - Understanding audit trail
• Environment Management - Sandbox vs Production workflows