Agent Governance ToolkitAgent Governance Toolkit 4.1.0 · Python 3.10+
Dashboard
0%

Proving the audit log's integrity

verify_integrity walks the flight recorder's hash chain and reports whether every row still matches its stored hash, so an edit made outside the toolkit is caught.

Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0

The flight recorder lesson chained each row to the one before. This lesson uses that chain: it edits a row the way an attacker with database access would, and watches the check fail.

Checking a clean log

On a log nobody has touched, verify_integrity returns valid true and the number of entries it checked.

ExampleA clean log verifies
result = recorder.verify_integrity()
print("valid:", result["valid"])
print("entries checked:", result["total_entries"])

Editing a row by hand

An attacker who reaches the database file can change a stored result with plain SQL, without going through the toolkit. This edits the first row's result and closes the recorder so the change is on disk.

python
recorder.close()

# change a stored result directly in sqlite, bypassing the toolkit
con = sqlite3.connect(db)
con.execute("UPDATE audit_log SET result='EDITED' WHERE id=1")
con.commit()
con.close()

Catching the edit

Reopening the recorder and verifying again shows the chain no longer matches. The check names which entry was tampered and why.

ExampleThe hash chain catches the edit
tampered = FlightRecorder(db_path=db, enable_batching=False)
result = tampered.verify_integrity()

# the edited content no longer matches its stored hash
print("valid:", result["valid"])
print("first tampered id:", result["first_tampered_id"])
print("reason:", result["error"])

What the check proves and what it does not

  • It proves no row was changed in place after it was written, because the content no longer matches its hash.
  • It names the first broken entry, so you know where the log stops being trustworthy.
  • It does not stop the edit, it detects it. Keeping the file somewhere an attacker cannot reach is still your job.

Detection vs prevention

The hash chainFile permissions
RoleDetects an edit after the factStops the edit
CatchesA changed or removed rowAn unauthorised writer
You still needTo store the file safelyThe chain, to catch what slips through

Where you use integrity checks

  • Before trusting a log in an investigation, to confirm it was not edited after the incident.
  • A scheduled job that verifies the log and alerts if the chain breaks.
  • A handover, proving to an auditor that the record is intact.
Watch out. The check detects tampering; it does not prevent it. An attacker who can rewrite the whole chain from a point could hide a change. Protect the file, and verify it somewhere the attacker does not control.
Try it yourself
  • Edit a different column, such as tool_name, and confirm the check still catches it.
  • Delete a row instead of editing one and read what verify_integrity reports.
  • Verify a clean log, then re-verify after one edit, and compare the two result dictionaries.

You understood something today that you didn't yesterday.