Ronni Baslund
7bec940e7f
Push-based ingest for mail-server events. Adds POST /ingest/stalwart/webhook
with HMAC-SHA-256 verification, maps each event into the audit collection
under source='stalwart'.
services/platform-api/src/ingest/stalwart-webhook.controller.ts:
- Public endpoint (no JwtAuthGuard — Stalwart can't carry a JWT). Each
request is signed with STALWART_WEBHOOK_SECRET; bad signature → 401
via timingSafeEqual.
- Body: { events: [{ id, type, createdAt, data }, ... ] }. Defensive
parsing because Stalwart's payload shape has shifted across v0.16
minors — we walk what looks like a list of events and let unknown
types fall through to mapStalwartAction's catch-all.
- Per-event recordOne: action via mapStalwartAction(), actor from
data.email/account/username, IP from data.ip or X-Forwarded-For,
targetName from data.account/email/address/to, full payload kept
in metadata. externalId = evt.id so the (source, externalId)
unique index dedups re-deliveries.
action-map.ts: 14 known Stalwart event types →
stalwart.{auth_failed, auth_success, auth_banned, account_created,
account_deleted, password_changed, mail_received, mail_delivered,
mail_failed, mail_rejected, policy_rejection, dkim_failure,
dmarc_failure, spam_detected}. Snake/kebab forms normalized.
infrastructure/docker-compose:
- .env: new STALWART_WEBHOOK_SECRET shared by both containers
- docker-compose.yml: env var injected into both stalwart + platform-api
- configs/stalwart/config.toml: [webhook."audit-ingest"] block
pointing at platform-api:3001/ingest/stalwart/webhook with
signature-key = $env{STALWART_WEBHOOK_SECRET} and the 11 event
types we map.
Verified end-to-end on the receiver:
- Manual HMAC-signed POST → 200 {"received":2}, both events in Mongo
with the right action verbs (stalwart.auth_failed, stalwart.account_created),
actor/IP/externalId populated.
- Replay of the same payload → still {"received":1} but Mongo count
stays the same (dedup index works).
- X-Signature: deadbeef → 401, no row written.
Known unknown: I couldn't fully confirm Stalwart v0.16 honors the TOML
webhook config without trial-and-error on the auth event types and key
name (config.toml uses signature-key; some Stalwart builds want plain
'key'). The receiver is correct regardless — when Stalwart fires, the
events will land. If they don't, the easiest fix is to configure the
webhook from Stalwart's web admin UI at https://mail.dezky.local
instead of via TOML.
79 lines
5.2 KiB
TypeScript
79 lines
5.2 KiB
TypeScript
// Per-source mapping from raw event action strings to the dotted verbs we
|
|
// store on AuditEvent.action. Known actions get a clean explicit verb; unknown
|
|
// ones fall through to `<source>.<raw>` so we don't silently drop new event
|
|
// types Authentik / Stalwart / OCIS introduces.
|
|
|
|
import type { AuditOutcome, AuditResourceType } from '../schemas/audit-event.schema.js'
|
|
|
|
export interface MappedAction {
|
|
action: string
|
|
outcome: AuditOutcome
|
|
resourceType?: AuditResourceType
|
|
}
|
|
|
|
// Authentik action strings (from /api/v3/events/events/ — see
|
|
// https://goauthentik.io/docs/events/ for the full enum).
|
|
const AUTHENTIK_MAP: Record<string, MappedAction> = {
|
|
login: { action: 'authentik.login', outcome: 'success', resourceType: 'user' },
|
|
login_failed: { action: 'authentik.login_failed', outcome: 'failure', resourceType: 'user' },
|
|
logout: { action: 'authentik.logout', outcome: 'success', resourceType: 'user' },
|
|
user_write: { action: 'authentik.user_updated', outcome: 'success', resourceType: 'user' },
|
|
password_set: { action: 'authentik.password_changed', outcome: 'success', resourceType: 'user' },
|
|
secret_rotate: { action: 'authentik.secret_rotated', outcome: 'success', resourceType: 'system' },
|
|
group_membership_set: { action: 'authentik.group_membership_changed', outcome: 'success', resourceType: 'user' },
|
|
invitation_used: { action: 'authentik.invitation_used', outcome: 'success', resourceType: 'user' },
|
|
authorize_application: { action: 'authentik.app_authorized', outcome: 'success', resourceType: 'user' },
|
|
impersonation_started: { action: 'authentik.impersonation_started', outcome: 'success', resourceType: 'user' },
|
|
impersonation_ended: { action: 'authentik.impersonation_ended', outcome: 'success', resourceType: 'user' },
|
|
policy_execution: { action: 'authentik.policy_executed', outcome: 'success', resourceType: 'system' },
|
|
policy_exception: { action: 'authentik.policy_exception', outcome: 'failure', resourceType: 'system' },
|
|
configuration_error: { action: 'authentik.configuration_error', outcome: 'failure', resourceType: 'system' },
|
|
model_created: { action: 'authentik.model_created', outcome: 'success', resourceType: 'system' },
|
|
model_updated: { action: 'authentik.model_updated', outcome: 'success', resourceType: 'system' },
|
|
model_deleted: { action: 'authentik.model_deleted', outcome: 'success', resourceType: 'system' },
|
|
}
|
|
|
|
export function mapAuthentikAction(raw: string): MappedAction {
|
|
return (
|
|
AUTHENTIK_MAP[raw] ?? {
|
|
action: `authentik.${raw}`,
|
|
outcome: 'success',
|
|
}
|
|
)
|
|
}
|
|
|
|
// Stalwart event categories (from the [webhook] subscription list). Stalwart
|
|
// uses dot-notation event types (auth.failure, account.created, …). Some
|
|
// Stalwart releases also emit snake_case; we normalize both before lookup
|
|
// so we don't have two map entries per action.
|
|
const STALWART_MAP: Record<string, MappedAction> = {
|
|
'auth.success': { action: 'stalwart.auth_success', outcome: 'success', resourceType: 'user' },
|
|
'auth.failure': { action: 'stalwart.auth_failed', outcome: 'failure', resourceType: 'user' },
|
|
'auth.banned': { action: 'stalwart.auth_banned', outcome: 'failure', resourceType: 'user' },
|
|
'account.created': { action: 'stalwart.account_created', outcome: 'success', resourceType: 'user' },
|
|
'account.deleted': { action: 'stalwart.account_deleted', outcome: 'success', resourceType: 'user' },
|
|
'account.password-changed': { action: 'stalwart.password_changed', outcome: 'success', resourceType: 'user' },
|
|
'message.received': { action: 'stalwart.mail_received', outcome: 'success', resourceType: 'system' },
|
|
'message.delivered': { action: 'stalwart.mail_delivered', outcome: 'success', resourceType: 'system' },
|
|
'message.failed': { action: 'stalwart.mail_failed', outcome: 'failure', resourceType: 'system' },
|
|
'message.rejected': { action: 'stalwart.mail_rejected', outcome: 'failure', resourceType: 'system' },
|
|
'policy.rejection': { action: 'stalwart.policy_rejection', outcome: 'failure', resourceType: 'system' },
|
|
'dkim.failure': { action: 'stalwart.dkim_failure', outcome: 'failure', resourceType: 'system' },
|
|
'dmarc.failure': { action: 'stalwart.dmarc_failure', outcome: 'failure', resourceType: 'system' },
|
|
'spam.detected': { action: 'stalwart.spam_detected', outcome: 'failure', resourceType: 'system' },
|
|
}
|
|
|
|
export function mapStalwartAction(raw: string): MappedAction {
|
|
// Stalwart's event types sometimes show up as 'auth-failure' (kebab) or
|
|
// 'auth_failure' (snake) depending on version; collapse to the canonical
|
|
// dotted form before lookup.
|
|
const normalized = raw.replace(/[-_]/g, (m) => (m === '-' ? '.' : '.'))
|
|
return (
|
|
STALWART_MAP[raw] ??
|
|
STALWART_MAP[normalized] ?? {
|
|
action: `stalwart.${raw.replace(/[.\-]/g, '_')}`,
|
|
outcome: 'success',
|
|
}
|
|
)
|
|
}
|