{"id":25883087,"url":"https://github.com/o-x-l/haproxy-ja4","last_synced_at":"2025-07-14T12:34:53.142Z","repository":{"id":253403849,"uuid":"843350099","full_name":"O-X-L/haproxy-ja4","owner":"O-X-L","description":"HAProxy (community) Lua Plugin for JA4 TLS Client-Fingerprinting","archived":false,"fork":false,"pushed_at":"2025-05-29T12:56:33.000Z","size":73,"stargazers_count":15,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"latest","last_synced_at":"2025-05-29T13:18:27.485Z","etag":null,"topics":["bot-detection","fingerprint","fingerprinting","haproxy","haproxy-plugin","ja3","ja3-fingerprint","ja4","ja4-fingerprint","lua","tls-fingerprint","waf","web-application-firewall","web-application-security"],"latest_commit_sha":null,"homepage":"https://docs.o-x-l.com/waf/2_fingerprinting.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/O-X-L.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"patreon":"OXL"}},"created_at":"2024-08-16T10:19:41.000Z","updated_at":"2025-05-29T12:56:37.000Z","dependencies_parsed_at":"2025-02-25T20:23:55.238Z","dependency_job_id":"b56ecc22-efc2-48bd-9245-b0afa0d55ff7","html_url":"https://github.com/O-X-L/haproxy-ja4","commit_stats":null,"previous_names":["o-x-l/haproxy-ja4"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/O-X-L/haproxy-ja4","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/O-X-L%2Fhaproxy-ja4","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/O-X-L%2Fhaproxy-ja4/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/O-X-L%2Fhaproxy-ja4/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/O-X-L%2Fhaproxy-ja4/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/O-X-L","download_url":"https://codeload.github.com/O-X-L/haproxy-ja4/tar.gz/refs/heads/latest","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/O-X-L%2Fhaproxy-ja4/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265291901,"owners_count":23741939,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot-detection","fingerprint","fingerprinting","haproxy","haproxy-plugin","ja3","ja3-fingerprint","ja4","ja4-fingerprint","lua","tls-fingerprint","waf","web-application-firewall","web-application-security"],"created_at":"2025-03-02T16:31:13.575Z","updated_at":"2025-07-14T12:34:53.134Z","avatar_url":"https://github.com/O-X-L.png","language":"Python","funding_links":["https://patreon.com/OXL"],"categories":[],"sub_categories":[],"readme":"# HAProxy - JA4 TLS Client-Fingerprint - Lua Plugin\n\nYou need to run [HAProxy 3.1 or higher](https://github.com/haproxy/haproxy/issues/2495) to use this plugin!\n\nIf 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')`\n\nTest it: [fingerprint.oxl.app](https://fingerprint.oxl.app)\n\n----\n\n## Intro\n\nAbout JA4:\n\n* [JA4 TLS details](https://github.com/FoxIO-LLC/ja4/blob/main/technical_details/JA4.md)\n* [Cloudflare Blog](https://blog.cloudflare.com/ja4-signals)\n* [FoxIO Blog](https://blog.foxio.io/ja4%2B-network-fingerprinting)\n* [FoxIO JA4 Database](https://ja4db.com/)\n* [JA4 Suite](https://github.com/FoxIO-LLC/ja4/blob/main/technical_details/README.md)\n* [JA4H HAProxy Lua Plugin](https://github.com/O-X-L/haproxy-ja4h)\n\nAbout JA3:\n* [JA3N HAProxy Lua Plugin](https://github.com/O-X-L/haproxy-ja3n)\n* [Salesforce Repository](https://github.com/salesforce/ja3)\n* [HAProxy Enterprise JA3 Fingerprint](https://customer-docs.haproxy.com/bot-management/client-fingerprinting/tls-fingerprint/)\n* [Why JA3 broke =\u003e JA3N](https://github.com/salesforce/ja3/issues/88)\n\nBrowser Fingerprinting:\n* [Browser Fingerprinting](https://github.com/O-X-L/browser-fingerprint)\n\n----\n\n## Usage\n\n* Add the LUA script `ja4.lua` to your system\n\n## Config\n\n* Enable SSL/TLS capture with the global setting [tune.ssl.capture-buffer-size 192](https://www.haproxy.com/documentation/haproxy-configuration-manual/latest/#tune.ssl.capture-buffer-size)\n* Load the LUA module by adding `lua-load /etc/haproxy/lua/ja4.lua` in the `global` section\n* Execute the LUA script on HTTP requests: `http-request lua.fingerprint_ja4`\n* Log the fingerprint: `http-request capture var(txn.fingerprint_ja4) len 36`\n\n### JA4 Database\n\nYou can use [the DB to MAP script](https://github.com/O-X-L/haproxy-ja4/blob/latest/ja4db-to-map.py) to create a HAProxy Mapfile from the [FoxIO JA4-Database](https://ja4db.com/):\n\nWARNING: The exact versions of client-applications may vary.\n\n```bash\n# download the database\ncurl -s https://ja4db.com/api/read/ -o ja4db.json\n\n# build the map-file\npython3 ja4db-dedupe.py\npython3 ja4db-to-map.py\n\n# examples:\n\u003e 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\n\u003e t13d1516h2_8daaf6152771_02713d6af862 Chromium_Browser\n```\n\nYou can enable lookups like this: `http-request set-var(txn.fingerprint_app) var(txn.fingerprint_ja4),map(/tmp/haproxy_ja4.map)`\n\nAnd log the results like this: `http-request capture var(txn.fingerprint_app) len 200`\n\n----\n\n## License\n\nThis script is licensed under the MIT-license and thus is free to use.\n\nThe JA4 algorithm is licensed under the `BSD 3-Clause` license and also free to use - see: [FoxIO-LLC/ja4](https://github.com/FoxIO-LLC/ja4?tab=readme-ov-file#licensing)\n\n----\n\n## Contribute\n\nIf you have:\n\n* Found an issue/bug - please [report it](https://github.com/O-X-L/haproxy-ja4/issues/new)\n* Have an idea on how to improve it - [feel free to start a discussion](https://github.com/O-X-L/haproxy-ja4/discussions/new/choose)\n* PRs are welcome\n\nPlease [read the JA4 TLS details](https://github.com/FoxIO-LLC/ja4/blob/main/technical_details/JA4.md)!\n\n### Testing\n\nExample:\n```\nFINGERPRINT\nt13d1713h2_5b57614c22b0_748f4c70de1c\n\nAPP FROM DB\nMozilla/5.0_(Android_14;_Mobile;_rv:126.0)_Gecko/126.0_Firefox/126.0\n\nDEBUG\nraw 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 \n```\n\n#### Docker\n\nIf you prefer to use Docker, the manual steps can be skipped.\nRun the docker container from the project root and access https://localhost:6969\n\n```bash\ndocker compose -f test/docker-compose.yaml up --build --watch\n```\n\n`--watch` will automatically rebuild the container on changes\n\n#### Local\n\n**WARNING**: You need to run a version of HAProxy \u003e=3.1 or `master` \n\n* Run: `bash test/run.sh`\n* Access the test website: https://localhost:6969/\n* Or query the API: `curl -v https://localhost:6969/api`\n\n  ```json\n  {\n    \"fingerprint\": \"t13d1517h2_8daaf6152771_b6f405a00624\",\n    \"details\": \"t_13_d_15_17_h2_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0005,000a,000b,000d,0012,0017,001b,0023,0029,002b,002d,0033,44cd,fe0d,ff01_0403,0804,0401,0503,0805,0501,0806,0601\",\n    \"app\": \"Chrome 136\"\n  }\n  ```\n\nExit with `CTRL+C`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fo-x-l%2Fhaproxy-ja4","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fo-x-l%2Fhaproxy-ja4","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fo-x-l%2Fhaproxy-ja4/lists"}