Skip to content
geekbyterPublic

About

spoof client tls(ja3,ja4,http2.0,http3.0,quic,tcp,clienthello....more)

Topics

Resources

Stars

19 stars

Watchers

0 watching

Forks

Repository files navigation

geektls

多语言 TLS/HTTP 全栈指纹伪造库:对 ClientHello 逐字节可控,覆盖 TLS(JA3/JA4)、HTTP/2(Akamai 指纹 + HPACK 编码策略)、HTTP/3 + QUIC、TCP 四层指纹,提供 Python / Node.js / Go 三种语言的一等 API。

当前状态:TLS 与 HTTP/2 已交付,并经外部 oracle(tls.peet.ws)实测验证;HTTP/3 的 Chrome 149 已完成真机采集(QUIC 内层 JA4 与真机逐字符一致),Firefox / Safari H3 待实测;TCP 仅 TTL/MSS 可承诺(window / window_scale / options 仅 Linux 探测模式,不影响真实连接)。各维度精确现状见 docs/capability-matrix.yml。

目录

功能矩阵

维度 状态 验证
TLS ClientHello 逐字段可控(ciphers / 扩展序 / GREASE / key_share / MLKEM / ALPS / RSL / DC / padding / ECH) ✅ tls.peet.ws 实测 JA3 / JA4 一致;QUIC Initial 字节级嗅探
真 ECH(config_list 注入) ✅ cloudflare-ech.com 实测 ECHAccepted=true
指纹入口:完整 profile / JA3 / JA4 / JA4R / ClientHello-hex,附 JA3/JA4 回读 ✅ FoxIO 官方向量 + 线上 round-trip;JA4 短哈希反查内置预设
HTTP/2 帧层(SETTINGS 序 / WINDOW_UPDATE 三态 / priority / 伪头序 / 首流号) ✅ tls.peet.ws Akamai 指纹一致;另有原始帧级断言
HTTP/3 + QUIC(SETTINGS / 伪头序 / GREASE 帧 / 内层 ClientHello 同 profile) ✅ Chrome 149 真机采集:QUIC 内层 JA4 与真机一致;transport params 可控。Initial 布局不可控、Firefox/Safari H3 待实测
HTTP/2 HPACK 编码策略(chrome / firefox / safari / generic 四档) ✅ 255/394 预设覆盖 逐字节块表示断言;chrome / firefox 档有源码或字节级证据,safari 档为保守近似
H2/H3 racing + Alt-Svc ✅ H3 默认关(h3=True / protocols 显式开) 协议选择用例 + 线上 ALPN 断言
请求头顺序可控(preserve / input / random) ✅(默认 preserve) 原始抓包逐行核对线上头序(集合不变、Host 恒最前)
身份自洽(自带 UA ↔ 客户端提示) ✅(identity_sync="auto") 冲突时 sec-ch-ua* 校正到调用方 UA 并告警;TLS/H2 不伪造
连接池(H2 多路复用 / H1 keep-alive / H3 共享 transport,并发安全) ✅ go test -race 零竞争;echo 侧连接数断言
流式上传(H1 chunked / H2 DATA,三语言绑定迭代器入参) ✅ 线上字节逐字节断言
响应自动解压(gzip / deflate / br / zstd,多编码链流式生效) ✅ 六路径矩阵 + 跨压缩块边界流式断言
WebSocket(wss / ws,RFC 6455 + permessage-deflate,握手走指纹链路) ✅ RFC 服务端断言头序 / 帧 / 关闭码;独立 flate 对端断言压缩流
明文 http:// / ws:// ✅(H1;无 TLS,selfcheck 恒为零值) 引擎用例 + pytest 一组;与 force_http3 互斥(明确报错)
命令行 geektls(version / presets / describe / check-profile / request) ✅ 子命令冒烟 + 退出码口径(0/1/2)
Python asyncio(AsyncSession,线程池异步) ✅ asyncio 并发 20 请求用例
TCP(TTL/MSS setsockopt,按平台分文件) ✅(Windows 无 MSS) getsockopt 读回;CI 跨平台编译门禁
Python 请求语义对齐(cookie jar / timeout 元组 / auth / 重定向开关 / 表单编码) ✅ pytest 10 条(本地明文服务端,零外部依赖)
低层装载自动兜底(hex/ja3/ja4r:HTTP 身份 + 扩展载荷,identity= / profile_patch= 可控) ✅ 三入口回环 selfcheck(本地 HTTPS)+真机 pcap 闭环(缺身份头 403 → 补齐后 404)
Python 上传与流式扩展(multipart/form-data、SSE text/event-stream) ✅ httpbin 原字节断言;本地 SSE 服务端全形态用例 + 真实 SSE 流实测
Python / Node / Go 绑定 ✅ pytest 34 通过(2 跳过)、node:test 18、go test 通过;跨语言 JA4 三方一致

安装

pip install geektls          # Python(manylinux_2_28 x86_64/aarch64、macOS 11.0+ arm64/x86_64、Windows x64,动态库随 wheel 分发)
npm install geektls          # Node.js(Windows x64 / Linux x64 / macOS Apple Silicon;⚠️ Intel Mac 暂不支持)
go get github.com/geekbyter/geektls/core@v0.2.0   # Go(monorepo 子目录模块;pkg.go.dev/github.com/geekbyter/geektls/core)

已发布到 PyPI 的 wheel(0.1.5 起)覆盖五平台:manylinux_2_28 x86_64 / aarch64、macosx_11_0 arm64 / x86_64、win_amd64 (构建矩阵见 .github/workflows/release-pypi.yml;其余平台安装会提示无匹配版本; 不提供 sdist——从源码构建需要 Go + C 工具链,本库只发 wheel)。

⚠️ 老版本的平台覆盖(实测 PyPI 索引):

版本 已上传的平台 说明
0.1.0 仅 manylinux_2_34_x86_64 没有 Windows;Linux 基线是 glibc 2.34
0.1.1 – 0.1.3 manylinux_2_34_x86_64 + win_amd64 同上
≥ 0.1.4 五平台:manylinux_2_28 x86_64/aarch64、macosx_11_0 arm64/x86_64、win_amd64 Linux 基线 2.34 → 2.28(兼容面更大);macOS 与 Linux aarch64 从这里才开始提供

⇒ macOS、Linux aarch64、或 glibc < 2.34 的系统上 pin 到 0.1.0–0.1.3 会直接 No matching distribution found;本库不发 sdist,没有源码安装这条退路。

Python 一行自检:

python -c "import geektls,json;print(json.dumps(geektls.version()));print(len(geektls.list_presets()),'presets')"
# {"abi": 1, "core": "0.2.0", "utls": "refraction-networking/utls v1.8.2; bogdanfinn/utls v1.7.8-barnius; ..."} / 394 presets

version()["utls"] 是指纹栈溯源:报告动态库里实际链接的 uTLS / fhttp / quic-go-utls 版本(由二进制 build info 推导,跟随 go.mod 自动更新,不会漂移),vendor fork 会显示成 bogdanfinn/fhttp v0.6.9 => ./third_party/fhttp。出问题时把这一串贴进 issue 即可定位栈版本; 极端裁剪的构建可能为空串,调用方需容忍。

快速上手

Python(pip install geektls,动态库随包):

from geektls import Session

with Session(impersonate="chrome_150") as s:
    r = s.get("https://example.com")
    print(r.status_code, r.ok, r.used_protocol)   # 200 True h2
    print(r.headers["content-type"])             # 大小写不敏感
    print(r.text[:200])                          # 直接当文本用
    print(r.selfcheck["ja4"])                    # 本次握手的 JA4 自算
    for line in r.iter_lines():                  # 需要流式时才用迭代
        ...

Node.js(npm install geektls):

const { Session } = require('geektls');

const s = new Session({ impersonate: 'chrome_150', timeout: 20 });
const r = await s.get('https://example.com', { params: { q: 1 } });
console.log(r.statusCode, r.ok, r.reason);     // 200 true OK
console.log(r.header('content-type'));         // 大小写不敏感
console.log(await r.text());                   // 直接当文本用
console.log((await r.json()).slideshow);       // 直接当 JSON 用
for await (const chunk of r.iterContent()) { ... }   // 需要流式时才迭代
s.close();

Go(import gtls "github.com/geekbyter/geektls/bindings/golang";包名 geektls):

// 引擎直连(要用到响应便捷方法时走这条;只要 net/http 习惯可用上面的 RoundTripper 形态)
p, _ := profiles.Get("chrome_150")
sess, _ := engine.NewSession(p, engine.SessionOptions{})
defer sess.Close()

resp, _ := sess.Do(&engine.Request{Method: "GET", URL: "https://example.com"})
defer resp.Close()
fmt.Println(resp.StatusCode(), resp.OK(), resp.Reason()) // 200 true OK
fmt.Println(resp.Header("content-type"))                 // 大小写不敏感
text, _ := resp.Text()                                   // charset → utf-8 → gb18030 → latin-1
var v map[string]any
_ = resp.JSON(&v)

命令行(geektls CLI)

不想先写代码就想看效果时:

