Skip to content

Commit 931feac

Browse files
xcodebuildxcodebuild
committed
Squashed 'vendor/whistle/' changes from 466900ca9f..904573e931
904573e931 fix the incorrect link of pipe.html 8f97f121ff Update pattern.md 512e58feda Release v2.9.94 0903b78849 refactor: refine ui 448688f9aa feat: Commands -> Install c2282bf8b7 fix: avwo/whistle#1192 0d8ff36928 docs: README 4d9b5ddd71 Release v2.9.93 ea99d3af9b docs: README ddb8968506 docs: sniCallback 53ec0394ce refactor: refine code eae6ce353d fix: avwo/whistle#1192 5ab12d3466 refactor: refine ui 57cc1e1f91 feat: w2 ca --enable-https 7ce2ee9639 Release v2.9.92 6854677161 feat: set server.requestTime = 0 48b3f8b15c docs: pipe 77b1314734 feat: update express 623ded0ec6 refactor: refine code d74c3dcad7 refactor: refine code 92f72eb5b8 feat: disable://keepH2Session 6dd4ee9c64 Release v2.9.91 aa4af22135 fix: avwo/whistle#1173 0812fd86cc Release v2.9.91 d6a1e92567 fix: avwo/whistle#1183 7be53e28bd fix: avwo/whistle#1081 2a26b619a4 Release v2.9.90 a076e7edc7 feat: search editor fd94769422 refactor: refine ui 156cc1d277 refactor: refine ui 1d612a81c3 refactor: refine ui 8dd3b9ff9c refactor: refine code b4211f5a70 Release v2.9.89 b1a3ba9b4b feat: parse curl 7eebcc7e9b refactor: refine code ed07550b9a refactor: refine ui 1fb7dfd4ef Release v2.9.88 549dfc8a8a refactor: refine composer 828480e2ff fix: resolve keys f7dba66c9c perf: captureStream 5678474cf4 docs: update 87944e5bd8 Release v2.9.87 f91f572a51 feat: delete://reqBody.xxx|resBody.xxx b3c102e63d feat: refine ui f79259cef8 test: reqMerge 0942e84a95 docs: delete 4479cf235b feat: delete://reqType|resType|reqCharset|resCharset 0d3de1f42e Release v2.9.87 git-subtree-dir: vendor/whistle git-subtree-split: 904573e931d7afdb2dc19dfba6807e2fe575b337
1 parent e688071 commit 931feac

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+2438
-1010
lines changed

