ja3import

Purpose

ja3import populates ClickHouse’s JA3 fingerprint tables (ja3_fingerprints, ja3_malicious) from three sources: a built-in list of common browser/tool fingerprints, the Trisul JA3 fingerprint database, and abuse.ch’s SSLBL malicious-JA3 feed. It can also import from a local CSV seed file. These tables are what capture and the dashboard use to label a TLS client as a known browser, tool, or malware family.

Usage

ja3import -c <config.yaml> [-seed <file.csv>] [-debug]

Flag	Description
`-c`	Path to config file (required)
`-seed`	Path to a CSV seed file to import fingerprints from
`-debug`	Enable debug logging

Configuration

name: ja3import
clickhouse:
  host: localhost
  port: 19000
  database: insights
  username: insights
  password: secret
debug: false

The Trisul and SSLBL source URLs are not set in this file — they’re read from the ClickHouse config table (keys ja3_trisul_url and ja3_sslbl_url), so they can be changed without redeploying.

Every run imports, in order: (1) the built-in common-browser fingerprints, (2) the CSV seed file if -seed is given, (3) Trisul fingerprints, (4) SSLBL malicious fingerprints. A failure in one source is logged but does not stop the others from running.

Seed CSV format

ja3_hash,description,category,os,tls_library

ja3_hash must be exactly 32 hex characters; malformed rows are skipped.

Examples

# Import from the online sources (Trisul + SSLBL) plus common browsers
ja3import -c configs/ja3import.yaml

# Also import a local seed file
ja3import -c configs/ja3import.yaml -seed test/data/ja3_fingerprints_seed.csv

datagen fingerprintd