make cli                                       # 构建到 build/geektls(Windows 下 build/geektls.exe)
build/geektls version
build/geektls presets --grade self             # 只看自测集;--json 结构化;--name 过滤
build/geektls describe chrome_154_windows | jq .tls.detail.extensions
build/geektls check-profile chrome_133         # 离线自检:预设名 / ja3: / ja4: / ja4r: / hex
build/geektls request https://example.com -i --selfcheck
build/geektls request http://127.0.0.1:8000/ --ja4 t13d1516h2_8daaf6152771_02713d6af862
  • 指纹构造与绑定同一批入口(profiles.Get / FromJA3 / FromJA4R / FromClientHelloHex / ResolveJA4Profile),用户自带输入同样过一遍 NormalizeForReplay 自洽归一 —— CLI 看到的就是代码里跑的;
  • --selfcheck 把"本次握手实际发出的 JA3/JA4"打到 stderr ⇒ stdout 只放正文,可直接管道或重定向;
  • 退出码:0 = 传输成功(含 4xx/5xx,curl 口径;加 --fail 让 4xx/5xx 返回 1)、 1 = 配置或传输错误(原因在 stderr)、2 = 用法错误。

从抓包复刻指纹(import_pcap / import-pcap)

Wireshark/tcpdump 的抓包直接变成可复用指纹——不需要 tshark、不需要解密。 三种语言内置同一解析核,两步直通(以 Python 为例,Node/Go 同构):

import geektls

res = geektls.import_pcap("chrome.pcapng", ua=UA)   # ① 文件进(UA 说明见下)
rec = res["records"][0]                             # 记录出:ja3/ja4/sni/tcp 形态
with geektls.Session(clienthello_hex=rec["clienthello_hex"]) as s:  # ② 直通装载
    r = s.get("https://tls.peet.ws/api/all")
print(r.selfcheck)                                  # 线上对拍:实际 JA3/JA4 vs 期望
// Node.js
const res = geektls.importPcap({ path: "chrome.pcapng", ua: UA });
const client = new geektls.Session({ clienthello_hex: res.records[0].clienthello_hex });
// Go
res, _ := gtls.ImportPcap("chrome.pcapng", &gtls.PcapOptions{UA: UA})
s, _, _ := gtls.NewSessionFromClientHelloHex(res.Records[0].ClientHelloHex, nil)

TLS 面怎么处理:clienthello_hex 是抓包中 ClientHello 的 record 层原始字节 (16 03 01 开头),装载后 TLS 面逐字节复现(cipher 序、扩展序与载荷、ALPN、 ECH 外层等);client_random / key_share / GREASE 等随机项每次自动重生成。 三层验证:记录自带 ja3/ja4(离线)→ check_profile 细看解析(离线)→ 请求后 selfcheck 与记录值对拍(线上)。

HTTP 身份(identity):clienthello_hex / ja3 / ja4r 这类低层装载不带 浏览器请求头套件——引擎会自动借用"最相似内置预设"的 identity 节(按 ciphers 集合 / 扩展集合 / ALPN 匹配,相似度 ≥ 0.75 才借),并在响应 warnings 里说明借了谁 (identity_auto)。不补身份头的请求会以 Go 默认 UA 上线,容易被云 WAF 的"精准访问 控制"直接拦截(实测同一 ClientHello 逐字节复刻:缺身份头 403、补齐后 404)。要指定 或关闭:identity="预设名" / identity={...}(头表)/ identity=False——三绑定同名 参数(Node identity、Go Options.Identity)。

载荷兜底:ja3 / ja4r 的扩展载荷按"最相似内置预设"的真实形态替换 / 补全 (payload_borrowed 告警说明来源;入口自带 groups / points(ja3)与 sig_algs(ja4r) 保持原样)。只想改个别字段(如运行时剔除某个扩展):profile_patch(JSON 片段深合并、 数组整体替换,先于兜底生效;三绑定同名参数)。

常规用法:all_streams / all 导出全部流(记录里的 sni 区分同名或异名 流)、stream=N 挑第 N 条、tcp_only / tcpOnly 只取 TCP 形态、data 字节入口。 被拒的流在 skipped 中逐条给出原因(resumption、缺 SYN、抓包缺口、无 CH), records 为空不是异常。未补 UA 时记录带 missing_ua 警告(不影响 TLS 面装载; HTTP 头在 TLS 隧道内,明文抓包看不到 UA,需要从浏览器侧抄)。

CLI(生成可入库预设时才需要,与绑定同一解析核):

build/geektls import-pcap --pcap chrome.pcapng --ua "$UA" -o fp.json
tests/e2e/cmd/gen-profiles -record fp.json -out ./presets

完整示例见各绑定 README(Python / Node.js / Go); 支持 pcapng 与 pcap classic(含 tcpdump -i any 的 cooked 链路); 设计与边界见 docs/12-pcap-import.md。

协议选择 / 请求头顺序 / 身份自洽

三个开关,默认行为与旧版完全一致,需要时才开:

关心的事 参数 默认 可选值
走哪个 HTTP 版本 protocols / h3 ["h1.1","h2"](不含 H3) ["h1.1"] 只 H1.1 | ["h2"] 只 H2 | ["h2","h3"] 允许 H3 | ["h3"] 强制 H3;便捷写法 h3=True
请求头顺序 header_order preserve(按预设声明序) input(按你给的顺序)| random(打乱)
自带 UA 与预设不一致 identity_sync auto(校正客户端提示 + 告警) off(不校正)

为什么 H3 默认关:同一个 URL 走 H2 还是 H3 是可观测差异(协议入口、QUIC 侧指纹都不同), 不该由"预设里带 http3 节"替用户决定;curl_cffi / requests 生态的默认也是 H2,H3 要显式开。 以前只要预设带 http3.enabled + h2_race_ms 就自动竞速 H3,现在必须 h3=True 或 protocols 含 "h3";请求级 force_http3=True 语义不变(失败不回落)。

协议选择:Python

from geektls import Session

# 1) 默认(什么都不给):h1.1 + h2,**不碰 H3** —— 与 curl_cffi / requests 同口径
with Session(impersonate="chrome_154_windows") as s:
    r = s.get("https://example.com/")
    print(r.used_protocol, r.selfcheck["negotiated"]["alpn"])   # 例:h2 h2

# 2) 只要 H1.1:ALPN 里不再 offer h2(对端偏好 h2 也只能给 http/1.1)
with Session(impersonate="chrome_154_windows", protocols=["h1.1"]) as s:
    print(s.get("https://example.com/").used_protocol)          # http/1.1

# 3) 只要 H2:对端不支持 h2 时**直接失败**,不静默回落 H1
with Session(impersonate="chrome_154_windows", protocols=["h2"]) as s:
    print(s.get("https://example.com/").used_protocol)          # h2

# 4) 允许 H3(竞速/Alt-Svc 优先,失败落回 TCP);h3=True 是便捷写法
with Session(impersonate="chrome_154_windows", h3=True) as s:
    print(s.get("https://example.com/").used_protocol)          # h3 或 h2(看谁先拿到响应头)

# 5) 只走 H3(会话级强制,失败即报错,不回落)
with Session(impersonate="chrome_154_windows", protocols=["h3"]) as s:
    print(s.get("https://example.com/").used_protocol)          # h3

# 6) 请求级强制(0.1.6 起语义不变:仍是"必须 H3",但会话 protocols 显式排除 h3 时冲突报错)
with Session(impersonate="chrome_154_windows") as s:
    r = s.request("GET", "https://example.com/", force_http3=True)

要点:h3=True 与 protocols=[...] 不能同时给(两种意图打架,直接报错,不静默取其一); h3=False 与 protocols 同给不报错(常见写法,无额外意图)。开了 h3 但预设没有 http3 声明 会在建会话时报错,而不是悄悄退回默认 QUIC 参数。

协议选择:Node

const { Session } = require('geektls');

const s = new Session({ impersonate: 'chrome_154_windows' });                       // 默认 h1.1+h2
const s1 = new Session({ impersonate: 'chrome_154_windows', protocols: ['h1.1'] }); // 只 H1.1
const s2 = new Session({ impersonate: 'chrome_154_windows', h3: true });            // 允许 H3
const s3 = new Session({ impersonate: 'chrome_154_windows', protocols: ['h3'] });   // 只 H3
const r = await s.get('https://example.com/');
console.log(r.usedProtocol, r.selfcheck?.negotiated?.alpn);

协议选择:CLI

build/geektls request https://example.com --protocols h1.1 --selfcheck   # 只 H1.1(ALPN 打 stderr)
build/geektls request https://example.com --protocols h2                 # 只 H2
build/geektls request https://example.com --h3                           # 允许 H3
build/geektls request https://example.com --protocols h3                 # 只 H3
build/geektls request https://example.com --http3                        # 请求级强制

请求头顺序:三档

with Session(impersonate="chrome_154_windows") as s:
    # 默认 preserve:按 profile.http1.header_order 归位(= 与 0.1.6 之前逐字节相同)
    s.get(url)

with Session(impersonate="chrome_154_windows", header_order="input") as s:
    # 按**你传入字典的顺序**发(Host 仍在最前);requests 用户自己排好序时用这个
    s.get(url, headers={"accept-language": "en-US,en;q=0.9", "accept": "*/*"})

with Session(impersonate="chrome_154_windows", header_order="random") as s:
    # 每次请求打乱普通头顺序(Host 恒最前);绕"顺序即信号"的检测用
    s.get(url)

