KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

Youzi-Mask

★ 14 Open GitHub ↗

Youzi-Mask 全新版补环境框架，采用模块化开发，轻松过瑞数6，cloudflare , 小红书x_s ,抖音a_b等算法；The new Youzi-Mask is a modular environment simulation framework. It easily bypasses Real6, Cloudflare verification, as well as Xiaohongshu x_s and Douyin a_b core algorithms with stable and reliable performance.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Youzi-Mask 🎭

[English Documentation](./README_EN.md)

> 一个面向 JavaScript 逆向、浏览器环境模拟、指纹补全和签名接口化调用的 Node.js 运行时框架。

Youzi-Mask 的核心目标很直接：把浏览器里的关键运行环境搬到 Node.js 中，让目标 JavaScript 可以在本地跑起来、调起来、服务化调用起来。它适合用来处理签名参数、加密参数、Cookie、请求头、风控字段等需要浏览器环境支撑的逻辑。

> 本项目仅用于学习、研究、调试和合法授权场景。请勿用于未授权访问、绕过限制、攻击行为或违反目标服务条款的用途。

---

## ✨ 项目特点

- 🧩 **补环境友好**：内置 `window`、`document`、`navigator`、`location`、`screen`、`storage`、`fetch`、`xhr`、`canvas`、`WebGL`、`WebRTC` 等常见浏览器对象。
- 🕵️ **指纹对抗辅助**：支持原型链、构造器、属性描述符、`Symbol.toStringTag`、`Function.prototype.toString` 等细节模拟。
- 🔍 **访问轨迹可观测**：通过 Proxy 监听目标代码访问了哪些字段，优先定位缺失环境和 `undefined` 来源。
- 🚀 **站点模板化管理**：每个站点独立放在 `start/站点名` 下，环境、目标代码、运行入口、Python 调用示例互不污染。
- 🌐 **本地服务化调用**：把 `get_info` 暴露为 HTTP 接口，方便 Python、Go、Java 或其他采集程序调用。
- 🔐 **常用加密工具内置**：集成 `crypto-js`、`jsencrypt`、Node.js `crypto`，方便还原 MD5、SHA、AES、RSA、BASE64 等逻辑。
- 🛠️ **调试到生产复用**：同一份 `run.js` 既可以本地打印调试，也可以一键切换成本地签名服务。

---

## ⚡ 快速开始

### 1. 安装依赖 📦

```bash
npm install
```

### 2. 创建站点模板 🧱

```bash
npm run new my_site
```

生成目录：

```text
start/my_site/
  env.js
  target_code.js
  run.js
  main.py
```

### 3. 抓取浏览器环境 🧲

打开目标网页，在浏览器控制台执行 `utils/grab.js` 中的环境抓取脚本。

把输出结果放到：

```text
start/my_site/env.js
```

常见需要补充的数据：

- `my_document`
- `my_navigator`
- `my_location`
- `my_history`
- `my_screen`
- `my_window`
- `my_localStorage`
- `my_sessionStorage`
- 站点私有变量
- 安全产品相关埋点变量

### 4. 放入目标代码 🎯

把目标 JavaScript 放到：

```text
start/my_site/target_code.js
```

推荐把最终要调用的能力挂到 `window` 上：

```js
window.youzi = function () {
  return 'result';
};
```

### 5. 编写运行入口 🏃

在 `start/my_site/run.js` 中组织环境、目标代码和统一出口：

```js
IS_LOG = true;
IS_OPEN_SERVER = false;

require('./env.js');
require('./target_code.js');

function get_info() {
  return window.youzi();
}

console.log(get_info());

module.exports = {
  get_info
};

require('../../src/server/1_index');
```

运行：

```bash
node start/my_site/run.js
```

### 6. 开启 HTTP 服务 🌐

如果要给 Python 或其他程序调用，把 `run.js` 中的配置改成：

```js
IS_OPEN_SERVER = true;
```

再次运行：

```bash
node start/my_site/run.js
```

默认接口：

```text
GET  /get_info
POST /get_info
GET  /get_info_async
POST /get_info_async
```

默认地址：

```text
http://127.0.0.1:3000
```

---

## 🧭 项目结构

