LightProxy Documentation

repository·master·Indexed 25 days ago

https://github.com/alibaba/lightproxy

An automated proxy tool for macOS and Windows based on whistle. LightProxy simplifies proxying tasks by automating certificate installation and system proxy settings, supporting packet capture, hosts binding, resource forwarding, and mocking. It allows for highly customizable proxy rules using whistle syntax and Node.js, including support for multi-line strings and wireless proxy configuration for mobile devices.

Tokens
11.2K
Snippets
16
Records
82
Agent score
83%

What's inside LightProxy

  1. Overview of LightProxy

    master
    LightProxy is a cross-platform Web proxy debugging tool. It provides automated certificate installation and system proxy settings to simplify the debugging process. It is built upon whistle, allowing users to leverage powerful packet capturing and proxy rules, including the ability to write custom rules using Node.js.
  2. Core Capabilities of LightProxy

    master

    LightProxy provides several proxy and debugging capabilities:

    • Packet Capture: Includes wireless scene capture.
    • Hosts Binding: Real-time hosts binding.
    • Resource Forwarding: Forward resources based on defined rules.
    • Mocking: Mock interfaces, pages, and more.
    • Content Modification: Modify request and response content (e.g., inserting script into a page or modifying return headers).
  3. Use LightProxy for Packet Capture and Mocking

    master

    LightProxy provides several key capabilities for developers:

    • Packet Capture: Includes support for wireless scenarios.
    • Hosts Binding: Real-time hosts binding.
    • Resource Forwarding: Forward resources based on specific rules.
    • Mocking: Mock interfaces (APIs), pages, and more.
    • Content Modification: Modify request and response content, such as inserting script tags into pages or modifying response headers.
  4. Use Wildcard Matching for Domain Names

    master

    You can use wildcards in domain names without the ^ prefix.

    • *.com matches domains like baidu.com or bing.com, but will not match subdomains like www.baidu.com.
    • ***.com matches all subdomains, including deeply nested ones like xxx.yyy.baidu.com.
    *.com
    ***.com
  5. Install Certificate on iOS

    master

    Follow these steps to install and trust the LightProxy certificate on iOS:

    1. Download Profile: Scan the QR code using the Camera app. Open the link in Safari to download the configuration profile.
    2. Install Profile: Go to Settings > Downloaded Profile (已下载的描述文件) and follow the prompts to install it.
    3. Trust Certificate: This is a critical final step. Navigate to Settings > General > About > Certificate Trust Settings (证书信任设置) and toggle on the switch for the LightProxy certificate.
    4. Configure Proxy: In your device's Wi-Fi settings, manually configure the HTTP proxy using the IP address and port number displayed in the LightProxy interface.
  6. Capture network traffic from a mobile device

    master

    To capture network requests from a mobile device, you must use the wireless proxy setup.

    Important: By default, LightProxy is not visible on the local area network (LAN). To enable LAN visibility for mobile device proxying, you must click on the 手机代理 (Mobile Proxy) tab in the LightProxy interface.

  7. Install LightProxy Certificate on iOS

    master

    To use LightProxy on iOS, you must download, install, and trust the certificate using the following steps:

    1. Download: Open your camera, scan the QR code displayed in LightProxy, and open the link in Safari to download the description file.
    2. Install Profile: Go to Settings, locate the downloaded description file, and install it.
    3. Trust Certificate: This is a critical final step. Navigate to Settings => General => About This Machine, scroll to the bottom to find Certificate Trust Settings, and enable the toggle for the LightProxy certificate.
    4. Configure Proxy: Go to your Wi-Fi settings, select your current network, and manually set the proxy to the specific address and port number displayed in the LightProxy interface.
  8. Use LightProxy with the command line

    master

    By default, LightProxy settings only apply to browsers and Webviews. To route command-line tools (like curl) through the LightProxy proxy, use the copy shell script function located in the LightProxy menubar.

    Once clicked, the proxy configuration commands are copied to your clipboard. After pasting and executing these commands in your terminal, subsequent commands in that session will use the LightProxy proxy.

    Note: This method only affects applications that respect environment variables; it does not force all system applications through the proxy.

    # Example of the commands generated by the copy shell script function
    export https_proxy=http://127.0.0.1:12888 http_proxy=http://127.0.0.1:12888 all_proxy=socks5://127.0.0.1:12889
    curl https://baidu.com -I
  9. Download and Install LightProxy

    master

    LightProxy is a local proxy packet capture software based on whistle. You can download the installers for macOS and Windows using the links below:

    Installation Steps:

    1. Download the appropriate version for your OS.
    2. For macOS: Open the .dmg file and drag LightProxy to your Applications folder.
    3. For Windows: Run the .exe installer.

    First-time Startup: When you launch LightProxy for the first time, you will be prompted to enter your password twice. This is required to install auxiliary programs and automatically install the necessary certificates.

  10. Use LightProxy in the command line (curl, etc.)

    master

    By default, LightProxy proxy settings only apply to browsers and Webviews. To use LightProxy with command-line tools like curl, you must configure your shell environment variables.

    You can use the "Copy Shell Script" feature provided in the LightProxy menubar to automatically copy the required proxy commands to your clipboard. After copying, paste and execute them in your terminal.

    Note: This method only affects applications that respect environment variables; it will not apply to all system applications.

  11. Install Certificate on Android

    master

    Installation steps may vary depending on your Android model, but the general process is:

    1. Scan the QR code to download the certificate.
    2. Navigate to System > Security > Trusted Credentials (授信凭据) to install the certificate.

    Note for high Android versions: High-version Android devices require applications to explicitly declare support for user certificates. You can test if the proxy is working by checking if Android Chrome successfully routes traffic through the proxy.