CLI 同理:--header-order preserve|input|random。

头序三档的取舍:真浏览器的头序是固定的,random 是"对抗顺序检测"的手段而不是更真—— 所以默认 preserve,且它会破坏可复现性(回归/对拍时别开)。

自带 UA 时的身份自洽

WIN_UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
          "(KHTML, like Gecko) Chrome/161.0.0.0 Safari/537.36")

# 预设是 macOS 形态,但你写 Windows UA ⇒ 默认 auto:sec-ch-ua*/platform/mobile 跟着校正
with Session(impersonate="chrome_154_macos") as s:
    r = s.get(url, headers={"user-agent": WIN_UA})
    print(r.warnings)      # ["identity_sync: … TLS/JA3/JA4/H2 仍为该预设 …"]

# 想要连 TLS 也一致:换同平台变体预设(它的 ClientHello 本来就不同),而不是靠改头
with Session(impersonate="chrome_154_windows") as s:
    s.get(url, headers={"user-agent": WIN_UA})   # TLS 与 UA 都是 Windows 形态

# 不想要任何校正/告警:off(= 旧行为)
with Session(impersonate="chrome_154_macos", identity_sync="off") as s:
    s.get(url, headers={"user-agent": WIN_UA})

CLI:--identity-sync auto|off。

身份自洽的边界:你自带 user-agent 时,identity_sync="auto" 会把 sec-ch-ua(版本号)/sec-ch-ua-platform/sec-ch-ua-mobile 校正到该 UA,因为这几项与 UA 同源、不一致是明显破绽。但 TLS/JA3/JA4/H2 不会跟着变——凭空改出来的指纹不属于任何真实 浏览器,比不一致更糟。想要"UA 与 TLS 也一致",正确做法是换同平台变体预设 (chrome_154 的 _windows / _macos / _android 变体的 TLS 真的不同),库会把这句写进 r.warnings。查变体:geektls.list_presets() 或 geektls check-profile <名>。

指纹怎么传:整体与局部

Session(...) 的指纹入参六选一(互斥,同时给以靠前的为准,优先级按下列顺序):

入参 语义 保真度 备注
impersonate="chrome_150_windows" 用内置预设(394 条) 高(多数有 E1/E2 证据) 名字是全名:chrome_154_macos、chrome_154_windows、okhttp_3_12_12…(没有裸 chrome_154)
profile={...} 自带完整指纹(profile JSON schema) 完全按你给的来 也接受 JSON 文本(profile='{"name":...}'),免去 json.loads
ja3="771,4865-...-23,4588-29-23-24,0" 只给 JA3 有损:扩展只有 type,负载全缺 载荷与 HTTP 身份按"最相似内置预设"自动补齐(payload_borrowed / identity_auto 告警),check_profile 会逐条列出 warnings
ja4r="t13d1516h2_002f,..._..._..." 只给 JA4R(含 cipher/扩展/sig_algs 列表) 中:列表有序化丢失(extensions_sorted 告警) 想"逐字节复刻"用这个或完整 profile;载荷按最相似预设补齐;带 ECH(65037) 时按 GREASE 近似并告警(ech_assumed_grease),因为 raw 串不含负载
ja4="t13d1516h2_8daaf6152771_d8a2da3f94cd" 只给 JA4 短哈希 哈希不可逆 引擎在内置预设里反查同一 JA4 并采用其参数(ja4_resolved_to_preset 告警);找不到会明确报错,不会编近似指纹
clienthello_hex="160301..." 直接给原始 ClientHello 字节 最高(等于抓包重放的结构) 与生成器/采集端同一条解析路径

没传的部分如何保持自洽(这是"局部指纹"能用的关键):

  1. 重放自洽归一(core/profiles/replay.go):带 pre_shared_key(41) 的双向约束——声明 TLS 1.3 就必须有 41 空占位且位于扩展末尾(RFC 8446),不声明就必须没有(否则 ClientHello 结构非法)。补的是空占位:无票据时线上省略、也不计入 JA3/JA4,所以首次握手的指纹不变;不补的话,一旦会话复用命中票据,uTLS 会直接 panic。
  2. 损失告警:JA3 入口会报 grease_lost / extension_payloads_lost;JA4R 会报 extensions_sorted;JA4 反查会报 ja4_resolved_to_preset。有损入口会明确告知损失,而不是假装保真。
  3. HTTP 身份与载荷兜底:ja3 / ja4r / clienthello_hex 装载时自动借用"最相似内置预设"的 identity 节与扩展载荷(告警 identity_auto / payload_borrowed 说明借了谁);identity= 可显式指定(预设名 / 头表)或 False 关闭,profile_patch= 做增量覆盖。
  4. 离线验证:geektls.check_profile(...) 不发包,直接告诉你"这么传会发出什么"(JA3/JA4/wire 长度/warnings):
import geektls

# 整体:完整 profile 文本
print(geektls.check_profile('{"name":"mine","tls":{"detail":{"ciphers":["grease","0x1301"],"extensions":[{"type":43,"versions":["grease","0x0304","0x0303"]}]}}}')["ja4"])

# 局部:只给 JA3(会看到补占位 + 负载丢失的告警)
print(geektls.check_profile("771,4865-4866-4867-49195-49199,43-10-11-13-16-23-5-0-65281,4588-29-23-24,0"))

# 只给 JA4 短哈希(反查内置预设)
print(geektls.check_profile("t13d1516h2_8daaf6152771_d8a2da3f94cd"))

Python API 参考

模块级函数

函数 签名 说明
version() -> dict {"abi":1,"core":"0.2.0","utls":"<指纹栈版本串>"};启动时可用它断言 ABI 匹配,utls 用于溯源(见上文)
init(options=None) -> None 幂等初始化钩子(当前无全局状态,留作后续)
last_error() -> dict 最近一次失败的结构化错误(code/message/op)
list_presets() -> list[str] 全部内置预设名(排序,394 条;返回规范名,旧名是别名)
describe_preset(name) -> dict 预设展开后的规范 JSON(ciphers/扩展/H2/H3/身份头全展开)
check_profile(spec) -> dict 离线自检:profile JSON / JA3 / JA4 / JA4R / hex → {ja3,ja3_hash,ja4,wire_len,warnings}
GeekTLSError 异常类 所有失败都是它;.code 结构化错误码(invalid_config/request_failed/…)
default_session(**options) -> Session 模块级共享会话;首次调用可传 Session(...) 参数配置(之后只读,再传报错)
get/head/post/put/patch/delete/options(url, **kwargs)、request(method, url, **kwargs) -> Response requests 风格快捷 API,走 default_session()(连接池与 Cookie jar 随之共享;与 requests 的模块级 API 同语义)

Session

Session(impersonate=None, *, profile=None, ja3=None, ja4=None, ja4r=None,
        clienthello_hex=None, identity=None, profile_patch=None, headers=None,
        proxies=None, timeout=None,
        read_timeout=None, resolve=None, local_address=None, ip_version=None,
        verify=None, cert=None, cert_key=None, allow_redirects=None,
        max_redirects=None, cookies=None, auth=None, trust_env=None, **options)