‎CHANGELOG.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,39 @@
1+
# v2.9.94
2+
1. fix: https://github.com/avwo/whistle/pull/1192
3+
4+
# v2.9.93
5+
1. feat: 重放请求时保留 http2 session
6+
2. feat: 添加命令行参数 `--enable-https`：`w2 ca --enable-https`
7+
3. feat: Composer 添加 QUERY 方法
8+
4. feat: locationHref 支持通过设置 locationHref://replace:url 改用 location.replace
9+
5. fix: https://github.com/avwo/whistle/pull/1192
10+
11+
# v2.9.92
12+
1. feat: 优化响应超时机制，关闭 `requestTimeout`
13+
14+
# v2.9.91
15+
1. fix: https://github.com/avwo/whistle/issues/1183
16+
2. fix: https://github.com/avwo/whistle/issues/1173
17+
3. fix: https://github.com/avwo/whistle/issues/1081
18+
19+
# v2.9.90
20+
1. feat: 支持 [whistle-client](https://github.com/avwo/whistle-client) 搜索功能
21+
22+
# v2.9.89
23+
1. feat: Composer 支持导入 CURL 文本
24+
2. feat: 优化 Composer
25+
26+
# v2.9.88
27+
1. perf: 优化 `enable://captureStream`
28+
2. feat: Composer 支持通过右键发送按钮选择发送文件
29+
3. fix: 某些情况下解析配置规则里面的数据对象有误（v2.9.87版本引入）
30+
31+
# v2.9.87
32+
1. feat: `delete://reqType||resType|reqCharset|resCharset`
33+
2. feat: `delete://resBody.xxx` 删除响应的 JSON 数据可以 key
34+
3. feat: `delete://reqBody.xxx` 删除请求内容为表单或 JSON 的 JSON 数据对应 key
35+
4. feat: Network 支持通过 `/` 快速聚集到搜索框
36+
137
# v2.9.86
238
1. feat: JSON View 右键菜单 `Inspect Value` 查看当前 key 对应的 Value 对象
339
2. feat: JSON Dialog 添加前进和后退键查看历史记录

‎README-en_US.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
<p align="center">
2+
<a href="https://avwo.github.io/whistle/">
3+
<img alt="whistle logo" src="https://user-images.githubusercontent.com/11450939/168828068-99e38862-d5fc-42bc-b5ab-6262b2ca27d6.png">
4+
</a>
5+
</p>
6+
7+
# whistle
8+
[![NPM version](https://img.shields.io/npm/v/whistle.svg?style=flat-square)](https://npmjs.org/package/whistle)
9+
[![node version](https://img.shields.io/badge/node.js-%3E=_8-green.svg?style=flat-square)](http://nodejs.org/download/)
10+
[![Test coverage](https://codecov.io/gh/avwo/whistle/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/avwo/whistle)
11+
[![npm download](https://img.shields.io/npm/dm/whistle.svg?style=flat-square)](https://npmjs.org/package/whistle)
12+
[![NPM count](https://img.shields.io/npm/dt/whistle.svg?style=flat-square)](https://www.npmjs.com/package/whistle)
13+
[![License](https://img.shields.io/aur/license/whistle?style=flat-square)](https://www.npmjs.com/package/whistle)
14+
15+
[中文](./README-zh_CN.md) · English
16+
17+
Whistle is a simple and powerful cross-platform packet capture and debugging tool based on Node.JS. It can be used as **HTTP proxy (default)**, **HTTPS proxy**, **Socks proxy**, **reverse proxy**, etc., for **packet capture analysis** or **modification through configuration rules** of HTTP, HTTPS, HTTP/2, WebSocket, TCP requests. It also has built-in **Weinre**, **Log**, **Composer** and other tools to view the DOM structure of remote pages, view console output content, replay and edit construction requests, etc. It also supports **plug-in extension functions** or **referenced by projects as NPM packages**.
18+
19+
# Installation
20+
21+
**Windows PC or Mac PC recommended client: [https://github.com/avwo/whistle-client](https://github.com/avwo/whistle-client).**
22+
23+
> If you use Whistle client, you can skip this installation step
24+
25+
Linux PC, server and other systems can use the command line version, which needs to be installed strictly according to the following 4 steps:
26+
27+
1. Install Whistle
28+
2. Start Whistle
29+
3. Install root certificate
30+
4. Set up proxy
31+
32+
### Install Whistle
33+
34+
Choose one of the following installation methods according to the actual situation:
35+
36+
1. Install through npm (need to install Node.JS first: https://nodejs.org/ ):
37+
38+
``` sh
39+
npm i -g whistle
40+
```
41+
42+
2. Install through brew (need to install brew first: https://brew.sh/ ):
43+
44+
``` sh
45+
brew install whistle
46+
```
47+
48+
### Start Whistle
49+
50+
``` sh
51+
w2 start
52+
```
53+
54+
> Whistle starts HTTP proxy by default (IP: `127.0.0.1`, port: `8899`), which can be started through `w2 start -p 8888` Modify the port. If it has been started, restart it with `w2 restart -p 8888` to modify the port.
55+
56+
For complete command line functions, please refer to the full document: https://wproxy.org/whistle/options.html
57+
58+
### Install the root certificate
59+
60+
After starting Whistle, you can install the root certificate with the following command:
61+
62+
``` sh
63+
w2 ca --enable-https
64+
```
65+
66+
<details>
67+
<summary>Windows needs to click "Yes (Y)" to confirm</summary>
68+
<img alt="Click Yes (Y)" width="420" src="https://user-images.githubusercontent.com/11450939/168846905-384e0540-e02f-46de-81d7-e395a496f032.jpeg">
69+
</details>
70+
71+
<details>
72+
<summary>Mac You need to enter the power-on password or fingerprint verification</summary>
73+
<img alt="Enter the power-on password" width="330" src="https://user-images.githubusercontent.com/11450939/176977027-4a7b06a0-64f6-4580-b983-312515e9cd4e.png">
74+
<img alt="Enter fingerprint" width="330" src="https://user-images.githubusercontent.com/11450939/168847123-e66845d0-6002-4f24-874f-b6943f7f376b.png">
75+
</details>
76+
77+
For how to install the root certificate on other terminals such as mobile phones, please refer to the complete document: https://wproxy.org/whistle/webui/https.html
78+
79+
### Setting up a proxy
80+
81+
**There are four ways to use Windows PC or Mac PC. You can choose one of them according to your actual situation:**
82+
83+
1. **[Recommended]** Set up a proxy by installing the Chrome plug-in SwitchyOmega: https://chromewebstore.google.com/detail/proxy-switchyomega/padekgcemlokbadohgkifijomclgjgif
84+
85+
> Chrome App Store requires a VPN. If you cannot access it, please install it manually: https://proxy-switchyomega.com/download/
86+
87+
<details>
88+
<summary>SwitchyOmega setting method example diagram</summary>
89+
<img width="620" alt="image" src="https://github.com/user-attachments/assets/24016b7c-8f2a-45a3-9dc8-5ef3ddf46233" /><img width="180" alt="image" src="https://github.com/user-attachments/assets/43afd3cd-5c17-4d6a-82d0-20a7ef2e0d99" />
90+
</details>
91+
92+
2. Set the system proxy through the command line:
93+
94+
```. sh
95+
w2 proxy
96+
```
97+
98+
> You can also specify the IP (default `127.0.0.1`) and port: `w2 proxy "10.x.x.x:8888"`, and use `w2 proxy 0` to turn off the system proxy setting
99+
100+
3. Set the proxy directly on the client, such as FireFox, WeChat developer tools, etc., which have built-in proxy setting functions
101+
<details>
102+
<summary>FireFox proxy setting example image</summary>
103+
<img width="1100" alt="image" src="https://github.com/user-attachments/assets/98c1ec5d-4955-4e23-a49a-c1015b128d9d" />
104+
</details>
105+
4. Set up a proxy through Proxifier (for clients that cannot set up a proxy and do not use a system proxy): https://www.proxifier.com/docs/win-v4/http-proxy.html
106+
107+
**Linux setting path: Settings > Network > VPN > Network Proxy > Manual**
108+
<details>
109+
<summary>Linux proxy setting example image</summary>
110+
<img width="1000" alt="image" src="https://github.com/user-attachments/assets/e9441d32-c818-4446-8be6-0fa3df3aed86" />
111+
</details>
112+
113+
**Mobile devices such as mobile phones need to configure the current `Wi-Fi` proxy, taking iOS as an example:**
114+
<details>
115+
<summary>iOS proxy settings example image</summary>
116+
<img width="1000" alt="image" src="https://github.com/user-attachments/assets/e97dc311-2ace-4287-b6b0-0247b13974a9" />
117+
</details>
118+
119+
# Use
120+
121+
After installing Whistle according to the above steps, open the link http://local.whistlejs.com on the Chrome browser, and you can see the following operation interface:
122+
123+
<img width="1200" alt="network" src="https://github.com/user-attachments/assets/3186e76a-486a-4e61-98a1-2d4b4f91fad0" />
124+
125+
<img width="1200" alt="rules" src="https://github.com/user-attachments/assets/2e336403-4810-48e5-91c1-6f22dcda7388" />
126+
127+
Among them, Network is the interface for viewing packet capture, Rules is the configuration rule, Values ​​is the configuration data interface (used with Rules), and Plugins is the list of installed plugins.
128+
129+
### Interface functions
130+
131+
<details>
132+
<summary>Replay request</summary>
133+
<img width="800" alt="image" src="https://github.com/user-attachments/assets/9f8276ac-e089-427b-97f4-becac250ae5e" />
134+
</details>
135+
136+
<details>
137+
<summary>Edit or construct request</summary>
138+
<img width="1200" alt="image" src="https://github.com/user-attachments/assets/f2a5b088-72b6-4098-8ba6-3e42f15f3ad8" />
139+
</details>
140+
141+
For other interface functions, see the full document: https://wproxy.org/whistle/webui/
142+
143+
### Rule functions
144+
145+
Whistle rules can be seen as an extension of the following system hosts rules:
146+
147+
``` txt
148+
# One domain name corresponds to one IP
149+
127.0.0.1 localhost
150+
::1 localhost
151+
# Multiple domain names correspond to one IP
152+
10.2.55.3 www.test.com www.example.com
153+
```
154+
155+
The system hosts rules have a single function, only supporting DNS modification and domain name matching, and there are DNS cache problems, which cannot meet daily work needs. Whistle rules extend the functions of system hosts rules. In terms of matching methods, they not only support domain name matching, path matching, wildcard matching, regular matching, etc., but also support further filtering by request method, response status code, request (response) header, request content, etc.; in terms of functions, they not only support DNS modification, but also support port modification, CNAME, proxy setting, request URL modification, request method, response status code, request header, response header, request content, response content, etc. In theory, everything in HTTP request can be modified. The format of Whistle rules is:
156+
157+
1. Default format
158+
159+
``` txt
160+
pattern operation
161+
```
162+
163+
2. Support matching multiple operations
164+
165+
``` txt
166+
pattern operation1 operation2 ...
167+
```
168+
169+
3. Support filters
170+
171+
``` txt
172+
pattern operation1 operation2 ... includeFilter://filterPattern1 ... excludeFilter://filterPatternN ...
173+
```
174+
175+
> Multiple filters are in an or relationship, that is, one of the conditions must be met
176+
177+
4. Support position swap (prerequisite: operation and pattern are not URLs or domain names at the same time)
178+
179+
``` txt
180+
operation pattern [filters ...]
181+
operation pattern1 pattern2 ... [filters ...]
182+
```
183+
184+
5. Support line breaks
185+
186+
``` txt
187+
line`
188+
operation
189+
pattern1
190+
pattern2 ...
191+
[filters ...]
192+
`
193+
```
194+
195+
Specific examples are as follows:
196+
197+
##### Modify DNS (set Hosts)
198+
199+
1. Domain name matching
200+
201+
``` txt
202+
www.test.com 127.0.0.1
203+
# Support port
204+
www.test.com 127.0.0.1:8080
205+
# CNAME function (port optional)
206+
www.test.com host://www.example.com:8181
207+
```
208+
209+
> Unlike the system hosts rule, the Whistle rule adopts **left-to-right mapping** and **top-to-bottom priority** by default, but the operation and pattern can be swapped when they are different URLs or domain names, so it is also compatible with the system hosts rule, that is: `127.0.0.1:8080 www.test.com`
210+
211+
2. Path matching
212+
213+
``` txt
214+
www.test.com/path/to 127.0.0.1:8080
215+
# Support with protocol
216+
https://www.test.com/path/to 127.0.0.1:8080
217+
```
218+
219+
3. Wildcard matching
220+
221+
``` txt
222+
# Domain name wildcard, matching test.com All descendant domain names of
223+
**.test.com 127.0.0.1:8080
224+
# Support wildcards for domain names with protocols
225+
https://**.test.com 127.0.0.1:8080
226+
# Path wildcards (* is a legal character for paths, so add ^ in front to tell Whistle that it is a wildcard)
227+
^**.test.com/*/path/to 127.0.0.1:8080
228+
# Support wildcards for paths with protocols
229+
^https://**.test.com/*/path/to 127.0.0.1:8080
230+
```
231+
232+
> `*`, `**`, `***` have different matching ranges, for details, see the full document: https://wproxy.org/whistle/pattern.html
233+
234+
4. Regular matching
235+
236+
``` txt
237+
# The internal `/` can be escaped, which is equivalent to `new RegExp('^https?://\w+\.test\.com')`
238+
/^https?://\w+\.test\.com/ 127.0.0.1:8080
239+
```
240+
241+
5. Filter matching
242+
243+
``` txt
244+
# `pattern` is the same as the domain name, path, and regular expression above, indicating that in addition to matching `pattern`, the request header `cookie` must also contain `env=test`
245+
pattern 127.0.0.1:8080 includeFilter://reqH.cookie=/env=test/
246+
```
247+
248+
##### Modify form data
249+
250+
``` txt
251+
# Modify the value of the `test` field in the form
252+
pattern reqMerge://test=123
253+
254+
# Delete the `abc` field in the form
255+
pattern delete://reqBody.abc
256+
```
257+
258+
##### Set the cross-domain response header
259+
260+
``` txt
261+
# Taking path matching as an example, set the cross-domain response header Access-Control-Allow-Origin: * and exclude OPTION requests
262+
pattern resCors://* excludeFilter://m:option
263+
```
264+
265+
For all rules, see the full document: https://wproxy.org/whistle/rules/
266+
267+
### Install the plugin
268+
269+
The plugin needs to be installed through the command line:
270+
271+
``` sh
272+
w2 i whistle.inspect whistle.vase
273+
```
274+
275+
> The above plug-in function introduction and source code: [https://github.com/whistle-plugins](https://github.com/whistle-plugins), the client can be installed through the interface: [https://github.com/avwo/whistle-client](https://github.com/avwo/whistle-client)
276+
277+
After installation, you can see these two plug-ins in the Plugins of the management interface:
278+
279+
<details>
280+
<summary>Plugin list example image</summary>
281+
<img width="1000" alt="image" src="https://github.com/user-attachments/assets/ec018691-c7a9-415e-9809-bf079694c024" />
282+
</details>
283+
284+
Each plug-in can add two rule protocols by default:
285+
286+
``` txt
287+
whistle.inspect://xxx
288+
inspect://xxx
289+
```
290+
291+
> By configuring the custom rules of the plug-in, the matching request can be forwarded to the plug-in specified hook implements custom functions. If not needed, you can also set `"hideLongProtocol": true` or `"hideShortProtocol": true` in `whistleConfig` of `package.json` of the plugin to hide the corresponding rule protocol
292+
293+
In addition to extending rules, the plugin also supports extending the Whistle interface, as well as providing operation interfaces, built-in rules and other functions. For installation, use and development of the plugin, please refer to the complete document: https://wproxy.org/whistle/plugins.html
294+
295+
# License
296+
297+
[MIT](./LICENSE)

0 commit comments

Comments
 (0)