smilebank7/anti-scrapling
GitHub: smilebank7/anti-scrapling
一款通过多层 TLS/HTTP2/JS 挑战与行为分析来拦截现代自动化抓取工具的 HTTP 安全防护中间件。
Stars: 1 | Forks: 0
# Anti-Scrapling
**在 HTTP 层拦截现代抓取工具（Scrapling、curl-impersonate、undetected-playwright、camoufox）。**
[](https://github.com/smilebank7/anti-scrapling/actions)
[](LICENSE)
[](https://github.com/smilebank7/anti-scrapling/releases)
## 它的功能
- **全栈指纹识别。** TLS ClientHello (JA3/JA4)、HTTP/2 SETTINGS 帧、header 顺序，以及探测 40 多种浏览器属性的 JS 验证（challenge）——所有这些结合成一个单一的风险评分。
- **无需 CAPTCHA 即可拦截。** 真实用户通过工作量证明（proof-of-work）验证和绑定的通行令牌（pass-token）静默通过。爬虫将收到 403 错误。
- **随处运行。** 即插即用的 Docker 反向代理、适用于 Kubernetes 的 Helm chart，或适用于 Express、NestJS、FastAPI 和 Flask 的 SDK 中间件。
## 工作原理
```
┌─────────────────────────────────────────────────────┐
│ Detection pipeline │
│ │
[client request] │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
─────────────────────►│ │ TLS/JA3 │ │ HTTP/H2 │ │ IP reputation │ │
│ │ JA4/JA4H │─►│ headers │─►│ ASN / datactr │ │
│ └──────────┘ └──────────┘ └────────┬─────────┘ │
│ │ │
│ ┌────────▼─────────┐ │
│ │ Policy engine │ │
│ │ (YAML + CEL) │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌─────────────▼──────────┐ │
│ │ Verdict: ALLOW / │ │
│ │ CHALLENGE / DENY │ │
│ └─────────────┬──────────┘ │
└────────────────────────────────────────┼────────────┘
│
┌────────────────────────────────────────────┤
│ │
ALLOW │ CHALLENGE │ DENY
▼ ▼ ▼
[upstream app] [JS challenge page] [403]
PoW + fingerprint
collect → score
→ pass-token cookie
→ 302 original URL
```
## 快速开始
### 1. Docker
```
docker run -p 8080:8080 \
-e AS_TARGET=http://your-app:3000 \
ghcr.io/smilebank7/anti-scrapling:latest
```
您的应用现在已在 `http://localhost:8080` 处受到保护。所有流量都将通过检测 pipeline 进行代理。
### 2. Kubernetes (Helm)
```
helm repo add anti-scrapling https://anti-scrapling.github.io/charts
helm install anti-scrapling smilebank7/anti-scrapling \
--set config.target=http://your-app-service:3000 \
--set config.tokenSecretFile=/etc/anti-scrapling/token.key
```
有关完整的值参考，请参阅 [`deploy/helm/README.md`](deploy/helm/README.md)。
### 3. SDK 中间件
**Node / Express:**
```
import express from 'express';
import { antiScrapling } from '@anti-scrapling/node/express';
const app = express();
app.use(antiScrapling({ daemonUrl: 'http://localhost:9091' }));
app.get('/', (req, res) => res.json({ ok: true }));
app.listen(3000);
```
**Python / FastAPI:**
```
from fastapi import FastAPI
from anti_scrapling import Client, AntiScraplingMiddleware
app = FastAPI()
client = Client(daemon_url="http://localhost:9091")
app.add_middleware(AntiScraplingMiddleware, client=client)
```
SDK 模式需要单独运行 daemon。只有当 daemon 终止 TLS 时，才能使用 TLS 层信号（JA3/JA4）。
## 检测层
| 层级 | 检查内容 | 信号 |
|-------|---------------|---------|
| **TLS** | JA3/JA4 哈希、JA4H header 指纹、H2 SETTINGS 帧、QUIC 枢轴 | `ja3_mismatch`、`ja3_known_scraper`、`h2_akamai_mismatch` |
| **HTTP 语义** | Header 顺序、`User-Agent` 与 `Sec-CH-UA` 的一致性、`Sec-Fetch-*` 有效性、BrowserForge 怪异特征 | `ua_ch_mismatch`、`browserforge_quirk`、`header_order_anomaly` |
| **IP 信誉** | 数据中心 ASN、Tor 出口节点、移动运营商（信任度提升） | `datacenter_ip`、`tor_exit`、`mobile_ip` |
| **JS 验证** | 40 多项浏览器属性探测：navigator、WebGL、canvas、audio、fonts、speech、service worker、shadow DOM | `nav_webdriver_set`、`canvas_seeded_noise`、`runtime_console_debug_disabled`、... |
| **行为分析** | 资源拦截模式、鼠标轨迹几何、Turnstile 自动点击时机 | `behavior_resource_block`、`behavior_smooth_path`、`behavior_turnstile_clicker` |
## 架构
```
anti-scrapling/
├── cmd/
│ ├── antiscrapling/ # main proxy daemon
│ └── antiscrapling-cli/ # admin CLI
├── internal/
│ ├── server/ # TLS listener + ClientHello capture
│ ├── proxy/ # reverse-proxy forwarder
│ ├── signal/
│ │ ├── tls/ # JA3/JA4 computation
│ │ ├── http2/ # H2 SETTINGS + pseudo-header order
│ │ ├── headers/ # header order, UA/CH consistency
│ │ ├── ip/ # ASN, datacenter, Tor
│ │ ├── fingerprint/ # JS report parser and scorer
│ │ └── behavior/ # telemetry beacon ingestion
│ ├── policy/ # YAML policy engine + CEL expressions
│ ├── decision/ # score combiner + verdict
│ ├── challenge/ # PoW issuance and verification
│ ├── token/ # pass-token (JWT) issue/verify
│ ├── cache/ # in-memory + optional Redis
│ └── observability/ # Prometheus, slog, audit endpoint
├── web/challenge/ # JS bundle served as the challenge page
├── sdk/
│ ├── node/ # @anti-scrapling/node
│ └── python/ # anti-scrapling (PyPI)
├── deploy/
│ ├── docker/
│ ├── helm/
│ └── examples/ # nginx, Caddy, Traefik configs
└── policies/
├── default.yaml # balanced baseline
└── strict.yaml # paranoid mode
```
## 对比
| 功能 | Anti-Scrapling | Anubis | Cloudflare Turnstile | CrowdSec |
|---------|---------------|--------|---------------------|----------|
| 开源 | 是 (Apache-2.0) | 是 (AGPL-3.0) | 否 | 是 (MIT) |
| 部署模型 | 反向代理或 SDK 中间件 | 反向代理 | CDN / JS 代码片段 | Agent + bouncer |
| TLS 指纹识别 (JA3/JA4) | 是 | 否 | 是（不透明） | 否 |
| HTTP/2 指纹识别 | 是 | 否 | 是（不透明） | 否 |
| JS 验证 | 是 (PoW + 40 多项探测) | 是（仅 PoW） | 是（隐形） | 否 |
| 行为分析 | 是 | 否 | 是（不透明） | 部分 |
| IP 信誉 | 是（内置 GeoLite2-ASN） | 否 | 是（不透明） | 是 |
| 多协议指纹识别 | 是 (TLS + H2 + HTTP + JS) | 否 | 否 | 否 |
| 自托管 | 是 | 是 | 否 | 是 |
| Scrapling 专属信号 | 是（40 多项目标探测） | 否 | 否 | 否 |
## 文档
| 文档 | 描述 |
|----------|-------------|
| [威胁模型](docs/01-threat-model.md) | Scrapling 绕过技术的完整目录及我们的对策 |
| [架构](docs/02-architecture.md) | 设计决策、模块边界、pipeline 图表 |
| [构建计划](docs/03-build-plan.md) | 带有完成状态的分波次构建计划 |
| [入门指南](docs/04-getting-started.md) | 5 分钟演练：安装、配置、验证、调优 |
| [策略参考](docs/05-policy-reference.md) | 包含所有字段和信号权重的完整 YAML schema 参考 |
| [SDK 集成](docs/06-sdk-integration.md) | 包含所有配置选项的 Node 和 Python 集成指南 |
| [运维](docs/07-operations.md) | 容量规划、可观测性、日志记录、误报调试 |
| [常见问题](docs/08-faq.md) | 关于准确性、隐私和 CDN 兼容性的常见问题 |
| [策略](policies/README.md) | 内置策略文件：schema、规则、评分权重 |
| [Docker 部署](deploy/docker/README.md) | Docker 镜像、环境变量、compose 示例 |
| [Helm 部署](deploy/helm/README.md) | Helm chart 值参考 |
| [反向代理示例](deploy/examples/README.md) | nginx、Caddy、Traefik 集成示例 |
## 项目状态
**Alpha — 正在积极开发中。** 核心检测 pipeline、策略引擎、JS 验证以及两个 SDK 均已实现。在针对您的特定威胁模型进行评估之前，暂不建议将该项目用于生产环境。
### 路线图
- **v0.2** — Redis 缓存后端，无需重启即可热重载策略
- **v0.3** — 跨实例的分布式决策共享
- **v0.4** — 基于机器学习（ML）的行为评分（取代加权规则）
- **v1.0** — 生产环境加固、稳定的 API、完整的测试覆盖率
## 许可证
Apache-2.0。请参阅 [LICENSE](LICENSE)。
## 致谢
Anti-Scrapling 建立在以下理念和现有技术的基础之上：
- [Anubis](https://github.com/TecharoHQ/anubis) — PoW 验证设计及整体方案的灵感
- [FoxIO JA4+](https://github.com/FoxIO-LLC/ja4) — JA4 指纹规范
- [salesforce/ja3](https://github.com/salesforce/ja3) — 原始 JA3 指纹规范
- [FingerprintJS](https://github.com/fingerprintjs/fingerprintjs) — 浏览器指纹识别技术
- [CreepJS](https://github.com/abrahamjuliot/creepjs) — 全面的无头模式（headless）检测探测
- [BotD](https://github.com/fingerprintjs/BotD) — 机器人（bot）检测信号目录
- [D4Vinci/Scrapling](https://github.com/D4Vinci/Scrapling) — 我们用于模拟对抗的对手
标签：CISA项目, EVTX分析, Radare2, TLS指纹, Web安全, 中间件, 反向代理, 反爬虫, 子域名突变, 搜索引擎查询, 数据可视化, 日志审计, 流量检测, 自定义请求头, 蓝队分析, 请求拦截, 逆向工具