Skip to main content

Decision logs and replay

Objective​

Explain what Writ decision logs capture and how replay lets you re-run recorded requests against a candidate policy before you promote it.

Concept​

Promotion gets a policy to prod. Decision logs and replay are how you know it is behaving, and how you change it safely.

Decision logs​

Every decision a governed PDP makes can be recorded as a decision log entry: the input that was evaluated, the decision that was returned, the bundle (and commit_sha) that produced it, and where in the entity hierarchy it happened. Writ is the Audit half of Define, Enforce, Audit. It collects these logs so that any allow or deny in production is explainable after the fact: not "we think the policy would deny that" but "here is the exact decision, on this input, from this signed bundle."

Enterprise OPA adds decision_logs.mask, which lets you mask sensitive fields out of the logged input before it is stored, so an audit trail does not become a data-leak of the very records it is protecting.

Replay​

Replay is what makes decision logs more than a receipt. Because a decision log entry stores the exact input, Writ can take a body of recorded requests and re-run them against a candidate policy, the new bundle you are about to promote, and show you where the new policy would decide differently from the one in production.

This is a regression test against real traffic. Before promoting, you ask: does this candidate change any decision that mattered? If replay shows a batch of previously-allowed requests would now be denied, you found the blast radius before your users did. If it shows a previously-denied request would now be allowed, you check that the new allow is intended and not an accidental hole.

recorded requests (from decision logs)
        |
        v
  replay against candidate bundle
        |
        v
  diff: which decisions changed?  --> promote or fix

Text version: replay feeds recorded request inputs into a candidate bundle and reports which decisions changed versus production. You use that diff to decide whether to promote the candidate or fix it first.

Replay pairs naturally with promotion from the previous lesson: replay in dev or staging against production-recorded inputs, confirm the diff is intended, then promote the same signed bundle forward.

Hands-on lab​

You can feel what replay does with the local tools, even though Writ is what runs it against production logs at scale. The lab's policy_test.rego is a hand-written stand-in for a set of recorded decisions: each test is one input and its expected decision. Run it:

git clone https://github.com/EnforceAuth/university-labs.git
cd university-labs
opa test courses/govern-with-writ -v

Expected: PASS: 6/6.

Now simulate a candidate policy and a replay. In ../lab/policy.rego, temporarily change the viewer rule to also allow write (add write to the viewer's permitted actions). Re-run opa test. The test test_viewer_cannot_write_own_org now fails: that is exactly the signal replay gives you, a recorded decision that the candidate policy would flip from deny to allow. In production, replay would surface that same flip across real logged requests, and you would decide whether it is intended. Revert your change and confirm the suite returns to PASS: 6/6 before moving on.

Check for understanding​

  1. Name three things a Writ decision log entry captures, and state which verb of Define, Enforce, Audit this feature serves.
  2. What does replay do that a plain decision log does not, and why is that useful specifically before a promotion?
  3. Enterprise OPA's decision_logs.mask exists so that decision logs do not become what kind of problem? Answer in one sentence.