Security Boundaries for Reconciliation › PCI-DSS Audit Trail Format for Reconciliation

# PCI-DSS Audit Trail Format for Reconciliation

This page answers a precise compliance question: when a reconciliation pipeline touches cardholder data, what does its audit trail have to record, and how do you make that trail tamper-evident? It sits under the security boundaries for reconciliation reference and turns the PCI-DSS logging requirements into a concrete record format — the mandatory fields per event, a hash chain that makes any later alteration detectable, and the masking rules that keep a primary account number out of the log itself.

# Problem Framing

Your reconciler compares a payments dataset across two engines, and PCI-DSS requires that every access to cardholder data and every action on it be logged with enough detail to reconstruct who did what, when, and to which record. Two mistakes are common. The first is logging too little — a verdict with no actor, no timestamp source, no record identity — so the trail cannot answer an assessor’s questions. The second is logging too much — a full primary account number in a discrepancy record — turning the audit log itself into a cardholder-data store that must be protected and scoped. The correct format records the mandated event fields, identifies the affected record by a masked or truncated form, and chains each entry to its predecessor so tampering is provable.

# Implementation

Each audit event carries the PCI-mandated fields, masks any account number to first-six/last-four, and links to the previous entry by hash so the trail is an append-only chain whose integrity can be verified end to end.

import hashlib
import json
import logging
import re
from dataclasses import dataclass, asdict
from typing import List, Optional

logging.basicConfig(
    format="%(asctime)s | %(levelname)s | %(name)s | %(message)s", level=logging.INFO
)
logger = logging.getLogger("recon.security.pci")

_PAN = re.compile(r"\b(\d{6})\d{2,9}(\d{4})\b")


def mask_pan(text: str) -> str:
    """Truncate any primary account number to first-six / last-four, per PCI-DSS."""
    return _PAN.sub(lambda m: f"{m.group(1)}******{m.group(2)}", text)


@dataclass(frozen=True)
class AuditEvent:
    event_time_utc: str            # trusted UTC source, not local wall clock
    actor: str                     # service or user identity
    action: str                    # "reconcile", "access", "remediate"
    record_ref: str                # masked/truncated identity of the affected record
    outcome: str                   # "match", "diverged", "quarantined"
    prev_hash: str                 # hash of the previous event -> the chain link

    def entry_hash(self) -> str:
        payload = json.dumps(asdict(self), sort_keys=True, separators=(",", ":"))
        return hashlib.sha256(payload.encode("utf-8")).hexdigest()


def append_event(chain: List[dict], event: AuditEvent) -> List[dict]:
    """Append a hash-chained, PAN-masked audit entry to an append-only trail."""
    safe = AuditEvent(**{**asdict(event), "record_ref": mask_pan(event.record_ref)})
    entry = {**asdict(safe), "entry_hash": safe.entry_hash()}
    chain.append(entry)
    return chain


def verify_chain(chain: List[dict]) -> bool:
    """Recompute each link; any break proves tampering or loss."""
    prev = "0" * 64
    for entry in chain:
        fields = {k: entry[k] for k in entry if k != "entry_hash"}
        if fields["prev_hash"] != prev:
            logger.error("chain break at %s: prev_hash mismatch", fields["event_time_utc"])
            return False
        recomputed = AuditEvent(**fields).entry_hash()
        if recomputed != entry["entry_hash"]:
            logger.error("tampered entry at %s", fields["event_time_utc"])
            return False
        prev = entry["entry_hash"]
    return True

# Audit Record Requirement Coverage

Each required field answers a specific assessor question; the chain and masking address integrity and scope.

# Key Implementation Notes

• Mask the PAN before it enters the log, not after. Truncating to first-six/last-four at write time keeps a full account number out of the audit store entirely, so the log never becomes in-scope cardholder data that must itself be vaulted.
• Chain every entry to its predecessor. Hashing each record with the previous record’s hash makes the trail append-only in effect: any deletion or edit breaks the chain and is detectable by re-verification, which is what “tamper-evident” requires.
• Timestamp from a trusted, synchronised source. A local wall clock can be skewed or set back; use a synchronised UTC source so the ordering and timing of events are defensible, and record it in a fixed format.
• The trail is a first-class output, not a log side effect. Treat audit generation as part of the reconciliation contract — every verdict from delta manifest generation and every remediation emits an event — so completeness is guaranteed by construction, not by hoping the logger was called.

# Verification

Assert PAN masking, chain integrity, and detection of a tampered entry.

chain: List[dict] = []
prev = "0" * 64
for action, ref, outcome in [
    ("access", "card 411111111111 1111", "match"),
    ("reconcile", "card 555500001111 2222", "diverged"),
]:
    ev = AuditEvent("2026-07-18T00:00:00Z", "recon-svc", action, ref, outcome, prev)
    chain = append_event(chain, ev)
    prev = chain[-1]["entry_hash"]

assert "411111******1111" in chain[0]["record_ref"]      # PAN masked
assert verify_chain(chain)                                # intact chain verifies
chain[0]["outcome"] = "match_TAMPERED"                     # mutate a recorded entry
assert not verify_chain(chain)                             # tampering detected
logger.info("pci-dss audit trail verified")

# Operational Considerations

Write the audit chain to append-only, access-controlled storage separate from the operational reconciliation data, and replicate it so a single-host loss cannot erase the trail. Run verify_chain on a schedule and on every export so a break is detected promptly rather than at assessment time, and alert on any verification failure as a security event. Retain the trail for the period your PCI-DSS scope requires, keep the masking regular expression under review so a new PAN format cannot slip through unmasked, and record the reconciler’s own version and config with each run so an assessor can tie a verdict to the exact pipeline that produced it. Because the audit trail is the evidence of compliance, treat its availability and integrity as seriously as the cardholder data it protects.

# Related

• Security boundaries for reconciliation — the parent reference whose audit mandate this formalises.
• GDPR pseudonymisation in reconciliation pipelines — the transform whose re-identification events this trail logs.
• Delta manifest generation — the verdict source each audit event records.
• Discrepancy routing and remediation — the remediation actions that must appear in the trail.