参数 类型 说明
impersonate / profile / ja3 / ja4 / ja4r / clienthello_hex str / dict / str 六选一(见上一节)
identity str / dict / False 低层装载(ja3/ja4r/clienthello_hex/不带 identity 的 profile)时的 HTTP 身份:预设名(借其 identity 节)/ 头表(如 {"User-Agent": …})/ False 关闭自动兜底。不传时自动借用"最相似内置预设"(见"指纹怎么传"节),并在响应 warnings 说明
profile_patch dict / str(JSON) 以最终 profile 为底的增量覆盖(深合并:对象递归、数组整体替换,与 profile 的 extends 同规则)——从预设/抓包出发只改要改的字段(增删扩展、换 ALPN、覆盖身份头…),免去手抄全量 profile;先于身份/载荷兜底生效
headers dict / list[tuple] 会话默认请求头(按给定顺序发出)
proxies dict / str requests 风格;引擎一次只用一个代理 URL({"https": ...} / {"all": ...})。scheme:http/https(CONNECT 隧道)、socks5(本地先解析域名)、socks5h(域名交给代理解析)、socks4/socks4a(仅 IPv4 目标;只有 user id 无口令位,URL 给口令即报错)
trust_env bool requests 同名,映射到引擎 proxy_from_env:False ⇒ 不读 HTTPS_PROXY/ALL_PROXY,只认显式 proxies;默认 True 会读,并按 NO_PROXY 与回环目标(localhost/127.0.0.1/::1)豁免
timeout float 秒 / (connect, read) 单值映射到引擎 timeout_ms(覆盖"dial+TLS+响应头");元组时 connect 进 timeout_ms、read 进 read_timeout_ms(任一项可为 None),请求级可用 timeout_ms= 覆盖
read_timeout float 秒 映射到引擎 read_timeout_ms:每次读 body 的空闲上限(默认 0=不限,与旧行为一致);请求级可用 read_timeout_ms= 覆盖。超时是结构化错误 code="read_timeout",调用线程毫秒级返回,底层连接作废
resolve dict[str, str] curl --resolve:{"host": "1.2.3.4"} 或 {"host:8443": "..."}(键精确匹配,不做通配/子域;值必须是 IP 字面量)。只改"连到哪":SNI / Host / 伪头 / ClientHello 仍用 URL 里的原域名,指纹字节不变。只在引擎本地解析的那几档生效(直连 / netstack / socks5 / socks4);socks5h/socks4a/CONNECT 由代理解析,钉位不参与(不静默改道)
local_address str curl --interface 的 IP 形态 / httpx local_address:绑出网源地址,只收 IP 字面量(网卡名不支持)。隐含协议族,与 ip_version、resolve 取值冲突建会话即 ValueError;tcp.mode=netstack 下报错(用户态栈源地址固定)而不是忽略
ip_version str / int curl -4 / -6:"4" / "6"(4、"v4"、"ipv4" 同义),限定解析与拨号族;命中的地址全被过滤时是明确的解析错误
verify bool / str / bytes / Path True(默认,系统信任库)/ False(跳过校验)/ CA bundle 路径、含 .pem/.crt/.cer 的目录、或内联 PEM(自持信任库,替换系统根)。其他类型直接 ValueError,不会静默退回系统根
cert str / bytes / Path / tuple mTLS 客户端证书:路径或 PEM(证书+私钥可同文件)、(证书, 私钥);三元组的 password 必须为 None(不支持加密私钥)
cert_key str / bytes / Path 单独给私钥(覆盖 cert 元组第二项)
allow_redirects bool False ⇒ 不跟随重定向(会话级;请求级也可传,请求级覆盖会话级)
max_redirects int 重定向上限(默认 10;会话级与请求级都可用)
cookies dict / list[tuple] / str / Cookies / bool dict 等形态 ⇒ 会话级 jar(每请求渲染成 Cookie 头,响应里的 Set-Cookie 自动并入);True/False ⇒ 只开关引擎 jar
auth tuple / 对象 (user, password) 或带 username/user + password 属性的对象 ⇒ HTTP Basic;自己传了 Authorization 头时以你的为准
protocols list[str] 允许的 HTTP 协议集合(顺序无关):"h1.1" / "h2" / "h3"。默认 ["h1.1","h2"],不含 H3(与 curl_cffi 同口径)。只要 ["h1.1"] ⇒ ALPN 收窄到 http/1.1;只要 ["h2"] ⇒ 对端不支持就失败(不静默回落);只要 ["h3"] ⇒ 会话级强制 H3
h3 bool protocols 的便捷写法:True = 默认集合加 "h3"(预设需带 http3 声明)。h3=False 与 protocols 同给不报错,h3=True 与 protocols 同给报错
header_order str 请求头顺序:"preserve"(默认,按 profile.http1.header_order)/ "input"(按你传入的顺序)/ "random"(打乱,Host 仍最前)。⚠️ random 与真浏览器不符且破坏可复现性
identity_sync str "auto"(默认):你自带 user-agent 与预设身份不一致时,自动把 sec-ch-ua / sec-ch-ua-platform / sec-ch-ua-mobile 校正到该 UA,并在 r.warnings 里说明"TLS/H2 仍是该预设";"off" = 不校正
**options — 其余按引擎会话原名透传(proxy/proxy_from_env/timeout_ms/read_timeout_ms/redirect_max/insecure_skip_verify/auto_decompress/cookie_jar/ca_bundle/client_cert/client_key/resolve/local_address/ip_version);不在名单里的键绑定层直接 ValueError
方法 说明
request(method, url, *, params=None, data=None, json=None, headers=None, body=None, timeout=None, timeout_ms=None, read_timeout=None, read_timeout_ms=None, proxy=None, proxies=None, cookies=None, auth=None, allow_redirects=None, max_redirects=None, stream=None, force_http3=None, **kwargs) 通用请求;头到达即返回,body 按需读取。proxies / cookies / auth / allow_redirects / max_redirects 请求级覆盖会话级
get / post / put / patch / delete / head / options(url, **kwargs) 便捷动词,等价于 request
websocket(url, headers=None, timeout=None, compress=False) 升级 WebSocket(见下节),返回拉模型 WebSocket;compress=True 握手 offer permessage-deflate
close() 释放会话(挂连接池/transport)
with Session(...) as s: 自动 close()

⚠️ verify / cert 是会话级:传给 request() 会明确报错而不是静默失效(要按请求切换就新建 Session)。allow_redirects / max_redirects / proxies / cookies / auth 请求级也能用。

⚠️ 拼错的关键字不会静默吞掉:core 的两处 JSON 解码都不严格(client config 只查指纹入参那六个键,SessionOptions 忽略未知字段),所以名单校验做在绑定层——Session(...) 收到未知会话选项、request() 收到未知请求级 kwargs 都立即报错(Node 侧同理:new Session({insecure_skip_verfy: true}) 抛 TypeError)。这类选项决定"校验开不开、超时走不走、连接钉到哪",绝不能配了却没生效。

multipart/form-data 上传

用 Multipart 构造器组装表单(boundary 为浏览器形态 ----WebKitFormBoundary…; 同名 part 可重复添加,用于"同一字段多文件"):

from geektls import Multipart

mp = Multipart()
mp.add_part("image", local_path="./image.png", content_type="image/png")
mp.add_part("image", data=b"...", filename="second.png", content_type="image/png")
mp.add_part("note", data="hello")            # 无文件名的普通字段

with Session(impersonate="chrome_154_windows") as s:
    r = s.post("https://httpbin.org/post", data={"foo": "bar"}, multipart=mp)
  • add_part(name, *, data=/local_path=, filename=, content_type=):local_path 与 data 二选一;data 接受 str / bytes / 数字;content_type 显式优先,未给时按 文件名扩展名推断(推断不出且带文件名时 application/octet-stream;纯字段不带该头)。 另有 Multipart.from_list([{...}, ...]) 批量构造、close()(纯内存对象,可选)。
  • data= 的 dict / [(k, v), ...] 会作为普通字段尾随并入表单(requests 语义); multipart 与 json=、data=(字符串 / 字节 / 可迭代)互斥——会报错,不静默降级。
  • content-type 由构造器接管(multipart/form-data; boundary=…,同名请求头会被覆盖); 文件整块读入内存(大文件注意占用;需要边读边发的场景用既有流式上传通道自己拼 body)。

SSE(text/event-stream)

with Session(impersonate="chrome_154_windows") as s:
    for ev in s.sse("https://example.com/events"):     # 用的就是本会话的指纹与连接
        print(ev.event, ev.data, ev.id, ev.retry)
  • Session.sse(url, *, method="GET", last_event_id=None, **kwargs) → 事件生成器; Response.iter_sse() 从任意已打开的响应上解析;模块级 geektls.sse(url, **kwargs) 走默认会话。事件是 SSEEvent(event, data, id, retry)(字段名同规范)。
  • 协议细节按 HTML 规范:行分隔兼容 \r\n/\n/\r;空行派发(data 为空的事件不派发); data: 多行以 \n 连接;: 开头为注释(心跳);retry: 数字透传;含 NUL 的 id 忽略。
  • last_event_id= 会带 Last-Event-ID 头(断线续传);生成器结束 / break 后关闭会 关闭响应。慢流场景 read_timeout=(body 单次读取空闲上限)照常生效;未以空行收尾的 挂起事件在流结束时按规范丢弃。

Response

成员 类型 说明
status_code / status int HTTP 状态码(status 是 0.1.0 起的旧名,等价)
ok bool < 400 为 True(requests 语义);对象真值即 ok
reason str 本地按 RFC 9110 映射的短语(非服务端原文)
headers CaseInsensitiveDict 大小写不敏感;保留插入原始大小写
raw_headers list[tuple] 原始 (name, value) 顺序视图
used_protocol str 实际协商到的协议:h2 / h3 / http/1.1
selfcheck dict 本次握手的自算指纹与比对(见「自校验」)
url / method / elapsed / encoding / apparent_encoding — 请求元信息与编码推断
content / read() / bytes() bytes 读完并缓存 body
text str 按响应编码解码(未声明 charset 时自动探测)
json(**kwargs) Any 按声明 charset(缺省 utf-8,剥 BOM)解 content;不走 text 的探测链(省掉一次"猜编码再解码")
iter_content(chunk_size=65536, decode_unicode=False) / iter_bytes(chunk_size) / iter_lines(chunk_size, decode_unicode=False) 生成器 边收边处理大响应(iter_bytes 是旧名;decode_unicode=True 跨块多字节不会切坏)
header(name, default=None) str 取单个响应头
cookies Cookies 本响应 Set-Cookie 的解析结果(requests 同名);session.cookies.update(r.cookies) 可让它参与后续请求
raise_for_status() None >=400 抛 HTTPError(GeekTLSError 子类,异常上挂 .response;code="http_error")
close() None 释放响应句柄(未读完 body 时更要显式调用)
content_encoding str 线上 Content-Encoding 原值(不篡改,与 requests 一致)
decoded bool 本次响应是否被引擎透明解压过
warnings list[str] 解压层非致命提示(未知编码原样透传等)

