Skip to content

Add JA4 TLS fingerprints to the Zeek sensor #776

Closed

Description

@Gerrrt

#437 asked for TLS metadata without decryption, and named JA3/JA3S. fenrir now logs SNI, certificate subjects and issuers, and chain validation (ssl.log, x509.log), but not fingerprints: the stock zeek/zeek:9.0.0 image in stacks/sensor ships no JA3 or JA4 script. ADR-0068 and stacks/sensor/zeek/local.zeek both record the gap.

Why JA4, not JA3

JA3 hashes the ClientHello's extension order, and browsers have randomised that order since 2023, so one client produces many JA3 hashes. JA4 sorts before hashing. The Zeek implementation is FoxIO's package, zkg install zeek/foxio/ja4.

Check the licence before choosing what to load. JA4 itself (the TLS client fingerprint) is BSD-3. The rest of JA4+ (JA4S, JA4H, JA4X, JA4SSH and the others) is under the FoxIO License 1.1. That is likely fine for a home lab, but the decision should name it.

The decision this needs

Nothing in this repository builds an image. Every image is pulled and digest-pinned from a compose.yaml, and scripts/check_image_pins.py enforces that. A zkg package has to get into the container somehow:

  1. A derived image built here: a build: in stacks/sensor/compose.yaml, FROM the pinned digest, plus zkg install at a pinned package version. This is the first locally built image in the estate. check_image_pins.py, check_compose_health.py --probe and Dependabot would each need to learn about it.
  2. Install at start into a volume: zkg install in an entrypoint wrapper. No new tooling, but what runs is whatever the package index served that day, which is the unpinned state the pinning rules exist to prevent.
  3. A published image that already includes it. Use one only if a maintained, digest-pinnable one exists.

Option 1 looks right, but it changes repository policy, so it should be an ADR rather than a line in a compose file.

Done when

  • ssl.log (or ja4*.log) on fenrir carries a JA4 for a guest's outbound TLS.
  • {job="zeek"} | json | ja4 != "" returns lines in the lab's Loki.
  • local.zeek's "JA4 fingerprints are not in the stock image" comment is removed, ADR-0068 gets a NOTE, and the changelog records the result.

Follows #437.

Activity

  1. added
    featureA new capability or a change
    socstacks/soc on odin (VLAN 30)
    on Oct 1, 2026
  2. Gerrrt commented on Oct 1, 2026

    @Gerrrt
    OwnerAuthor

    Reopened. It closed when #780 merged, but #780 only recorded the decision (ADR-0069) and said Refs #776. The implementation hasn't landed: the vendored ja4-zeek-scripts with LICENSE, LICENSE-JA4 and NOTICE, the read-only mount, the @load, scripts/vendor-ja4.sh, and the before/after loss measurement. The baseline is now about 0% after #782's GRO fix, rather than the 8.1% ADR-0069 first recorded.

  3. reopened this on Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureA new capability or a changesocstacks/soc on odin (VLAN 30)

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions