Policy Versions
A policy decides what an agent may do, so a change to it is a change to what has been approved. MITRITY records every save of a policy as a version: the whole document as the API serves it, who saved it, and what changed. Versions are never edited or deleted while the policy exists. Restoring an earlier version creates a new one, so the history always reads forward.
What a version records
A version is written by every operation that changes the policy document:
| Operation | Recorded as |
|---|---|
| Creating a policy | created (version 1) |
| Updating the policy's fields | updated |
| Adding, editing or removing a rule | rule_created, rule_updated, rule_deleted |
| Restoring an earlier version | restored |
Each version stores a snapshot — the policy's fields and its rules, ordered by priority — and a change summary: the fields whose value differs from the previous version, and how many rules were added, removed or changed. A save that changed nothing still records a version with an empty summary, because the history is a record of saves, not only of differences.
Policies that existed before versioning was introduced start their history at version 1, recorded from their state at the time.
Two things that shape an agent's behavior are separate resources and are not part of a policy version: DLP pattern bindings, which have their own history, and which agents are bound to the policy.
Version numbers
Version numbers start at 1 and increase by one per save; they are never reused. The policy's newest version is its current version — shown on the policy page and carried to the edge in the agent's mission profile as policy_version, so an edge always knows which version of the document it is enforcing.
Reading the history
Open a policy and scroll to Version history. The list shows every version, newest first, with what produced it, what changed, who saved it and when. View changes opens one version and shows, field by field, the value before and after, plus the rules that were added, removed or changed since the previous version. The first version has nothing earlier to compare with and says so.
The same history is available from the API:
GET /api/v1/policies/{policy_id}/versions
GET /api/v1/policies/{policy_id}/versions/{version}
The list returns each version's change summary; a single version returns its full snapshot and the diff against the version before it.
Restoring a version
Managers and owners can restore any earlier version. A restore makes the policy's current fields and rules equal to that version's snapshot and records the result as a new version — for example, restoring version 2 on a policy at version 5 produces version 6. Nothing in the history is rewritten: versions 2 through 5 stay exactly as they were, and the new version names the one it came from.
Before anything is written, the restored document is checked by the same validation a normal save runs. A version whose contents no longer pass — a tool pattern written before the pattern grammar was tightened, for example — is refused with a message naming the field, and the policy is left unchanged. If the restored document turns on a plan-gated feature such as DLP, the plan gate applies as it would to a normal save.
Rules keep their identity across a restore, so the next diff shows a rule as changed rather than as removed and added again. Agents bound to the policy receive the restored configuration on their next heartbeat.
POST /api/v1/policies/{policy_id}/versions/{version}/restore
Every restore is recorded in the audit trail as policy.restored, with the version restored from and the version it produced. Policy creates, updates and rule changes carry their version number on their audit rows too.
Approved versus running
A governance review that approves or attests an agent records the policy version in force at that moment as the approval of record. The edge reports, on every heartbeat, which policy version it is enforcing for each agent it serves. The agent page shows both side by side — approved v3 · running v4 — together with the version the control plane is serving now.
A missing approval or a missing report is shown as exactly that. Neither is ever presented as a match: an agent nobody has approved, or one whose edge has not reported yet, has no drift to show and no approval to lean on.
When the running version is not the approved one — because the policy was saved after the approval, or the agent was moved to another policy — the badge turns red, the agent gets a policy_drift_unapproved finding, and a change review opens so someone can decide. Approving that review makes the running configuration the approved one; restoring the approved version from the policy's history closes the finding on the next heartbeat instead. The agent page links the badge straight to the open review.