```text
Youzi-Mask/
├── config/
│   └── env.config.js              # 全局开关与调试配置
├── src/
│   ├── core/                      # 核心运行时能力
│   ├── env/                       # 浏览器环境模拟层
│   ├── js_hook/                   # JS Hook 辅助
│   ├── server/                    # 本地 HTTP 服务
│   ├── template/site/             # 新站点模板
│   ├── utils/                     # 工具函数
│   └── v8_hook/                   # V8 相关 Hook 能力
├── start/
│   ├── test/                      # 测试样例
│   ├── cf/                        # 站点样例
│   ├── douyin_a_b/                # 站点样例
│   ├── pdd/                       # 站点样例
│   ├── ths/                       # 站点样例
│   ├── xhs/                       # 站点样例
│   └── yuanyuanxue10/             # 站点样例
├── utils/
│   ├── grab.js                    # 浏览器环境抓取脚本
│   └── killport.ps1               # Windows 端口处理脚本
├── package.json
└── README.md
```

---

## 🧠 框架运行模型

Youzi-Mask 可以理解为五层结构：

```text
目标调用方
  ↓
run.js：统一入口，定义 get_info
  ↓
env.js：注入浏览器环境数据
  ↓
target_code.js：运行目标 JavaScript
  ↓
src/env + src/core：提供浏览器对象、原型链、toString、Proxy、网络和加密能力
```

运行时重点关注三件事：

1. **环境是否像浏览器**：目标代码需要的对象、字段、原型关系是否存在。
2. **调用链是否稳定**：目标代码是否能稳定跑到签名、加密或参数生成位置。
3. **结果是否可复用**：最终通过 `get_info` 输出统一结果，既能本地调试，也能服务化调用。

---

## 🔧 核心能力详解

### 1. 浏览器环境模拟 🪟

框架在 Node.js 中模拟常见浏览器对象，让依赖浏览器上下文的目标代码可以在本地运行。

主要覆盖：

- `window`
- `document`
- `location`
- `navigator`
- `history`
- `screen`
- `XMLHttpRequest`
- `WebSocket`
- `fetch`
- `Headers`
- `Request`
- `Response`
- `localStorage`
- `sessionStorage`
- `canvas`
- `WebGL`
- `WebRTC`
- `AudioContext`
- `performance`
- `setTimeout` / `setInterval`
- 常见 HTML Element 构造器
- 常见原型链与属性描述符

适合处理目标代码中的环境检测、指纹读取、DOM 依赖和浏览器 API 依赖。

### 2. 原型链与构造器模拟 🧬

很多检测逻辑不会只判断字段是否存在，还会继续检查对象的构造器、原型、描述符和调用方式。

框架重点支持：

- 构造器名称伪装
- `Illegal constructor` 行为模拟
- `Illegal invocation` 行为模拟
- 原型链继承关系模拟
- `Symbol.toStringTag` 模拟
- 属性描述符控制
- getter / setter 行为控制
- 实例合法性校验

这部分能力主要用来降低“看起来不像浏览器”的风险。

### 3. `toString` 保护 🪞

不少风控代码会检查函数是否像原生函数：

```js
Function.prototype.toString.call(window.fetch)
```

框架会让常见模拟函数返回类似浏览器原生函数的形态：

```js
function fetch() { [native code] }
```

这能减少目标代码通过函数源码字符串识别 Node.js 环境的概率。

### 4. Proxy 监听与补环境辅助 🔍

补环境最怕“缺什么不知道”。框架内置代理监听能力，用来观察目标代码访问路径。

典型用途：

- 判断缺少哪个浏览器属性
- 定位 `undefined` 来源
- 观察读取了哪些指纹字段
- 辅助补全 `navigator`、`document`、`screen` 等对象
- 跟踪环境检测路径

调试初期建议只看 `undefined`，能大幅减少噪音。

### 5. 网络请求支持 📡

框架基于 `node-fetch` 提供接近浏览器形态的：

- `fetch`
- `Headers`
- `Request`
- `Response`

如果目标代码依赖 `fetch` 请求，可以在 Node.js 中继续执行。同时框架会补充常见请求头，让请求行为更接近浏览器。

### 6. 加密工具箱 🔐

已内置常用加密能力：

