Audit Logging and Non-Repudiation — Tamper-Evident File Transfer Audit Log

Audit Logging and Non-Repudiation

Xferity maintains a structured audit log that records every significant system event. The audit log is separate from the application log — it is designed for compliance, incident investigation, and non-repudiation.

Enabling audit logging

audit:
  enabled: true
  path: /var/log/xferity/audit.jsonl
  retention_days: 365           # prune events older than 365 days
  strict_redaction: false        # see redaction section
  tamper_evidence_enabled: true  # SHA-256 hash chain
  query_index_enabled: true      # fast query index sidecar

What is recorded

Every audit event contains:

Field	Description
`timestamp`	UTC timestamp with nanosecond precision
`level`	Event severity (info, warn, error)
`flow_name`	Name of the flow that triggered the event
`run_id`	Unique identifier for this flow execution
`correlation_id`	Correlation ID for linking related events
`event_type`	Category of event (see event types below)
`file`	Filename being operated on
`remote_path`	Remote path on SFTP/FTPS/S3/AS2
`local_path`	Local path on the filesystem
`idempotency_key`	SHA-256 hash used for deduplication
`outcome`	`success`, `failure`, or `skipped`
`error_code`	Machine-readable error code on failure
`error_message`	Redacted error description
`metadata`	Additional context key-value pairs

Event types

Xferity emits events for the following operations:

flow_start — a flow execution begins
flow_complete — a flow execution completes successfully
flow_failed — a flow execution fails after all retries
file_download — a file is downloaded from a remote source
file_upload — a file is uploaded to a remote destination
file_encrypt — a file is PGP encrypted
file_decrypt — a file is PGP decrypted
file_sign — a file is PGP signed
file_verify — a PGP signature is verified
file_delete — a file is deleted (local or remote)
file_skipped — a file is skipped due to idempotency
as2_receive — an inbound AS2 message is received
as2_send — an outbound AS2 message is sent
as2_mdn — an AS2 MDN is sent or received
auth_login — a user authenticates (success or failure)
auth_logout — a user session ends

Tamper-evident hash chain

When tamper_evidence_enabled: true, each audit event is linked to the previous event using a SHA-256 hash chain.

Every event receives three additional fields:

Field	Description
`chain_seq`	Monotonically incrementing sequence number (starts at 1)
`prev_hash`	SHA-256 hash of the previous event (empty for the first event)
`event_hash`	SHA-256 hash of this event’s canonical JSON + `prev_hash`

This creates a cryptographic chain: modifying, inserting, or deleting any audit event breaks the chain and is detectable.

How the chain is computed

event_hash = SHA-256(prev_hash + "|" + canonical_event_json)

Where canonical_event_json is the full event JSON with the event_hash field set to an empty string before hashing.

Verifying the hash chain

Because the audit log is a plain JSONL file, the hash chain can be verified independently using any JSON processing tool. No proprietary tooling is required.

Verification checks:

Every event has a chain_seq field
Sequence numbers are consecutive (no gaps)
Each prev_hash matches the event_hash of the preceding event
Each event_hash matches the recomputed hash

Manual verification

# Check that chain_seq values are consecutive
jq '.chain_seq' /var/log/xferity/audit.jsonl | awk 'NR>1 && $1!=prev+1{print "BREAK at seq ",$1}{prev=$1}'

You can also recompute event hashes from the stored canonical JSON to confirm no event was altered.

Audit log format

The audit log is JSONL (one JSON object per line). Example:

{"timestamp":"2026-03-16T22:00:01.234567Z","level":"info","flow_name":"payroll-upload","run_id":"run-abc123","correlation_id":"corr-xyz789","event_type":"file_upload","file":"payroll-2026-03.xml","remote_path":"/outgoing/payroll/payroll-2026-03.xml.pgp","outcome":"success","idempotency_key":"sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","chain_seq":42,"prev_hash":"a1b2c3...","event_hash":"d4e5f6..."}

Redaction

Sensitive values are automatically redacted from audit events. Fields containing keywords such as password, passphrase, private_key, token, secret, api_key are replaced with [REDACTED] before writing.

Strict redaction mode

When strict_redaction: true, additional patterns are redacted:

Email addresses
Bearer tokens and JWT patterns
File paths (Unix and Windows)
PEM private key blocks
API key patterns
Passphrase fields

Use strict redaction in regulated environments where even metadata must be protected.

audit:
  strict_redaction: true

Audit query index

When query_index_enabled: true (default), Xferity maintains a sidecar index file (audit.jsonl.idx.jsonl) that enables fast queries without scanning the full audit log.

Query by flow, event type, file name, outcome, or time range:

# Query audit for a specific flow
xferity trace --flow payroll-upload

# Query for a specific file
xferity trace --file payroll-2026-03.xml

# Query for failures in the last 24 hours
xferity trace --outcome failure --since 24h

Retention

Xferity automatically prunes audit events older than retention_days:

audit:
  retention_days: 365

Retention runs at startup and periodically during execution. When retention runs:

Events older than the cutoff are removed
The chain state is reset (the chain restarts after pruning)
Malformed lines are preserved to prevent accidental data loss

Set retention_days: 0 or omit to keep all events indefinitely.

On-disk structure

Given audit.path: /var/log/xferity/audit.jsonl, Xferity creates:

File	Description
`audit.jsonl`	Main audit log (one JSON event per line)
`audit.jsonl.chain.state`	Current chain head (seq + hash for continuity across restarts)
`audit.jsonl.idx.jsonl`	Query index sidecar (when `query_index_enabled: true`)

Back up all three files together. The .chain.state file is required for chain continuity after restart.

Compliance-relevant characteristics

The audit log structure provides characteristics relevant to regulated environments:

Transfer record completeness: every file movement, encryption, decryption, and authentication event is recorded with timestamp and outcome
Tamper evidence: the SHA-256 hash chain detects modification, deletion, or insertion of events
Redaction controls: sensitive field values are excluded from the log; strict redaction mode is available for environments with stricter metadata requirements
Retention controls: configurable retention period with automatic pruning

Organizations working toward SOX, HIPAA, or PCI-DSS requirements typically need a complete file transfer audit record. Xferity provides that record. Whether the audit log satisfies specific regulatory requirements depends on your overall compliance architecture, not on a single component.