Policy change control

EgisAI’s policies are the runtime control plane for your AI agents — and because that control plane is mutable, change management on the policies themselves is a compliance concern. This page documents the current capability: who can edit, what’s logged, how the SDK picks up changes, and how you’d hand the resulting audit trail to a SOC 2 auditor.

​

Roles and permissions

Policy management is gated by workspace role. EgisAI uses four built-in roles: The manage_policies permission resolves to Owner + Admin. Every state-changing endpoint on policies requires this permission; reads require workspace membership. Role assignments are managed from the Team page on the dashboard and are themselves audit-logged whenever they change (user.role_changed). For Enterprise customers running SAML / OIDC SSO, the workspace role is the per-user role inside EgisAI. Group-based role provisioning via the SSO provider’s group claims is on the near-term roadmap.

​

What’s recorded on every change

Every create, update, toggle, and delete of a policy writes an operator-action audit row to the audit_log_entries table. The row is append-only and carries: A dedicated policy.toggle action is emitted when a state change is a pure enable / disable flip (priority, config, name, targets all unchanged). This lets a reviewer separate one-click on/off flips from substantive content edits.

​

How the dashboard surfaces this

The Audit log page shows the operator-action stream live, with filters for action category, actor, resource type, and date range. Every row is clickable; the detail drawer shows the captured metadata_json so a reviewer can see what changed without leaving the page. Operators with manage_policies permission can also restrict their view to policy-touching actions only by filtering by resource_type = "policy".

​

How changes reach your processes

Policies are not pushed; they are pulled by ETag. The SDK in your process holds a cached snapshot of the active policy set and re-polls the control plane periodically with an If-None-Match header carrying the cached ETag. When an operator commits a change on the dashboard, the control plane bumps the ETag and the next poll receives the new snapshot. In practice this means changes propagate to every running SDK process within seconds of an operator clicking Save, without any redeploy or SDK restart on your side. The propagation lag is what an operator should plan for when rolling out a tight new rule — there’s typically a few-second window where in-flight calls are still being evaluated against the previous snapshot.

​

Pausing an agent

Beyond editing a policy, an operator can flip an agent into a paused state from the dashboard’s Agents page. While paused, the SDK refuses every call attributed to that agent before any policy phase runs — no tokens are spent, no prompt text is hashed. The pause is delivered on the same ETag-aware refresh channel as policies, so it takes effect within seconds. Pausing and resuming are themselves audit-logged (agent.pause / agent.resume).

​

What’s in policies.csv at export time

The Audit-evidence export ZIP carries a policies.csv inventory snapshot of every policy in your workspace at the moment of export, including type, phase, priority, enabled state, and the full config_json. Joined against audit_log.csv (which records which user edited which policy, when), an auditor has a complete change-management evidence pack:

• Who is allowed to author policies? → users.csv (role) + the table above.
• When did each policy change, and to what? → audit_log.csv rows where resource_type = "policy".
• What was the policy set on day X? → policies.csv snapshot + the audit-log trail back to day X (the export’s window).
• What did each policy do to traffic? → request_logs.csv rows joined to matched_policy.

This is the change-management evidence pack a SOC 2 reviewer asks for under CC8.1 (change management) and ISO 27001 A.8.16 (information security event monitoring).

​

What’s on the near-term roadmap

We treat the items below as known gaps and are tracking them as product work, not as marketing claims. Specifically:

1. Policy version history with one-click restore. A policy_versions table that snapshots the full configuration on every change, with a “Restore this version” button on the policy detail drawer that creates a new version equivalent to the old payload. This makes “show me the prior version” a one-click operation instead of a manual reconstruction from the audit metadata.
2. Two-person approval flow. A tenant-flagged mode where a policy edit lands as draft, requires a second authorised user to approve, and is applied only after approval. Operators who don’t enable the flag retain today’s single-approver workflow.
3. Reviewer-only role. A role between Viewer and Admin that can flag anomalies and request reviews but cannot author policies.

Each of these is additive and back-compatible with today’s audit trail — no existing audit row will be re-interpreted. We’ll update this page when they ship.

​

Auditing checklist

When you hand this control set to an internal or external reviewer, the artefacts to deliver are:

1. Policy authoring scope. The list of users with the manage_policies permission (from users.csv, filtered to Owner + Admin).
2. Policy edit history. audit_log.csv filtered to resource_type = "policy" for the audit window.
3. Policy inventory at the close of the window. policies.csv.
4. Live verdict on traffic. request_logs.csv joined to matched_policy so the reviewer can confirm each policy actually fired on traffic — the “configured vs enforced” distinction the dashboard already shows.
5. Agent pause history. audit_log.csv filtered to action LIKE 'agent.%'.

Every artefact above is available without raising a support ticket — the export modal builds the archive on demand.

​

What’s next