WebSocket(wss:// 与 ws://,RFC 6455)

wss:// 握手走同一条拨号 + TLS 指纹链路;ws://(明文)只做 TCP —— 帧层与 TLS 无关, 两条路径共用同一套帧实现,差别只在拨号那一步(与 http:// 同一条路)。 wss 的 ALPN 收窄到 http/1.1(Upgrade 在 h2 上无效;收窄的是 detail 副本里的 ALPN 扩展内容, 不只改本地偏好;明文 ws 没有 ALPN)。 Upgrade 请求头序默认对齐真 Chrome(host → connection → upgrade → origin → 身份头 → sec-websocket-version → sec-websocket-key),profile.http1.header_order 非空时整体再过排序器。 帧层为自行实现(stdlib,无新依赖):text/binary/ping/pong/close、客户端 masking(RFC 强制)、 分片重组、控制帧 125 字节上限、ping 自动回 pong。 permessage-deflate(RFC 7692)已实现:compress=True 让握手 offer permessage-deflate, 只有对端在 101 里按我方 offer 真的接受才启用——之后 send/recv 收发的仍是明文 (RSV1 位、跨消息压缩上下文、分片续接都在库里管理)。默认 False 不发这个头: 没有逐浏览器 WS 握手的字节级证据,就不承诺 Chrome 那个 client_max_window_bits 参数 (stdlib 的压缩窗固定 15 bit)。要精确控制 offer 参数(server_no_context_takeover 等) 直接把它写进 headers。

with Session(impersonate="chrome_133") as s:
    ws = s.websocket("wss://ws.postman-echo.com/raw")
    ws.send("hello")                          # text 帧
    opcode, payload = ws.recv(timeout=8)      # (1, b'hello');1=text 2=binary
    ws.close()                                # 或交给 Session 的 with 统一释放

    # 想要服务端按 RFC 7692 压缩载荷(收发仍是明文):
    ws = s.websocket("wss://example.com/socket", compress=True)
  • 拉模型:send(data)(str ⇒ text 帧,bytes ⇒ binary;Python 可 send(data, opcode) 显式指定)/ recv(timeout=None, buf_size=1<<20)(秒)/ close(code=1000),不做回调式。
  • Node:const ws = await session.websocket(url, { compress: true }) → await ws.send(data) / ws.recvText(timeoutMs) / ws.close();asyncio 同款(AsyncSession.websocket)。
  • 协商严格按 RFC,不做"看起来能用再说":对端回声我方没请求的参数、协商了不认识的扩展、 把我方压缩窗限到 <15 bit,握手直接失败;没协商却收到 RSV1(以及 RSV2/RSV3、带 RSV1 的 控制帧)也直接报错——"把压缩字节当文本返回"是绝不允许的失败模式。
  • 不做 RFC 8441(WebSocket over H2):Chrome 实际仍以 H1 Upgrade 为主(capability-matrix ws.rfc8441_h2 登记)。
  • 已验证:本地 echo-server 双向收发/分片/控制帧(pytest test_websocket、node websocket)+ 公网 wss://ws.postman-echo.com/raw 真实握手与回显;permessage-deflate 用 core/engine/ws_deflate_test.go 里独立写的 stdlib flate 对端(真 TLS 监听)双向验证——发方向的压缩块拼起来交给普通 flate.NewReader 整体解开,证明是合法连续 DEFLATE 流而非自家私有格式。

响应透明解压(默认开)

引擎按响应 Content-Encoding 自动解压 body:gzip / deflate(zlib 头 + raw flate 容错)/ br / zstd,多重编码链(如 gzip, br)按声明顺序逆序解开;全链路流式生效—— r.content / r.text / r.json() / iter_* 拿到的都是解压后的字节(charset 探测在解压之后)。

  • 关闭:Session(auto_decompress=False),或请求级 request(..., auto_decompress=False)(请求级覆盖会话级)。
  • headers 保留线上原值:Content-Encoding / Content-Length 不篡改;解压状态看 r.decoded / r.content_encoding。
  • 未知编码值原样透传不报错,记入 r.warnings。
  • H3 路径同样生效(解压统一收归引擎;vendor fhttp 的内置单层解压已用 SkipResponseDecompress patch 关闭,杜绝双重解压)。

Node.js API 参考

const { Session, version, listPresets, describePreset, checkProfile,
        lastError, errorOf, GeekTLSError,
        request, get, post, del, options, defaultSession } = require('geektls');  // 后五个:requests 风格模块级快捷 API
成员 说明
new Session(options) options 同 Python:指纹入参六选一 + proxy/proxies、proxyFromEnv/trustEnv(false = 不读 HTTPS_PROXY/ALL_PROXY)、timeoutMs/timeout、readTimeoutMs/readTimeout(秒,body 读取空闲上限)、redirectMax/allowRedirects、cookieJar、insecureSkipVerify/verify(true/false/CA bundle 路径或 PEM)、cert(路径 / [证书, 私钥] / {cert, key})+ certKey、headers、地址控制 resolve({'host[:port]': ip})/localAddress/ipVersion。也认引擎原名(timeout_ms/insecure_skip_verify/resolve…);两个名单都不在的键抛 TypeError,不会静默消失
s.request({method, url, ...}) 返回 Promise<Response>(不阻塞事件循环);请求级可给 timeoutMs/readTimeoutMs/proxy,以及 allowRedirects:false(⇒ 引擎 redirect_max=-1)
s.get/post/put/patch/delete/head/options(url, options) 便捷动词
await s.websocket(url, { headers, timeoutMs, compress }) WebSocket(拉模型:send / recv / recvText / close);compress:true 握手 offer permessage-deflate
s.close() 释放会话
r.statusCode / r.ok / r.reason / r.headers / r.usedProtocol / r.selfcheck 同 Python 语义
r.contentEncoding / r.decoded / r.warnings 解压元信息(同 Python)
await r.read() / r.bytes() / r.text() / r.json() / r.header(name) body 读取
r.iterContent(size) / r.iterLines(size) 异步迭代器(for await)
r.close() 释放
version() / init() / lastError() / listPresets() / describePreset(name) / checkProfile(input) 与 Python 同名同语义
errorOf(handle) 按对象取最近一次错误(gtls_error_of;handle 查不到再回落 lastError())。异步绑定在 worker 线程报的错靠它取回
cookie Node 侧没有 Python 那样的显式 jar API:线上 Set-Cookie 的存取与重发由引擎 jar 自动完成(含重定向中间跳);要带指定 cookie 就写 Cookie 头

Go API 参考

两条路:绑定层(github.com/geekbyter/geektls/bindings/golang,http.Client/RoundTripper 形态)与引擎直连(core/engine,能力最全)。

包 关键 API 说明
core/profiles List() / Get(name) / Describe(name) / FromJA3 / FromJA4R / FromClientHelloHex / NormalizeForReplay / Parse 预设与指纹入口(含上面说的自洽归一)
core/tls CompileDetail / ComputeJA3 / ComputeJA4 / JA3Hash / CheckProfile / ResolveJA4Preset 编译、自算、离线自检、JA4 反查
core/engine NewSession(profile, SessionOptions) → Do(*Request) → *Response(StatusCode/OK/Reason/Header/Text/JSON/IterBytes/Close);DialWS(*WSRequest) → *WSConn(Send/Recv/Close,WSRequest.Compress 开 permessage-deflate) 引擎直连;支持 H2/H3 racing、Alt-Svc、代理、流式、wss
github.com/geekbyter/geektls/bindings/golang(包名 geektls) NewSession(preset, *Options) → Do/Get / DialWS(*WSRequest) → *WSConn / Close();NewRoundTripper(preset, *Options) 绑定层(不走 FFI,直接 import core);WSRequest/WSConn 是 engine 类型的别名,不再包一层以免漂移
core/ffi gtls_* C ABI(见 core/ffi/geektls.h) Python/Node 绑定的底座;gtls_client_new 的 config_json 支持 impersonate/profile/ja3/ja4/ja4r/clienthello_hex

使用场景

1) 单请求(最常用)

with Session(impersonate="chrome_154_windows") as s:
    print(s.get("https://tls.peet.ws/api/all").json()["tls"]["ja4"])

2) 并发抓取(会话复用 + 连接池)

import concurrent.futures as cf
with Session(impersonate="chrome_150") as s:
    with cf.ThreadPoolExecutor(16) as ex:
        for r in ex.map(lambda u: s.get(u), urls):
            print(r.status_code, r.used_protocol)

3) 会话复用/票据(第二次握手带 PSK,selfcheck 里能看到)

with Session(impersonate="firefox_156_windows") as s:
    s.get("https://example.com").close()
    r = s.get("https://example.com")     # resumed(同 origin 连接复用)

4) 强制 HTTP/3 / H3 竞速

with Session(profile=geektls.describe_preset("chrome_154_macos")) as s:
    r = s.get("https://cloudflare.com", force_http3=True, timeout_ms=8000)
    print(r.used_protocol)               # h3(不支持则按策略回落 h2)

5) 走代理 / 关校验 / 不跟随重定向

with Session(impersonate="edge_153_windows", proxies={"https": "http://127.0.0.1:8080"},
             verify=False, allow_redirects=False) as s:
    print(s.get("https://example.com").status_code)   # 3xx 原样返回

