Immutable Audit Trail and WORM Retention

A DVIR pipeline is only as defensible as the record it can produce two years after the inspection happened. When a DOT auditor opens a compliance review, the carrier must show that every Driver Vehicle Inspection Report documenting a defect was preserved, unaltered, for the full retention window that 49 CFR § 396.11©(2)(iii) and § 396.3© require — and that nothing in the storage path could have quietly rewritten it. A database row that anyone with credentials can UPDATE does not clear that bar. This guide, part of the Core DVIR Architecture & FMCSA Compliance Mapping pipeline, specifies the storage and recordkeeping layer that makes a DVIR record tamper-evident from the moment it is accepted and keeps it that way through a Write-Once-Read-Many (WORM) retention period the carrier cannot shorten by accident.

Two mechanisms carry the weight. First, an append-only event log where each entry carries the SHA-256 hash of the entry before it (prev_hash), so any deletion, reorder, or in-place edit is detectable by re-walking the chain — the tamper-evidence property. Second, WORM object storage — S3 Object Lock in compliance mode — that physically refuses to overwrite or delete an object until a computed retain-until date has passed — the immutability property. The record that clears the validation gate in JSON Schema Validation for Electronic DVIRs is hashed, chained, and sealed here, and the role-boundary controls in Compliance Boundary Enforcement in Cloud Workflows decide who may read it during an audit. This section anchors two focused guides: WORM Retention and SHA-256 Hashing for DVIR Records and Audit Logging and Tamper-Evident Event Chains.

The recordkeeping layer is deliberately boring: it does no scoring, no routing, and no repair-state decisions. It receives an already-validated, already-scored DVIR record and its job is to seal it so nobody — not an operator, not a rogue script, not a later bug — can alter it inside the retention window. Target Python 3.10+ (the code below uses X | Y unions and match statements) with:

• boto3 1.34+ — the S3 client, including put_object with ObjectLockMode, ObjectLockRetainUntilDate, and put_object_legal_hold.
• hashlib and json (stdlib) — SHA-256 digests over a canonical JSON serialization; correctness depends far more on the canonicalization than on the hash primitive.
• Pydantic 2.x — immutable (frozen=True) models for the sealed event and the chain entry, so an in-memory object cannot drift from what was hashed.
• A monotonic, authoritative clock — retain-until dates are legal deadlines; compute them from a trusted server clock or a time-authority service, never from a device-supplied inspection_ts.
• An out-of-band head-hash register — a small, separately-secured store (a locked DynamoDB item, an HSM-backed value) holding the current chain head, so an attacker who compromises the log store still cannot forge a consistent chain.

The bucket itself must be created with Object Lock enabled at creation time — it cannot be switched on for an existing bucket — and versioning is a hard prerequisite for Object Lock. Provision it once with compliance mode as the default and treat any bucket without Object Lock as unfit to hold a defect DVIR.

Two records define this layer: the sealed DVIR event that goes into WORM storage, and the chain entry that records its place in the tamper-evident log. Field names and the SHA-256 audit_hash convention are held identical to the rest of the pipeline so a single inspection can be reconstructed end to end. The audit_hash is always the SHA-256 digest of the record’s canonical JSON, and prev_hash is the audit_hash of the immediately preceding chain entry.

Any DVIR that documents a defect carries the 3-month retention floor. A record with no defects has a shorter statutory obligation, but most carriers apply the same retention to every DVIR as a policy override rather than branch storage logic on defect presence. Encode the sealed event as an immutable Pydantic model so the object that gets hashed is exactly the object that gets stored:

from datetime import datetime
from typing import Literal

from pydantic import BaseModel


class SealedDVIREvent(BaseModel):
    model_config = {"frozen": True}  # what we hash is what we store

    record_id: str
    inspection_ts: datetime            # device event time
    sealed_at: datetime                # authoritative server clock
    defect_category: str
    severity_score: int                # 0-100, bands 0-34 / 35-69 / 70-100
    compliance_guardrail: Literal["OOS", "conditional", "monitor_only"]
    version: int


class ChainEntry(BaseModel):
    model_config = {"frozen": True}

    seq: int
    audit_hash: str        # SHA-256 over canonical JSON of the SealedDVIREvent
    prev_hash: str         # audit_hash of entry seq-1, or the genesis constant
    retain_until: datetime

Sealing a record is a fixed sequence. Run it as one ordered, single-writer transaction per chain so a failed step aborts the append rather than leaving a half-linked entry. The single-writer discipline is what makes prev_hash unambiguous.

1. Canonicalize the record. Serialize the SealedDVIREvent to JSON with sorted keys, no insignificant whitespace, and ensure_ascii=False so unicode is represented consistently. Two logically-equal records must produce byte-identical JSON — otherwise their audit_hash values diverge and integrity checks fail on read.
2. Compute the digest. Take the SHA-256 of the canonical bytes; this is the record’s audit_hash. Store it alongside the object as metadata and inside the chain entry.
3. Read the head and link. Read the current head hash from the out-of-band register, set prev_hash to it, set seq to the last sequence plus one, and compute the entry.
4. Compute retain-until — from a trusted clock. Set retain_until to sealed_at plus the greater of the statutory 3-month minimum and any carrier-policy retention. Round up, never down; a retain-until short of the statutory window is a recordkeeping violation waiting to be found.
5. Write to WORM with the lock applied atomically. put_object with ObjectLockMode="COMPLIANCE" and ObjectLockRetainUntilDate=retain_until in the same call that writes the body, so there is never a window where the object exists unlocked.
6. Advance the head. Only after the WORM write succeeds, update the head register to this entry’s audit_hash. If the write failed, the head is untouched and the append is a no-op.

The canonicalization and digest are the load-bearing steps; get them stable and the rest follows.

