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.
result = recorder.verify_integrity()
print("valid:", result["valid"])
print("entries checked:", result["total_entries"])valid: True entries checked: 3
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.
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.
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"])valid: False first tampered id: 1 reason: Content hash mismatch at entry 1: field tampering detected
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 chain | File permissions | |
|---|---|---|
| Role | Detects an edit after the fact | Stops the edit |
| Catches | A changed or removed row | An unauthorised writer |
| You still need | To store the file safely | The 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.
Related
- Previous: Querying the audit log
- Next: The audit log as JSONL
- 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_integrityreports. - 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.