From 7bec940e7f7df5ffaba1063e715cc8610eed93e9 Mon Sep 17 00:00:00 2001 From: Ronni Baslund Date: Sun, 24 May 2026 20:21:29 +0200 Subject: [PATCH] feat(audit): Stalwart webhook ingest endpoint (Phase 2 chunk 2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../configs/stalwart/config.toml | 25 ++++ .../docker-compose/docker-compose.yml | 6 + .../platform-api/src/ingest/action-map.ts | 35 +++++ .../platform-api/src/ingest/ingest.module.ts | 9 +- .../src/ingest/stalwart-webhook.controller.ts | 139 ++++++++++++++++++ 5 files changed, 211 insertions(+), 3 deletions(-) create mode 100644 services/platform-api/src/ingest/stalwart-webhook.controller.ts diff --git a/infrastructure/docker-compose/configs/stalwart/config.toml b/infrastructure/docker-compose/configs/stalwart/config.toml index a008d48..a90c456 100644 --- a/infrastructure/docker-compose/configs/stalwart/config.toml +++ b/infrastructure/docker-compose/configs/stalwart/config.toml @@ -84,6 +84,31 @@ enable = true [spam-filter] enable = false +# ───────────────────────────────────────────────────────────────── +# Audit webhook — push security-relevant events to platform-api so the +# operator's /audit timeline reflects mail-server activity (failed auth, +# new accounts, policy/DKIM rejections). Signed via HMAC-SHA-256 with +# STALWART_WEBHOOK_SECRET (a shared env between this container and the +# platform-api container). +# ───────────────────────────────────────────────────────────────── +[webhook."audit-ingest"] +url = "http://platform-api:3001/ingest/stalwart/webhook" +signature-key = "$env{STALWART_WEBHOOK_SECRET}" +events = [ + "auth.success", + "auth.failure", + "auth.banned", + "account.created", + "account.deleted", + "account.password-changed", + "message.rejected", + "policy.rejection", + "dkim.failure", + "dmarc.failure", + "spam.detected", +] +throttle = "1s" + # ───────────────────────────────────────────────────────────────── # Local development hint: # After first boot, create your first mailbox by visiting diff --git a/infrastructure/docker-compose/docker-compose.yml b/infrastructure/docker-compose/docker-compose.yml index b0fc3c8..908ab5d 100644 --- a/infrastructure/docker-compose/docker-compose.yml +++ b/infrastructure/docker-compose/docker-compose.yml @@ -209,6 +209,9 @@ services: # generates a one-time-shown password at first boot and discards it after # initial setup. STALWART_RECOVERY_ADMIN: admin:${STALWART_ADMIN_PASSWORD} + # Shared HMAC secret for the audit webhook POSTed to platform-api. + # config.toml references this via %{env:STALWART_WEBHOOK_SECRET}%. + STALWART_WEBHOOK_SECRET: ${STALWART_WEBHOOK_SECRET} volumes: - stalwart_data:/opt/stalwart - ./configs/stalwart/config.toml:/opt/stalwart/etc/config.toml:ro @@ -451,6 +454,9 @@ services: STALWART_API_URL: https://mail.dezky.local STALWART_ADMIN_USER: admin STALWART_ADMIN_PASSWORD: ${STALWART_ADMIN_PASSWORD} + # HMAC secret Stalwart signs its webhook POSTs with; we verify on + # /ingest/stalwart/webhook. Both ends read the same env var. + STALWART_WEBHOOK_SECRET: ${STALWART_WEBHOOK_SECRET} OCIS_API_URL: https://files.dezky.local # JWT validation against Authentik for portal-issued access tokens. # Issuers are comma-separated — each Authentik OAuth provider issues tokens diff --git a/services/platform-api/src/ingest/action-map.ts b/services/platform-api/src/ingest/action-map.ts index 1d11125..82c644c 100644 --- a/services/platform-api/src/ingest/action-map.ts +++ b/services/platform-api/src/ingest/action-map.ts @@ -41,3 +41,38 @@ export function mapAuthentikAction(raw: string): MappedAction { } ) } + +// 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 = { + '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', + } + ) +} diff --git a/services/platform-api/src/ingest/ingest.module.ts b/services/platform-api/src/ingest/ingest.module.ts index e1fc2ec..e444cd8 100644 --- a/services/platform-api/src/ingest/ingest.module.ts +++ b/services/platform-api/src/ingest/ingest.module.ts @@ -8,10 +8,12 @@ import { } from '../schemas/ingest-cursor.schema.js' import { Tenant, TenantSchema } from '../schemas/tenant.schema.js' import { AuthentikIngest } from './authentik.ingest.js' +import { StalwartWebhookController } from './stalwart-webhook.controller.js' -// Workers that pull audit events from external systems (Authentik today, -// Stalwart + OCIS later) and forward them to AuditService. Each worker owns -// its own cursor in the ingest_cursors collection so restarts resume cleanly. +// Workers + endpoints that bring audit events from external systems into +// AuditService. Authentik = polling worker (pull). Stalwart = webhook +// endpoint (push). OCIS lands next as a file-tail worker (Phase 2 chunk 3). +// Each integration owns its own cursor / dedup story. @Module({ imports: [ AuditModule, @@ -21,6 +23,7 @@ import { AuthentikIngest } from './authentik.ingest.js' { name: Tenant.name, schema: TenantSchema }, ]), ], + controllers: [StalwartWebhookController], providers: [AuthentikIngest], }) export class IngestModule {} diff --git a/services/platform-api/src/ingest/stalwart-webhook.controller.ts b/services/platform-api/src/ingest/stalwart-webhook.controller.ts new file mode 100644 index 0000000..29512da --- /dev/null +++ b/services/platform-api/src/ingest/stalwart-webhook.controller.ts @@ -0,0 +1,139 @@ +// Stalwart calls this endpoint whenever an event in its webhook subscription +// list fires (auth failures, account creation, policy rejections, DKIM +// failures, etc.). We don't authenticate via JWT here — Stalwart can't carry +// one — instead each request is HMAC-SHA-256 signed with a secret shared via +// the STALWART_WEBHOOK_SECRET env var. Bad signatures get a 401 and a debug +// log line; valid ones are mapped and recorded into the audit collection. +// +// The handler is intentionally permissive about the body shape: Stalwart's +// webhook payload schema has shifted between minor versions, so we read the +// raw body (for HMAC), parse JSON loosely, walk anything that looks like a +// list of events, and let unknown event types fall through to the +// `stalwart.` catch-all in the action map. Worst case: we record raw +// events with a generic verb instead of dropping them. + +import { + Body, + Controller, + Headers, + Logger, + Post, + Req, + UnauthorizedException, +} from '@nestjs/common' +import { ConfigService } from '@nestjs/config' +import { createHmac, timingSafeEqual } from 'node:crypto' +import { clientIp } from '../auth/client-ip.js' +import { AuditService } from '../audit/audit.service.js' +import { mapStalwartAction } from './action-map.js' + +interface StalwartEvent { + // Stalwart sends `id` (uuid), `createdAt` (ISO), `type` (string), and + // a `data` blob whose shape depends on `type`. We don't bind tightly to it + // — anything we use is destructured defensively below. + id?: string + createdAt?: string + type?: string + data?: Record +} + +interface StalwartWebhookBody { + events?: StalwartEvent[] +} + +@Controller('ingest/stalwart') +export class StalwartWebhookController { + private readonly logger = new Logger(StalwartWebhookController.name) + private readonly secret: string + + constructor( + private readonly audit: AuditService, + config: ConfigService, + ) { + this.secret = config.getOrThrow('STALWART_WEBHOOK_SECRET') + } + + @Post('webhook') + async receive( + @Body() body: StalwartWebhookBody, + @Headers('x-signature') signature: string | undefined, + @Req() req: Parameters[0] & { rawBody?: Buffer | string }, + ) { + // Stalwart sends `X-Signature: ` on every webhook. If the + // body parser already consumed the stream, fall back to JSON-stringifying + // — Stalwart computes HMAC over the JSON it serializes, which matches + // what Fastify reconstructs from `body`. + const raw = + req.rawBody instanceof Buffer + ? req.rawBody.toString('utf8') + : typeof req.rawBody === 'string' + ? req.rawBody + : JSON.stringify(body ?? {}) + if (!this.verifySignature(raw, signature)) { + this.logger.warn(`stalwart webhook: bad signature from ${clientIp(req)}`) + throw new UnauthorizedException('Invalid webhook signature') + } + + const events = Array.isArray(body?.events) ? body.events : [] + if (!events.length) { + this.logger.debug('stalwart webhook: payload had no events') + return { received: 0 } + } + + const senderIp = clientIp(req) + let written = 0 + for (const evt of events) { + if (!evt.type) continue + await this.recordOne(evt, senderIp) + written++ + } + this.logger.log(`stalwart webhook: received ${written} event(s)`) + return { received: written } + } + + private verifySignature(rawBody: string, header: string | undefined): boolean { + if (!header) return false + // Strip a `sha256=` prefix if Stalwart includes one (matches GitHub's + // convention some setups copy). + const provided = header.replace(/^sha256=/i, '').trim() + const expected = createHmac('sha256', this.secret).update(rawBody).digest('hex') + if (provided.length !== expected.length) return false + return timingSafeEqual(Buffer.from(provided, 'hex'), Buffer.from(expected, 'hex')) + } + + private async recordOne(evt: StalwartEvent, senderIp: string | undefined): Promise { + const mapped = mapStalwartAction(evt.type ?? 'unknown') + const data = evt.data ?? {} + const at = evt.createdAt ? new Date(evt.createdAt) : new Date() + + // Common Stalwart data fields — present on most categories, missing on + // others. Pull what we can; let the rest land in metadata. + const actorEmail = pickString(data, ['email', 'username', 'account', 'remote-email', 'from']) + const tenantSlug = pickString(data, ['tenant', 'domain']) + const targetName = pickString(data, ['account', 'email', 'address', 'to', 'message-id']) + const ip = pickString(data, ['ip', 'remote-ip', 'source-ip']) ?? senderIp + + await this.audit.record( + { + action: mapped.action, + outcome: mapped.outcome, + resourceType: mapped.resourceType, + resourceName: targetName ?? evt.type, + tenantSlug, + source: 'stalwart', + externalId: evt.id, + at, + metadata: { rawType: evt.type, data }, + }, + { email: actorEmail, ip }, + ) + } +} + +function pickString(obj: Record, keys: string[]): string | undefined { + for (const k of keys) { + const v = obj[k] + if (typeof v === 'string' && v.length) return v + } + return undefined +}