- `crypto-js`
- `jsencrypt`
- Node.js `crypto`
- MD5
- SHA256
- BASE64
- AES
- RSA
- UTF-8 编码处理

适合快速还原签名、加密参数、请求头字段和 Cookie 生成逻辑。

---

## 🌐 本地服务调用

开启 `IS_OPEN_SERVER = true` 后，框架会把 `get_info` 暴露为 HTTP 接口。

### 无参数调用

`run.js`：

```js
function get_info() {
  return window.youzi();
}
```

Python：

```python
import requests

res = requests.get('http://127.0.0.1:3000/get_info').json()
print(res['data']['value'])
```

### 有参数调用

`run.js`：

```js
function get_info(page) {
  return window.youzi(page);
}
```

Python：

```python
import requests

payload = {
    'page': 1
}

res = requests.post('http://127.0.0.1:3000/get_info', json=payload).json()
print(res['data']['value'])
```

### 多参数调用

`run.js`：

```js
function get_info(url, body) {
  return window.sign(url, body);
}
```

Python：

```python
import requests

payload = {
    'url': '/api/test',
    'body': {
        'page': 1,
        'size': 10
    }
}

res = requests.post('http://127.0.0.1:3000/get_info', json=payload).json()
print(res['data']['value'])
```

### 异步调用

`run.js`：

```js
async function get_info(page) {
  await window._sleep(1);
  return window.youzi(page);
}
```

Python：

```python
import requests

res = requests.post(
    'http://127.0.0.1:3000/get_info_async',
    json={'page': 1, 'wait': 0}
).json()

print(res['data']['value'])
```

统一响应格式：

```json
{
  "status": 0,
  "message": "ok",
  "data": {
    "value": "result"
  }
}
```

---

## ⚙️ 常用配置

配置可以在 `run.js` 中提前声明，也可以走默认值。

```js
IS_LOG = true;
IS_PROXY = true;
IS_ONLY_LOG_UNDEFINED = true;
LOG_FILTER = [];
MAX_LOG_LEN = 100;
IS_OPEN_SERVER = false;
MY_SERVER_PORT = 3000;
Hook_Error_Stack = true;
IS_LOG_SETTING = false;
IS_RECURSION_PROXY = false;
IS_ONLY_LOG_UNDEFINED_DEEP = false;
IS_DEBUG_DEEP = false;
```

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `IS_LOG` | `true` | 全局日志开关。开启后会输出环境访问、调试提示、服务启动等运行信息 |
| `IS_PROXY` | `true` | 一级 Proxy 监听开关。用于观察目标代码直接访问了哪些环境字段 |
| `IS_ONLY_LOG_UNDEFINED` | `true` | 一级 Proxy 是否只打印 `undefined` 访问。补环境初期建议开启，方便优先处理缺失字段 |
| `LOG_FILTER` | `[]` | 日志关键词过滤。为空时不过滤；填写关键词后只关注匹配到的访问记录 |
| `MAX_LOG_LEN` | `100` | 单条 watch 日志最大输出长度，避免对象过大时刷屏 |
| `IS_OPEN_SERVER` | `false` | 本地 HTTP 服务开关。开启后会暴露 `/get_info` 和 `/get_info_async` |
| `MY_SERVER_PORT` | `3000` | 本地 HTTP 服务端口 |
| `Hook_Error_Stack` | `true` | 错误堆栈处理开关。用于降低错误栈暴露 Node.js 运行痕迹的概率 |
| `IS_LOG_SETTING` | `false` | 是否打印设置值行为。开启后可以观察目标代码对环境字段的写入动作 |
| `IS_RECURSION_PROXY` | `false` | 递归代理监听开关。用于深入观察多层对象访问；开启后通常会关闭或弱化一级代理思路 |
| `IS_ONLY_LOG_UNDEFINED_DEEP` | `false` | 递归代理是否只打印深层 `undefined` 访问。适合对象层级很深、日志噪音很大的场景 |
| `IS_DEBUG_DEEP` | `false` | 递归代理 debug 模式。联调递归代理本身或排查深层代理异常时使用 |

配置作用域建议：