代理支持六种 scheme:http/https(CONNECT 隧道,带 user:pass 即发 Proxy-Authorization)、socks5(本地先解析域名再交代 IP)、socks5h (域名原样交给代理解析)、socks4/socks4a(老协议:只有 IPv4 目标、 鉴位只有 user id 没有口令;4a 的域名由代理侧解析)。 socks5 遇到解析不出的域名会直接报错,不会静默降级成 socks5h。

不给 proxies 时读标准环境变量 HTTPS_PROXY → ALL_PROXY(大小写都认),并按 NO_PROXY 豁免;trust_env=False 可整条关掉(指纹调试要可复计时建议关)。 域名是字面量匹配,不做 DNS——真 Chrome 会先解析再判 NO_PROXY,geektls 故意不这么 做:为的是"同一个预设、同一个 URL 每次走同一条路"。 回环目标(localhost / 127.0.0.1 / ::1)不吃环境变量派生的代理,避免开发机 上挂了 ALL_PROXY 就连不上本地测试服务;显式给的 proxies 对回环仍然生效。

⚠️ 有代理时 H3/QUIC 一律不参与(含 racing 与 Alt-Svc 升级):QUIC 过 HTTP 代理 需要 CONNECT-UDP(RFC 9298),本库未实现。force_http3=True + 代理会明确报 invalid 而不是偷偷直发漏指纹——这是"要么按你说的路走、要么报错"的一般原则。

5b) 自持信任库 / mTLS(requests 的 verify=<path>、cert=(crt, key))

with Session(impersonate="chrome_150",
             verify="/etc/ssl/certs/internal-ca.pem",          # 路径 / 目录 / PEM 文本皆可
             cert=("/etc/client/tls.crt", "/etc/client/tls.key")) as s:
    print(s.get("https://internal.example.com/api").status_code)

CA 解析不出来、或证书与私钥配不上对时,建会话就报错(GeekTLSError, code=invalid_config),不会退化成"用系统根继续"。TCP(uTLS)与 QUIC/H3 内层 握手共用同一份证书材料。

5c) 不走系统 DNS:把域名钉到固定 IP / 绑源地址 / 限协议族

with Session(impersonate="chrome_150",
             resolve={"api.example.com": "93.184.216.34",   # 键也可以是 "host:443"
                      "cdn.example.com": "104.16.132.249"},
             local_address="192.168.1.23",                  # 出网走这张网卡/这个 IP
             ip_version="4") as s:                          # 只要 A 记录
    print(s.get("https://api.example.com/v1").selfcheck["ja4"])

这三项只改"连到哪、从哪连",一律不改线上指纹字节:SNI、Host、伪头、 ClientHello 用的还是 URL 里的原域名,所以钉位前后 JA3/JA4 完全一致(有测试守着)。 local_address 必须是本机持有的 IP——绑一个不属于它的地址会在拨号时明确报错, 不会"静默换一张网卡"。 和 netstack 组合时它是正向能力:用户态栈要求目标是 IPv4 字面量,resolve 正好 供给;源 IP 由 ip_version/resolve 的族隐含。

生效范围按"谁做解析"划分,不做静默改道:直连、tcp.mode=netstack、socks5、 socks4 由引擎本地解析 ⇒ 钉位/族收窄都生效;socks5h、socks4a、CONNECT 隧道把 域名原样交给代理 ⇒ resolve/ip_version 不参与(那两档生效就等于绕过代理语义)。 local_address 在 netstack 下报错(用户态栈源地址固定为 TUN 侧地址)而不是忽略。 取值互相冲突(ip_version="4" 配 IPv6 源地址、resolve 值不是 IP、键写成网卡名) 建会话即 invalid_config;force_http3 与三者同给也是明确报错——QUIC 拨号没接地址 控制:配置不生效时直接失败,不会静默走别的路。

6) 对比两个预设的指纹差异(不发包)

import json
a = geektls.check_profile(json.dumps(geektls.describe_preset("chrome_152_macos")))
b = geektls.check_profile(json.dumps(geektls.describe_preset("chrome_154_macos")))
print(a["ja4"], b["ja4"], a["wire_len"], b["wire_len"])

7) 自定义完整指纹(自己的 profile JSON)

mine = {
    "name": "mine_chrome_like",
    "tls": {"detail": {
        "legacy_version": "0x0303",
        "ciphers": ["grease", "0x1301", "0x1302", "0x1303", "0xc02b", "0xc02f"],
        "extensions": [
            {"type": 0, "sni": "auto"},
            {"type": 16, "alpn": ["h2", "http/1.1"]},
            {"type": 43, "versions": ["grease", "0x0304", "0x0303"]},
            {"type": 10, "groups": ["grease", "X25519MLKEM768", "X25519"]},
            {"type": 13, "sig_algs": ["0x0403", "0x0804", "0x0401"]},
            {"type": 41},                       # 空占位:会话复用要求它在末尾
        ],
    }},
    "http2": {"hpack_strategy": "chrome", "settings": [[1, 65536], [2, 0], [4, 6291456], [6, 262144]],
              "window_update": 15663105,              # 三态:不写=补默认 15663105 / 0=不发这帧 / N=发 N
              "first_stream_id": 1,                   # 客户端首流号(正奇数);不写=1,真 Firefox 用 3
              "pseudo_header_order": ["m", "a", "s", "p"]},
}
geektls.check_profile(json.dumps(mine))          # 先离线自检:看 warnings 与 JA3/JA4
with Session(profile=mine) as s:
    print(s.get("https://example.com").selfcheck["ja4"])

8) 从抓包迁移:JA3 / JA4R / 原始 hex

with Session(ja3="771,4865-4866-4867,43-10-11-13-16-23-5-0-65281,4588-29-23-24,0") as s:
    r = s.get("https://example.com")             # 其余字段按引擎默认补齐
r = geektls.check_profile("t13d1516h2_8daaf6152771_d8a2da3f94cd")   # 反查内置预设

9) 抓包 → 预设(把线上真实指纹固化成文件)

import json, pathlib
r = Session(impersonate="chrome_150").get("https://tls.peet.ws/api/all")
cap = r.json()
spec = {  # 只保留指纹相关字段(tcp 节按宿主平台另配)
    "name": "my_captured_profile",
    "tls": {"detail": {"legacy_version": "0x0303", "ciphers": ["grease", "0x1301"], "extensions": []}},
    "http2": {"akamai": cap["http2"]["akamai_fingerprint"]},
}
pathlib.Path("my_profile.json").write_text(json.dumps(spec, ensure_ascii=False, indent=2))

更规范的做法是走仓库的 tests/e2e/cmd/gen-profiles(从原始 ClientHello 字节生成,落 core/profiles/builtin/ 并带证据等级)。

10) 回归/自校验

JA4 = "t13d1517h2_8daaf6152771_cb7bf5808d99"
with Session(impersonate="chrome_154_windows") as s:
    assert s.get("https://example.com").selfcheck["ja4"] == JA4

预设体系

  • 数量与命名:368 条,core/profiles/builtin/<name>.json,文件名即预设名,规范是 <家族>_<版本>[_<变体>][_<平台>]:chrome_154_windows、firefox_156_android、okhttp_3_12_12。
    • 平台后缀能判定就必须写(windows/macos/linux/android/ios),判不定的留空(工具/App 族);
    • Safari 也带 _macos——它同时有 macOS 与 iOS 形态(safari_18_6_ios),后缀只允许 _macos / _ios(已按此把 safari_16 → safari_16_macos、safari_18 → safari_18_legacy_macos);
    • 旧名是别名:改名过的预设(chrome_131/133/150、firefox_120/135 → *_windows;Safari 两条同上)旧名继续可用, 取到同一份形态;映射表只增不删,新代码用规范名。
    • 仍然没有族级短名/前缀匹配:impersonate="chrome_154" 会报 preset not found,要写全名。 完整规范与理由见 docs/03-profile-format.md §3.1(测试 core/profiles/naming_test.go)。
  • 字段:tls.detail(ciphers/扩展与负载/GREASE 策略)、http2(SETTINGS/window_update(三态)/伪头序/first_stream_id/hpack_strategy/headers_priority)、http3(transport params/inner hello 规约)、identity(导航头集合与顺序)、可选 tcp、grade、source。
  • 证据分级(grade 字段,详见 docs/09-alignment-and-superiority.md):
    • 留空 = 本项目自测(E1 真机抓包 / E1r 字段级实测 / E2 本机可复现)→ 参与 E1 级断言;
    • E2i / E2i-u = 谱系内插(实测锚点 + 逐字段稳定性规则,-u 表示区间内有变化且边界未知);
    • E3 = 外部指纹集导入(只补覆盖,不做保真承诺)。
    • 4 个 E1 级测试(fp oracle / Chromium GT / Firefox GT / TLS1.2 回退)一律跳过 grade != "" 的预设——没实测的不参与"实测"断言。
  • 怎么挑:要稳就挑 grade 为空、且与目标族/版本/平台都对的(describe_preset() 看全貌);只求覆盖面可用 E3。
  • 怎么加:见 docs/maintenance.md 的"预设入库流程"。由 gen-profiles 生成的预设禁止手改(CI 逐字节比对校验)。

自校验

