XiaoMo/anyproxy
1
0
Fork 0
mirror of https://github.com/alibaba/anyproxy.git synced 2025-04-23 16:01:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix the URL of AnyProxy project on github, and fix the way we define the favicon in docs

Browse Source
This commit is contained in:
砚然 2017-12-02 14:09:30 +08:00
parent f7521a8685
commit 4fd60da6fa
10 changed files with 4 additions and 4179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs-src/cn/_layouts/layout.html
View File

@ -18,7 +18,6 @@
{% endif %} {% endif %}
{% endfor %} {% endfor %}
{% endblock %} {% endblock %}
{% block head %}{% endblock %}
<link rel="shortcut icon" href="/assets/favicon.png" type="image/png"> <link rel="shortcut icon" href="/assets/favicon.png" type="image/png">
<link rel="stylesheet" href="/assets/website.css"> <link rel="stylesheet" href="/assets/website.css">
<script src="/assets/main.js" ></script> <script src="/assets/main.js" ></script>

848
docs-src/cn/doc.md
View File

@ -1,848 +0,0 @@
# 快速开始
## 作为全局模块
### 安装
对于Debian或者Ubuntu系统，在安装AnyProxy之前，可能还需要安装 `nodejs-legacy`
```bash
sudo apt-get install nodejs-legacy
```
然后，安装AnyProxy
```bash
npm install -g anyproxy@beta #本文档对应的AnyProxy为4.0Beta版
```
### 启动
* 命令行启动AnyProxy，默认端口号8001
```bash
anyproxy
```
* 启动后将终端http代理服务器配置为127.0.0.1:8001即可
* 访问http://127.0.0.1:8002 ，web界面上能看到所有的请求信息
### 其他命令
* 配置启动端口，如1080端口启动
```bash
anyproxy --port 1080
```
## 作为npm模块使用
AnyProxy可以作为一个npm模块使用，整合进其他工具。
> 如要启用https解析，请在代理服务器启动前自行调用`AnyProxy.utils.certMgr`相关方法生成证书，并引导用户信任安装。或引导用户使用`anyproxy-ca`方法。
* 引入
```bash
npm i anyproxy@beta --save # 4.0版正在beta中
```
* 使用举例
```js
const AnyProxy = require('anyproxy');
const options = {
port: 8001,
rule: require('myRuleModule'),
webInterface: {
enable: true,
webPort: 8002,
wsPort: 8003,
},
throttle: 10000,
forceProxyHttps: false,
silent: false
};
const proxyServer = new AnyProxy.ProxyServer(options);
proxyServer.on('ready', () => { /* */ });
proxyServer.on('error', (e) => { /* */ });
proxyServer.start();
//when finished
proxyServer.close();
```
* Class: AnyProxy.proxyServer
* 创建代理服务器
```js
const proxy = new AnyProxy.proxyServer(options)
```
* `options`
* `port` {number} 必选，代理服务器端口
* `rule` {object} 自定义规则模块
* `throttle` {number} 限速值，单位kb/s，默认不限速
* `forceProxyHttps` {boolean} 是否强制拦截所有的https，忽略规则模块的返回，默认`false`
* `silent` {boolean} 是否屏蔽所有console输出，默认`false`
* `dangerouslyIgnoreUnauthorized` {boolean} 是否忽略请求中的证书错误，默认`false`
* `webInterface` {object} web版界面配置
* `enable` {boolean} 是否启用web版界面，默认`false`
* `webPort` {number} web版界面端口号，默认`8002`
* Event: `ready`
* 代理服务器启动完成
* 示例
```js
proxy.on('ready', function() { })
```
* Event: `error`
* 代理服务器发生错误
* 示例
```js
proxy.on('error', function() { })
```
* Method: `start`
* 启动代理服务器
* 示例
```js
proxy.start();
```
* Method: `close`
* 关闭代理服务器
* 示例
```js
proxy.close();
```
* AnyProxy.utils.systemProxyMgr
* 管理系统的全局代理配置，方法调用时可能会弹出密码框
* 使用示例
```js
// 配置127.0.0.1:8001为全局http代理服务器
AnyProxy.utils.systemProxyMgr.enableGlobalProxy('127.0.0.1', '8001');
// 关闭全局代理服务器
AnyProxy.utils.systemProxyMgr.disableGlobalProxy();
```
* AnyProxy.utils.certMgr
* 管理AnyProxy的证书
* `AnyProxy.utils.certMgr.ifRootCAFileExists()`
* 校验系统内是否存在AnyProxy的根证书
* `AnyProxy.utils.certMgr.generateRootCA(callback)`
* 生成AnyProxy的rootCA，完成后请引导用户信任.crt文件
* 样例
```js
const AnyProxy = require('AnyProxy');
const exec = require('child_process').exec;
if (!AnyProxy.utils.certMgr.ifRootCAFileExists()) {
AnyProxy.utils.certMgr.generateRootCA((error, keyPath) => {
// let users to trust this CA before using proxy
if (!error) {
const certDir = require('path').dirname(keyPath);
console.log('The cert is generated at', certDir);
const isWin = /^win/.test(process.platform);
if (isWin) {
exec('start .', { cwd: certDir });
} else {
exec('open .', { cwd: certDir });
}
} else {
console.error('error when generating rootCA', error);
}
});
}
```
# 代理HTTPS
* AnyProxy默认不对https请求做处理，如需看到明文信息，需要配置CA证书
> 解析https请求的原理是中间人攻击（man-in-the-middle），用户必须信任AnyProxy生成的CA证书，才能进行后续流程
* 生成证书并解析所有https请求
```bash
anyproxy-ca #生成rootCA证书，生成后需要手动信任
anyproxy --intercept #启动AnyProxy，并解析所有https请求
```
* [附录：如何信任CA证书](#证书配置)
# rule模块
AnyProxy提供了二次开发的能力，你可以用js编写自己的规则模块（rule），来自定义网络请求的处理逻辑。
>注意：引用规则前，请务必确保文件来源可靠，以免发生安全问题
规则模块的能力范围包括：
* 拦截并修改正在发送的请求
* 可修改内容包括请求头（request header)，请求体（request body），甚至是请求的目标地址等
* 拦截并修改服务端响应
* 可修改的内容包括http状态码(status code)、响应头（response header）、响应内容等
* 拦截https请求，对内容做修改
* 本质是中间人攻击（man-in-the-middle attack），需要客户端提前信任AnyProxy生成的CA
### 开发示例
* 举例
* 需要编写一个规则模块，在 GET http://httpbin.org/user-agent 的返回值里加上测试信息，并延迟5秒返回
* Step 1，编写规则
```js
// file: sample.js
module.exports = {
summary: 'a rule to modify response',
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url === 'http://httpbin.org/user-agent') {
const newResponse = responseDetail.response;
newResponse.body += '-- AnyProxy Hacked! --';
return new Promise((resolve, reject) => {
setTimeout(() => { // delay
resolve({ response: newResponse });
}, 5000);
});
}
},
};
```
* Step 2, 启动AnyProxy，加载规则
* 运行 `anyproxy --rule sample.js`
* Step 3, 测试规则
* 用curl测试
```bash
curl http://httpbin.org/user-agent --proxy http://127.0.0.1:8001
```
* 用浏览器测试：配置浏览器http代理为 127.0.0.1:8001，访问 http://httpbin.org/user-agent
* 经过代理服务器后，期望的返回如下
```
{
"user-agent": "curl/7.43.0"
}
- AnyProxy Hacked!
```
* Step 4, 查看请求信息
* 浏览器访问http://127.0.0.1:8002 ，界面上能看到刚才的请求信息
### 处理流程
* 处理流程图如下
<img src="https://zos.alipayobjects.com/rmsportal/TWyNuSJtEZBdrdcOMRjE.png" width="550" />
* 当http请求经过代理服务器时，具体处理过程是：
* 收集请求所有请求参数，包括method, header, body等
* AnyProxy调用规则模块`beforeSendRequest`方法，由模块做处理，返回新的请求参数，或返回响应内容
* 如果`beforeSendRequest`返回了响应内容，则立即把此响应返回到客户端（而不再发送到真正的服务端），流程结束。
* 根据请求参数，向服务端发出请求，接收服务端响应。
* 调用规则模块`beforeSendResponse`方法，由模块对响应内容进行处理
* 把响应信息返回给客户端
* 当代理服务器收到https请求时，AnyProxy可以替换证书，对请求做明文解析。
* 调用规则模块`beforeDealHttpsRequest`方法，如果返回`true`，会明文解析这个请求，其他请求不处理
* 被明文解析后的https请求，处理流程同http一致。未明文解析请求不会再进入规则模块做处理。
### 如何引用
如下几种方案都可以用来引用规则模块：
* 使用本地路径
```bash
anyproxy --rule ./rule.js
```
* 使用在线地址
```bash
anyproxy --rule https://sample.com/rule.js
```
* 使用npm包
* AnyProxy使用`require()`加载本地规则，你可以在参数里传入一个本地的npm包路径，或是某个全局安装的npm包
```bash
anyproxy --rule ./myRulePkg/ #本地包
npm i -g myRulePkg && anyproxy --rule myRulePkg #全局包
```
# rule接口文档
规则模块应该符合cmd规范，一个典型的规则模块代码结构如下。模块中所有方法都是可选的，只需实现业务感兴趣的部分即可。
```js
module.exports = {
// 模块介绍
summary: 'my customized rule for AnyProxy',
// 发送请求前拦截处理
*beforeSendRequest(requestDetail) { /* ... */ },
// 发送响应前处理
*beforeSendResponse(requestDetail, responseDetail) { /* ... */ },
// 是否处理https请求
*beforeDealHttpsRequest(requestDetail) { /* ... */ },
// 请求出错的事件
*onError(requestDetail, error) { /* ... */ },
// https连接服务器出错
*onConnectError(requestDetail, error) { /* ... */ }
};
```
> 规则文件中，除了summary，都是由 [co](https://www.npmjs.com/package/co) 驱动的，函数需要满足yieldable。可以返回promise或使用generator函数。
### summary
#### summary(): string | summary:string
* 规则模块的介绍文案，用于AnyProxy提示用户, 可以是一个函数，也可以是一个普通的字符串
### beforeSendRequest
#### beforeSendRequest(requestDetail)
* AnyProxy向服务端发送请求前，会调用`beforeSendRequest`，并带上参数`requestDetail`
* `requestDetail`
* `protocol` {string} 请求使用的协议，http或者https
* `requestOptions` {object} 即将发送的请求配置，供require('http').request作为使用。详见：https://nodejs.org/api/http.html#http_http_request_options_callback
* `requestData` {object} 请求Body
* `url` {string} 请求url
* `_req` {object} 请求的原始request
* 举例：请求 *anyproxy.io* 时，`requestDetail`参数内容大致如下
```js
{
protocol: 'http',
url: 'http://anyproxy.io/',
requestOptions: {
hostname: 'anyproxy.io',
port: 80,
path: '/',
method: 'GET',
headers: {
Host: 'anyproxy.io',
'Proxy-Connection': 'keep-alive',
'User-Agent': '...'
}
},
requestData: '...',
_req: { /* ... */}
}
```
* 以下几种返回都是合法的
* 不做任何处理，返回null
```js
return null;
```
* 修改请求协议，如强制改用https发起请求
```js
return {
protocol: 'https'
};
```
* 修改请求参数
```js
var newOption = Object.assign({}, requestDetail.requestOptions);
newOption.path = '/redirect/to/another/path';
return {
requestOptions: newOption
};
```
* 修改请求body
```js
return {
requestData: 'my new request data'
//这里也可以同时加上requestOptions
};
```
* 直接返回客户端，不再发起请求，其中`statusCode` `header` 是必选字段
```js
return {
response: {
statusCode: 200,
header: { 'content-type': 'text/html' },
body: 'this could be a <string> or <buffer>'
}
};
```
### beforeSendResponse
#### beforeSendResponse(requestDetail, responseDetail)
* AnyProxy向客户端发送请求前，会调用`beforeSendResponse`，并带上参数`requestDetail` `responseDetail`
* `requestDetail` 同`beforeSendRequest`中的参数
* `responseDetail`
* `response` {object} 服务端的返回信息，包括`statusCode` `header` `body`三个字段
* `_res` {object} 原始的服务端返回对象
* 举例，请求 *anyproxy.io* 时，`responseDetail`参数内容大致如下
```js
{
response: {
statusCode: 200,
header: {
'Content-Type': 'image/gif',
Connection: 'close',
'Cache-Control': '...'
},
body: '...'
},
_res: { /* ... */ }
}
```
* 以下几种返回都是合法的
* 不做任何处理，返回null
```js
return null;
```
* 修改返回的状态码
```js
var newResponse = Object.assign({}, responseDetail.response);
newResponse.statusCode = 404;
return {
response: newResponse
};
```
* 修改返回的内容
```js
var newResponse = Object.assign({}, responseDetail.response);
newResponse.body += '--from anyproxy--';
return {
response: newResponse
};
```
### beforeDealHttpsRequest
#### beforeDealHttpsRequest(requestDetail)
* AnyProxy收到https请求时，会调用`beforeDealHttpsRequest`，并带上参数`requestDetail`
* 如果配置了全局解析https的参数，则AnyProxy会略过这个调用
* 只有返回`true`时，AnyProxy才会尝试替换证书、解析https。否则只做数据流转发，无法看到明文数据。
* 注意：https over http的代理模式中，这里的request是CONNECT请求
* `requestDetail`
* `host` {string} 请求目标的Host，受制于协议，这里无法获取完整url
* `_req` {object} 请求的原始request
* 返回值
* `true`或者`false`，表示是否需要AnyProxy替换证书并解析https
### onError
#### onError(requestDetail, error)
* 在请求处理过程中发生错误时，AnyProxy会调用`onError`方法，并提供对应的错误信息
* 多数场景下，错误会在请求目标服务器的时候发生，比如DNS解析失败、请求超时等
* `requestDetail` 同`beforeSendRequest`中的参数
* 以下几种返回都是合法的
* 不做任何处理。此时AnyProxy会返回一个默认的错误页。
```js
return null;
```
* 返回自定义错误页
```js
return {
response: {
statusCode: 200,
header: { 'content-type': 'text/html' },
body: 'this could be a <string> or <buffer>'
}
};
```
### onConnectError
#### onConnectError(requestDetail, error)
* AnyProxy在与目标HTTPS服务器建立连接的过程中，如果发生错误，AnyProxy会调用这个方法
* `requestDetail` 同`beforeDealHttpsRequest`中的参数
* 此处无法控制向客户端的返回信息，无需返回值。
# rule样例
* 这里提供一些样例，来讲解规则模块的常见用法
* 你可以通过 `anyproxy --rule http://....js` 来加载模块并体验
* 用curl发请求测试的方法如下
* 直接请求服务器：`curl http://httpbin.org/`
* 通过代理服务器请求：`curl http://httpbin.org/ --proxy http://127.0.0.1:8001`
### 使用本地数据
* 拦截发送到 http://httpbin.org 的请求，使用本地数据代替服务端返回
```bash
anyproxy --rule rule_sample/sample_use_local_response.js
```
```js
/*
sample:
intercept all requests toward httpbin.org, use a local response
test:
curl http://httpbin.org/user-agent --proxy http://127.0.0.1:8001
*/
module.exports = {
*beforeSendRequest(requestDetail) {
const localResponse = {
statusCode: 200,
header: { 'Content-Type': 'application/json' },
body: '{"hello": "this is local response"}'
};
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
return {
response: localResponse
};
}
},
};
```
### 修改请求头
* 修改发送到 httpbin.org 的user-agent
```bash
anyproxy --rule rule_sample/sample_modify_request_header.js
```
```js
/*
sample:
modify the user-agent in requests toward httpbin.org
test:
curl http://httpbin.org/user-agent --proxy http://127.0.0.1:8001
*/
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newRequestOptions = requestDetail.requestOptions;
newRequestOptions.headers['User-Agent'] = 'AnyProxy/0.0.0';
return {
requestOptions: newRequestOptions
};
}
},
};
```
### 修改请求数据
* 修改发送到 http://httpbin.org/post 的post数据
```bash
anyproxy --rule rule_sample/sample_modify_request_data.js
```
```js
/*
sample:
modify the post data towards http://httpbin.org/post
test:
curl -H "Content-Type: text/plain" -X POST -d 'original post data' http://httpbin.org/post --proxy http://127.0.0.1:8001
expected response:
{ "data": "i-am-anyproxy-modified-post-data" }
*/
module.exports = {
summary: 'Rule to modify request data',
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org/post') === 0) {
return {
requestData: 'i-am-anyproxy-modified-post-data'
};
}
},
};
```
### 修改请求的目标地址
* 把所有发送到 http://httpbin.org/ 的请求全部改到 http://httpbin.org/user-agent
```bash
anyproxy --rule rule_sample/sample_modify_request_path.js
```
```js
/*
sample:
redirect all httpbin.org requests to http://httpbin.org/user-agent
test:
curl http://httpbin.org/any-path --proxy http://127.0.0.1:8001
expected response:
{ "user-agent": "curl/7.43.0" }
*/
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newRequestOptions = requestDetail.requestOptions;
newRequestOptions.path = '/user-agent';
newRequestOptions.method = 'GET';
return {
requestOptions: newRequestOptions
};
}
},
};
```
### 修改请求协议
* 把用http协议请求的 http://httpbin.org 改成https并发送
```bash
anyproxy --rule rule_sample/sample_modify_request_protocol.js
```
```js
/*
sample:
redirect all http requests of httpbin.org to https
test:
curl 'http://httpbin.org/get?show_env=1' --proxy http://127.0.0.1:8001
expected response:
{ "X-Forwarded-Protocol": "https" }
*/
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newOption = requestDetail.requestOptions;
newOption.port = 443;
return {
protocol: 'https',
requestOptions: newOption
};
}
}
};
```
### 修改返回状态码
* 把 所有http://httpbin.org 的返回状态码都改成404
```bash
anyproxy --rule rule_sample/sample_modify_response_statuscode.js
```
```js
/*
sample:
modify all status code of http://httpbin.org/ to 404
test:
curl -I 'http://httpbin.org/user-agent' --proxy http://127.0.0.1:8001
expected response:
HTTP/1.1 404 Not Found
*/
module.exports = {
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newResponse = responseDetail.response;
newResponse.statusCode = 404;
return {
response: newResponse
};
}
}
};
```
### 修改返回头
* 在 http://httpbin.org/user-agent 的返回头里加上 X-Proxy-By:AnyProxy
```bash
anyproxy --rule rule_sample/sample_modify_response_header.js
```
```js
/*
sample:
modify response header of http://httpbin.org/user-agent
test:
curl -I 'http://httpbin.org/user-agent' --proxy http://127.0.0.1:8001
expected response:
X-Proxy-By: AnyProxy
*/
module.exports = {
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url.indexOf('http://httpbin.org/user-agent') === 0) {
const newResponse = responseDetail.response;
newResponse.header['X-Proxy-By'] = 'AnyProxy';
return {
response: newResponse
};
}
}
};
```
### 修改返回内容并延迟
* 在 http://httpbin.org/user-agent 的返回最后追加AnyProxy的签名，并延迟5秒
```bash
anyproxy --rule rule_sample/sample_modify_response_data.js
```
```js
/*
sample:
modify response data of http://httpbin.org/user-agent
test:
curl 'http://httpbin.org/user-agent' --proxy http://127.0.0.1:8001
expected response:
{ "user-agent": "curl/7.43.0" } -- AnyProxy Hacked! --
*/
module.exports = {
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url === 'http://httpbin.org/user-agent') {
const newResponse = responseDetail.response;
newResponse.body += '-- AnyProxy Hacked! --';
return new Promise((resolve, reject) => {
setTimeout(() => { // delay the response for 5s
resolve({ response: newResponse });
}, 5000);
});
}
},
};
```
# 证书配置
### OSX系统信任CA证书
* 类似这种报错都是因为系统没有信任AnyProxy生成的CA所造成的
<img src="https://zos.alipayobjects.com/rmsportal/CBkLGYgvoHAYwNVAYkpk.png" width="450" />
> 警告：CA证书和系统安全息息相关，建议亲自生成，并妥善保管
安装CA：
* 双击打开*rootCA.crt*
* 确认将证书添加到login或system
<img src="https://zos.alipayobjects.com/rmsportal/bCwNUFFpvsmVuljQKrIk.png" width="350" />
* 找到刚刚导入的AnyProxy证书，配置为信任（Always Trust）
<img src="https://zos.alipayobjects.com/rmsportal/HOmEElNGdoZEWFMLsTNT.png" width="700" />
### Windows系统信任CA证书
<img src="https://t.alipayobjects.com/tfscom/T1D3hfXeFtXXXXXXXX.jpg" width="700" />
### 配置OSX系统代理
* 在wifi高级设置中，配置http代理即可
<img src="https://zos.alipayobjects.com/rmsportal/vduwhobSTypTfgniBvoa.png" width="500" />
### 配置浏览器HTTP代理
* 以Chrome的[SwitchyOmega插件](https://chrome.google.com/webstore/detail/padekgcemlokbadohgkifijomclgjgif)为例
<img src="https://zos.alipayobjects.com/rmsportal/jIPZrKmqXRaSledQeJUJ.png" width="500" />
### iOS系统信任CA证书
* 点击web ui中的 *Root CA*，按提示扫描二维码即可安装
<img src="https://zos.alipayobjects.com/rmsportal/BrugmMelGVysLDOIBblj.png" width="260" />
### iOS >= 10.3信任CA证书
* 除了上述证书安装过程，还需要在 *设置->通用->关于本机->证书信任设置* 中把AnyProxy证书的开关打开，否则safari将报错。
<img src="https://zos.alipayobjects.com/rmsportal/hVWkXHrzHmOKOtCKGUWx.png" width="500" />
### 配置iOS/Android系统代理
* 代理服务器都在wifi设置中配置
* iOS HTTP代理配置
<img src="https://zos.alipayobjects.com/rmsportal/tLGqIozhffTccUgPakuw.png" width="260" />
* Android HTTP代理配置
<img src="https://zos.alipayobjects.com/rmsportal/YQtbQYVNuOszZGdAOauU.png" width="260" />
# FAQ
#### Q: 为什么https请求不能进入处理函数？
A: 以下任意一项都能用来改变https的处理特性：
1. 命令行启动AnyProxy时配置`--intercept`参数，按npm模块启动时配置`forceProxyHttps`参数，所有Https请求都会被替换证书并解析
2. 规则文件内提供`beforeDealHttpsRequest`方法，返回 *true* 的https请求会被解析
#### Q: 提示 *function is not yieldable*
* A: 规则模块是用 [co](https://www.npmjs.com/package/co) 驱动的，函数需要满足yieldable。可以使用generator方法或是返回Promise。
#### Q: The connection is not private
当访问特定的HTTPS站点，AnyProxy会提示该站点不是一个安全的网站，这通常是因为站点的证书设置不能被正确识别导致的（比如，站点的证书是自签发的）。如果您信任该网站，可以用以下方式来继续访问：
- 命令行直接启动
通过启动参数 `--ignore-unauthorized-ssl` 来忽略证书认证的错误。需要注意的是，该参数是全局生效的，如果你在此期间访问了其他未知的网站，他们的证书问题也会被忽略，这可能会带来安全隐患。
```bash
anyproxy -i --ignore-unauthorized-ssl
```
- 在Nodejs代码中启动
在构造AnyProxy实例的时候，传入参数`dangerouslyIgnoreUnauthorized:true`, 如下：
```js
const options = {
...,
dangerouslyIgnoreUnauthorized: true
};
const anyproxyIns = new AnyProxy.ProxyCore(options);
anyproxyIns.start();
```
*通过这种方式初始化的AnyProxy，其配置也是全局性的，所有网站的证书问题都会被忽略*
- 通过自定义的Rule来修改
我们自然也可以借助自定义的Rule来实现这个效果，而且我们还可以控制到只允许指定网址的证书错误，对不在列表的网址，进行证书的强验证。
```js
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('https://the-site-you-know.com') === 0) {
const newRequestOptions = requestDetail.requestOptions;
// 设置属性 rejectUnauthorized 为 false
newRequestOptions.rejectUnauthorized = false;
return {
requestOptions: newRequestOptions
};
}
},
};
```

2
docs-src/cn/src_doc.md
View File

@ -7,7 +7,7 @@ Ref: [English Doc](../en)
AnyProxy是一个开放式的HTTP代理服务器。 AnyProxy是一个开放式的HTTP代理服务器。
Github主页：https://github.com/alibaba/anyproxy/tree/4.x Github主页：https://github.com/alibaba/anyproxy
主要特性包括： 主要特性包括：

1
docs-src/en/_layouts/layout.html
View File

@ -18,7 +18,6 @@
{% endif %} {% endif %}
{% endfor %} {% endfor %}
{% endblock %} {% endblock %}
{% block head %}{% endblock %}
<link rel="shortcut icon" href="/assets/favicon.png" type="image/png"> <link rel="shortcut icon" href="/assets/favicon.png" type="image/png">
<link rel="stylesheet" href="/assets/styles/website.css"> <link rel="stylesheet" href="/assets/styles/website.css">
<script src="/assets/main.js" ></script> <script src="/assets/main.js" ></script>

842
docs-src/en/doc.md
View File

@ -1,842 +0,0 @@
# Getting Start
### install
To Debian and Ubuntu users, you may need to install `nodejs-legacy` at the same time
```bash
sudo apt-get install nodejs-legacy
```
Then install the AnyProxy
```bash
npm install -g anyproxy@beta # 4.x is in beta now
```
### launch
* start AnyProxy in command line, with default port 8001
```bash
anyproxy
```
* now you can use http proxy server by 127.0.0.1:8001
* visit http://127.0.0.1:8002 to see the http requests
### options
* specify the port of http proxy
```bash
anyproxy --port 1080
```
### Use AnyProxy as an npm module
AnyProxy can be used as an npm module
> To enable https feature, please guide users to use `anyproxy-ca` in cli. Or use methods under `AnyProxy.utils.certMgr` to generate certificates.
* install
```bash
npm i anyproxy@beta --save # 4.0 is in beta now
```
* sample
```js
const AnyProxy = require('anyproxy');
const options = {
port: 8001,
rule: require('myRuleModule'),
webInterface: {
enable: true,
webPort: 8002,
wsPort: 8003,
},
throttle: 10000,
forceProxyHttps: false,
silent: false
};
const proxyServer = new AnyProxy.ProxyServer(options);
proxyServer.on('ready', () => { /* */ });
proxyServer.on('error', (e) => { /* */ });
proxyServer.start();
//when finished
proxyServer.close();
```
* Class: AnyProxy.proxyServer
* create a proxy server
```js
const proxy = new AnyProxy.proxyServer(options)
```
* `options`
* `port` {number} required, port number of proxy server
* `rule` {object} your rule module
* `throttle` {number} throttle in kb/s, unlimited for default
* `forceProxyHttps` {boolean} in force intercept all https request, false for default
* `silent` {boolean} if keep silent in console, false for default`false`
* `dangerouslyIgnoreUnauthorized` {boolean} if ignore certificate error in request, false for default
* `webInterface` {object} config for web interface
* `enable` {boolean} if enable web interface, false for default
* `webPort` {number} port number for web interface
* Event: `ready`
* emit when proxy server is ready
* sample
```js
proxy.on('ready', function() { })
```
* Event: `error`
* emit when error happened inside proxy server
* sample
```js
proxy.on('error', function() { })
```
* Method: `start`
* start proxy server
* sample
```js
proxy.start();
```
* Method: `close`
* close proxy server
* sample
```js
proxy.close();
```
* AnyProxy.utils.systemProxyMgr
* manage the system proxy config. sudo password may be required
* sample
```js
// set 127.0.0.1:8001 as system http server
AnyProxy.utils.systemProxyMgr.enableGlobalProxy('127.0.0.1', '8001');
// disable global proxy server
AnyProxy.utils.systemProxyMgr.disableGlobalProxy();
```
* AnyProxy.utils.certMgr
* Manage certificates of AnyProxy
* `AnyProxy.utils.certMgr.ifRootCAFileExists()`
* detect if AnyProx rootCA exists
* `AnyProxy.utils.certMgr.generateRootCA(callback)`
* generate a rootCA
* Sample
```js
const AnyProxy = require('AnyProxy');
const exec = require('child_process').exec;
if (!AnyProxy.utils.certMgr.ifRootCAFileExists()) {
AnyProxy.utils.certMgr.generateRootCA((error, keyPath) => {
// let users to trust this CA before using proxy
if (!error) {
const certDir = require('path').dirname(keyPath);
console.log('The cert is generated at', certDir);
const isWin = /^win/.test(process.platform);
if (isWin) {
exec('start .', { cwd: certDir });
} else {
exec('open .', { cwd: certDir });
}
} else {
console.error('error when generating rootCA', error);
}
});
}
```
# Proxy Https
* AnyProxy does NOT intercept https requests by default. To view decrypted info, you have to config the CA certificate.
> Under the hood, AnyProxy decryptes https requests by man-in-the-middle attack. Users have to trust the CA cert in advance. Otherwise, client side will issue errors about unsecure network.
* generate certifycates and intercept
```bash
anyproxy-ca #generate root CA. manually trust it after that.
anyproxy --intercept #launch anyproxy and intercept all https traffic
```
* [Appendix：how to trust CA](#config-certification)
# Rule Introduction
AnyProxy provides the ability to load your own rules written in javascript. With rule module, you could customize the logic to handle requests.
> Make sure your rule file is got from a trusted source. Otherwise, you may face some unknown security risk.
Rule module could do the following stuff:
* intercept and modify the request which is being sent
* editable fields include request header, body, target address
* intercept and modify the response from server
* editable fields include response status code, header, body
* intercept https requests, modify request and response
### sample
* Target
* write a rule module to append some text to the response of GET http://httpbin.org/user-agent, and delay the response for 5 seconds
* Step 1，Write the rule file, save as sample.js
```js
// file: sample.js
module.exports = {
summary: 'a rule to modify response',
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url === 'http://httpbin.org/user-agent') {
const newResponse = responseDetail.response;
newResponse.body += '-- AnyProxy Hacked! --';
return new Promise((resolve, reject) => {
setTimeout(() => { // delay
resolve({ response: newResponse });
}, 5000);
});
}
},
};
```
* Step 2, start AnyProxy and load the rule file
* run `anyproxy --rule sample.js`
* Step 3, test
* use curl
```bash
curl http://httpbin.org/user-agent --proxy http://127.0.0.1:8001
```
* use browser. Point the http proxy of browser to 127.0.0.1:8001, then visit http://httpbin.org/user-agent
* the expected response from proxy is
```
{
"user-agent": "curl/7.43.0"
}
- AnyProxy Hacked!
```
* Step 4, view the request log
* visit http://127.0.0.1:8002, the request just sent should be listed here
### how does it work
* The flow chart is as follows
<img src="https://zos.alipayobjects.com/rmsportal/TWyNuSJtEZBdrdcOMRjE.png" width="550" />
* When got an http request, the entire process of proxy server is
* AnyProxy collects all the quest info, include method, header, body
* AnyProxy calls `beforeSendRequest` of the rule module. Rule module deal the request, return new request param or response content
* If `beforeSendRequest` returns the response content, AnyProxy will send the response to client without sending to target server. The process ends here.
* Send request to target server, collect response
* Call `beforeSendResponse` of the rule module. Rule module deal the response data
* Send response to client
* When AnyProxy get https request, it could replace the certificate and decrypt the request data
* AnyProxy calls `beforeDealHttpsRequest` of the rule module
* If the function returns `true`, AnyProxy will do the man-in-the-middle attack to it. Otherwise, the request will not be dealed.
### how to load rule module
* use local file
```bash
anyproxy --rule ./rule.js
```
* use an online rule file
```bash
anyproxy --rule https://sample.com/rule.js
```
* use an npm module
* AnyProxy uses `require()` to load rule module. You could either load a local npm module or a global-installed one.
```bash
anyproxy --rule ./myRulePkg/ #local module
npm i -g myRulePkg && anyproxy --rule myRulePkg #global-installed module
```
# Rule module interface
A typical rule module is as follows. All the functions are optional, just write the part you are interested in.
```js
module.exports = {
// introduction
summary: 'my customized rule for AnyProxy',
// intercept before send request to server
*beforeSendRequest(requestDetail) { /* ... */ },
// deal response before send to client
*beforeSendResponse(requestDetail, responseDetail) { /* ... */ },
// if deal https request
*beforeDealHttpsRequest(requestDetail) { /* ... */ },
// error happened when dealing requests
*onError(requestDetail, error) { /* ... */ },
// error happened when connect to https server
*onConnectError(requestDetail, error) { /* ... */ }
};
```
> All functions in your rule file, except summary, are all driven by [co](https://www.npmjs.com/package/co) . They should be yieldable, i.e. return a promise or be a generator function.
### summary
#### summary
* Introduction of this rule file. AnyProxy will read this field and give some tip to user.
### beforeSendRequest
#### beforeSendRequest(requestDetail)
* Before sending request to server, AnyProxy will call `beforeSendRequest` with param `requestDetail`
* `requestDetail`
* `protocol` {string} the protocol to use, http or https
* `requestOptions` {object} the options of the request-to-go, a param of require('http').request . ref: https://nodejs.org/api/http.html#http_http_request_options_callback
* `requestData` {object} request body
* `url` {string} request url
* `_req` {object} the native node.js request object
* e.g. When requesting *anyproxy.io*, `requestDetail` is something like the following
```js
{
protocol: 'http',
url: 'http://anyproxy.io/',
requestOptions: {
hostname: 'anyproxy.io',
port: 80,
path: '/',
method: 'GET',
headers: {
Host: 'anyproxy.io',
'Proxy-Connection': 'keep-alive',
'User-Agent': '...'
}
},
requestData: '...',
_req: { /* ... */}
}
```
* Any of these return values are valid
* do nothing, and return null
```js
return null;
```
* modify the request protocol，i.e. force use https
```js
return {
protocol: 'https'
};
```
* modify request param
```js
var newOption = Object.assign({}, requestDetail.requestOptions);
newOption.path = '/redirect/to/another/path';
return {
requestOptions: newOption
};
```
* modify request body
```js
return {
requestData: 'my new request data'
// requestOptions can also be used here
};
```
* give response to the client, not sending request any longer. `statusCode` `headers`are required is this situation.
```js
return {
response: {
statusCode: 200,
header: { 'content-type': 'text/html' },
body: 'this could be a <string> or <buffer>'
}
};
```
### beforeSendResponse
#### beforeSendResponse(requestDetail, responseDetail)
* Before sending response to client, AnyProxy will call `beforeSendResponse` with param `requestDetail` `responseDetail`
* `requestDetail` is the same param as in `beforeSendRequest`
* `responseDetail`
* `response` {object} the response from server, includes `statusCode` `header` `body`
* `_res` {object} the native node.js response object
* e.g. When requesting *anyproxy.io*, `responseDetail` is something like the following
```js
{
response: {
statusCode: 200,
header: {
'Content-Type': 'image/gif',
Connection: 'close',
'Cache-Control': '...'
},
body: '...'
},
_res: { /* ... */ }
}
```
* Any of these return values are valid
* do nothing, and return null
```js
return null;
```
* modify the response status code
```js
var newResponse = Object.assign({}, responseDetail.response);
newResponse.statusCode = 404;
return {
response: newResponse
};
```
* modify the response content
```js
var newResponse = Object.assign({}, responseDetail.response);
newResponse.body += '--from anyproxy--';
return {
response: newResponse
};
```
### beforeDealHttpsRequest
#### beforeDealHttpsRequest(requestDetail)
* When receiving https request, AnyProxy will call `beforeDealHttpsRequest` with param `requestDetail`
* If configed with `forceProxyHttps` in launching, AnyProxy will skip calling this method
* Only by returning true, AnyProxy will try to replace the certificate and intercept the https request.
* `requestDetail`
* `host` {string} the target host to request. Due to the request protocol, full url couldn't be got here
* `_req` {object} the native node.js request object. The `_req` here refers to the CONNECT request.
* return value
* `true` or `false`, whether AnyProxy should intercept the https request
### onError
#### onError(requestDetail, error)
* AnyProxy will call this method when an error happened in request handling.
* Errors usually are issued during requesting, e.g. DNS failure, request timeout
* `requestDetail` is the same one as in `beforeSendRequest`
* Any of these return values are valid
* do nothing, and AnyProxy will response a default error page
```js
return null;
```
* return a customized error page
```js
return {
response: {
statusCode: 200,
header: { 'content-type': 'text/html' },
body: 'this could be a <string> or <buffer>'
}
};
```
### onConnectError
#### onConnectError(requestDetail, error)
* AnyProxy will call this method when failed to connect target server in https request
* `requestDetail` is the same one as in `beforeDealHttpsRequest`
* no return value is required
# Rule Samples
* here are some samples about frequently used rule file
* try these samples by `anyproxy --rule http://....js`
* how to test with curl:
* request the server directly `curl http://httpbin.org/`
* request the server via proxy `curl http://httpbin.org/ --proxy http://127.0.0.1:8001`
### use local response
* intercept the request towards http://httpbin.org , return the local-defined response
```bash
anyproxy --rule rule_sample/sample_use_local_response.js
```
```js
/*
sample:
intercept all requests toward httpbin.org, use a local response
test:
curl http://httpbin.org/user-agent --proxy http://127.0.0.1:8001
*/
module.exports = {
*beforeSendRequest(requestDetail) {
const localResponse = {
statusCode: 200,
header: { 'Content-Type': 'application/json' },
body: '{"hello": "this is local response"}'
};
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
return {
response: localResponse
};
}
},
};
```
### modify request header
* modify the user-agent sent to httpbin.org
```bash
anyproxy --rule rule_sample/sample_modify_request_header.js
```
```js
/*
sample:
modify the user-agent in requests toward httpbin.org
test:
curl http://httpbin.org/user-agent --proxy http://127.0.0.1:8001
*/
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newRequestOptions = requestDetail.requestOptions;
newRequestOptions.headers['User-Agent'] = 'AnyProxy/0.0.0';
return {
requestOptions: newRequestOptions
};
}
},
};
```
### modify request body
* modify the post body of http://httpbin.org/post
```bash
anyproxy --rule rule_sample/sample_modify_request_data.js
```
```js
/*
sample:
modify the post data towards http://httpbin.org/post
test:
curl -H "Content-Type: text/plain" -X POST -d 'original post data' http://httpbin.org/post --proxy http://127.0.0.1:8001
expected response:
{ "data": "i-am-anyproxy-modified-post-data" }
*/
module.exports = {
summary: 'Rule to modify request data',
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org/post') === 0) {
return {
requestData: 'i-am-anyproxy-modified-post-data'
};
}
},
};
```
### modify the request target
* send all the request towards http://httpbin.org/ to http://httpbin.org/user-agent
```bash
anyproxy --rule rule_sample/sample_modify_request_path.js
```
```js
/*
sample:
redirect all httpbin.org requests to http://httpbin.org/user-agent
test:
curl http://httpbin.org/any-path --proxy http://127.0.0.1:8001
expected response:
{ "user-agent": "curl/7.43.0" }
*/
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newRequestOptions = requestDetail.requestOptions;
newRequestOptions.path = '/user-agent';
newRequestOptions.method = 'GET';
return {
requestOptions: newRequestOptions
};
}
},
};
```
### modify request protocol
* modify the http request towards http://httpbin.org to https
```bash
anyproxy --rule rule_sample/sample_modify_request_protocol.js
```
```js
/*
sample:
redirect all http requests of httpbin.org to https
test:
curl 'http://httpbin.org/get?show_env=1' --proxy http://127.0.0.1:8001
expected response:
{ "X-Forwarded-Protocol": "https" }
*/
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newOption = requestDetail.requestOptions;
newOption.port = 443;
return {
protocol: 'https',
requestOptions: newOption
};
}
}
};
```
### modify response status code
* modify all status code from http://httpbin.org to 404
```bash
anyproxy --rule rule_sample/sample_modify_response_statuscode.js
```
```js
/*
sample:
modify all status code of http://httpbin.org/ to 404
test:
curl -I 'http://httpbin.org/user-agent' --proxy http://127.0.0.1:8001
expected response:
HTTP/1.1 404 Not Found
*/
module.exports = {
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newResponse = responseDetail.response;
newResponse.statusCode = 404;
return {
response: newResponse
};
}
}
};
```
### modify the response header
* add X-Proxy-By:AnyProxy to the response header from http://httpbin.org/user-agent
```bash
anyproxy --rule rule_sample/sample_modify_response_header.js
```
```js
/*
sample:
modify response header of http://httpbin.org/user-agent
test:
curl -I 'http://httpbin.org/user-agent' --proxy http://127.0.0.1:8001
expected response:
X-Proxy-By: AnyProxy
*/
module.exports = {
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url.indexOf('http://httpbin.org/user-agent') === 0) {
const newResponse = responseDetail.response;
newResponse.header['X-Proxy-By'] = 'AnyProxy';
return {
response: newResponse
};
}
}
};
```
### modify response data and delay
* append some info to the response of http://httpbin.org/user-agent, then delay the response for 5 seconds.
```bash
anyproxy --rule rule_sample/sample_modify_response_data.js
```
```js
/*
sample:
modify response data of http://httpbin.org/user-agent
test:
curl 'http://httpbin.org/user-agent' --proxy http://127.0.0.1:8001
expected response:
{ "user-agent": "curl/7.43.0" } -- AnyProxy Hacked! --
*/
module.exports = {
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url === 'http://httpbin.org/user-agent') {
const newResponse = responseDetail.response;
newResponse.body += '-- AnyProxy Hacked! --';
return new Promise((resolve, reject) => {
setTimeout(() => { // delay the response for 5s
resolve({ response: newResponse });
}, 5000);
});
}
},
};
```
# Config Certification
### Config root CA in OSX
* this kind of errors is usually caused by untrusted root CA
<img src="https://zos.alipayobjects.com/rmsportal/CBkLGYgvoHAYwNVAYkpk.png" width="450" />
> Warning: please keep your root CA safe since it may influence your system security.
install ：
* double click *rootCA.crt*
* add cert into login or system
<img src="https://zos.alipayobjects.com/rmsportal/bCwNUFFpvsmVuljQKrIk.png" width="350" />
* find the newly imported AnyProxy certificates, configured as **Always Trust**
<img src="https://zos.alipayobjects.com/rmsportal/HOmEElNGdoZEWFMLsTNT.png" width="700" />
### Config root CA in windows
<img src="https://t.alipayobjects.com/tfscom/T1D3hfXeFtXXXXXXXX.jpg" width="700" />
### Config OSX system proxy
* the config is in wifi - advanced
<img src="https://zos.alipayobjects.com/rmsportal/vduwhobSTypTfgniBvoa.png" width="500" />
### config http proxy server
* take Chrome extent [SwitchyOmega] as an example(https://chrome.google.com/webstore/detail/padekgcemlokbadohgkifijomclgjgif)为例
<img src="https://zos.alipayobjects.com/rmsportal/jIPZrKmqXRaSledQeJUJ.png" width="500" />
### trust root CA in iOS
* Click *Root CA* in web ui, and follow the instruction to install
<img src="https://zos.alipayobjects.com/rmsportal/BrugmMelGVysLDOIBblj.png" width="260" />
### trust root CA in iOS after 10.3
* Besides installing root CA, you have to "turn on" the certificate for web manually in *settings - general - about - Certificate Trust Settings*. Otherwire, safari will not trust the root CA generated by AnyProxy.
<img src="https://zos.alipayobjects.com/rmsportal/hVWkXHrzHmOKOtCKGUWx.png" width="500" />
### config iOS/Android proxy server
* proxy settings are placed in wifi setting
* iOS
<img src="https://zos.alipayobjects.com/rmsportal/tLGqIozhffTccUgPakuw.png" width="260" />
* Android
<img src="https://zos.alipayobjects.com/rmsportal/YQtbQYVNuOszZGdAOauU.png" width="260" />
# FAQ
### Q: can not deal https request in rule module.
* A: Any of these options could be used to change the way AnyProxy deall https requests
1. config `--intercept` when luanching AnyProxy via cli, or use `forceProxyHttps` when using as an npm module
2. place a `beforeDealHttpsRequest` function in your rule file and determine which request to intercept by your own.
### Q: get an error says *function is not yieldable*
* A: Rule module is driven by [co](https://www.npmjs.com/package/co). The functions inside should be yieldable, i.e. return a promise or be a generator function.
### Q: The connection is not private
AnyProxy will propmt this message when the certification of the site you're visiting is not issued by a common known CA. This happens when the certification is self-signed. If you know and trust it, you can ignore the error as below.
- If you run AnyProxy by command line
Pass in the option `--ignore-unauthorized-ssl` to ignore the certification errors, please mind that the option will be active for all connections.
```bash
anyproxy -i --ignore-unauthorized-ssl
```
- If you run AnyProxy by Nodejs
Pass in the option `dangerouslyIgnoreUnauthorized:true`, like this:
```js
const options = {
...,
dangerouslyIgnoreUnauthorized: true
};
const anyproxyIns = new AnyProxy.ProxyCore(options);
anyproxyIns.start();
```
*This is also a global option, all certification errors will be ignored*
- With the help of AnyProxy Rule
You can change the request with rule of course. For this scenario, all you need is to pass in an option to Nodejs `Http.rquest`, as we do in AnyProxy. A simple demo below:
```js
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('https://the-site-you-know.com') === 0) {
const newRequestOptions = requestDetail.requestOptions;
// set rejectUnauthorized as false
newRequestOptions.rejectUnauthorized = false;
return {
requestOptions: newRequestOptions
};
}
},
};
```
And we get a bonous here, AnyProxy will only ignore the errors for the site(s) we want it to!

2
docs-src/en/src_doc.md
View File

@ -7,7 +7,7 @@ Ref: [中文文档](../cn)
Github: Github:
* https://github.com/alibaba/anyproxy/tree/4.x * https://github.com/alibaba/anyproxy
Features: Features:

2
docs/assets/auto-lang.js
View File

@ -16,7 +16,7 @@ function isInLocaleView() {
function initDefaultLocaleAndStatic() { function initDefaultLocaleAndStatic() {
if (!isInLocaleView()) { if (!isInLocaleView()) {
location.href = isUTF8Zone() ? '/cn' : 'en'; location.href = isUTF8Zone() ? '/cn' : '/en';
} }
} }

848
docs/cn/doc.md
View File

@ -1,848 +0,0 @@
# 快速开始
## 作为全局模块
### 安装
对于Debian或者Ubuntu系统，在安装AnyProxy之前，可能还需要安装 `nodejs-legacy`
```bash
sudo apt-get install nodejs-legacy
```
然后，安装AnyProxy
```bash
npm install -g anyproxy@beta #本文档对应的AnyProxy为4.0Beta版
```
### 启动
* 命令行启动AnyProxy，默认端口号8001
```bash
anyproxy
```
* 启动后将终端http代理服务器配置为127.0.0.1:8001即可
* 访问http://127.0.0.1:8002 ，web界面上能看到所有的请求信息
### 其他命令
* 配置启动端口，如1080端口启动
```bash
anyproxy --port 1080
```
## 作为npm模块使用
AnyProxy可以作为一个npm模块使用，整合进其他工具。
> 如要启用https解析，请在代理服务器启动前自行调用`AnyProxy.utils.certMgr`相关方法生成证书，并引导用户信任安装。或引导用户使用`anyproxy-ca`方法。
* 引入
```bash
npm i anyproxy@beta --save # 4.0版正在beta中
```
* 使用举例
```js
const AnyProxy = require('anyproxy');
const options = {
port: 8001,
rule: require('myRuleModule'),
webInterface: {
enable: true,
webPort: 8002,
wsPort: 8003,
},
throttle: 10000,
forceProxyHttps: false,
silent: false
};
const proxyServer = new AnyProxy.ProxyServer(options);
proxyServer.on('ready', () => { /* */ });
proxyServer.on('error', (e) => { /* */ });
proxyServer.start();
//when finished
proxyServer.close();
```
* Class: AnyProxy.proxyServer
* 创建代理服务器
```js
const proxy = new AnyProxy.proxyServer(options)
```
* `options`
* `port` {number} 必选，代理服务器端口
* `rule` {object} 自定义规则模块
* `throttle` {number} 限速值，单位kb/s，默认不限速
* `forceProxyHttps` {boolean} 是否强制拦截所有的https，忽略规则模块的返回，默认`false`
* `silent` {boolean} 是否屏蔽所有console输出，默认`false`
* `dangerouslyIgnoreUnauthorized` {boolean} 是否忽略请求中的证书错误，默认`false`
* `webInterface` {object} web版界面配置
* `enable` {boolean} 是否启用web版界面，默认`false`
* `webPort` {number} web版界面端口号，默认`8002`
* Event: `ready`
* 代理服务器启动完成
* 示例
```js
proxy.on('ready', function() { })
```
* Event: `error`
* 代理服务器发生错误
* 示例
```js
proxy.on('error', function() { })
```
* Method: `start`
* 启动代理服务器
* 示例
```js
proxy.start();
```
* Method: `close`
* 关闭代理服务器
* 示例
```js
proxy.close();
```
* AnyProxy.utils.systemProxyMgr
* 管理系统的全局代理配置，方法调用时可能会弹出密码框
* 使用示例
```js
// 配置127.0.0.1:8001为全局http代理服务器
AnyProxy.utils.systemProxyMgr.enableGlobalProxy('127.0.0.1', '8001');
// 关闭全局代理服务器
AnyProxy.utils.systemProxyMgr.disableGlobalProxy();
```
* AnyProxy.utils.certMgr
* 管理AnyProxy的证书
* `AnyProxy.utils.certMgr.ifRootCAFileExists()`
* 校验系统内是否存在AnyProxy的根证书
* `AnyProxy.utils.certMgr.generateRootCA(callback)`
* 生成AnyProxy的rootCA，完成后请引导用户信任.crt文件
* 样例
```js
const AnyProxy = require('AnyProxy');
const exec = require('child_process').exec;
if (!AnyProxy.utils.certMgr.ifRootCAFileExists()) {
AnyProxy.utils.certMgr.generateRootCA((error, keyPath) => {
// let users to trust this CA before using proxy
if (!error) {
const certDir = require('path').dirname(keyPath);
console.log('The cert is generated at', certDir);
const isWin = /^win/.test(process.platform);
if (isWin) {
exec('start .', { cwd: certDir });
} else {
exec('open .', { cwd: certDir });
}
} else {
console.error('error when generating rootCA', error);
}
});
}
```
# 代理HTTPS
* AnyProxy默认不对https请求做处理，如需看到明文信息，需要配置CA证书
> 解析https请求的原理是中间人攻击（man-in-the-middle），用户必须信任AnyProxy生成的CA证书，才能进行后续流程
* 生成证书并解析所有https请求
```bash
anyproxy-ca #生成rootCA证书，生成后需要手动信任
anyproxy --intercept #启动AnyProxy，并解析所有https请求
```
* [附录：如何信任CA证书](#证书配置)
# rule模块
AnyProxy提供了二次开发的能力，你可以用js编写自己的规则模块（rule），来自定义网络请求的处理逻辑。
>注意：引用规则前，请务必确保文件来源可靠，以免发生安全问题
规则模块的能力范围包括：
* 拦截并修改正在发送的请求
* 可修改内容包括请求头（request header)，请求体（request body），甚至是请求的目标地址等
* 拦截并修改服务端响应
* 可修改的内容包括http状态码(status code)、响应头（response header）、响应内容等
* 拦截https请求，对内容做修改
* 本质是中间人攻击（man-in-the-middle attack），需要客户端提前信任AnyProxy生成的CA
### 开发示例
* 举例
* 需要编写一个规则模块，在 GET http://httpbin.org/user-agent 的返回值里加上测试信息，并延迟5秒返回
* Step 1，编写规则
```js
// file: sample.js
module.exports = {
summary: 'a rule to modify response',
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url === 'http://httpbin.org/user-agent') {
const newResponse = responseDetail.response;
newResponse.body += '-- AnyProxy Hacked! --';
return new Promise((resolve, reject) => {
setTimeout(() => { // delay
resolve({ response: newResponse });
}, 5000);
});
}
},
};
```
* Step 2, 启动AnyProxy，加载规则
* 运行 `anyproxy --rule sample.js`
* Step 3, 测试规则
* 用curl测试
```bash
curl http://httpbin.org/user-agent --proxy http://127.0.0.1:8001
```
* 用浏览器测试：配置浏览器http代理为 127.0.0.1:8001，访问 http://httpbin.org/user-agent
* 经过代理服务器后，期望的返回如下
```
{
"user-agent": "curl/7.43.0"
}
- AnyProxy Hacked!
```
* Step 4, 查看请求信息
* 浏览器访问http://127.0.0.1:8002 ，界面上能看到刚才的请求信息
### 处理流程
* 处理流程图如下
<img src="https://zos.alipayobjects.com/rmsportal/TWyNuSJtEZBdrdcOMRjE.png" width="550" />
* 当http请求经过代理服务器时，具体处理过程是：
* 收集请求所有请求参数，包括method, header, body等
* AnyProxy调用规则模块`beforeSendRequest`方法，由模块做处理，返回新的请求参数，或返回响应内容
* 如果`beforeSendRequest`返回了响应内容，则立即把此响应返回到客户端（而不再发送到真正的服务端），流程结束。
* 根据请求参数，向服务端发出请求，接收服务端响应。
* 调用规则模块`beforeSendResponse`方法，由模块对响应内容进行处理
* 把响应信息返回给客户端
* 当代理服务器收到https请求时，AnyProxy可以替换证书，对请求做明文解析。
* 调用规则模块`beforeDealHttpsRequest`方法，如果返回`true`，会明文解析这个请求，其他请求不处理
* 被明文解析后的https请求，处理流程同http一致。未明文解析请求不会再进入规则模块做处理。
### 如何引用
如下几种方案都可以用来引用规则模块：
* 使用本地路径
```bash
anyproxy --rule ./rule.js
```
* 使用在线地址
```bash
anyproxy --rule https://sample.com/rule.js
```
* 使用npm包
* AnyProxy使用`require()`加载本地规则，你可以在参数里传入一个本地的npm包路径，或是某个全局安装的npm包
```bash
anyproxy --rule ./myRulePkg/ #本地包
npm i -g myRulePkg && anyproxy --rule myRulePkg #全局包
```
# rule接口文档
规则模块应该符合cmd规范，一个典型的规则模块代码结构如下。模块中所有方法都是可选的，只需实现业务感兴趣的部分即可。
```js
module.exports = {
// 模块介绍
summary: 'my customized rule for AnyProxy',
// 发送请求前拦截处理
*beforeSendRequest(requestDetail) { /* ... */ },
// 发送响应前处理
*beforeSendResponse(requestDetail, responseDetail) { /* ... */ },
// 是否处理https请求
*beforeDealHttpsRequest(requestDetail) { /* ... */ },
// 请求出错的事件
*onError(requestDetail, error) { /* ... */ },
// https连接服务器出错
*onConnectError(requestDetail, error) { /* ... */ }
};
```
> 规则文件中，除了summary，都是由 [co](https://www.npmjs.com/package/co) 驱动的，函数需要满足yieldable。可以返回promise或使用generator函数。
### summary
#### summary(): string | summary:string
* 规则模块的介绍文案，用于AnyProxy提示用户, 可以是一个函数，也可以是一个普通的字符串
### beforeSendRequest
#### beforeSendRequest(requestDetail)
* AnyProxy向服务端发送请求前，会调用`beforeSendRequest`，并带上参数`requestDetail`
* `requestDetail`
* `protocol` {string} 请求使用的协议，http或者https
* `requestOptions` {object} 即将发送的请求配置，供require('http').request作为使用。详见：https://nodejs.org/api/http.html#http_http_request_options_callback
* `requestData` {object} 请求Body
* `url` {string} 请求url
* `_req` {object} 请求的原始request
* 举例：请求 *anyproxy.io* 时，`requestDetail`参数内容大致如下
```js
{
protocol: 'http',
url: 'http://anyproxy.io/',
requestOptions: {
hostname: 'anyproxy.io',
port: 80,
path: '/',
method: 'GET',
headers: {
Host: 'anyproxy.io',
'Proxy-Connection': 'keep-alive',
'User-Agent': '...'
}
},
requestData: '...',
_req: { /* ... */}
}
```
* 以下几种返回都是合法的
* 不做任何处理，返回null
```js
return null;
```
* 修改请求协议，如强制改用https发起请求
```js
return {
protocol: 'https'
};
```
* 修改请求参数
```js
var newOption = Object.assign({}, requestDetail.requestOptions);
newOption.path = '/redirect/to/another/path';
return {
requestOptions: newOption
};
```
* 修改请求body
```js
return {
requestData: 'my new request data'
//这里也可以同时加上requestOptions
};
```
* 直接返回客户端，不再发起请求，其中`statusCode` `header` 是必选字段
```js
return {
response: {
statusCode: 200,
header: { 'content-type': 'text/html' },
body: 'this could be a <string> or <buffer>'
}
};
```
### beforeSendResponse
#### beforeSendResponse(requestDetail, responseDetail)
* AnyProxy向客户端发送请求前，会调用`beforeSendResponse`，并带上参数`requestDetail` `responseDetail`
* `requestDetail` 同`beforeSendRequest`中的参数
* `responseDetail`
* `response` {object} 服务端的返回信息，包括`statusCode` `header` `body`三个字段
* `_res` {object} 原始的服务端返回对象
* 举例，请求 *anyproxy.io* 时，`responseDetail`参数内容大致如下
```js
{
response: {
statusCode: 200,
header: {
'Content-Type': 'image/gif',
Connection: 'close',
'Cache-Control': '...'
},
body: '...'
},
_res: { /* ... */ }
}
```
* 以下几种返回都是合法的
* 不做任何处理，返回null
```js
return null;
```
* 修改返回的状态码
```js
var newResponse = Object.assign({}, responseDetail.response);
newResponse.statusCode = 404;
return {
response: newResponse
};
```
* 修改返回的内容
```js
var newResponse = Object.assign({}, responseDetail.response);
newResponse.body += '--from anyproxy--';
return {
response: newResponse
};
```
### beforeDealHttpsRequest
#### beforeDealHttpsRequest(requestDetail)
* AnyProxy收到https请求时，会调用`beforeDealHttpsRequest`，并带上参数`requestDetail`
* 如果配置了全局解析https的参数，则AnyProxy会略过这个调用
* 只有返回`true`时，AnyProxy才会尝试替换证书、解析https。否则只做数据流转发，无法看到明文数据。
* 注意：https over http的代理模式中，这里的request是CONNECT请求
* `requestDetail`
* `host` {string} 请求目标的Host，受制于协议，这里无法获取完整url
* `_req` {object} 请求的原始request
* 返回值
* `true`或者`false`，表示是否需要AnyProxy替换证书并解析https
### onError
#### onError(requestDetail, error)
* 在请求处理过程中发生错误时，AnyProxy会调用`onError`方法，并提供对应的错误信息
* 多数场景下，错误会在请求目标服务器的时候发生，比如DNS解析失败、请求超时等
* `requestDetail` 同`beforeSendRequest`中的参数
* 以下几种返回都是合法的
* 不做任何处理。此时AnyProxy会返回一个默认的错误页。
```js
return null;
```
* 返回自定义错误页
```js
return {
response: {
statusCode: 200,
header: { 'content-type': 'text/html' },
body: 'this could be a <string> or <buffer>'
}
};
```
### onConnectError
#### onConnectError(requestDetail, error)
* AnyProxy在与目标HTTPS服务器建立连接的过程中，如果发生错误，AnyProxy会调用这个方法
* `requestDetail` 同`beforeDealHttpsRequest`中的参数
* 此处无法控制向客户端的返回信息，无需返回值。
# rule样例
* 这里提供一些样例，来讲解规则模块的常见用法
* 你可以通过 `anyproxy --rule http://....js` 来加载模块并体验
* 用curl发请求测试的方法如下
* 直接请求服务器：`curl http://httpbin.org/`
* 通过代理服务器请求：`curl http://httpbin.org/ --proxy http://127.0.0.1:8001`
### 使用本地数据
* 拦截发送到 http://httpbin.org 的请求，使用本地数据代替服务端返回
```bash
anyproxy --rule rule_sample/sample_use_local_response.js
```
```js
/*
sample:
intercept all requests toward httpbin.org, use a local response
test:
curl http://httpbin.org/user-agent --proxy http://127.0.0.1:8001
*/
module.exports = {
*beforeSendRequest(requestDetail) {
const localResponse = {
statusCode: 200,
header: { 'Content-Type': 'application/json' },
body: '{"hello": "this is local response"}'
};
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
return {
response: localResponse
};
}
},
};
```
### 修改请求头
* 修改发送到 httpbin.org 的user-agent
```bash
anyproxy --rule rule_sample/sample_modify_request_header.js
```
```js
/*
sample:
modify the user-agent in requests toward httpbin.org
test:
curl http://httpbin.org/user-agent --proxy http://127.0.0.1:8001
*/
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newRequestOptions = requestDetail.requestOptions;
newRequestOptions.headers['User-Agent'] = 'AnyProxy/0.0.0';
return {
requestOptions: newRequestOptions
};
}
},
};
```
### 修改请求数据
* 修改发送到 http://httpbin.org/post 的post数据
```bash
anyproxy --rule rule_sample/sample_modify_request_data.js
```
```js
/*
sample:
modify the post data towards http://httpbin.org/post
test:
curl -H "Content-Type: text/plain" -X POST -d 'original post data' http://httpbin.org/post --proxy http://127.0.0.1:8001
expected response:
{ "data": "i-am-anyproxy-modified-post-data" }
*/
module.exports = {
summary: 'Rule to modify request data',
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org/post') === 0) {
return {
requestData: 'i-am-anyproxy-modified-post-data'
};
}
},
};
```
### 修改请求的目标地址
* 把所有发送到 http://httpbin.org/ 的请求全部改到 http://httpbin.org/user-agent
```bash
anyproxy --rule rule_sample/sample_modify_request_path.js
```
```js
/*
sample:
redirect all httpbin.org requests to http://httpbin.org/user-agent
test:
curl http://httpbin.org/any-path --proxy http://127.0.0.1:8001
expected response:
{ "user-agent": "curl/7.43.0" }
*/
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newRequestOptions = requestDetail.requestOptions;
newRequestOptions.path = '/user-agent';
newRequestOptions.method = 'GET';
return {
requestOptions: newRequestOptions
};
}
},
};
```
### 修改请求协议
* 把用http协议请求的 http://httpbin.org 改成https并发送
```bash
anyproxy --rule rule_sample/sample_modify_request_protocol.js
```
```js
/*
sample:
redirect all http requests of httpbin.org to https
test:
curl 'http://httpbin.org/get?show_env=1' --proxy http://127.0.0.1:8001
expected response:
{ "X-Forwarded-Protocol": "https" }
*/
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newOption = requestDetail.requestOptions;
newOption.port = 443;
return {
protocol: 'https',
requestOptions: newOption
};
}
}
};
```
### 修改返回状态码
* 把 所有http://httpbin.org 的返回状态码都改成404
```bash
anyproxy --rule rule_sample/sample_modify_response_statuscode.js
```
```js
/*
sample:
modify all status code of http://httpbin.org/ to 404
test:
curl -I 'http://httpbin.org/user-agent' --proxy http://127.0.0.1:8001
expected response:
HTTP/1.1 404 Not Found
*/
module.exports = {
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url.indexOf('http://httpbin.org') === 0) {
const newResponse = responseDetail.response;
newResponse.statusCode = 404;
return {
response: newResponse
};
}
}
};
```
### 修改返回头
* 在 http://httpbin.org/user-agent 的返回头里加上 X-Proxy-By:AnyProxy
```bash
anyproxy --rule rule_sample/sample_modify_response_header.js
```
```js
/*
sample:
modify response header of http://httpbin.org/user-agent
test:
curl -I 'http://httpbin.org/user-agent' --proxy http://127.0.0.1:8001
expected response:
X-Proxy-By: AnyProxy
*/
module.exports = {
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url.indexOf('http://httpbin.org/user-agent') === 0) {
const newResponse = responseDetail.response;
newResponse.header['X-Proxy-By'] = 'AnyProxy';
return {
response: newResponse
};
}
}
};
```
### 修改返回内容并延迟
* 在 http://httpbin.org/user-agent 的返回最后追加AnyProxy的签名，并延迟5秒
```bash
anyproxy --rule rule_sample/sample_modify_response_data.js
```
```js
/*
sample:
modify response data of http://httpbin.org/user-agent
test:
curl 'http://httpbin.org/user-agent' --proxy http://127.0.0.1:8001
expected response:
{ "user-agent": "curl/7.43.0" } -- AnyProxy Hacked! --
*/
module.exports = {
*beforeSendResponse(requestDetail, responseDetail) {
if (requestDetail.url === 'http://httpbin.org/user-agent') {
const newResponse = responseDetail.response;
newResponse.body += '-- AnyProxy Hacked! --';
return new Promise((resolve, reject) => {
setTimeout(() => { // delay the response for 5s
resolve({ response: newResponse });
}, 5000);
});
}
},
};
```
# 证书配置
### OSX系统信任CA证书
* 类似这种报错都是因为系统没有信任AnyProxy生成的CA所造成的
<img src="https://zos.alipayobjects.com/rmsportal/CBkLGYgvoHAYwNVAYkpk.png" width="450" />
> 警告：CA证书和系统安全息息相关，建议亲自生成，并妥善保管
安装CA：
* 双击打开*rootCA.crt*
* 确认将证书添加到login或system
<img src="https://zos.alipayobjects.com/rmsportal/bCwNUFFpvsmVuljQKrIk.png" width="350" />
* 找到刚刚导入的AnyProxy证书，配置为信任（Always Trust）
<img src="https://zos.alipayobjects.com/rmsportal/HOmEElNGdoZEWFMLsTNT.png" width="700" />
### Windows系统信任CA证书
<img src="https://t.alipayobjects.com/tfscom/T1D3hfXeFtXXXXXXXX.jpg" width="700" />
### 配置OSX系统代理
* 在wifi高级设置中，配置http代理即可
<img src="https://zos.alipayobjects.com/rmsportal/vduwhobSTypTfgniBvoa.png" width="500" />
### 配置浏览器HTTP代理
* 以Chrome的[SwitchyOmega插件](https://chrome.google.com/webstore/detail/padekgcemlokbadohgkifijomclgjgif)为例
<img src="https://zos.alipayobjects.com/rmsportal/jIPZrKmqXRaSledQeJUJ.png" width="500" />
### iOS系统信任CA证书
* 点击web ui中的 *Root CA*，按提示扫描二维码即可安装
<img src="https://zos.alipayobjects.com/rmsportal/BrugmMelGVysLDOIBblj.png" width="260" />
### iOS >= 10.3信任CA证书
* 除了上述证书安装过程，还需要在 *设置->通用->关于本机->证书信任设置* 中把AnyProxy证书的开关打开，否则safari将报错。
<img src="https://zos.alipayobjects.com/rmsportal/hVWkXHrzHmOKOtCKGUWx.png" width="500" />
### 配置iOS/Android系统代理
* 代理服务器都在wifi设置中配置
* iOS HTTP代理配置
<img src="https://zos.alipayobjects.com/rmsportal/tLGqIozhffTccUgPakuw.png" width="260" />
* Android HTTP代理配置
<img src="https://zos.alipayobjects.com/rmsportal/YQtbQYVNuOszZGdAOauU.png" width="260" />
# FAQ
#### Q: 为什么https请求不能进入处理函数？
A: 以下任意一项都能用来改变https的处理特性：
1. 命令行启动AnyProxy时配置`--intercept`参数，按npm模块启动时配置`forceProxyHttps`参数，所有Https请求都会被替换证书并解析
2. 规则文件内提供`beforeDealHttpsRequest`方法，返回 *true* 的https请求会被解析
#### Q: 提示 *function is not yieldable*
* A: 规则模块是用 [co](https://www.npmjs.com/package/co) 驱动的，函数需要满足yieldable。可以使用generator方法或是返回Promise。
#### Q: The connection is not private
当访问特定的HTTPS站点，AnyProxy会提示该站点不是一个安全的网站，这通常是因为站点的证书设置不能被正确识别导致的（比如，站点的证书是自签发的）。如果您信任该网站，可以用以下方式来继续访问：
- 命令行直接启动
通过启动参数 `--ignore-unauthorized-ssl` 来忽略证书认证的错误。需要注意的是，该参数是全局生效的，如果你在此期间访问了其他未知的网站，他们的证书问题也会被忽略，这可能会带来安全隐患。
```bash
anyproxy -i --ignore-unauthorized-ssl
```
- 在Nodejs代码中启动
在构造AnyProxy实例的时候，传入参数`dangerouslyIgnoreUnauthorized:true`, 如下：
```js
const options = {
...,
dangerouslyIgnoreUnauthorized: true
};
const anyproxyIns = new AnyProxy.ProxyCore(options);
anyproxyIns.start();
```
*通过这种方式初始化的AnyProxy，其配置也是全局性的，所有网站的证书问题都会被忽略*
- 通过自定义的Rule来修改
我们自然也可以借助自定义的Rule来实现这个效果，而且我们还可以控制到只允许指定网址的证书错误，对不在列表的网址，进行证书的强验证。
```js
module.exports = {
*beforeSendRequest(requestDetail) {
if (requestDetail.url.indexOf('https://the-site-you-know.com') === 0) {
const newRequestOptions = requestDetail.requestOptions;
// 设置属性 rejectUnauthorized 为 false
newRequestOptions.rejectUnauthorized = false;
return {
requestOptions: newRequestOptions
};
}
},
};
```

2
docs/cn/src_doc.md
View File

@ -7,7 +7,7 @@ Ref: [English Doc](../en)
AnyProxy是一个开放式的HTTP代理服务器。 AnyProxy是一个开放式的HTTP代理服务器。
Github主页：https://github.com/alibaba/anyproxy/tree/4.x Github主页：https://github.com/alibaba/anyproxy
主要特性包括： 主要特性包括：

1635
docs/en/doc.html
View File

File diff suppressed because it is too large Load Diff