Audit Logging

Yopass can emit a structured audit log recording every security-relevant event — secret creation, access, deletion, and authentication — without ever logging encrypted content. The log is designed for compliance requirements such as SOC 2, ISO 27001, and GDPR data-access accountability.

Requires a valid license. Audit logging is a premium feature gated behind --license-key.

---

Enabling audit logging

yopass-server \
  --license-key "your-license-key" \
  --audit-log

By default, audit records are written to stdout as NDJSON (one JSON object per line), separate from the regular application log. To write to a dedicated file instead:

yopass-server \
  --license-key    "your-license-key" \
  --audit-log \
  --audit-log-file /var/log/yopass/audit.log

---

Flags

Flag	Env var	Default	Description
--audit-log	AUDIT_LOG	false	Enable audit logging (requires valid license)
--audit-log-file	AUDIT_LOG_FILE	—	Write audit log to this file path. When unset, records go to stdout.

---

Log format

Each event is a single JSON object terminated by a newline (NDJSON). Fields are only emitted when they are relevant to the event — optional fields are omitted rather than set to null or empty.

Fields

Field	Type	Always present	Description
timestamp	string (RFC3339Nano, UTC)	yes	When the event occurred
event	string	yes	Event type (see Events)
outcome	string	yes	success, failure, or denied
client_ip	string	yes	Real client IP, respecting --trusted-proxies
secret_id	string	no	Key identifying the secret or file
user_email	string	no	Authenticated user's email (OIDC sessions only)
user_subject	string	no	Authenticated user's OIDC subject claim
one_time	bool	no	Whether the secret was configured for one-time access
expiration_seconds	number	no	TTL in seconds at creation time
require_auth	bool	no	Whether the secret requires OIDC authentication to access
error	string	no	Human-readable reason for failure or denied outcomes

Privacy note: Encrypted secret content is never written to the audit log — only the key (ID) and metadata are recorded.

Example records

Successful secret creation:

{"timestamp":"2026-04-09T12:00:01.123456789Z","event":"secret.created","outcome":"success","client_ip":"203.0.113.42","secret_id":"k9bXz3mQ2vR7nLpA4wEy5a","one_time":true,"expiration_seconds":3600,"require_auth":false,"user_email":"alice@corp.example","user_subject":"auth0|abc123"}

Access denied (unauthenticated):

{"timestamp":"2026-04-09T12:01:00.000000001Z","event":"secret.accessed","outcome":"denied","client_ip":"198.51.100.7","secret_id":"k9bXz3mQ2vR7nLpA4wEy5a","require_auth":true,"error":"authentication required"}

Successful login:

{"timestamp":"2026-04-09T12:00:00.500000000Z","event":"auth.callback_success","outcome":"success","client_ip":"203.0.113.42","user_email":"alice@corp.example","user_subject":"auth0|abc123"}

---

Events

Secret events

Event	Triggered by	Outcomes
secret.created	POST /create/secret	success, failure
secret.accessed	GET /secret/{key}	success, failure, denied
secret.deleted	DELETE /secret/{key}	success, failure

File events

Event	Triggered by	Outcomes
file.uploaded	POST /create/file	success, failure
file.downloaded	GET /file/{key}	success, failure, denied
file.deleted	DELETE /file/{key}	success, failure

Auth events

Event	Triggered by	Outcomes
auth.callback_success	OIDC callback (successful login)	success
auth.callback_failed	OIDC callback (rejected login)	failure, denied
auth.logout	POST /auth/logout	success

Outcomes:

• success — operation completed normally
• failure — operation failed (validation error, database error, not found)
• denied — operation was rejected due to missing or insufficient authentication

---

Log rotation

When writing to a file (--audit-log-file), Yopass does not rotate logs itself. Use your platform's standard tooling:

logrotate (/etc/logrotate.d/yopass-audit):

/var/log/yopass/audit.log {
    daily
    rotate 90
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

The copytruncate directive truncates the file in place so no SIGHUP or file descriptor hand-off is needed.

systemd with StandardOutput=append:/var/log/yopass/audit.log and journald log rotation handles this automatically for systemd-managed deployments.

---

Docker Compose example

services:
  yopass:
    image: ghcr.io/jhaals/yopass:latest
    ports:
      - "1337:1337"
    environment:
      MEMCACHED: memcached:11211
      LICENSE_KEY: your-license-key
      AUDIT_LOG: "true"
    volumes:
      - ./logs:/var/log/yopass
    command: >
      yopass-server
      --audit-log-file /var/log/yopass/audit.log
    depends_on:
      - memcached

  memcached:
    image: memcached

To write to stdout (and let your log collector handle it):

environment:
  AUDIT_LOG: "true"
  # no AUDIT_LOG_FILE — records go to stdout alongside application logs

Tip: When writing to stdout in a containerized environment, prefix your log shipping filter on "event": to separate audit records from regular application log lines.

---

Combining with OIDC

Audit logging is most valuable when combined with OpenID Connect. With OIDC configured, every audit record that involves an authenticated session includes user_email and user_subject, giving you a full identity trail for compliance reviews.

yopass-server \
  --license-key        "your-license-key" \
  --audit-log \
  --oidc-issuer        "https://accounts.google.com" \
  --oidc-client-id     "123456789-abc.apps.googleusercontent.com" \
  --oidc-client-secret "GOCSPX-…" \
  --oidc-redirect-url  "https://yopass.example.com/auth/callback"

Without OIDC, user_email and user_subject are omitted from all audit records.