每个响应带 selfcheck:实际发出 ClientHello 的自算 JA3/JA4 + JA3 fullstring、线上扩展序(含/剔 GREASE 双份)、GREASE 值与位置、协商 cipher/版本/ALPN、SNI 是否上链(IP 目标自动报 i);JA3/JA4R 入口还含期望值比对;gtls_check_profile 支持 profile JSON / JA3 / JA4 / JA4R / hex 五入参离线自检。

身份层也有对应校验(core/profiles/builtin_identity_test.go):任何预设都不得带 headless 令牌,且 UA 与 sec-ch-ua 的平台/版本必须自洽(Windows NT ↔ "Windows"、Macintosh ↔ "macOS"、Chrome/Edg 主版本 ↔ "Chromium";v="N")。

性能摘要

  • FFI 调用开销:gtls_version 6–7µs、gtls_check_profile 26–30µs(<50µs 目标达成)
  • 回环吞吐(连接池开启,并发 100,10s):共享 Session(同 origin 单连接,浏览器真实形态)≈5–9k req/s;每 worker 会话模型 Go 12.7k / Python 9.4k / Node 8.9k req/s
  • 冷启动:Session 初始化 0.2ms、首请求 ~3.5ms

与同类项目对比

对比依据(2026-09-29 复核):逐仓拉取下列项目 README 原文核对能力声明,结合 tls-spoofing-library-matrix 与 docs/10-ecosystem-comparison.md。 三点口径:① akamai/uls 实为 Akamai 的日志流 SIEM 工具,不是指纹库,已从对比剔除 (此前表格误列);② cyCronet 的地址是 2833844911/cyCronet (Python + Chromium Cronet 真栈)——此前按名字猜 slug(cycronet/cycronet)查不到就写"仓库不存在", 是错的:查不到 ≠ 不存在,已补回对比行;③ bogdanfinn/tls-client 的 README 本次拉取失败 (raw 与镜像均 404),其能力按既有文档与本项目 E3 导入记录描述。单元格 — 表示公开材料未说明 该维度(不等于没有)。

完整客户端(TLS / H2 / H3 伪装客户端)

项目 栈 / 语言 TLS 指纹 H2 帧 + 头序 H2 HPACK 策略 H3 / QUIC 四层 TCP WebSocket 预设与证据 响应内自校验
geektls Go(c-shared)+ Python / Node / Go 绑定 ✅ uTLS fork + E1 真机采集链路 ✅ ✅ 四档(generic/chrome/firefox/safari),255/394 预设带值 ✅ 内层 ClientHello 同 profile + transport params blob 直通;Initial 布局不可控(待 QUIC 栈内化后解锁) ✅ TTL/MSS/DF/window/wscale:setsockopt 三平台 + netstack 档(Linux root,gVisor 栈) ✅ RFC 6455 + permessage-deflate(握手走指纹链路) ✅ 394 条 grade/source 分级:29 自测 / 6 E2i / 8 E2i-u / 351 E3 ✅ selfcheck + check_profile 五入参
bogdanfinn/tls-client(hrequests、noble-tls、tls-client-sharp 等绑定) Go fhttp + utls ✅ ✅ — ✅ — — 自带 profile 集;与本项目 E3 覆盖(320 条)无直接来源关系——E3 的 source 逐条指向第三方快照 profiles/evidence/thirdparty/tls_config-0.0.2(TestE3SourceTraceable 校验),profile 组织形态是同类参照 —
lexiforest/curl_cffi(活跃)/ lwthiker/curl-impersonate(原始) libcurl 补丁 + BoringSSL / NSS ✅ ✅ — ✅(curl_cffi 新版起) ❌(libcurl 无 TCP 指纹面) ✅ 内置画像 + 自定义指纹;社区节奏最快 —
Danny-Dasilva/CycleTLS、cycletls_python Go utls + fhttp + quic-go ✅(JA3 可配置) ✅(fhttp 头序) — ✅ — ✅ profile 清单;socks4/5/5h —
sardanioss/httpcloak Rust 栈,Python/JS/C# 绑定 ✅ ✅(WINDOW_UPDATE/priority 可调) 部分(priority 侧) ✅(H3 GREASE 帧) ✅(TTL/MSS/Window,README 声明) — 内置 preset + "抓一次用到底"(JA3+Akamai 粘贴导入) —
jaredboynton/specter Rust + 自研 H2(RFC 9113)/ H3 ✅ Chrome 142–148、Firefox 133–151+ESR ✅(记录分帧/帧时序/池行为) — ✅ — ✅ 内置 profile + UA-CH 算法文档 —
zhkl0228/impersonator Java / kwik(QUIC) ✅ ✅ OkHttp 形态 — ✅ 含 QUIC Initial 布局(分片/乱序/PADDING 按浏览器拟真) — — — —
sqdshguy/wreq-js Node(Rust wreq 内核) ✅ ✅ Akamai — — — ✅(WHATWG 风格 + 会话复用) Chrome 至 149 / Firefox 151,声明"live capture 验证" —
daijro/hrequests Python(tls-client 内核) ✅ ✅ — — — — requests 风格 + BrowserForge 头生成 + 浏览器自动化 —
2833844911/cyCronet Python + Chromium Cronet 真栈(libcronet.so) ✅ 真栈(默认 chrome_144,tls_profiles.json 可自定义) ✅ 真栈 —(真栈内置,策略不可控) —(README 未见 H3/QUIC) ❌ ✅(WSS,TLS 指纹一致) chrome_144 + 自定义 json;SOCKS5 带鉴权 ❌(无自校验回读)
deedy5/primp、wangluozhe/requests-go、z402166914/pyhttpx、tocha688/curl-cffi-node 各语言封装 ✅ 依赖上游 ✅ 依赖上游(requests-go 另有 JA3 扩展随机化) — 部分 — 部分 — —
thesatellite-ai/fetchr Go + CLI + MCP server ✅(JA3/JA4) ✅ — ✅ — — 浏览器画像 —

采集 / 检测 / 代理(对照面,不是竞品)

项目 作用 与 geektls 的关系
gospider007/fp 独立 ClientHello 解析器 E1 采集链路直接使用(tests/e2e/cmd/e1-browser)
FoxIO-LLC/ja4、Crank-Git/ja4plus-go、XOR-op/ja-tools JA3 / JA4 / JA4+ 参考实现 JA4 规范与测试向量来源;只依赖 JA4 本体(JA4+ 部分方法有许可证限制)
wi1dcard/fingerproxy、LyleMi/ja3proxy、O-X-L/haproxy-ja4-fingerprint 反向代理 / 网关算指纹并透传 输出形态对照;selfcheck 做在响应里,不依赖网关
jaeles-project/gospider、gitee baixudong/gospider、Ecalose/gospider 爬虫 / 工具链(同名不同项目) 爬虫侧用法参照
tlsmask/tlsmask、Easonliuliang/helloprint 指纹伪装 / 一致性工具 UA ↔ TLS 一致性思路对照;落成身份层测试

上表里 geektls 的差异点

  1. 四层一起:TLS + H2(含 HPACK 编码策略四档)+ H3 / QUIC(内层 ClientHello 同 profile)+ TCP(TTL/MSS/DF/window/wscale:setsockopt 三平台 + Linux netstack 档)。上表其他客户端多数止步 TLS / H2;四层 TCP 只有 httpcloak 声明了同档能力。
  2. 证据分级:grade(30 自测 / 6 E2i / 8 E2i-u / 320 E3)+ source 溯源校验 + E1 真机采集链路 + 语料回归 + 外部 oracle 周检;同类普遍只给一份清单,不区分实测与转写。
  3. 响应内自校验:本次握手实际发出的 JA3 / JA4 / 扩展序 / GREASE 值直接从响应取,可当回归断言;check_profile 支持五种入参离线自检。
  4. 三语言同引擎:Python / Node / Go 共用同一 C ABI,跨语言 JA4 三方一致,不需要为每种语言重写指纹栈。
  5. 预设结构:394 条按 grade 分层(29 自测可参与严格断言 + 6 E2i / 8 E2i-u 谱系内插 + 351 E3 导入),覆盖浏览器 / App / 工具 / 代理等 29 族,含跨平台同版本一致性断言(chrome_152 / chrome_154 在 macOS / Android / Windows 上 JA4 逐字符相同)。
  6. 部署形态:Go 实现、CGO 只用于构建动态库,产物是单文件动态库 + 平台 wheel,无需 libcurl 补丁链。
  7. 自主化路线:指纹相关代码路径正向 100% 自有推进(uTLS / fhttp / quic-go-utls 内化裁枝四阶段,见 docs/plans/2026-09-29-self-contained-roadmap.md);密码学原语(circl / brotli / zstd)按行业共识保留成熟实现,不自写。
  8. 能力面补齐:WebSocket(wss / ws,握手走指纹链路)+ 明文 http:// + Python asyncio + 四编码自动解压 + 命令行入口 + requests 语义面(cookie jar / timeout 元组 / auth / 重定向开关 / 表单编码),与 CycleTLS / curl_cffi / noble-tls 的能力清单逐项对齐(逐库对照见 docs/10-ecosystem-comparison.md)。

T-HPACK 四档的证据来源:chrome 档对齐 Chromium QUICHE HpackEncoder 的默认策略(源码级), firefox 档对齐 Firefox 59 抓包(字节级),safari 档为保守近似(待 E1 校验);上游 x/net 编码器 "一切皆可入动表"的行为与前三者都不同。