- `IS_LOG`、`IS_PROXY`、`IS_ONLY_LOG_UNDEFINED`：日常补环境最常用。
- `IS_LOG_SETTING`：目标代码会动态写入环境字段时再开。
- `IS_RECURSION_PROXY`、`IS_ONLY_LOG_UNDEFINED_DEEP`、`IS_DEBUG_DEEP`：对象层级复杂、一级监听不够用时再开。
- `IS_OPEN_SERVER`、`MY_SERVER_PORT`：本地接口化调用时再开。

调试建议：

```js
IS_LOG = true;
IS_PROXY = true;
IS_ONLY_LOG_UNDEFINED = true;
IS_OPEN_SERVER = false;
```

服务建议：

```js
IS_LOG = false;
IS_PROXY = false;
IS_OPEN_SERVER = true;
```

---

## 🧪 推荐工作流

### 第一步：创建站点 🏗️

```bash
npm run new my_site
```

### 第二步：抓取环境 🧲

在浏览器控制台执行 `utils/grab.js`，把结果填入 `start/my_site/env.js`。

### 第三步：放入目标代码 🎯

把目标 JavaScript 放入 `start/my_site/target_code.js`。

### 第四步：打开调试日志 🔦

```js
IS_LOG = true;
IS_PROXY = true;
IS_ONLY_LOG_UNDEFINED = true;
```

运行：

```bash
node start/my_site/run.js
```

优先补齐日志里出现的 `undefined` 字段。

### 第五步：收敛环境 🧹

当目标逻辑稳定后，逐步关闭高噪音日志：

```js
IS_LOG = false;
IS_PROXY = false;
```

### 第六步：开启服务 🚀

```js
IS_OPEN_SERVER = true;
```

让外部程序通过 `/get_info` 或 `/get_info_async` 调用结果。

---

## 📁 站点文件说明

### `env.js`

负责准备目标站点运行所需的环境数据。

通常包含：

- 浏览器环境抓取结果
- 页面 URL、UA、Referer 等上下文
- 本地存储数据
- Cookie 或站点初始化变量
- 目标代码运行前必须存在的全局字段

### `target_code.js`

负责存放目标 JavaScript。

建议保持目标代码尽量原始，只做必要的导出挂载，避免过度修改导致后续难以对照网页版本。

### `run.js`

负责组织完整运行链路。

它通常承担四件事：

1. 设置调试或服务配置
2. 加载 `env.js`
3. 加载 `target_code.js`
4. 定义并导出 `get_info`

### `main.py`

Python 调用示例，用来验证本地服务是否可用。

---

## 🧯 常见问题

### 运行时报“请先使用吐环境脚本去网页控制台里面抓取基础数据”

说明当前站点缺少基础环境数据。

处理方式：

1. 打开目标网页
2. 执行 `utils/grab.js`
3. 把输出内容写入对应站点的 `env.js`
4. 再次运行 `node start/my_site/run.js`

### `get_info` 接口无法启动

优先检查：

- `run.js` 是否导出了 `get_info`
- `require('../../src/server/1_index')` 是否放在最后
- `IS_OPEN_SERVER` 是否设置为 `true`
- 端口是否被占用

### 有参数时 GET 请求失败

如果 `get_info` 有参数，推荐使用 POST JSON。

例如：

```js
function get_info(page) {
  return window.youzi(page);
}
```

对应请求：

```python
requests.post('http://127.0.0.1:3000/get_info', json={'page': 1})
```

### 日志太多看不过来

调试初期建议：

```js
IS_ONLY_LOG_UNDEFINED = true;
MAX_LOG_LEN = 100;
LOG_FILTER = [];
```

先解决 `undefined`，再看完整访问轨迹。

### 多次调用结果不变或状态异常

可能是目标代码内部有缓存、时间戳、随机数、全局状态或运行时缓存。

建议检查：

- 是否需要清理模块缓存
- 是否需要重新加载目标代码
- 是否存在全局变量污染
- 是否需要每次调用前重置上下文

---

## 🗺️ Roadmap

- 🧬 持续补全浏览器环境对象
- 🪞 增强原型链与原生函数伪装
- 🧰 增加更多站点模板和测试样例
- 📡 优化本地服务的调用体验
- 🧪 增强自动化环境检测与缺失字段提示
- 📚 补充更多实战型文档

---

## 👤 Author

柚子spider

Youzi-Mask

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README