Audit Logging — Tamper-Evident JSONL Records for Every File Transfer

Audit Logging

Xferity writes structured audit events so operators can trace what happened to a flow, run, or file without reconstructing history from multiple log sources.

In a self-hosted managed file transfer deployment, audit logging is a primary source of transfer traceability.

Purpose

The audit model supports:

transfer investigation
operator troubleshooting
run reconstruction
file lifecycle lookup
export into SIEM or external retention systems

Audit logging is one layer of a complete compliance picture. It works alongside change control, access control, backup policy, and external evidence retention.

Event format

Audit events are written as structured JSON records. Fields can include:

timestamp
level
flow name
run ID
correlation ID
event type
file name
local path
remote path
idempotency key
outcome
error code
metadata

When tamper evidence is enabled, records can also include:

chain_seq
prev_hash
event_hash

Write model

The audit writer appends one JSON event per line. This append-oriented model makes the file suitable for newline-delimited JSON processing and log shipping.

Query workflows

Operators typically use audit data to:

trace a file lifecycle
inspect run-level activity

Xferity supports:

direct file queries against the JSON audit log
a sidecar index for faster file lookups
HTTP API lookup through GET /api/audit?file=<basename>

The query path sanitizes requested file names to a basename before lookup. It is intended for lifecycle tracing, not arbitrary file access.

Sidecar index

For larger audit files, Xferity can maintain a sidecar index of file-related offsets. This improves file lookup speed without replacing the primary audit JSONL file.

Tamper-evidence model

When enabled, Xferity adds hash-chain linkage between events. Xferity can also verify chain continuity and event hashes.

This should be described carefully:

it provides tamper evidence
it does not provide an external immutable trust anchor by itself
privileged access to the same host or storage boundary still matters

Redaction behavior

Before events are written, Xferity applies redaction logic to reduce accidental exposure of secrets in audit-visible records.

This includes:

redaction of secret-like metadata keys
redaction of sensitive values in metadata and errors
stricter pattern-based redaction when strict redaction is enabled

Audit logs can still contain operationally sensitive information such as file names, partner context, and paths. They should not be treated as unrestricted data.

Backend boundary

Audit logging is not the same thing as the state backend.

Even in Postgres-backed deployments, the append-oriented audit file remains part of the evidence model. Postgres can supplement investigation paths, but it does not replace the audit log file automatically.

Retention

Audit retention is configurable by days. When retention is enforced, older events are removed from the JSONL file. If tamper evidence is enabled, the chain state is reset to the retained dataset.