rawandahmad698/noble-tls
GitHub: rawandahmad698/noble-tls
一个基于 Python 的高级异步 TLS 库，通过自动更新 JA3 指纹与丰富配置实现高度拟真 HTTP 请求。
Stars: 303 | Forks: 41
# Noble TLS
[](https://www.python.org/downloads/release/python-310/)
Noble TLS 是一个基于 requests 和 tls-client 的高级 HTTP 库。
完全异步，支持自动更新 JA3 指纹。
# 安装
```
pip install noble-tls
```
### 功能特性
- [x] 自动从 bogdanfinn/tls-client 更新 TLS 客户端库
- [x] 异步支持
- [x] 代理支持（HTTP、HTTPS、SOCKS4、SOCKS5）
- [x] 自定义 JA3 字符串
- [x] 自定义 H2 和 H3 设置
- [x] 自定义支持的签名算法
- [x] 自定义支持的版本
- [x] 自定义密钥共享曲线（包括后量子算法）
- [x] 自定义证书压缩算法
- [x] 自定义伪头部顺序
- [x] 自定义连接流程
- [x] 自定义头部顺序
- [x] 76 种预设浏览器配置文件（Chrome、Firefox、Opera、Safari、iOS、iPadOS、Android）
- [x] 随机 TLS 扩展顺序
- [x] HTTP/3（QUIC）支持协议竞争
- [x] 证书钉扎（HPKP）
- [x] ECH（加密客户端 Hello）和 ALPS
- [x] 会话生命周期管理（关闭、从 Go 层获取/添加 Cookie）
- [x] 响应流式写入文件
- [x] 协议检测（`response.used_protocol`）
- [x] 毫秒级精度超时
- [x] IPv4/IPv6 控制
- [x] SNI 和 Host 头部覆盖
- [x] 轮询代理支持
- [x] `requests` 风格的 `history` 和 `allow_redirects`
## 新版特性
### 会话生命周期
现在可以显式销毁会话并在 Go 层管理 Cookie：
```
session = noble_tls.Session(client=Client.CHROME_133)
# 做你的工作...
res = await session.get("https://example.com")
# 在 Go 会话中直接管理 Cookie
cookies = await session.get_cookies("https://example.com")
await session.add_cookies("https://example.com", [
{"name": "sid", "value": "abc", "domain": "example.com", "path": "/"},
])
# 完成后释放 Go 内存和连接
await session.close()
# 或者一次性清除所有
await Session.close_all()
```
### 协议检测
每个响应都会告诉你实际协商的是哪个协议。使用 `Protocol` 枚举：
```
from noble_tls import Protocol
res = await session.get("https://example.com")
print(res.used_protocol) # Protocol.HTTP_2
if res.used_protocol == Protocol.HTTP_3:
print("Running over QUIC")
```
### HTTP/3 与协议竞争
支持 HTTP/3（QUIC），可以像 Chrome 一样对 HTTP/2 和 HTTP/3 进行竞争测试（HTTP/2 领先 300 毫秒，H3 仍可获胜）：
```
session = noble_tls.Session(
ja3_string="...",
protocol_racing=True,
h3_settings={"QPACK_MAX_TABLE_CAPACITY": 4096},
h3_settings_order=["QPACK_MAX_TABLE_CAPACITY"],
h3_pseudo_header_order=[":method", ":authority", ":scheme", ":path"],
h3_send_grease_frames=True,
)
```
如果 H3 导致问题，可以禁用：`disable_http3=True`。
### 网络与安全选项
每个会话的网络与安全设置：
```
session = noble_tls.Session(
client=Client.CHROME_133_PSK,
disable_ipv6=True, # IPv4 only
local_address="0.0.0.0:0", # Bind to specific interface (host:port)
server_name_overwrite="sni.com", # Override TLS SNI
is_rotating_proxy=True, # Force new connection per request
without_cookie_jar=True, # Disable cookie jar entirely
certificate_pinning={ # HPKP - reject if pin doesn't match
"example.com": ["sha256_pin_base64"],
},
)
# 每个请求：毫秒超时，主机覆盖，流式传输到文件
res = await session.get(
"https://example.com",
timeout_milliseconds=2500,
request_host_override="other.host.com",
stream_output_path="/tmp/response.json",
stream_output_block_size=4096,
)
```
### ECH、ALPS 与后量子曲线
加密客户端 Hello、应用层协议设置以及后量子密钥共享曲线，用于自定义 TLS 配置：
```
session = noble_tls.Session(
ja3_string="...",
alps_protocols=["h2"],
ech_candidate_payloads=[256],
ech_candidate_cipher_suites=[
{"kdfId": "HKDF_SHA256", "aeadId": "AEAD_AES_128_GCM"},
],
key_share_curves=["GREASE", "X25519MLKEM768", "X25519"],
supported_signature_algorithms=[
"ECDSAWithP256AndSHA256",
"PSSWithSHA256",
"Ed25519",
],
record_size_limit=16384,
allow_http=True,
stream_id=1,
)
```
### 更新浏览器配置文件
现在有 76 个配置文件，已与最新的 Go 源代码同步。新增加：
| 浏览器 | 新增配置文件 |
|--------|-------------|
| Chrome | 130 PSK、144、144 PSK、146 PSK |
| Firefox | 123、133、146 PSK、147 PSK |
| Safari | iOS 18.5、iOS 26.0 |
已移除 `CHROME_141` 和 `CHROME_142`
### 默认头部（多值）
独立于常规的 `headers` 字典，`default_headers` 使用多值格式，当请求未指定头部时作为默认值：
```
session = noble_tls.Session(
client=Client.CHROME_133,
default_headers={"Accept": ["text/html", "application/json"]},
)
```
# 示例
语法紧密遵循 [requests](https://github.com/psf/requests)。大多数用法相同。
示例 1 —— 预设浏览器配置文件：
```
import asyncio
import noble_tls
from noble_tls import Client
async def main():
await noble_tls.update_if_necessary()
session = noble_tls.Session(
client=Client.CHROME_133,
random_tls_extension_order=True
)
res = await session.get(
"https://www.example.com/",
headers={"key1": "value1"},
proxy="http://user:password@host:port"
)
print(res.status_code)
print(res.used_protocol)
print(res.text)
await session.close()
asyncio.run(main())
```
示例 2 —— 自定义 JA3 指纹：
```
import asyncio
import noble_tls
async def main():
await noble_tls.update_if_necessary()
session = noble_tls.Session(
ja3_string="771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513,29-23-24,0",
h2_settings={
"HEADER_TABLE_SIZE": 65536,
"MAX_CONCURRENT_STREAMS": 1000,
"INITIAL_WINDOW_SIZE": 6291456,
"MAX_HEADER_LIST_SIZE": 262144
},
h2_settings_order=[
"HEADER_TABLE_SIZE",
"MAX_CONCURRENT_STREAMS",
"INITIAL_WINDOW_SIZE",
"MAX_HEADER_LIST_SIZE"
],
supported_signature_algorithms=[
"ECDSAWithP256AndSHA256",
"PSSWithSHA256",
"PKCS1WithSHA256",
"ECDSAWithP384AndSHA384",
"PSSWithSHA384",
"PKCS1WithSHA384",
"PSSWithSHA512",
"PKCS1WithSHA512",
],
supported_versions=["GREASE", "1.3", "1.2"],
key_share_curves=["GREASE", "X25519"],
cert_compression_algo="brotli",
pseudo_header_order=[":method", ":authority", ":scheme", ":path"],
connection_flow=15663105,
header_order=["accept", "user-agent", "accept-encoding", "accept-language"]
)
res = await session.post(
"https://www.example.com/",
headers={"key1": "value1"},
proxy="http://user:password@host:port"
)
print(res.text)
await session.close()
asyncio.run(main())
```
更多示例请参考 [`examples/`](examples/) 文件夹。
# Pyinstaller / Pyarmor
**如果要将库打包到 Pyinstaller 或 Pyarmor，请在命令中添加以下内容：**
Linux - Ubuntu / x86：
```
--add-binary '{path_to_library}/tls_client/dependencies/tls-client-x86.so:tls_client/dependencies'
```
Linux Alpine / AMD64：
```
--add-binary '{path_to_library}/tls_client/dependencies/tls-client-amd64.so:tls_client/dependencies'
```
MacOS M1 及更早版本：
```
--add-binary '{path_to_library}/tls_client/dependencies/tls-client-x86.dylib:tls_client/dependencies'
```
MacOS M2：
```
--add-binary '{path_to_library}/tls_client/dependencies/tls-client-arm64.dylib:tls_client/dependencies'
```
Windows：
```
--add-binary '{path_to_library}/tls_client/dependencies/tls-client-64.dll;tls_client/dependencies'
```
### 最后说明
该软件包以《Rebel Moon: Part One - A Child of Fire》中的 [Admiral Att Noble](https://www.youtube.com/watch?v=cO-GPaASWV0) 命名。
### 感谢
特别感谢 [Bogdanfinn](https://github.com/bogdanfinn) 开源了他的 Go 语言 [tls-client](https://github.com/bogdanfinn/tls-client)，
以及 [FlorianREGAZ](https://github.com/FlorianREGAZ) 提供的原始 Python 包装器。
可用客户端标识符（76 个配置文件）
| Chrome | Safari | Firefox | Opera | |--------|--------|---------|-------| | `CHROME_103` | `SAFARI_15_6_1` | `FIREFOX_102` | `OPERA_89` | | `CHROME_104` | `SAFARI_16_0` | `FIREFOX_104` | `OPERA_90` | | `CHROME_105` | `SAFARI_IPAD_15_6` | `FIREFOX_105` | `OPERA_91` | | `CHROME_106` | `SAFARI_IOS_15_5` | `FIREFOX_106` | | | `CHROME_107` | `SAFARI_IOS_15_6` | `FIREFOX_108` | | | `CHROME_108` | `SAFARI_IOS_16_0` | `FIREFOX_110` | | | `CHROME_109` | `SAFARI_IOS_17_0` | `FIREFOX_117` | | | `CHROME_110` | `SAFARI_IOS_18_0` | `FIREFOX_120` | | | `CHROME_111` | `SAFARI_IOS_18_5` | `FIREFOX_123` | | | `CHROME_112` | `SAFARI_IOS_26_0` | `FIREFOX_132` | | | `CHROME_116_PSK` | | `FIREFOX_133` | | | `CHROME_116_PSK_PQ` | | `FIREFOX_135` | | | `CHROME_117` | | `FIREFOX_146_PSK` | | | `CHROME_120` | | `FIREFOX_147` | | | `CHROME_124` | | `FIREFOX_147_PSK` | | | `CHROME_130_PSK` | | | | | `CHROME_131` | | | | | `CHROME_131_PSK` | | | | | `CHROME_133` | | | | | `CHROME_133_PSK` | | | | | `CHROME_144` | | | | | `CHROME_144_PSK` | | | | | `CHROME_146` | | | | | `CHROME_146_PSK` | | | | | Mobile / App | |-------------| | `ZALANDO_ANDROID_MOBILE`, `ZALANDO_IOS_MOBILE` | | `NIKE_IOS_MOBILE`, `NIKE_ANDROID_MOBILE` | | `CLOUDSCRAPER` | | `MMS_IOS`, `MMS_IOS_1`, `MMS_IOS_2`, `MMS_IOS_3` | | `MESH_IOS`, `MESH_IOS_1`, `MESH_IOS_2` | | `MESH_ANDROID`, `MESH_ANDROID_1`, `MESH_ANDROID_2` | | `CONFIRMED_IOS`, `CONFIRMED_ANDROID` | | `OKHTTP4_ANDROID_7` through `OKHTTP4_ANDROID_13` |标签：ALPS, Android, Chrome, Cookie管理, DSL, ECH, Firefox, Host头覆盖, HPKP, HTTP/3, HTTPS代理, HTTP代理, HTTP库, iOS, iPadOS, IPv4控制, IPv6控制, JA3指纹, Opera, QUIC, Radare2, requests库, Safari, SNI覆盖, SOCKS5代理, SSL/TLS混淆, TLS伪装, TLS指纹, 代理支持, 会话管理, 加密客户端问候, 协议检测, 告警, 响应流, 安全测试, 异步HTTP, 攻击性安全, 旋转代理, 日志审计, 毫秒级超时, 流量伪装, 浏览器指纹, 浏览器配置文件, 网络规避, 自动更新, 自定义TLS设置, 证书固定, 逆向工具, 重定向管理