相对短板(同一张表下的客观差距)

维度 差距
生态与熟悉度 远不如 curl_cffi / curl-impersonate:Python 迁移成本、示例与社区最少;没有 hrequests 那种浏览器自动化集成
真栈行为级 curl_cffi(libcurl + BoringSSL)与 cyCronet(Chromium Cronet 真栈)的行为级细节天然全真(含握手重试、协议栈内部实现);这里靠逐维度对齐逼近,理论上存在未发现的行为差异
预设更新 依赖人工采样(SLA 2 周);大量预设是 E3 转写而非实测,curl_cffi / curl-impersonate 靠社区补丁更快
H3 可控面 QUIC 首飞全控:首 datagram 填充下限(initial_packet_size,1200–1452,不设=1200)、SCID 长度(connection_id_length,0 = Chrome 形态空 SCID)、PADDING 位置、CRYPTO 分片表、scrambling 开关、coalesce 阈值(initial_layout,vendor patch #8/#10);transport params 顺序靠 blob 直通;Firefox / Safari H3 未实测
Safari 侧 HPACK 的 safari 档是全 literal 保守近似;padding 用实测字节数表达;无 CFNetwork 字节级证据
四层 Windows 仅 setsockopt 档(TTL/MSS/DF,MSS 项缺失);netstack 档(window/wscale 精确控制)仅 Linux root;IP ID / TSval 不可控
发布面 npm 与 Go module 尚未发布;wheel 只覆盖 5 平台(无 musllinux / Windows ARM64)
依赖 fork fhttp、quic-go-utls 是 vendor fork,升级上游要重打 patch 并跑回归(流程已登记,仍是维护成本)
有损入口 JA3 / JA4 入参天然丢负载,此处选择明确告警、而不是伪装保真,在只求"JA3 过检测"的场景不是最省事的路径

自主化进度(docs/plans/2026-09-29-self-contained-roadmap.md): 边界声明与依赖清单已完成;gvisor.dev/gvisor(netstack 档)已引入;core/internal/ 目前只有 registry ⇒ 自主化三项(uTLS 内化改写 / fhttp 裁枝内化 / quic-go-utls 内化)均未开始, "指纹路径 100% 自有"的终态尚未达成。不变量:ABI 签名只增不改、394 预设指纹输出逐比特不变、 每阶段全量回归 + L2 nginx 终审。

能力对齐现状与追赶排期(差距清单 + 关闭判据 + 明确不做的事)见 docs/plans/2026-09-29-parity-and-improvement-plan.md: 指纹能力面已对等或领先。形态面已补齐(明文 http:// / ws://、CLI、cookie 手感、 requests 语义面);剩余差距集中在发布面(Node/Go 未发布、平台不全)与两条结构性差距 (QUIC Initial 的 coalesce / 分片表属上述第三项,真栈行为级无法追平)。

已知边界与不足

边界 说明
QUIC 内层 ECH 与 bogdanfinn 服务端 其 QUIC server 不处理 ECH-in-QUIC 会静默失败(客户端侧已合成 Chrome 等效 payload;真服务器按规范忽略 GREASE ECH)
QUIC Initial 布局 已全控(vendor patch #8/#10):PADDING 位置、CRYPTO 分片表、scrambling 开关、coalesce 阈值(initial_layout)、首包填充下限(initial_packet_size,不设=1200,不是"精确尺寸")、首飞 SCID 长度(connection_id_length,0 = Chrome 形态空 SCID;此时 initial_source_connection_id 才允许空值)。逐字节复刻真机首包 1230B 还需 CH 尺寸与分片表一致(属 profile 侧保真,不在布局旋钮内)
明文 http:// 的边界 只走 H1(不做 h2c,无 prior knowledge / Upgrade 路径);经 HTTP 代理时走 CONNECT 隧道(不发 absolute-form GET http://…);明文没有 TLS 层 ⇒ selfcheck 恒为零值、force_http3 + http:// 直接报错
代理环境变量按 scheme 取 https/wss 读 HTTPS_PROXY、http/ws 读 HTTP_PROXY,都不跨 scheme 取(curl/requests 同语义);都没命中再退 ALL_PROXY
QUIC transport params 顺序/非标参数 经 transport params blob 直通可控(顺序与值均有断言);个别残余值与 blob 整块替换冲突,待 fork 决策
Windows TCP MSS 不支持(WSAENOPROTOOPT 实测),跳过+warning;raw socket 档仅 Linux 探测模式
uTLS PSK 复用 vs Go std 服务端 binder 校验失败(上游 interop,发出侧已证正确)
JA4 短哈希入参 哈希不可逆 ⇒ 只能反查内置预设;想精确复刻必须给 JA4R 或完整 profile
nginx L2 终审 ✅ 已通过(WSL2,35/35);JA4TCP 验收仍需真实二层网络

开发与发布

make build                     # 构建动态库到 build/
make cli                       # 构建命令行入口到 build/geektls
make smoke                     # Go/Python/Node 三语言冒烟
cd core && go test ./...       # 引擎全量(含 E1/E2 门禁、语料回归)
cd tests/e2e && go test ./...  # e2e:生成器校验、HPACK/H2 回放、loopback、跨语言
GEEKTLS_ORACLE_PRESETS=chrome_154_* GEEKTLS_ORACLE_ASSERT=1 \
  go test -tags external -run Oracle -v   # 外部 oracle 对拍(子集 + 不一致即失败)
wsl -d Ubuntu -- bash scripts/wsl-test.sh   # Linux 侧验证(WSL,Go 自动装到 ~/.local)
  • 发布:docs/versioning.md(语义化 + ABI 规则 + 三处版本同步);PyPI 流水线 .github/workflows/release-pypi.yml(五平台 wheel)、CI .github/workflows/ci.yml(含"预设必须等于生成器产物"逐字节校验)。
  • nightly 实测:.github/workflows/oracle-nightly.yml — 外部 oracle(JA3/JA4 + Akamai H2)以断言档跑选定子集、ECH 与真机会话恢复(resumed=true 是硬门禁)、Go/Python/Node 三语言一致性与两套绑定 e2e(Linux + Windows 真构建动态库)。子集由 GEEKTLS_ORACLE_PRESETS 控制,手动 dispatch 可临时加新预设;每周另有 .github/workflows/preset-freshness.yml 比对内置预设与 Chrome/Firefox 官方渠道版本,落后即开 issue。
  • 预设维护:docs/maintenance.md(Chrome 2 周 SLA、入库五步、oracle 周检、fork rebase)。

许可证

本项目自身按 MIT 授权(见 LICENSE,2026-09-29 定)。

发布物(wheel / npm 包 / Go module / 编译进动态库的依赖)内含第三方代码,各依赖的许可证与 归属声明登记在 LICENSES.md 并随 wheel 一起分发:全量闭包审计无 GPL/LGPL; 两个已知注意项:上游 fhttp 无显式 LICENSE(仅"无授权使用"风险,行业生态同此依赖) 与 JA4+ 的许可证/商标边界(只依赖 JA4 本体,见上文对比表)。

文档索引

文档 内容
CHANGELOG.md 各版本更新内容(0.1.5 起)
docs/00-architecture.md 技术选型、模块划分、FFI 模型
docs/01-fingerprint-dimensions.md 四层指纹维度清单
docs/02-ffi-abi.md C ABI 契约
docs/03-profile-format.md profile JSON schema + 预设体系
docs/06-task-list.md 任务计划与完成状态
docs/07-capability-gaps.md 能力缺口与实测记录(含族横向对照)
docs/08-plan-pending-samples.md 待补采样与后期扩充计划
docs/09-alignment-and-superiority.md 证据分级与同类对比(内部版)
docs/capability-matrix.yml 机器可读能力矩阵(CI 断言/变量映射共用)
docs/CONTRACT-FREEZE.md 已验证面冻结契约(防"改而改弱")
docs/plans/2026-09-24-geektls-hardening-and-h3-plan.md 硬化与 H3 补齐方案(2026-09-24)
docs/p1-utls-capability.md / p2-h2 / p4-h3 各层能力摸底矩阵
docs/11-lowlevel-forgery.md TLS 以下的指纹伪造:分层可行性、一致性红线、参考仓库
docs/12-pcap-import.md pcap 抓包 → 装载:分层可见性、五个坑、import-pcap 设计与端到端实测
docs/tcp-platform-matrix.md TCP 指纹平台边界
docs/benchmarks.md 性能基准
docs/versioning.md / docs/maintenance.md 版本与运营机制
profiles/evidence/README.md 预设证据登记
LICENSES.md 依赖许可证审计
docs/10-ecosystem-comparison.md 生态对比与差距分析(33 库逐维对照)
docs/plans/2026-09-29-self-contained-roadmap.md 自主化路线图(脱离第三方指纹栈)

非目标

  • 不做服务端指纹采集。
  • 不做浏览器级 JS 环境模拟(Canvas/WebGL 等)。
  • 不内置任何绕过具体站点防护的"开箱即用"策略——只提供精确的指纹原语。

About

spoof client tls(ja3,ja4,http2.0,http3.0,quic,tcp,clienthello....more)

Topics

Resources

Stars

19 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages