Awesome
JA4 Nginx
This fork of Nginx adds a small modification to the core of nginx to use in conjunction with the JA4 module. That means, to use the JA4 module, you'll need to use this fork of Nginx when compiling. Additionally, this fork requires a patched version of OpenSSL.
Getting Started
To run the JA4 module, you'll first need to pull it into this repository. Then, you'll need to pull the OpenSSL fork into this repository. After that, you can build the software and run the server.
Integrating the JA4 Module
Start by cloning the JA4 module into the root of this project.
git clone git@github.com:FoxIO-LLC/ja4-nginx-module.git
Now, the module code will be available when building nginx.
Integrating the OpenSSL Fork
The Nginx patch required by the JA4 module requires an OpenSSL patch. Clone it into the root of this project:
git clone git@github.com:FoxIO-LLC/ja4-openssl.git
Build
If you are using the OpenSSL fork, you will need to build with the following command:
./auto/configure --with-debug --with-compat --add-module=./ja4-nginx-module/src --with-http_ssl_module --with-openssl=$(pwd)/ja4-openssl --prefix=$(pwd)/nginx_local
make
make install
NOTE:
When you make changes to the nginx code or the module code, you only need to run make install
to rebuild the project.
Run Server
Nginx servers can be optionally configured with a custom nginx.conf file. This instructs the server how to responds to requests across different ports and controls other global settings. In ./nginx_utils
, there is a sample nginx.conf which returns the necessary JA4 fingerprint variables in a text response. Additionally, you will need there are server.crt
and server.key
files which are necessary for SSL connections and thus necessary for generating JA4 fingerprints. There is a handy command in the YaMakefile to generate locally signed versions of these files.
After building the software, copy ./nginx_utils/nginx.conf
and your server.crt
and server.key
files to ./nginx_local/conf
and then run the server with the following command:
sudo ./nginx_local/sbin/nginx -g "daemon off;"
Logging/Debugging
You can log data to nginx_local/logs/error.log
like this:
ngx_log_debug2(NGX_LOG_DEBUG_EVENT, pool->log, 0, "ssl_ja4: | cipher: 0x%04uxD -> %d", ja4->ciphers[i], ja4->ciphers[i]);
Parity with Nginx
When updates come into Nginx, we need to update our fork. We can simply do these by adding nginx as a remote upstream repository:
git remote add upstream git@github.com:nginx/nginx.git
Then, merging updates with our main branch:
git pull upstream master
git checkout main
git merge upstream/master
Creating a Patch
Because the JA4 module requires a small change to nginx core, we ship the module via GitHub releases along with a patch file. To create a patch file, make sure you have retrieved most recent nginx as specified in section: Parity with Nginx. Then:
(git diff upstream/master:src/event/ngx_event_openssl.c ./src/event/ngx_event_openssl.c && git diff upstream/master:src/event/ngx_event_openssl.h ./src/event/ngx_event_openssl.h && git diff upstream/master:src/http/modules/ngx_http_ssl_module.c ./src/http/modules/ngx_http_ssl_module.c)> ja4-nginx-module/patches/nginx.patch
Parity with OpenSSL
The JA4 nginx module also requires a patch to the underlying OpenSSL library which must included when compiling Nginx.
We need to maintain an updated fork of OpenSSL. We can simply do these by adding OpenSSL as a remote upstream repository:
ja4-openssl
should be cloned within this repository.
Then, add the official OpenSSL repository as a remote upstream repository:
cd ja4-openssl
git remote add upstream git@github.com:openssl/openssl.git
Then, merging updates with our master branch:
git pull upstream master
git checkout master
git merge upstream/master
Creating a Patch for OpenSSL
Because the JA4 module requires a small change to OpenSSL, we ship the module via GitHub releases along with a patch file. To create a patch file, make sure you have pulled most recent changes from OpenSSL as specified in section: Parity with OpenSSL. Then:
(git diff upstream/master:ssl/ssl_lib.c ./ssl/ssl_lib.c && git diff upstream/master:include/openssl/ssl.h.in ./include/openssl/ssl.h.in) > ../ja4-nginx-module/patches/openssl.patch
Architecture
Nginx Patch
File: src/event/ngx_event_openssl.h
Data Structure Modified: ngx_ssl_connection_s
Purpose: Adds some members to store data captured by TLS handshake for JA4 fingerprint.
File: src/event/ngx_event_openssl.c
Function Added: ngx_SSL_client_features
Purpose: Captures cipher suites and signature algorithms from the SSL handshake and stores them in the Nginx connection structure.
Function modified: ngx_ssl_handshake
Purpose: Does client hello callback to retrieve extensions. Calls ngx_SSL_client_features
to capture Cipher suites and signature algorithms. Collected data is added to ngx_ssl_connection_s
structure.
Function modified: ngx_SSL_early_cb_fn
Purpose: This callback function notably uses an OpenSSL API function we patched in: SSL_client_hello_getall_extensions_present
. It collects the extensions present in the ClientHello packet and collected data is added to ngx_ssl_connection_s
structure.
File: http/modules/ngx_http_ssl_module.c
Function Modified: ngx_http_ssl_alpn_select
Purpose: Stores the client's preferred ALPN value in the Nginx connection structure. Collected data is added to ngx_ssl_connection_s
structure.
OpenSSL Patch
Files: ssl/ssl_lib.c
and include/openssl/ssl.h.in
Function Added: SSL_client_hello_getall_extensions_present
Purpose: Adds a new function to the OpenSSL library to retrieve all extensions present in the ClientHello packet.