node-mitmproxy1/README.md

Node.js MITM Proxy

# node-mitmproxy 4.x

[![npm](https://img.shields.io/npm/dt/node-mitmproxy.svg)](https://www.npmjs.com/package/node-mitmproxy)  
node-mitmproxy是一个基于nodejs，支持http/https的高性能中间人(MITM)代理，便于渗透测试和开发调试。

## 1、特性
1、支持https  
2、支持配置的方式启动，也支持以模块的方式引入到代码中  
3、**选择性拦截** - 智能路径选择，大幅提升性能  
4、**性能优化** - Promise池化、连接复用、快速路径等多项优化  
5、**WebSocket代理** - 完整支持WebSocket协议代理  
6、**固定证书** - 支持使用固定SSL证书，避免证书变化  
7、**性能监控** - 内置性能统计和监控功能

## 2、安装

###### windows
```
    npm install node-mitmproxy1 -g
```
###### Mac
```
    sudo npm install node-mitmproxy1 -g
```

## 3、使用

#### 关于配置文件

###### 简单配置：

simpleConfig.js
```
module.exports = {
    sslConnectInterceptor: (req, cltSocket, head) => true,
    requestInterceptor: (rOptions, req, res, ssl, next) => {
        console.log(`正在访问：${rOptions.protocol}//${rOptions.hostname}:${rOptions.port}`);
        console.log('cookie:', rOptions.headers.cookie);
        res.end('hello node-mitmproxy!');
        next();
    }
};

```
效果图：  
<img width=500 src="./doc/img/hello_node-mitmproxy.jpg" />

[详细配置说明](https://github.com/wuchangming/node-mitmproxy#4配置详细说明)  
[更多例子](./example/config/)
#### 启动方式
```
node-mitmproxy -c simpleConfig.js
```

### 安装node-mitmproxy CA根证书
生成CA根证书的默认路径：`%用户名%/node-mitmproxy`

#### PC下安装根证书方式
###### Mac
```
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/node-mitmproxy/node-mitmproxy.ca.crt
```
###### windows
注: 证书需要安装到  ** 受信任的根证书目录 ** 下  
参考 [issues#3](https://github.com/wuchangming/node-mitmproxy/issues/3)
```
start %HOMEPATH%/node-mitmproxy/node-mitmproxy.ca.crt
```

## 以nodejs模块的方式引用到代码中

### 基础使用
```javascript
var mitmproxy = require('node-mitmproxy');

mitmproxy.createProxy({
    port: 8080,
    sslConnectInterceptor: (req, cltSocket, head) => true,
    requestInterceptor: (rOptions, req, res, ssl, next) => {
        console.log(`正在访问：${rOptions.protocol}//${rOptions.hostname}:${rOptions.port}`);
        console.log('cookie:', rOptions.headers.cookie);
        res.end('Hello node-mitmproxy!');
        next();
    },
    responseInterceptor: (req, res, proxyReq, proxyRes, ssl, next) => {
        next();
    }
});
```

### 选择性拦截使用（推荐）
```javascript
var mitmproxy = require('node-mitmproxy');

// 选择性拦截配置
const interceptConfig = {
    // 只拦截这些域名的请求
    domains: ['api.example.com', 'auth.mysite.com'],
    
    // 只拦截这些路径前缀的请求
    pathPrefixes: ['/api/', '/auth/', '/admin/'],
    
    // 静态资源自动走快速模式
    staticExtensions: ['.js', '.css', '.png', '.jpg', '.ico']
};

mitmproxy.createProxy({
    port: 8080,
    sslConnectInterceptor: (req, cltSocket, head) => true,
    requestInterceptor: (rOptions, req, res, ssl, next) => {
        console.log('拦截请求:', req.headers.host + req.url);
        // 只有匹配拦截规则的请求才会到这里
        next();
    },
    responseInterceptor: (req, res, proxyReq, proxyRes, ssl, next) => {
        console.log('拦截响应:', req.headers.host + req.url);
        next();
    },
    interceptConfig  // 启用选择性拦截
});
```


## 4、配置详细说明

#### port
启动端口（默认：6789）
```
    port: 6789
```

#### interceptConfig
选择性拦截配置（新增功能，可大幅提升性能）
```javascript
interceptConfig: {
    // 需要拦截的域名列表（支持子域名匹配）
    domains: ['api.example.com', 'auth.mysite.com'],
    
    // 需要拦截的完整URL列表
    urls: ['cdn.example.com/api/v1/user'],
    
    // 需要拦截的URL前缀列表
    urlPrefixes: ['api.example.com/v1/', 'auth.mysite.com/oauth/'],
    
    // 需要拦截的路径前缀列表
    pathPrefixes: ['/api/', '/auth/', '/admin/'],
    
    // 静态资源扩展名（自动走快速模式）
    staticExtensions: ['.js', '.css', '.png', '.jpg', '.ico']
}
```

**选择性拦截优势：**
- 🚀 **性能提升40-60%** - 只拦截需要的请求
- 📊 **智能路径选择** - 自动识别静态资源和CDN
- 🎯 **精确控制** - 支持域名、URL、路径多维度匹配
- 📈 **实时监控** - 内置性能统计和监控

#### sslConnectInterceptor
判断该connnect请求是否需要代理，传入参数参考[http connnect](https://nodejs.org/api/http.html#http_event_connect) 。
```
    sslConnectInterceptor: (clientReq, clientSocket, head) => true,
