README.md

HAProxy - JA4 TLS Client-Fingerprint - Lua Plugin

You need to run HAProxy 3.1 or higher to use this plugin!

If the needed features are not yet available in your version - it will fail with the error attempt to call a nil value (method 'ssl_fc_supported_versions_bin')

---

Intro

About JA4:

• JA4 TLS details
• Cloudflare Blog
• FoxIO Blog
• FoxIO JA4 Database
• JA4 Suite

About JA3:

• HAProxy Lua Plugin (JA3N)
• Salesforce Repository
• HAProxy Enterprise JA3 Fingerprint
• Why JA3 broke => JA3N

---

Usage

• Add the LUA script ja4.lua to your system

Config

• Enable SSL/TLS capture with the global setting tune.ssl.capture-buffer-size 128
• Load the LUA module by adding lua-load /etc/haproxy/lua/ja4.lua in the global section
• Execute the LUA script on HTTP requests: http-request lua.fingerprint_ja4
• Log the fingerprint: http-request capture var(txn.fingerprint_ja4) len 36

JA4 Database

You can use the DB to MAP script to create a HAProxy Mapfile from the FoxIO JA4-Database:

WARNING: The exact versions of client-applications may vary.

# download the database
curl -s https://ja4db.com/api/read/ -o ja4db.json

# build the map-file
python3 ja4db-dedupe.py
python3 ja4db-to-map.py

# examples:
> t13d1517h2_8daaf6152771_b0da82dd1658 Mozilla/5.0_(Windows_NT_10.0;_Win64;_x64)_AppleWebKit/537.36_(KHTML,_like_Gecko)_Chrome/125.0.0.0_Safari/537.36
> t13d1516h2_8daaf6152771_02713d6af862 Chromium_Browser

You can enable lookups like this: http-request set-var(txn.fingerprint_app) var(txn.fingerprint_ja4),map(/tmp/haproxy_ja4.map)

And log the results like this: http-request capture var(txn.fingerprint_app) len 200

---

Contribute

If you have:

• Found an issue/bug - please report it
• Have an idea on how to improve it - feel free to start a discussion
• PRs are welcome

Please read the JA4 TLS details!

Testing

Example:

FINGERPRINT
t13d1713h2_5b57614c22b0_748f4c70de1c

APP FROM DB
Mozilla/5.0_(Android_14;_Mobile;_rv:126.0)_Gecko/126.0_Firefox/126.0

DEBUG
raw fingerprint: t_13_d_17_13_h2_002f,0035,009c,009d,1301,1302,1303,c009,c00a,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0005,000a,000b,000d,0017,001c,0022,002b,0033,fe0d,ff01_0403,0503,0603,0804,0805,0806,0401,0501,0601,0203,0201 

Docker

If you prefer to use Docker, the manual steps can be skipped. Run the docker container from the project root and access https://localhost:6969

docker compose -f test/docker-compose.yaml up --build --watch

--watch will automatically rebuild the container on changes

Local

WARNING: You need to run a version of HAProxy >=3.1 or master

• Run: bash test/run.sh
• Access the test website: https://localhost:6969/

Exit with CTRL+C