import hashlib
import json


GENESIS = "0" * 64


def canonical_json(event: SealedDVIREvent) -> bytes:
    """Deterministic bytes: sorted keys, compact, unicode preserved.
    Two logically-equal records MUST serialize identically."""
    payload = json.loads(event.model_dump_json())
    return json.dumps(
        payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False
    ).encode("utf-8")


def audit_hash(event: SealedDVIREvent) -> str:
    return hashlib.sha256(canonical_json(event)).hexdigest()


def build_entry(event: SealedDVIREvent, seq: int, head: str,
                retain_until: datetime) -> ChainEntry:
    return ChainEntry(
        seq=seq,
        audit_hash=audit_hash(event),
        prev_hash=head or GENESIS,
        retain_until=retain_until,
    )

import boto3

s3 = boto3.client("s3")


def seal_to_worm(bucket: str, event: SealedDVIREvent,
                 entry: ChainEntry) -> None:
    """Write once, lock in the same call. COMPLIANCE mode blocks even
    the root account from deleting before retain_until (49 CFR 396.3(c))."""
    s3.put_object(
        Bucket=bucket,
        Key=f"dvir/{event.record_id}.json",
        Body=canonical_json(event),
        ObjectLockMode="COMPLIANCE",
        ObjectLockRetainUntilDate=entry.retain_until,
        Metadata={
            "audit-hash": entry.audit_hash,
            "prev-hash": entry.prev_hash,
            "seq": str(entry.seq),
        },
    )

The retention window is set by what the record documents, and the storage layer must encode the obligation rather than trust a human to remember it:

• DVIR documenting one or more defects: retain a minimum of 3 months from the date of preparation, per § 396.11©(2)(iii) and § 396.3©. Compute retain_until as sealed_at + 3 months at the floor, and apply any longer carrier-policy retention on top. This is the common case for any report that reaches the audit trail.
• Carrier-policy override: many carriers retain all DVIRs — and their supporting repair certifications — for a year or more to align with insurance and litigation-hold practice. Encode the override as a per-record maximum of the statutory floor and the policy value, so policy can only extend the window, never shorten it below the federal minimum.
• Legal hold: when litigation or an active DOT investigation attaches, apply an S3 Object Lock legal hold in addition to the retention date. A legal hold has no expiry and blocks deletion until explicitly released by an authorized custodian, independent of retain_until.

The severity bands are the same everywhere in this section — 0–34 minor, 35–69 major, 70–100 critical — and the retention layer does not re-interpret them; a defect tagged DOT_OOS_CRITERIA keeps its immovable critical floor of 70 as it was scored upstream by the Severity Scoring Algorithms for DVIR Defects engine. What the retention layer adds is the guarantee that the OOS decision and its supporting DVIR are still byte-for-byte retrievable when an auditor asks why a vehicle was, or was not, held out of service. The repair-certification records that close out those defects under Certifying Repairs Under 396.11©(2) are sealed into the same chain, so the reported-to-repaired lifecycle is one continuous, verifiable record.

The audit trail sits at the end of the ingestion path and must not lose a record or admit a duplicate. Treat each seal as an idempotent, chained event:

• Idempotent seal. Key the seal on record_id. A retried seal of an already-sealed record is a no-op — read back the stored object and confirm its audit_hash matches rather than writing a second, differently-timestamped copy.
• Single-writer append. Serialize appends per chain (a partition key, a lock, or a single consumer) so prev_hash and seq are never assigned concurrently by two writers. Concurrent appends are the most common source of a forked chain.
• Cross-system fan-out. After a successful seal, emit an immutable notification to downstream consumers — the CMMS work-order sync in Mapping DVIR Defects to CMMS Work Orders and any telematics platform — carrying the record_id and audit_hash, never the mutable body. Downstream systems reference the sealed record; they do not become a second source of truth.
• Encrypted at rest and in transit. WORM protects against overwrite, not against disclosure. Store the sealed objects under the envelope-encryption and TLS controls described in Encrypting DVIR Data at Rest and in Transit, and note that you encrypt the canonical bytes before you hash-and-store, then hash the plaintext canonical form so the digest is stable across a key rotation.
• Read-only audit export. Grant auditors a role that can GetObject and re-run chain verification but holds no PutObject, DeleteObject, or lock-modification permission, per the role model in Implementing Role-Based Access for DVIR Data.

• Object Lock at bucket creation — enable Object Lock and versioning when the bucket is created; a bucket without them cannot hold a defect DVIR.
• Compliance mode, not governance — use COMPLIANCE retention so no principal, including root, can delete before retain_until.
• Canonical-JSON hashing — sorted keys, compact separators, explicit unicode handling; two equal records must hash identically.
• Trusted clock for retain-until — compute retention from an authoritative server clock, never from a device-supplied timestamp, and always round the window up.
• Out-of-band head hash — store the chain head separately from the log so a store compromise cannot forge a consistent chain.
• Single-writer appends — serialize per chain so prev_hash and seq are unambiguous.
• Idempotent seals — key on record_id; a retry re-reads and verifies instead of writing a duplicate.
• Read-only audit role — auditors retrieve and verify; they never hold a mutation permission.

• WORM Retention and SHA-256 Hashing for DVIR Records — the boto3 implementation of the sealing and hashing steps described here.
• Audit Logging and Tamper-Evident Event Chains — verifying the whole hash chain and what an auditor checks.
• Compliance Boundary Enforcement in Cloud Workflows — the role and encryption boundary the audit store sits behind.
• JSON Schema Validation for Electronic DVIRs — the gate a record clears before it is sealed here.
• Certifying Repairs Under 396.11©(2) — the repair-certification records sealed into the same chain.

Back to Core DVIR Architecture & FMCSA Compliance Mapping.