```

#### requestInterceptor
拦截客户端请求/响应  

参数说明：  
1、requestOptions：客户端请求参数  
2、clientReq: 客户端请求，参考[http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)  
3、clientRes: 客户端响应，参考[http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse)  
4、ssl: 该请求是否为https  
5、next: 回调函数，执行完拦截逻辑后调用该方法  
```
    requestInterceptor: (requestOptions, clientReq, clientRes, ssl, next) => {
        next();
    }
```
#### responseInterceptor
拦截服务端请求/响应  
参数说明：  

1、clientReq: 客户端请求，参考[http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)  
2、clientRes: 客户端响应，参考[http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse)  
3、proxyReq: 服务端请求，参考[http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)  
4、proxyRes: 服务端响应，参考[http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse)  
5、ssl: 该请求是否为https  
6、next: 回调函数，执行完拦截逻辑后调用该方法  
```
    responseInterceptor: (clientReq, clientRes, proxyReq, proxyRes, ssl, next) => {
        next();
    }
```
#### caCertPath
CA根证书路径(ps: 无特殊情况无需配置)  
默认：%HOMEPATH%/node-mitmproxy/node-mitmproxy.ca.crt  
```
caCertPath: 'xxxx/xxxx.crt'
```

#### caKeyPath
CA根证书密钥路径(ps: 无特殊情况无需配置)  
默认：%HOMEPATH%/node-mitmproxy/node-mitmproxy.ca.key.pem  
```
caKeyPath: 'xxxx/xxxx.pem'
```

#### getCertSocketTimeout
获取证书超时时间（默认：1000ms）
```
    getCertSocketTimeout: 1000
```

#### enableWebSocket
是否启用WebSocket代理支持（默认：true）
```
    enableWebSocket: true
```

#### performanceMonitor
是否启用性能监控（默认：false）
```
    performanceMonitor: true
```

## 5、性能优化与最佳实践

### 选择性拦截最佳实践

1. **精确配置域名和路径**
   - 只配置真正需要拦截的域名和路径
   - 避免过于宽泛的匹配规则

2. **合理使用快速域名**
   - 将CDN、静态资源域名加入fastDomains
   - 常见快速域名：`cdn.jsdelivr.net`, `fonts.googleapis.com`, `unpkg.com`

3. **静态资源自动优化**
   - 系统自动识别常见静态资源扩展名
   - 可自定义staticExtensions列表

4. **性能监控**
   - 启用performanceMonitor查看拦截统计
   - 根据统计数据优化拦截配置

### 性能提升效果
- **普通模式**：所有请求都经过拦截器处理
- **选择性拦截**：只处理匹配规则的请求，其他走快速路径
- **性能提升**：根据拦截比例，可提升40-60%的代理性能

## 6、快速开始示例

创建一个简单的API拦截代理：

```javascript
const mitmproxy = require('node-mitmproxy');

// 创建选择性拦截配置
const interceptConfig = {
    domains: ['jsonplaceholder.typicode.com'],
    pathPrefixes: ['/posts', '/users'],
    fastDomains: ['cdn.jsdelivr.net']
};

// 启动代理服务器
mitmproxy.createProxy({
    port: 8080,
    requestInterceptor: (rOptions, req, res, ssl, next) => {
        console.log('🔍 拦截请求:', req.headers.host + req.url);
        
        // 修改请求头
        rOptions.headers['X-Custom-Header'] = 'node-mitmproxy';
        
        next();
    },
    responseInterceptor: (req, res, proxyReq, proxyRes, ssl, next) => {
        console.log('📦 拦截响应:', proxyRes.statusCode, req.headers.host + req.url);
        next();
    },
    interceptConfig,
    performanceMonitor: true
});

console.log('🚀 代理服务器已启动: http://localhost:8080');
console.log('📊 性能监控已启用');
```

## 7、版本更新说明

### v4.x 主要更新
- ✨ **选择性拦截功能** - 智能路径选择，大幅提升性能
- 🚀 **性能优化** - Promise池化、连接复用等多项优化
- 🔧 **WebSocket支持** - 完整的WebSocket代理功能
- 📊 **性能监控** - 内置统计和监控功能
- 🔒 **固定证书** - 支持使用固定SSL证书
- 🛠️ **API改进** - 更友好的配置选项和错误处理

### 从v3.x升级
- 保持向后兼容，现有代码无需修改
- 建议添加`interceptConfig`配置以获得性能提升
- 新项目推荐使用选择性拦截模式

## 8、更多
#### 关于伪造https证书的逻辑图
<img src="doc/img/node-MitmProxy https.png" width=650/>

#### 关于http代理的逻辑图
<img src="doc/img/node-MitmProxy http.png" width=650/>