CDX-301b · Module 3

Audit Logging & Session Forensics

3 min read

Audit logging captures what Codex did, when it did it, and in what context. A complete audit log includes: session start/end timestamps, the active profile and model, every file read, every file written, every command executed (with exit codes), and the AGENTS.md rules that were active. This data serves three purposes: security incident investigation ("did Codex access the credentials file?"), cost analysis ("which model consumed the most tokens?"), and process improvement ("which rules did Codex follow or violate?").

Session forensics goes beyond logging to reconstructing what happened and why. When Codex produces unexpected output, the audit log lets you trace the chain: which files did it read for context, which rules were active, which model processed the request, and what commands did it run to validate its output. This forensic capability is essential for debugging automated pipelines where Codex operates without human oversight.

# Audit logging configuration
# Session logs capture all Codex activity

# Log destination options:
# - file: local JSONL file (default)
# - stdout: stream to CI log capture
# - webhook: POST to a logging service

# Environment variables for logging:
# CODEX_LOG_LEVEL=debug          # debug|info|warn|error
# CODEX_LOG_FILE=./codex-audit.jsonl
# CODEX_LOG_FILE_READS=true      # Log every file read
# CODEX_LOG_COMMANDS=true        # Log every command + exit code
# CODEX_LOG_TOKENS=true          # Log token usage per request

# CI integration: stream logs for capture
# steps:
#   - name: Run Codex with audit logging
#     env:
#       CODEX_LOG_LEVEL: debug
#       CODEX_LOG_FILE: /tmp/codex-audit.jsonl
#     run: codex review --json
#   - name: Upload audit log
#     uses: actions/upload-artifact@v4
#     with:
#       name: codex-audit-log
#       path: /tmp/codex-audit.jsonl

Do This

  • Log every session with file reads, commands, and token usage
  • Store logs in a tamper-evident system with compliance-grade retention
  • Include the active AGENTS.md rules in each session log for context
  • Upload CI audit logs as build artifacts for long-term storage

Avoid This

  • Log only errors — normal sessions are the ones auditors want to review
  • Store audit logs locally on developer machines where they can be deleted
  • Skip logging in CI — automated sessions need MORE audit coverage, not less
  • Forget token usage logging — it is your primary cost control signal