unifi-siem-sink: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An MCP server that receives UniFi's CEF-over-syslog SIEM export (UDP), stores it in SQLite with a retention window, and exposes it to an LLM over Streamable HTTP. It exists because the UniFi Network Local API does not expose IPS/IDS threat events (the stat/ips/event endpoint was removed in firmware 10.x) — the SIEM/syslog export is the only remaining path to that data. It pairs with the sibling project unifi-mcp-server, which covers everything else in the UniFi Network API; this project fills only the Security-category gap. A third sibling, unifi-siem-lens, sits on top of this project's event store and runs scheduled, code-driven analysis heuristics against it — it's a consumer of this project's MCP tools, not a dependency of this codebase.

Commands

npm run build        # tsc -> dist/
npm start             # node --env-file=.env dist/index.js (run after build)
npm test              # vitest run — full suite
npm run test:watch    # vitest watch mode
npm run lint           # biome check src

Run a single test file: npx vitest run tests/parser/cef.test.ts Run tests matching a name: npx vitest run -t "some test name"

npm run dev (node --experimental-strip-types src/index.ts) is currently broken on Node 24.x/25.x — --experimental-strip-types doesn't resolve .js-suffixed relative imports against sibling .ts files the way tsc does. Use npm run build && npm start for local runs instead, rebuilding after each change.

Node >= 22.5.0 is required (uses node:sqlite, which is built in — no better-sqlite3 or other native SQLite dependency).

Integration tests against a real UDM Pro don't exist yet; the suite runs entirely against synthetic and recorded CEF fixtures in tests/fixtures/real-cef-samples.md.

Architecture

Startup wiring lives in src/index.ts: load config → open DB → start the UDP syslog listener → start the Express/MCP HTTP server → register a SIGTERM/SIGINT shutdown that drains all three in order. There's also a setInterval-driven hourly purge of events older than RETENTION_DAYS.