🌊 Riptide

Riptide is a NetFlow analysis engine: it ingests flow telemetry from network devices, enriches every flow record with network context, and persists the result to ClickHouse for analysis.

What it does

UDP/TCP ingest (NetFlow v5 · NetFlow v9 · IPFIX · sFlow)
   → decode
   → match exporter to a configured node (subnet + observation domain)
   → enrich:  classification · clock correction · locality ·
              AS numbers/orgs · GeoIP country/city ·
              SNMP interface names/aliases/speed · reverse-DNS hostnames
   → persist to ClickHouse (tenant/organisation/zone/system identity)

• Flow protocols: NetFlow v5, NetFlow v9, IPFIX, and sFlow (UDP; IPFIX also via TCP). See Receivers.
• Inventory model: named credential sets and polling profiles in the main config; agent ranges and exporter enrichment entries in a hot-reloaded inventory file. A device inside a credentialed range is polled from its first flow, with no per-device configuration. See SNMP agents and Exporter enrichment.
• Secrets: SNMP credentials are references (env://, file://, vault://, sops://), never plaintext in configuration. See Secret references.
• Enrichment: a graceful-degradation ladder — rule-based classification, exporter clock correction, locality, AS data from the routing mapping, GeoIP country/city (MaxMind GeoLite2 or IPinfo, with per-prefix overrides), SNMP IF-MIB interface data, exporter-pushed option records, reverse-DNS hostnames. Flows persist even when every live source is unreachable. See Enrichment and GeoIP.
• Multi-tenancy: every flow carries tenant/organisation/zone/system identity; riptide onboard provisions role-based ClickHouse access with hard row-level isolation per tenant. See the multi-tenancy runbook.
• AI Agent Integration: native embedded MCP server (org.riptide.mcp.*) over stdio IPC and HTTP/SSE with 7 auto-shipped Agent Skills (/riptide-investigate-ddos, /riptide-cause-analysis, etc.) and SecretRef token authentication. See MCP Server.

Technology

Java 25 · Spring Boot · Netty · SNMP4J · ClickHouse. Licensed GPL-3.0-or-later.

Where to go next

• 🚀 Deploy Riptide — run the published image (Compose or plain JAR)
• 🛠 Develop & Contribute — build, debug, test, send PRs
• Receivers — configure flow listeners
• SNMP agents — credential sets, polling profiles, agent ranges
• Exporter enrichment — naming exporters and pinning interfaces
• Secret references — Vault, SOPS, env, file
• MCP Server — native AI Agent integration & skills
• ClickHouse — persistence