Skip to content
Eon Insights
Getting Started

Getting Started

Overview

This page walks through building Eon Insights from source, initializing the ClickHouse schema, running a capture and a scan, and viewing the results in the dashboard. It assumes a Linux or macOS development machine with Go 1.24+, Docker, and Redis available.

Prerequisites

  • Go 1.24 or newer (see go.mod)
  • ClickHouse (traffic metadata, scan results, certificates, compliance rules)
  • Redis (task queue for the tlsscand/nmapscand/notifyd daemons, and service heartbeats)
  • libpcap headers for the capture tool’s live-capture build (macOS/BSD path; Linux uses raw sockets)

Build the tools

Eon Insights is a Go monorepo (module insights). Every command lives under cmd/<name> and has a matching Makefile target — do not run go build directly, since that scatters binaries into the repo root instead of bin/<os>/<arch>/:

# Build everything
make all

# Or build one tool for linux/arm64, linux/amd64, and darwin/arm64
make insights
make capture

Binaries land in bin/<os>/<arch>/<tool>, e.g. bin/darwin/arm64/insights.

Set up the database

Database migrations are handled by a standalone tool, dbmigrate, not by anything inside this repo:

go install github.com/quantumgateway/dbmigrate@latest

Start ClickHouse (a plain container is enough for development):

docker run -d --name insights-clickhouse \
  -p 19000:9000 -p 18123:8123 \
  clickhouse/clickhouse-server

Then initialize the schema, pointing dbmigrate at the SQL migration list shipped in this repo:

dbmigrate -e clickhouse -h localhost -p 19000 -U default \
  -db insights -path deployments/insights/sql/2.0.0/index.lst

dbmigrate also accepts -W to prompt for a password interactively, or -password <value> to pass one on the command line. Add -data test/data/csv to load the CSV fixtures alongside the schema, useful for a throwaway development database.

Start Redis as well, since the scan/notification daemons depend on it:

docker run --name insights-redis -d -p 6379:6379 redis

Configure and run the API server

insights is the REST API the dashboard talks to. Copy and edit configs/insights.yaml (ClickHouse connection, listen address, FusionAuth settings for login), then run it:

go run cmd/insights/insights.go -c configs/insights.yaml -debug

See insights for the full flag reference.

Generate test data (optional)

If you don’t have a live network segment to capture from, datagen populates ClickHouse with realistic synthetic hosts, clients, TLS handshakes, and certificates so you have something to look at immediately:

go run cmd/datagen/datagen.go -h localhost -p 19000 -U default -db insights \
  -d 30 -q 5000 -hosts 50 -clients 100

See datagen for all flags.

Run your first capture

To capture real traffic instead, run capture against a live interface (requires root/raw-socket privileges) or an existing PCAP file:

# Live TLS capture (needs sudo on most systems)
sudo go run ./cmd/capture tls -i eth0 -debug \
  -host localhost -port 19000 -db insights

# Or replay a PCAP file — no privileges required
go run ./cmd/capture tls -r /path/to/capture.pcap \
  -host localhost -port 19000 -db insights

capture is a multi-file package main (main.go plus one file per protocol), so it must be run as a directory (./cmd/capture), unlike the single-file tools below.

See capture for the other protocols (quic, ssh, ike, vpn, all) and their flags.

Run your first scan

Once hosts start showing up in the hosts table (either from capture or datagen), start hostsync to discover them and enqueue scan tasks, and tlsscand/nmapscand to process the queue:

go run cmd/hostsync/hostsync.go -c configs/hostsync.yaml -once
go run cmd/tlsscand/tlsscand.go -c configs/tlsscand.yaml -debug
go run cmd/nmapscand/nmapscand.go -c configs/nmapscand.yaml -debug

Or scan a single endpoint directly from the command line without going through the queue at all:

go run cmd/tlsscan/tlsscan.go https://example.com

View it in the dashboard

The dashboard is a Svelte app under web/dashboard. In development it proxies API calls to the insights server:

cd web/dashboard
npm install
npm run dev

Open the printed local URL (typically http://localhost:5173) and log in against the FusionAuth instance configured in configs/insights.yaml. See Dashboard for what each page shows.

All-in-one: devctl

For local development, devctl is a terminal UI that starts/stops every daemon (insights, capture, hostsync, tlsscand, nmapscand, scascand, pcapworker, notifyd, fingerprintd, the dashboard dev server, and the tlslab TLS test server) from one screen, streams their logs, and can fire off datagen or a synthetic-traffic generator on demand. Run it from the project root:

go run cmd/devctl/devctl.go

See devctl for details.

Dashboard