capture

Purpose

capture passively captures handshakes for five protocols — TLS, QUIC (HTTP/3), SSH, IKE/IPsec, and OpenVPN — either from a live network interface or from a PCAP file, and writes extracted metadata to ClickHouse. It never needs private keys and never decrypts payload; it only parses the cleartext parts of each handshake (ClientHello, key-exchange algorithms, certificates, banners) to fingerprint the connection.

On Linux, live capture uses raw AF_PACKET sockets; on macOS/BSD it uses libpcap (BPF).

Usage

capture <command> [options]

Command	Captures
`tls`	TLS/SSL handshakes (ClientHello/ServerHello)
`quic`	QUIC/HTTP3 handshakes (ClientHello extracted from Initial packets)
`ssh`	SSH connections and key exchanges
`ike`	IKE/IPsec negotiations
`vpn`	OpenVPN connections
`all`	All of the above simultaneously
`version`	Print the tool version
`help`	Print usage

Options common to the protocol subcommands:

Flag	Description
`-c <file>`	Path to a YAML configuration file
`-i <interface>`	Network interface to capture from
`-r <file>`	Read packets from a PCAP file instead of a live interface
`-ports <list>`	Comma-separated list of ports to capture (per-protocol default if omitted: TLS 443, SSH 22, QUIC 443, IKE 500/4500, VPN 1194)
`-debug`	Enable debug logging
`-batch <size>`	Batch size for ClickHouse inserts
`-host <host>`	ClickHouse host
`-port <port>`	ClickHouse port
`-db <database>`	ClickHouse database
`-dbuser <user>`	ClickHouse username
`-dbpass <pass>`	ClickHouse password
`-redis-host <host>`	Redis host, for heartbeat/status reporting
`-redis-port <port>`	Redis port, for heartbeat/status reporting
`-noheartbeat`	Disable heartbeat reporting to Redis

capture all additionally accepts per-protocol port lists — -tls-ports, -quic-ports, -ssh-ports, -ike-ports, -vpn-ports — since -ports alone would be ambiguous across five protocols.

Configuration file

Instead of (or in addition to) CLI flags, capture reads configs/capture.yaml:

pcapfile: ""
batchsize: 1

enable_tls: true
enable_quic: true
enable_ssh: true
enable_ike: true
enable_vpn: true

tls_ports: [443, 8443, 4450, 4451, 4452, 4453]
quic_ports: [443, 8443]
ssh_ports: [22]
ike_ports: [500, 4500]
vpn_ports: [1194]

debug: false

clickhouse:
  host: localhost
  port: 19000
  database: insights
  username: insights
  password: "secret"

redis:
  host: localhost
  port: 6379
  channel: insights

Internal-network classification and traffic direction filtering (internal_networks, direction_filter) are not set in this file — they live in the ClickHouse config table, editable from the dashboard or directly:

INSERT INTO config (key, values) VALUES ('internal_networks', ['10.0.0.0/8', '192.168.0.0/16']);
INSERT INTO config (key, values) VALUES ('direction_filter', ['inbound']);

Examples

# Capture TLS handshakes live from eth0
sudo capture tls -i eth0 -debug

# Capture QUIC/HTTP3 handshakes
sudo capture quic -i eth0 -debug

# Capture TLS with heartbeat/status reporting to Redis
sudo capture tls -i eth0 -redis-host localhost -redis-port 6379

# Capture SSH connections from a PCAP file (no privileges needed)
capture ssh -r traffic.pcap

# Capture IKE/IPsec on non-default ports
sudo capture ike -i eth0 -ports 500,4500,10500

# Capture OpenVPN traffic
sudo capture vpn -i eth0 -ports 1194

# Capture all five protocols at once, driven by a config file
sudo capture all -i eth0 -c configs/capture.yaml

To generate a test PCAP with TLS ClientHello traffic for replay:

sudo tcpdump -i enp4s0 \
  "tcp port 443 and (tcp[((tcp[12] & 0xf0) >>2)] = 0x16) && (tcp[((tcp[12] & 0xf0) >>2)+5] = 0x01)" \
  -w sample.pcap

insights hostsync