SeaWatch: Audit & Security Events

SeaWatch records the security-relevant actions in FerrisKey. A login, a password reset, a user creation, a role assignment, a settings change: each produces a structured event carrying who did it, what they touched, when, from where, and why it worked or did not.

Without it, a compromised account is a mystery. With it, you can trace one back to the exact login attempt, IP address, and user agent. The same trail is what SOC 2, ISO 27001, GDPR, and HIPAA audits ask for, and what makes “repeated failures from one IP” a query rather than a hunch.

Event structure

Every SeaWatch event captures a complete picture:

{
  "id": "01914b3c-7e8a-7f5a-b456-789012345678",
  "realm_id": "01914b3c-1234-7f5a-b456-000000000001",
  "event_type": "login_failure",
  "status": "failure",
  "actor_id": null,
  "actor_type": null,
  "target_type": "user",
  "target_id": "01914b3c-5678-7f5a-b456-000000000002",
  "resource": "alice@example.com",
  "ip_address": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "details": {
    "reason": "invalid_credentials",
    "client_id": "my-frontend"
  },
  "timestamp": "2026-03-17T14:30:00Z"
}

Field	Description
`id`	Unique event identifier (UUIDv7, time-ordered)
`realm_id`	Realm where the event occurred
`event_type`	What happened (see Event Types)
`status`	`success` or `failure`
`actor_id` / `actor_type`	Who triggered the event and their classification
`target_type` / `target_id`	What resource was affected
`resource`	Human-readable resource description
`ip_address` / `user_agent`	Client context
`trace_id`	OpenTelemetry trace ID for distributed correlation
`details`	Event-specific JSON payload
`timestamp`	When the event occurred (UTC)

Actor types

Actor	When Used
`user`	A regular authenticated user performed the action
`service_account`	A client’s service account performed the action
`admin`	An administrator performed the action via the admin console
`system`	FerrisKey itself (automated processes, scheduled tasks)

What people do with it

Security operations. Forward events to your SIEM, Splunk, Elastic, Datadog, and correlate them with the rest of your signals. trace_id is what links an authentication event to the API requests that followed it.

Compliance reporting. Query by time range and event type. The structured format makes “every admin action on the identity system in Q1” a query result rather than a project.

Alerting. Pair SeaWatch with Webhooks to fire on the patterns that matter: repeated login_failure from one IP, a client_secret_rotated outside a maintenance window, a realm_config_changed from an actor nobody expected.

Privacy

Events carry IP addresses and user agents, which are personal data in some jurisdictions. The realm setting seawatch_pii_mode decides what is stored:

Mode	Behaviour
`off`	Store events as they are. The default
`mask`	Truncate the IP address and reduce the user agent before storing
`pseudonymise`	Replace the identifying fields with an HMAC, keyed by `seawatch_pseudo_key`

Pseudonymisation keeps events correlatable, the same source produces the same value, without keeping the raw address. Set seawatch_pseudo_key on the realm when you use that mode.