Policy Versions
Policy versions let you see every change to a policy, compare versions and restore an earlier one. A policy decides what an agent may do, so a change to the policy is a change to what has been approved.
MITRITY records every save of a policy as a version. Each version holds:
- the whole document, as the API serves it;
- who saved it;
- 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;
- 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. 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;
- which agents are bound to the policy.
Version numbers
Version numbers start at 1 and increase by one with each save. They are never reused.
The policy's newest version is its current version. It is shown on the policy page, and carried to the edge (the MITRITY runtime beside your agents) 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. It shows the value before and after, field by field, and 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 goes through the same validation as a normal save. A version whose contents no longer pass is refused with a message naming the field, and the policy is left unchanged. A tool pattern written before the pattern grammar was tightened is one example. 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, not 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
When a governance review approves or attests an agent, it records the policy version in force at that moment as the approval of record. On every heartbeat, the edge reports which policy version it is enforcing for each agent it serves. The agent page shows both side by side, as in 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, and never as a match. An agent that nobody has approved, or one whose edge has not reported yet, has no drift to show and no approval to lean on.
The running version can differ from the approved one, because the policy was saved after the approval or because the agent was moved to another policy. When it does:
- the badge turns red;
- the agent gets a
policy_drift_unapprovedfinding; - a change review opens, so someone can decide.
There are two ways to resolve it:
- approve the review, which makes the running configuration the approved one;
- restore the approved version from the policy's history, which closes the finding on the next heartbeat instead.
The agent page links the badge straight to the open review.