Control CoreDocs

Control Impact Simulator

Audience: Control authors, compliance officers, security engineers Time: ~5 min to run your first simulation

The Control Impact Simulator (CIS) is Control Core's first-class control testing tool. You pick one control, provide one input payload, and the simulator returns the ALLOW/DENY decision, the decision reason, the execution trace, and writes the run to the simulation history for audit.

It uses the same OPA engine the Bouncer uses at runtime, so a simulator result is the decision the Bouncer would make for that exact input.

Scope & limits (read this first)

The Control Impact Simulator evaluates one control against one input payload per run. It is not a blast-radius, traffic-replay, or fleet-impact tool, and it does not introspect running Bouncers.

What it does:

  • Runs the selected control's Rego against the input JSON using OPA.
  • Returns ALLOW / DENY, a human-readable reason, and a structured trace.
  • Persists every run to policy_simulation_logs and emits a POLICY_SIMULATION_RUN audit event.
  • Lets you re-open any run and export it as JSON, CSV, or PDF.

What it does not do:

  • Does not score or estimate the real-world impact of activating a control across live traffic.
  • Does not introspect running PEPs / Bouncers or pull their live decision cache.
  • Does not run bulk or scheduled batch simulations from this page.
  • Does not replay historical Bouncer denials in the main build. (Denial replay and semantic test generation are preview features available only in the all-in-one demo build.)

If you need to change the control itself, do that in the Controls Manager or Visual Builder; this page is for evaluating an already-saved control.

Prerequisites

  • The target control is saved (draft, sandbox, or production).
  • You have permission to view the control (authors, simulator users, admins).
  • For production-environment simulations, your role must permit production testing.

The simulator does not require any data-source configuration in the main build. You can test any saved control by providing your own input payload.

Workflow

Step 1 — Open the simulator

  1. Click Controls in the sidebar and open any saved control (optional), or open Operations → Control Simulator directly.
  2. The console uses tabs: Basic Testing, Advanced Features, and Test History. Flow: pick control → build attributes → run (no separate wizard strip).

Troubleshooting: If no controls appear, check the environment badge, your role, and that at least one control exists in that environment.

Step 2 — Basic Testing: control, environment, and payload

  1. Confirm the environment badge (Sandbox vs Production).
  2. Pick the primary control from the dropdown (search appears when the list is long).
  3. Review resource, Bouncer, and target actions for that control.

The attribute builder auto-generates a form from the control's Rego:

  • Control Core parses the Rego AST and finds every input.* reference.
  • Each reference becomes a form field with a label and inferred type (string, number, boolean, array, object).
  • Use JSON View to edit the structured input directly; changes sync with the form.

Step 3 — Run the simulation

  1. Leave Test Type on Decision for a fast ALLOW/DENY check.
  2. Click Run Controls Impact Test.
  3. The result area shows the decision badge (ALLOW, DENY, MASK, or NO_MATCH), reason, Policy Trace, and raw input/output JSON.

How the decision is computed. The simulator uses opa eval against the control's package as the authoritative decision. OPA opa test results are non-authoritative metadata; they never override a live DENY from evaluation.

Step 4 — Review the trace

In Policy Trace, expect policy_matched, condition_eval steps with TRUE/FALSE, and final_decision. For DENY, the trace highlights the failing condition and values.

Step 5 — Test History tab

Open the Test History tab for past runs (full width, not a side panel).

  • Detail view uses GET /v1/pis/simulations/{simulation_id}.
  • Export JSON, CSV, or PDF from the detail actions.

After a successful run on Basic Testing, revisit Test History if the list did not refresh automatically.

Access rules (main build):

  • Regular users see and export only their own runs.
  • Admins (admin, builtin_admin) can see and export any run on a control they can access.
  • Exporting another user’s run returns 403 Forbidden.

Persistence: Successful runs should return a non-null simulation_id when audit persistence succeeds. If you see simulation_id: null, check Control Plane logs for PIS/audit persistence — history and re-open need that id.

Step 6 — Advanced Features tab

  • Policy comparison: Pick Policy A and Policy B, then Compare. Both runs use the same attribute payload as the Basic builder. Compare can run without a prior Basic result; if the payload is empty or invalid, the button stays disabled with a hint.
  • Suggested test cases and bulk tools appear when a primary control is selected.

If a compared control has a syntax error, the error shows inline.

Troubleshooting: If Compare never enables, complete the payload on Basic Testing or confirm simulator access if your tenant gates it by license.

Saving and reusing test scenarios

You can save a configured input payload as a named scenario and reload it later.

  • Fill in the input, then click Save as Scenario and give it a descriptive name.
  • Load a saved scenario from the Load Saved Scenario dropdown on any subsequent run.
  • Scenarios are per-user in the main build. Share one with a teammate by exporting a run that used it.

Saved scenarios live in the test_scenarios table and are managed via /v1/pis/scenarios.

Pre-promotion checklist

Before you promote a control from sandbox to production:

  • Run at least one should-allow input and confirm the decision and reason are correct.
  • Run at least one should-deny input and confirm the failing condition in the trace is the one you expect.
  • If the control references PIP-populated attributes, confirm the field names in your input match the production PIP shape.
  • Export the simulation runs that document the above and attach them to the change request.

The simulator is the single source of truth for "what would this control do with this input"; it is not a substitute for shadow mode, staged rollout, or traffic replay. Those are separate tools.

Troubleshooting

Test History is empty after a run

  • Confirm the API response included a simulation_id. If it was null, history cannot list that run; check Control Plane / PIS logs and permissions.
  • Non-admin users only see their own simulations; admins see broader rows per the access rules above.

"No controls available for testing"

  • Check the environment filter (Sandbox vs Production).
  • Confirm the control is saved and you have permission to view it.

"Failed to extract attributes"

  • The Rego code has a parse error; open the control in the builder and validate it.
  • OPA is bundled with control-plane-api. If extraction still fails, check the API pod / container logs.

Decision is NO_MATCH or undefined

  • The control's conditions did not match the input. The enforcement engine treats this as an implicit deny.
  • Confirm input field paths exactly match the control's references (for example, input.subject.department).
  • Add a print() statement in the Rego editor to trace evaluation.

"Simulation timed out"

  • Complex controls may take longer. Individual simulations are capped at 30s in the API layer.
  • Review the control for expensive operations or accidental loops.