Skip to content

feat(codespaces): add audit logging for security and observability #350

@btessiau

Description

@btessiau

Summary

Add structured audit logging for PolyPilot's Codespaces integration. Audit logging enables security analysis, troubleshooting, and compliance visibility for operations involving SSH connections, DevTunnel tokens, and headless Copilot processes.

Audit Events (10 types)

# Event When
1 CODESPACE_CONNECTION_INITIATED SSH port-forward or tunnel about to open
2 CODESPACE_SSH_HANDSHAKE_SUCCESS Port-forward/tunnel established successfully
3 CODESPACE_SSH_HANDSHAKE_FAILURE Port-forward/tunnel failed
4 COPILOT_HEADLESS_START Headless copilot started in codespace
5 COPILOT_HEADLESS_FAILURE Headless copilot failed to start
6 DEVTUNNEL_TOKEN_ACQUIRED Access token issued for DevTunnel
7 DEVTUNNEL_CONNECTION_ESTABLISHED Tunnel hosted successfully
8 DEVTUNNEL_CONNECTION_FAILED Tunnel hosting failed
9 SESSION_CLOSED DevTunnel stopped
10 SESSION_ERROR Unrecoverable error in session

Storage Format

  • Location: ~/.polypilot/audit_logs/
  • Format: JSON Lines (audit_YYYY-MM-DD.jsonl)
  • Rotation: Daily, 30-day retention with auto-deletion
  • Thread safety: SemaphoreSlim(1,1) for file writes
  • Performance: Async I/O, never blocks session threads

Security Constraints

  • ❌ NO GitHub tokens, SSH keys, or passwords in logs
  • ❌ NO full token values (first 8 chars only via SanitizeSecret)
  • ✅ Token TTL, fingerprints, auth failure reasons logged
  • ✅ Error messages sanitized (home paths, ghp/gho/github_pat/JWT tokens redacted)

Code Structure

New Files

  • PolyPilot/Models/AuditLogEntry.cs — Data model + event type constants
  • PolyPilot/Services/AuditLogService.cs — 10 typed Log methods, sanitization, JSONL writer, retention cleanup
  • PolyPilot.Tests/AuditLogTests.cs — 19 tests covering all aspects

Modified Files

  • PolyPilot/Services/CodespaceService.cs — Audit calls at SSH/tunnel lifecycle points
  • PolyPilot/Services/CodespaceService.Lifecycle.cs — Audit calls for headless start/failure
  • PolyPilot/Services/DevTunnelService.cs — Audit calls for token, tunnel, and session lifecycle
  • PolyPilot/MauiProgram.cs — Register AuditLogService singleton

Testing

  • File creation & daily rotation
  • All 10 event types with field verification
  • Sensitive data sanitization (tokens, keys, paths)
  • Thread safety (10 concurrent tasks × 20 entries, zero data loss)
  • Error handling (invalid paths don't crash)
  • 30-day retention purge
  • JSON serialization round-trip

Acceptance Criteria

  • All 10 event types logged at the correct lifecycle points
  • No sensitive data in logs (tokens, keys, passwords)
  • Thread-safe concurrent writes
  • Logging failures never crash the app
  • 19 passing tests
  • No regression in existing test suite

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions