What is a Policy Diff?

Security policies should never change without review. A single-character change in a policy document can be the difference between blocking and allowing access to a sensitive tool. A modified regex pattern might broaden or narrow the scope of a rule in ways that aren't obvious from reading the new version alone. The diff — the precise delta between the old and new versions — is what reviewers need to evaluate the impact of a change.

Policy diffs serve multiple purposes. During code review, they let reviewers focus on what changed rather than re-reading the entire policy document. During incident investigation, they help determine whether a recent policy change caused the issue. During compliance audits, they provide evidence of what changed, when, and who approved it.

Because policies for AI agent enforcement are declarative JSON documents, diffs are particularly readable. A reviewer can see that a tool's entry moved from allow to deny, or that a condition was modified to include an additional argument check. This readability means reviewers can evaluate the exact document rather than inferring a change's effect from its description.

PolicyLayer policies are single JSON documents attached to grants, and the dashboard's Raw JSON view exposes the exact document — so standard diff tooling applies. Teams that keep exported policy JSON in version control get pull request workflows on GitHub, GitLab, or Bitbucket displaying policy diffs for review, and can add custom CI checks that annotate diffs with the impact of changes — for example, highlighting when a tool has moved from deny to allow or a condition has been broadened. Because the document is small and declarative, policy diffs are accessible to security reviewers who may not be software engineers.