Draft
Conversation
Member
Author
|
[approve ci osx] |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a new experimental Apache Traffic Server plugin, jax_fingerprint, intended to generate configurable client fingerprints (JA4, JA3, and partial JA4H) and optionally inject them into request headers and/or a dedicated plugin log, with optional SNI allowlisting and remap-rule scoping.
Changes:
- Add a new experimental plugin implementation (
plugins/experimental/jax_fingerprint/*) including JA3/JA4/JA4H fingerprinting logic and header/log emission helpers. - Add unit tests for the embedded JA3/JA4 helper logic and integrate the plugin into the experimental build.
- Add admin documentation for the plugin and link it from the plugin index.
Reviewed changes
Copilot reviewed 31 out of 31 changed files in this pull request and generated 30 comments.
Show a summary per file
| File | Description |
|---|---|
| plugins/experimental/jax_fingerprint/plugin.cc | Plugin entrypoints, hook handling, remap integration, option parsing |
| plugins/experimental/jax_fingerprint/plugin.h | Plugin constants and debug control declaration |
| plugins/experimental/jax_fingerprint/config.h | Plugin configuration struct and servername set hashing |
| plugins/experimental/jax_fingerprint/context.cc | Per-connection/txn context storage (fingerprint, client address) |
| plugins/experimental/jax_fingerprint/context.h | Context class definition |
| plugins/experimental/jax_fingerprint/userarg.cc | User-arg reserve/lookup/set/get helpers |
| plugins/experimental/jax_fingerprint/userarg.h | User-arg helper declarations |
| plugins/experimental/jax_fingerprint/header.cc | Request header add/replace/append/remove logic |
| plugins/experimental/jax_fingerprint/header.h | Header helper declarations |
| plugins/experimental/jax_fingerprint/log.cc | Text log object creation and write helper |
| plugins/experimental/jax_fingerprint/log.h | Log helper declarations |
| plugins/experimental/jax_fingerprint/method.h | Fingerprinting method abstraction (handlers + type) |
| plugins/experimental/jax_fingerprint/ja4/ja4.cc | JA4 fingerprint string construction utilities |
| plugins/experimental/jax_fingerprint/ja4/ja4.h | JA4 data structures and APIs |
| plugins/experimental/jax_fingerprint/ja4/tls_client_hello_summary.cc | TLS client hello summary accumulation for JA4 |
| plugins/experimental/jax_fingerprint/ja4/ja4_method.cc | JA4 method integration with TSClientHello |
| plugins/experimental/jax_fingerprint/ja4/ja4_method.h | JA4 method declaration |
| plugins/experimental/jax_fingerprint/ja4/test_ja4.cc | JA4 unit tests (Catch2) |
| plugins/experimental/jax_fingerprint/ja3/ja3_utils.cc | JA3 encoding helpers |
| plugins/experimental/jax_fingerprint/ja3/ja3_utils.h | JA3 encoding helper declarations |
| plugins/experimental/jax_fingerprint/ja3/ja3_method.cc | JA3 method integration with TSClientHello |
| plugins/experimental/jax_fingerprint/ja3/ja3_method.h | JA3 method declaration |
| plugins/experimental/jax_fingerprint/ja3/test_ja3.cc | JA3 unit tests (Catch2) |
| plugins/experimental/jax_fingerprint/ja4h/ja4h.cc | JA4H request-header extractor utilities |
| plugins/experimental/jax_fingerprint/ja4h/ja4h.h | JA4H extractor class declaration |
| plugins/experimental/jax_fingerprint/ja4h/ja4h_method.cc | JA4H fingerprint construction from HTTP request properties |
| plugins/experimental/jax_fingerprint/ja4h/ja4h_method.h | JA4H method declaration |
| plugins/experimental/jax_fingerprint/CMakeLists.txt | Build rules for the plugin and tests |
| plugins/experimental/CMakeLists.txt | Adds jax_fingerprint subdirectory under experimental plugins |
| doc/admin-guide/plugins/jax_fingerprint.en.rst | New admin documentation for the plugin |
| doc/admin-guide/plugins/index.en.rst | Adds jax_fingerprint to the experimental plugin index |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a new experimental jax_fingerprint plugin that can generate multiple TLS/client fingerprints (JA4, JA4H partial, JA3) with flexible output controls (headers/logging) and optional SNI-based filtering, and wires it into the build and admin documentation.
Changes:
- Add the
jax_fingerprintexperimental plugin implementation (config parsing, per-txn/per-connection context handling, header mutation, logging). - Add JA3/JA4/JA4H fingerprinting implementations (JA4/JA3 include Catch2 unit tests).
- Integrate the plugin into CMake build options and add admin-guide documentation.
Reviewed changes
Copilot reviewed 32 out of 32 changed files in this pull request and generated 16 comments.
Show a summary per file
| File | Description |
|---|---|
| plugins/experimental/jax_fingerprint/CMakeLists.txt | Builds the plugin and unit tests |
| plugins/experimental/jax_fingerprint/plugin.cc | Main plugin/remap entrypoints, config parsing, hooks |
| plugins/experimental/jax_fingerprint/plugin.h | Plugin metadata + debug tag |
| plugins/experimental/jax_fingerprint/config.h | Plugin configuration struct and SNI set |
| plugins/experimental/jax_fingerprint/method.h | Abstraction for per-method callbacks |
| plugins/experimental/jax_fingerprint/context.cc | Per-connection/txn context + address formatting |
| plugins/experimental/jax_fingerprint/context.h | Context interface |
| plugins/experimental/jax_fingerprint/userarg.cc | TS user-arg reserve/lookup + get/set helpers |
| plugins/experimental/jax_fingerprint/userarg.h | User-arg helper declarations |
| plugins/experimental/jax_fingerprint/header.cc | Request header add/append/overwrite/remove helpers |
| plugins/experimental/jax_fingerprint/header.h | Header helper declarations |
| plugins/experimental/jax_fingerprint/log.cc | Text log creation and write |
| plugins/experimental/jax_fingerprint/log.h | Logging helper declarations |
| plugins/experimental/jax_fingerprint/ja4/ja4.cc | JA4 raw portions + fingerprint assembly |
| plugins/experimental/jax_fingerprint/ja4/ja4.h | JA4 types + template fingerprint builder |
| plugins/experimental/jax_fingerprint/ja4/ja4_method.cc | JA4 hook implementation (client hello parsing + SHA256) |
| plugins/experimental/jax_fingerprint/ja4/ja4_method.h | JA4 method declaration |
| plugins/experimental/jax_fingerprint/ja4/tls_client_hello_summary.cc | JA4 TLS summary helpers (ciphers/extensions/SNI) |
| plugins/experimental/jax_fingerprint/ja4/test_ja4.cc | Catch2 unit tests for JA4 |
| plugins/experimental/jax_fingerprint/ja3/ja3_method.cc | JA3 hook implementation (client hello parsing + MD5) |
| plugins/experimental/jax_fingerprint/ja3/ja3_method.h | JA3 method declaration |
| plugins/experimental/jax_fingerprint/ja3/ja3_utils.cc | JA3 buffer encoding helpers |
| plugins/experimental/jax_fingerprint/ja3/ja3_utils.h | JA3 encoding helper declarations |
| plugins/experimental/jax_fingerprint/ja3/test_ja3.cc | Catch2 unit tests for JA3 utils |
| plugins/experimental/jax_fingerprint/ja4h/ja4h.cc | HTTP-request extractor for JA4H inputs |
| plugins/experimental/jax_fingerprint/ja4h/ja4h.h | Extractor class declaration |
| plugins/experimental/jax_fingerprint/ja4h/ja4h_method.cc | JA4H method implementation (partial) |
| plugins/experimental/jax_fingerprint/ja4h/ja4h_method.h | JA4H method declaration |
| plugins/experimental/CMakeLists.txt | Adds BUILD_JAX_FINGERPRINT subdir toggle |
| cmake/ExperimentalPlugins.cmake | Adds BUILD_JAX_FINGERPRINT option |
| doc/admin-guide/plugins/jax_fingerprint.en.rst | New admin documentation for plugin usage/options |
| doc/admin-guide/plugins/index.en.rst | Adds plugin to admin-guide index |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds an experimental plugin jax_fingerprint. The basic functionality is the same as ja3_fingerprint and ja4_fingerprint, but the configuration is more flexible.
jax_fingerprint plugin supports multiple fingerprinting methods, JA4 and JA3. The code to generate fingerprint was copied from the existing plugins. It partially supports JA4H as well. I only implemented the
JA4H_aandJA4H_b.JA4H_candJA4H_dare filled with0s.All the outputs, HTTP headers and logging, are disabled by default. You can selectively enable them by specifying header names or a log file name. Also you can choose how the plugin deal with headers from clients. You can keep the original header intact, overwrite it, or append a new value.
A completely new feature is generating fingerprints only for specified server names (SNI). You can pass a list of server names. And of course you can set headers only on specified paths (remap rules) by setting up the plugin as a remap plugin.
The plugin can be used with either OpenSSL or BoringSSL (the existing ja3 plugin does not work with BoringSSL).
All the features are available regardless of fingerprinting methods.