vncloudsco/ja4-nginx-module
GitHub: vncloudsco/ja4-nginx-module
一个专为 Nginx 设计的第三方模块，通过提取 TLS、HTTP 和 TCP 的 JA4 指纹来实现精细化客户端识别与安全分析。
Stars: 24 | Forks: 6
# JA4 Nginx 模块
## 概述
此 Nginx 模块针对 HTTP 和 TLS 客户端实现了 **JA4**、**JA4H**、**JA4TCP** 和 **JA4one** 指纹识别标准。它使您能够根据传入请求的 TLS 握手、HTTP 标头和 TCP 特征来识别和提取其指纹。
该模块专为以下用途设计：
- **安全性：** 检测机器人、网络爬虫和恶意工具。
- **分析：** 记录客户端类型以进行流量分析。
## ⚠️ 自定义实现说明
**重要提示：** 此实现为指纹组件使用了 **完整的 SHA256 哈希值（64 个字符）**，而不是原始 JA4 规范中定义的标准截断 12 字符哈希值。
- **为什么？** 根据用户要求，提供最大的抗碰撞性和完整的密码学细节。
- **结果：** 此模块生成的指纹将比标准 JA4 字符串长得多。
## 功能
- **JA4 (TLS)**：对 TLS Client Hello（版本、密码套件、扩展等）进行指纹识别。
- **JA4H (HTTP)**：对 HTTP 标头（方法、版本、Cookie、标头顺序）进行指纹识别。
- **JA4S (HTTP/2)**：对 HTTP/2 连接状态（窗口大小、帧大小）进行指纹识别。
- **JA4TCP (TCP)**：对 TCP 特征（窗口大小、选项、标志、TTL）进行指纹识别。
- **JA4one (复合)**：一种组合指纹（`JA4_JA4H`），提供对客户端（TLS + HTTP）的整体视图。
- **变量：** 将指纹作为 Nginx 变量公开，以便进行日志记录或 Lua 脚本编写。
## 性能基准测试
以下基准测试展示了 JA4 模块对 Nginx 性能的影响。
**结论**：该模块经过高度优化，在典型场景中引入的**开销微乎其微或无法测量**。在某些测试运行中，由于系统方差，带有模块的路径甚至可能显得更快，这证明它不会阻塞或显著减慢请求处理速度。
**测试环境**：
- **连接数**：100 个并发
- **持续时间**：30秒
- **线程数**：4
| 指标 | 含义（目标） | 无模块（基线） | 有模块 | 性能差异 | 解释 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Requests/sec** | 容量（越高越好） | 12,817 | 13,321 | **+3.93%** | ✅ 无性能下降 |
| **Avg Latency** | 速度（越低越好） | 9.34ms | 8.80ms | **-0.54ms** | ✅ 无性能下降 |
| **p99 Latency** | 最慢的 1%（越低越好） | 24.33ms | 22.45ms | **-1.88ms** | ✅ 无性能下降 |
*注：基准测试在虚拟化环境中运行；预计会有微小的方差（<5%）。*
## 安装说明
### 依赖项
- Nginx 源代码（已使用 1.27.3+ 版本测试）
- OpenSSL（开发头文件）
### 编译
使用指向此目录的 `--add-module` 标志配置 Nginx：
```
./configure --with-compat --add-module=/path/to/ja4-nginx-module --with-http_ssl_module
make
make install
```
## 配置
### 1. 变量与日志记录
该模块公开了以下变量：
- `$http_ssl_ja4`：TLS 指纹。
- `$http_ssl_ja4h`：HTTP 指纹。
- `$http_ssl_ja4s`：HTTP/2 指纹（JA4S）。
- `$http_ssl_ja4tcp`：TCP 指纹。
- `$http_ssl_ja4one`：复合指纹。
将它们添加到您的 `log_format` 中：
```
http {
log_format ja4_log '$remote_addr - [$time_local] "$request" '
'JA4="$http_ssl_ja4" JA4H="$http_ssl_ja4h" '
'JA4S="$http_ssl_ja4s" JA4TCP="$http_ssl_ja4tcp" JA4one="$http_ssl_ja4one"';
access_log logs/ja4.log ja4_log;
}
```
## 指纹格式（自定义）
由于采用了完整哈希值的修改，其格式如下：
- **JA4**：`t13d1516h2_<64-char-cipher-hash>_<64-char-extension-hash>`
- **JA4H**：`ge11n03_<64-char-header-hash>`
- `ge`：GET 方法
- `11`：HTTP 1.1
- `n`：无 Cookie
- `03`：3 个标头
- **JA4S**：`h2____0`
- 示例：`h220_02_70946d4d1524_10485760_0`
- `ver`：协议版本（20 = HTTP/2.0）
- `cnt`：设置数量（02 = No-Patch 模式下的常量）
- `hash`：Window 和 Frame Size 的 SHA256 值
- `window`：初始窗口大小
- **JA4TCP**：`___`
- 示例：`65535_2-4-8-3_1460_7`
- `window`：TCP 窗口大小（十进制）
- `option_kinds`：按顺序排列的 TCP 选项类型（十进制，以破折号分隔，包含 NOP）
- `mss`：最大分段大小（十进制）
- `scale`：窗口扩大因子（十进制）
- **JA4one**：`[JA4]_[JA4H]`（拼接）
## 使用示例
### 示例 1：分析与监控
记录所有指纹以进行流量分析：
```
http {
# Define comprehensive logging format
log_format fingerprint_analytics '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'JA4="$http_ssl_ja4" '
'JA4H="$http_ssl_ja4h" '
'JA4TCP="$http_ssl_ja4tcp" '
'JA4one="$http_ssl_ja4one"';
server {
listen 443 ssl;
server_name analytics.example.com;
# Log to special file
access_log /var/log/nginx/fingerprints.log fingerprint_analytics;
location / {
return 200 "Logged";
}
}
}
```
### 示例 2：基于指纹的速率限制
将指纹与 Lua/OpenResty 结合使用以实现高级速率限制：
```
http {
lua_shared_dict fingerprint_limit 10m;
server {
listen 443 ssl;
location /api/ {
access_by_lua_block {
local limit = require "resty.limit.req"
local fingerprint = ngx.var.http_ssl_ja4one or "unknown"
-- Different limits based on fingerprint
local lim, err = limit.new("fingerprint_limit", 10, 5)
if not lim then
ngx.log(ngx.ERR, "failed to instantiate limit.req: ", err)
return ngx.exit(500)
end
local key = fingerprint
local delay, err = lim:incoming(key, true)
if not delay then
if err == "rejected" then
return ngx.exit(429)
end
return ngx.exit(500)
end
}
proxy_pass http://backend;
}
}
}
```
### 示例 3：基于指纹类型的条件访问
针对不同的客户端类型实施不同的行为：
```
map $http_ssl_ja4tcp $client_type {
default "unknown";
"~^65535_" "modern_client";
"~^1024_" "legacy_client";
"~^8192_" "suspicious";
}
server {
listen 443 ssl;
location / {
# Redirect suspicious clients to captcha
if ($client_type = "suspicious") {
return 302 /captcha;
}
# Limit features for legacy clients
if ($client_type = "legacy_client") {
return 301 /legacy-version;
}
# Full access for modern clients
proxy_pass http://backend;
}
location /captcha {
return 200 "Please verify you are human";
}
}
```
## 故障排除
- **缺少 JA4？** 确保您通过 **HTTPS** 进行连接。普通的 HTTP 请求没有 TLS 握手，因此 `$http_ssl_ja4` 将为空。
- **缺少 JA4S？** 仅对 **HTTP/2** 连接可用。请检查客户端是否支持 H2，以及是否启用了 NGINX 的 `http2` 功能。
- **缺少 JA4TCP？** JA4TCP 需要访问原始 TCP 连接数据。请确保 NGINX 在运行时带有 `--with-http_realip_module` 并进行了正确的网络配置。如果使用 Docker，请使用 `--network host` 模式以获取准确的 TCP 指纹。
- **短哈希值？** 如果您看到的是 12 个字符的哈希值，说明您正在运行标准版本。如果需要完整的哈希值，请使用修改后的通用哈希长度重新编译。
## 许可证
MIT License。
该模块专为以下用途设计：
- **安全性：** 检测机器人、网络爬虫和恶意工具。
- **分析：** 记录客户端类型以进行流量分析。
## ⚠️ 自定义实现说明
**重要提示：** 此实现为指纹组件使用了 **完整的 SHA256 哈希值（64 个字符）**，而不是原始 JA4 规范中定义的标准截断 12 字符哈希值。
- **为什么？** 根据用户要求，提供最大的抗碰撞性和完整的密码学细节。
- **结果：** 此模块生成的指纹将比标准 JA4 字符串长得多。
## 功能
- **JA4 (TLS)**：对 TLS Client Hello（版本、密码套件、扩展等）进行指纹识别。
- **JA4H (HTTP)**：对 HTTP 标头（方法、版本、Cookie、标头顺序）进行指纹识别。
- **JA4S (HTTP/2)**：对 HTTP/2 连接状态（窗口大小、帧大小）进行指纹识别。
- **JA4TCP (TCP)**：对 TCP 特征（窗口大小、选项、标志、TTL）进行指纹识别。
- **JA4one (复合)**：一种组合指纹（`JA4_JA4H`），提供对客户端（TLS + HTTP）的整体视图。
- **变量：** 将指纹作为 Nginx 变量公开，以便进行日志记录或 Lua 脚本编写。
## 性能基准测试
以下基准测试展示了 JA4 模块对 Nginx 性能的影响。
**结论**：该模块经过高度优化，在典型场景中引入的**开销微乎其微或无法测量**。在某些测试运行中，由于系统方差，带有模块的路径甚至可能显得更快，这证明它不会阻塞或显著减慢请求处理速度。
**测试环境**：
- **连接数**：100 个并发
- **持续时间**：30秒
- **线程数**：4
| 指标 | 含义（目标） | 无模块（基线） | 有模块 | 性能差异 | 解释 |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Requests/sec** | 容量（越高越好） | 12,817 | 13,321 | **+3.93%** | ✅ 无性能下降 |
| **Avg Latency** | 速度（越低越好） | 9.34ms | 8.80ms | **-0.54ms** | ✅ 无性能下降 |
| **p99 Latency** | 最慢的 1%（越低越好） | 24.33ms | 22.45ms | **-1.88ms** | ✅ 无性能下降 |
*注：基准测试在虚拟化环境中运行；预计会有微小的方差（<5%）。*
## 安装说明
### 依赖项
- Nginx 源代码（已使用 1.27.3+ 版本测试）
- OpenSSL（开发头文件）
### 编译
使用指向此目录的 `--add-module` 标志配置 Nginx：
```
./configure --with-compat --add-module=/path/to/ja4-nginx-module --with-http_ssl_module
make
make install
```
## 配置
### 1. 变量与日志记录
该模块公开了以下变量：
- `$http_ssl_ja4`：TLS 指纹。
- `$http_ssl_ja4h`：HTTP 指纹。
- `$http_ssl_ja4s`：HTTP/2 指纹（JA4S）。
- `$http_ssl_ja4tcp`：TCP 指纹。
- `$http_ssl_ja4one`：复合指纹。
将它们添加到您的 `log_format` 中：
```
http {
log_format ja4_log '$remote_addr - [$time_local] "$request" '
'JA4="$http_ssl_ja4" JA4H="$http_ssl_ja4h" '
'JA4S="$http_ssl_ja4s" JA4TCP="$http_ssl_ja4tcp" JA4one="$http_ssl_ja4one"';
access_log logs/ja4.log ja4_log;
}
```
## 指纹格式（自定义）
由于采用了完整哈希值的修改，其格式如下：
- **JA4**：`t13d1516h2_<64-char-cipher-hash>_<64-char-extension-hash>`
- **JA4H**：`ge11n03_<64-char-header-hash>`
- `ge`：GET 方法
- `11`：HTTP 1.1
- `n`：无 Cookie
- `03`：3 个标头
- **JA4S**：`h2标签：AMSI绕过, Bot检测, DLL注入, HTTP/2指纹, HTTP指纹, IP 地址批量处理, JA4指纹, Nginx模块, Open Source, Radare2, rizin, TCP指纹, TLS Client Hello, TLS指纹, 反向代理, 威胁检测, 安全测试工具, 客户端加密, 客户端指纹识别, 密码管理, 恶意工具检测, 流量审计, 深度包检测, 爬虫检测, 网络安全, 网络安全分析, 网络指纹, 隐私保护