category: spec
tags: [security, logging, owasp, plan]
last_updated: 2026-03-18
confidence: high

Security Logging Plan

Addresses OWASP A09 finding: "No audit trail for auth events, ACL changes, wiki deletions."

Events to Log

Auth server (app/auth_server.py)

Management middleware (app/management/routes.py)

Resolver (app/resolver.py)

Not logged: ACL flag changes (allow_read, allow_write, is_admin, is_approved). These happen inside otterwiki's admin UI with no current hook point. Deferred — track as a follow-on once otterwiki lifecycle hooks or the per-wiki DB plan is in place.

Log Format

Structured JSON, one object per line, emitted via Python stdlib logging to stdout → systemd journal (already configured). No new log file or rotation needed — journal handles retention (30-day, 500MB cap per robot-journald.conf).

{
  "ts": "2026-03-18T12:34:56.789Z",
  "event": "login.success",
  "actor_did": "did:plc:abc123",
  "actor_handle": "user.bsky.social",
  "wiki_slug": null,
  "client_id": null,
  "outcome": "success",
  "ip": "1.2.3.4",
  "syslog_identifier": "robot-auth"
}

Fields:

• ts — UTC ISO-8601
• event — dot-namespaced string (see tables above)
• actor_did — DID of the acting user, or null for anonymous/system
• actor_handle — AT Protocol handle, or null
• wiki_slug — target wiki, or null for platform-level events
• client_id — OAuth client_id for consent events, else null
• outcome — "success" | "failure" | "blocked"
• ip — client IP (from request.remote_addr in Flask, or get_client_ip(environ) in WSGI middleware)

PII note: IP addresses are PII. They are logged for security purposes (rate limit forensics, abuse investigation). Journal retention is 30 days — no change needed. Do not log full handles in combination with IPs in any external/forwarded log sink.

Implementation Approach

New module: app/audit.py

A thin wrapper around stdlib logging. No new dependencies.

import logging, json
from datetime import datetime, timezone

_audit = logging.getLogger("robot.audit")

def log(event: str, *, actor_did=None, actor_handle=None,
        wiki_slug=None, client_id=None, outcome="success", ip=None):
    _audit.info(json.dumps({
        "ts": datetime.now(timezone.utc).isoformat(),
        "event": event,
        "actor_did": actor_did,
        "actor_handle": actor_handle,
        "wiki_slug": wiki_slug,
        "client_id": client_id,
        "outcome": outcome,
        "ip": ip,
    }))

The logger name robot.audit lets operators filter with journalctl -u robot-auth SYSLOG_IDENTIFIER=robot-auth | grep robot.audit or similar.

Call sites

app/auth_server.py — add from app import audit (or from app.audit import log as audit_log) and call audit_log(...) at the points noted in the events table. Most insertions are single lines immediately after the decision that determines the outcome. The ratelimit_handler() at the bottom of create_app() is the single place to cover all rate limit hits on the auth server.

app/management/routes.py — ManagementMiddleware.__call__() already has the 429 path. _create_wiki() and _delete_wiki() return tuples — log immediately before return. actor_did comes from user.user_did, ip from get_client_ip(environ) (already imported).

app/resolver.py — TenantResolver._resolve_bearer_token() raises AuthError on invalid/mismatched tokens — log before raising. The 429 block in __call__() already has client_ip. No logging in _permissions_for_user() — permission derivation is not itself an audit event.

IP extraction

• Flask routes: request.remote_addr (ProxyFix is already wired in create_app())
• WSGI middleware: get_client_ip(environ) from app.rate_limit (already imported in both routes.py and resolver.py)

No request ID correlation (yet)

Cross-service correlation (e.g., tracing a consent grant through auth → resolver → MCP) would require propagating a request ID header. Deferred — the audit events are service-scoped and the actor_did + ts + wiki_slug triple is sufficient for forensics at this scale.

Ansible Changes

1. No new service file changes needed. All services already emit stdout to the journal (StandardOutput=journal). The robot.audit logger will appear in the same journal unit as the service that emits it.

2. Log level configuration. Add AUDIT_LOG_LEVEL=INFO to ansible/roles/deploy/templates/robot.env.j2 and wire it in app/audit.py (logging.basicConfig or the app's existing logging setup). The default INFO level is correct; DEBUG should never emit audit records.

3. No logrotate role needed. ansible/roles/logging/ already configures journald with 30-day retention and 500MB cap — sufficient.

4. Future: if a SIEM or external log forwarder is added, journalctl -o json -u robot-auth -u robot-api -u robot-mcp can be tailed. No Ansible change required at that point beyond a forwarding role.

Out of Scope (Deferred)

• ACL flag changes via otterwiki admin UI — needs lifecycle hook or per-wiki DB plan
• Token issuance/refresh events for the ATProto OAuth session — currently no post-refresh hook; low priority since the platform JWT (24h) is the user-facing credential
• Feeding into a monitoring dashboard — tracked separately
• Structured log querying / alerting — revisit when user base grows beyond single-digit wikis