Audit Logging

Nefia records every command execution, file operation, and session event in an append-only audit log. Log entries are chained using SHA-256 hashes and signed with HMAC-SHA256, making any tampering detectable through verification.

What Gets Logged

Log Format

Audit logs are stored as JSONL (JSON Lines) files, date-partitioned with a new file per calendar day. The default directory follows the platform config path:

For example, 2026-02-24.jsonl within that directory. Each entry contains these fields:

Example Entry

{
  "seq": 142,
  "prev_hash": "a1b2c3d4e5f6...previous entry hash...",
  "hash": "f7e8d9c0b1a2...current entry hash...",
  "hash_version": 3,
  "hmac": "e3b0c44298fc1c149afbf4c8996fb924...",
  "ts": "2026-02-24T09:15:32Z",
  "host_id": "web-01",
  "op_kind": "exec",
  "job_id": "j-a8f3bc91",
  "user": "operator@example.com",
  "team_id": "team-abc123",
  "actor_role": "admin",
  "request": { "command": "systemctl restart nginx", "timeout": "30s" },
  "result": { "exit_code": 0, "duration_ms": 1240 }
}

Hash Chain Integrity

Audit log tamper detection consists of two layers: a SHA-256 hash chain and HMAC-SHA256 signatures.

SHA-256 Hash Chain

Each entry's hash is computed from the entry's content and the previous entry's hash using SHA-256. Tampering with any entry invalidates the hashes of all subsequent entries:

Entry 1: hash = SHA-256(seq=1 | prev_hash="" | fields...)
Entry 2: hash = SHA-256(seq=2 | prev_hash=entry_1.hash | fields...)
Entry 3: hash = SHA-256(seq=3 | prev_hash=entry_2.hash | fields...)

HMAC-SHA256 Signatures

A hash chain alone allows an attacker to conceal tampering by recomputing the entire chain. To prevent this, each entry's hash is signed with an HMAC-SHA256 signature (the hmac field). The HMAC key is stored outside the audit log directory, under the parent configuration directory (<config_dir>/secrets/audit_hmac.key), so an attacker without the key cannot produce valid HMAC values even if they recompute the chain.

Hash Version

The fields included in the hash computation vary by version:

Integrity Protection on Write Failure

If a file write (write) or sync (sync) fails, the seq and prev_hash are rolled back to preserve hash chain consistency. The failed entry is not incorporated into the chain, ensuring that subsequent entries link correctly.

CLI Commands

View Recent Entries

nefia audit tail -n 200

Show a Specific Job

nefia audit show --job j-a8f3bc91

Verify Hash Chain

Verifies the hash chain integrity of a single day's audit log file. Defaults to today's date when no argument is provided.

nefia audit verify              # verify today's log
nefia audit verify 2026-02-24   # verify a specific date

Performance and Resource Management

File Handle Reuse

Audit log writes are optimized by reusing file handles on a per-day basis. Only two system calls — write + sync — are needed per record (no open/close required).

Record write flow:
  1. ensureFile(date) — skipped if the existing handle's date matches (O(1))
  2. write(data)      — direct write without buffering
  3. sync()           — immediate flush to disk (prevents data loss)

Automatic File Rotation on Date Change

When the date changes (UTC-based), ensureFile() detects it, closes the previous day's file handle, and automatically opens a new file for the current day. No explicit rotation operation is required.

Resource Cleanup via Close()

When App.Close() is called, Audit.Close() is executed, performing the following:

1. Closes the current file handle
2. Waits for any running cleanup goroutines to complete

This ensures no file handle leaks occur on application shutdown.

Configuration

Configure audit logging in nefia.yaml:

audit:
  enabled: true
  required: false  # when true, operations fail if audit write fails
  dir: ~/.config/nefia/audit
  retention_days: 90
  syslog_addr: "localhost:514"
  syslog_proto: "udp"

When syslog forwarding is enabled, events are sent in real time alongside the local JSONL write. The local log is always written regardless of syslog availability, ensuring the hash chain remains intact.

Verification Workflow

For compliance or incident investigation, verify integrity first, then filter and inspect:

# Step 1: Verify the hash chain for today (or a specific date)
nefia audit verify
nefia audit verify 2026-02-24
 
# Step 2: View recent entries
nefia audit tail -n 100
 
# Step 3: Inspect specific jobs
nefia audit show --job j-a8f3bc91

Related