Neutral Point Measurement

    allproxy

    2.14.8 • Public • Published

    AllProxy: MITM HTTP Debugging Tool

    AllProxy is a free HTTP debugging proxy that enables a developer to view and modify all of the HTTP and HTTPS (SSL) traffic between their machine and the Internet. It is an open-source alternative to the popular Charles and Fiddler developer tools.

    Setup:

    1. Install and start: npm install -g allproxy && allproxy-ca && allproxy
    2. Open browser to: localhost:8888
    3. Configure browser to proxy HTTP and HTTPS to localhost:8888.
    4. In terminal, export HTTPS_PROXY=localhost:8888 and HTTP_PROXY=localhost:8888.

    Additional Features: Capture MySQL, gRPC, MongoDB, Redis, Memcached, TCP, and log messages.

    npm npm

    image image image

    image

    AllProxy Dashboard image

    Using Dark Reader Plugin image

    Features:

    • captures HTTP and/or HTTPS messages as either a forward or reverse proxy
    • captures SQL, MongoDB, Redis, gRPC, and other protocol messages sent to backend services
    • captures log messages from dockers logs
    • modify and resend HTTP requests
    • add breakpoints to modify HTTP responses
    • search entire request/response message for matching text
    • stop/start recording
    • take snapshots of captured messages
    • export and import captured messages
    • supports multiple dashboard browser tabs
    • HTTP/2 support

    image image image image image

    Table of Contents

    Quick Start

    Node Version

    Version 10 or higher is required. Use nvm to install the appropriate node version.

    Install AllProxy

    The AllProxy may be install from either NPM or GitHub.

    Install From NPM

    $ npm install -g allproxy

    Install From GitHub Project

    $ cd ~/git/allproxy
    allproxy$ npm install

    Start the AllProxy Server

    The AllProxy server is started using either the NPM installed allproxy script or using npm start, depending on how it was installed.

    Start NPM Package

    $ allproxy
    
      Listening on http:  8888
      Open browser to http://localhost:8888/allproxy

    Start GitHub Project

    allproxy$ npm start
    
     Listening on http:  8888
     Open browser to http://localhost:8888/allproxy

    Install CA Certificate

    The allproxy-ca can be used to install the CA certificate so it is trusted by your browser.

    The ca.pem location:

    • GitHub Project: ~/git/allproxy/ca.pem # assuming the allproxy project was cloned to ~/git/
    • NPM Package: ~/allproxy/ca.pem

    If you need to manually install the AllProxy ca.pem. These online tutorials many help:

    NPM Package

    $ allproxy-ca

    GitHub Project

    $ cd ~/git/allproxy/bin
    bin$ ./allproxy-ca

    Open Dashboard in Browser

    Enter http://localhost:8888/allproxy in browser.

    Configure Proxy

    Chrome will also honor the system proxy configuration for MacOS. The allproxy-system-proxy command can be used to configure the system proxy.

    NPM Package

    $ cd ~/git/allproxy
    allproxy$ allproxy-system-proxy enable

    GitHub Project

    $ allproxy-system-proxy enable

    Terminal

    To capture http/https messages initiated by terminal commands, set the https_proxy and http_proxy environment variables.

    $ export https_proxy=localhost:8888
    $ export http_proxy=localhost:8888

    Firefox Proxy Configuration

    To capture HTTP and HTTPS messages, configure your browser to proxy HTTP/HTTPS messages to the AllProxy. The default is to proxy both HTTP and HTTPS messages to port 8888. This is how Firefox can be configured to proxy HTTP and HTTPS messages. image

    Linux Proxy Configuration

    For chrome and chromium you can set the browser proxy using environment variables http_proxy and https_proxy.

    $ http_proxy=http://localhost:8888 https_proxy://8888 chromium-browser

    Screenshots

    Dashboard

    image

    Settings

    image

    Reachable Hosts

    image

    Configuration

    This section gives example on how to configure the AllProxy. Clicking the settings icon in the upper right corner opens the Setting modal.

    HTTP/HTTPS Proxy

    Both a forward and reverse proxy is supported for HTTP/HTTPS messages. Your browser must be configured to proxy HTTP/HTTPS messages to the forward proxy. See Configure Browser Proxy for more information on configuring your browser.

    The reverse proxy can be used to transparently capture HTTP/HTTPS messages sent by backend services. The backend service is configured to send the HTTP/HTTPS messages to the AllProxy. For example, a -search- microservice could be configured to send Elasticsearch messages to the AllProxy by setting environment variables.

    Example -search- microservice configuration:

    ELASTIC_HOST=elasticsearch
    ELASTIC_PORT=9200

    Modified -search- micorservice configuration:

    ELASTIC_HOST=allproxy   # allproxy is the docker container host name
    ELASTIC_PORT=8888       # allproxy HTTP port is 8888.

    An HTTP path is added to proxy HTTP requests to the elasticsearch host. All HTTP requests matching path /_search are proxied to the elasticsearch host on port 9200. image

    HTTP/2 Support

    You can use HTTP/2 to connect to HTTP/2 enabled servers (e.g., duckduckgo.com). To enable HTTP/2: ```sh $ allproxy --http2 ```

    MySQL Proxy

    The SQL proxy can transparently capture SQL messages sent by backend microservices to a MySQL server.

    Example microservice config file:

    MYSQL_HOST=mysql
    MYSQL_PORT=3306

    Modified microservice config file:

    MYSQL_HOST=allproxy    # Proxy queries to the AllProxy
    MYSQL_PORT=3306

    The AllProxy is configured to proxy MySQL requests to the MySQL server: image

    gRPC Proxy

    The gRPC proxy can transparently capture gRPC HTTP/2 messages sent to backend microservices. Only unsecure connections are supported. Secure TLS support may be added in the future.

    Example gRPC microservice config file:

    GRPC_HOST=grpchost    # gRPC host name
    GRPC_PORT=12345       # gRPC port number

    Modified gRPC microservice config file:

    GRPC_HOST=allproxy    # Proxy gRPC requests to the AllProxy
    GRPC_PORT=12345

    Proto Files

    Proto files can be added to the proto/ directory so that the AllProxy tool can decode the binary data, and make it readable. AllProxy currently only supports GRPC URLs of the form //. (e.g., /mypackage/mMService/MyFunc).

    The AllProxy is configured to proxy gRPC requests to a microservice: image

    MongoDB Proxy

    The MongoDB proxy can transparently capture MongoDB messages sent by backend microservices.

    Example MongoDB microservice config file:

    MONGO_HOST=mongodb     # MongoDB host name
    MONGO_PORT=27017       # MongoDB port number

    Modified MongoDB microservice config file:

    MONGO_HOST=allproxy    # Proxy MongoDB requests to the AllProxy
    MONGO_PORT=27017

    The AllProxy is configured to proxy MongoDB requests to a microservice: image

    Redis Proxy

    The Redis proxy can transparently capture Redis messages sent by backend microservices.

    Example Redis microservice config file:

    REDIS_HOST=redis    # Redis host name
    REDIS_PORT=6379     # Redis port number

    Modified Redis microservice config file:

    REDIS_HOST=allproxy    # Proxy Redis requests to the AllProxy
    REDIS_PORT=6379

    The AllProxy is configured to proxy Redis requests to a microservice: image

    TCP Proxy

    The TCP proxy can transparently capture TCP request/response messages sent by backend microservices. For example, the TCP proxy can be used to capture memcached messages.

    Example Memcached microservice config file:

    MEMCACHED_HOST=memcached    # Memcached host name
    MEMCACHED_PORT=11211        # Memcached port number

    Modified Memcached microservice config file:

    MEMCACHED_HOST=allproxy    # Proxy Memcached requests to the AllProxy
    MEMCACHED_PORT=11211

    The AllProxy is configured to proxy Memcached requests to a microservice: image

    Dockers Logs

    The Docker log proxy can capture log messages.

    The AllProxy is configured to capture Dockers log messages: image

    Dashboard

    The AllProxy dashboard is stated from the browser with URL http://localhost:8888/allproxy.

    Pause Recording

    The recording of messages can be temporarily stopped, to allow time to examine the messages without the log wrapping.

    Filter Messages

    Filtering allows you to find messages matching a search filter, and hide other messages. The entire message is search for a match. The filter may be case insensitive, case sensitive, a logical expression, or a regular expression.

    Types of filters:

    • case insensitive - If Aa is not selected, a case insensitive search is performed.
    • case ensensitive - If Aa is selected, a case sensitive search is performed.
    • logical expression - If && is selected, &&, ||, (), and ! operators may be used to build a logical expression.
    • regular expression - If .* is selected, regular expression match in performed.

    Boolean filters can use &&, ||, !, and parenthesis.

    Resend HTTP Requests

    To resend an HTTP or HTTPS request, click on the icon next to the request to open a modal. Optionally modify the request body, and then click the send button. If the dashboard is not paused, the resent request should appear at the bottom of the dashboard request log.

    Breakpoint to Modify HTTPS Responses

    Breakpoints can be set to match any part of the HTTP request or response, and then modify the JSON response then the breakpoint matches.

    Click Settings->Breakpoints: breakpoint

    In this example a breakpoint is set to match on URL https://us-south-stage01.iaasdev.cloud.ibm.com/v1/vpcs. image

    When a request URL matches https://us-south-stage01.iaasdev.cloud.ibm.com/v1/vpcs, a model pops up to allow the JSON response body to be edited. The response JSON body can be edited, and Ok clicked to forward the response back to the client. image

    Modify HTTPS JSON Responses

    Custom JavaScript code may be provided to modify any JSON response. Add your custom code to the InterceptJsonResponse() function is called for every JSON response, and can be modified to customize the JSON response body. Edit the **intercept/InterceptResponse.js file as needed.

    $ vi intercept/InterceptResponse.js

    Example:

    module.exports = function InterceptJsonResponse(clientReq, json) {
        const reqUrl = url.parse(clientReq.url);
        const path = reqUrl.pathname;
        const query = reqUrl.query;
    
        /**
         * Add your code here to modify the JSON response body
         */
        if (path === '/aaa/bbb') {
          json.addMyField = 1;
          return json; // return modified JSON response body
        }
    
        return null; // do not modify JSON response body
    }

    Snapshots

    Clicking on the camera icon will take a snapshot of the currently captured messages, and create a new snapshot tab. A snapshot tab may be exported to a file, and later imported again.

    Multiple Browser Tabs

    Multiple Dashboard instances can be opened in separate browser tabs, and all of the open Dashboards will record messages.

    Each Dashboard instance keeps its own copy of the messages, so clearing or stopping recording in one Dashboard instance, does not affect another other Dashboard instances.

    Certificates

    Certificates are managed by the node-http-mitm-proxy package.

    Generated certificates are stored in allproxy/.http-mitm-proxy/certs/. Import allproxy/ca.pem to your browser to trust all AllProxy generated certificates.

    The allproxy-ca script can be used to install the CA certificate on MacOS and Linux.

    For Windows, execute the allproxy-ca script to get the path of the CA certificate, and manually import it to your browser.

    Implementation:

    • HTTP proxy - The http package is used to proxy HTTP traffic as either a forward or reverse proxy.
    • HTTPS proxy - The node-http-mitm-proxy package is used to build certificates to capture decrypted HTTPS traffic as either a forward or reverse proxy.
    • TCP proxy - The net package is used to listen on a TCP port for non-HTTP messages, and proxy the protocol messages to the target host.
    • Socket.IO - The node socket.io package is used to pass messages between the server and browser where they are recorded and displayed in a dashboard.
    • stdout/stderr - Spawn a child process to read stdout and stderr from any docker log or log file, and display the log messages in the dashboard.

    Configuration File

    • When running from a GitHub package, config.json file is stored in the root directory of your GitHub project.
    • When running from an NPM package (allproxy script), the config.json file is stored your home directory at $HOME/allconfig/config.json.

    Command Line Parameters

    Usage: allproxy [--listen [host:]port] [--listenHttps [host:]port]
    
    Options:
    	--listen - listen for incoming http connections.  Default is 8888.
    	--listenHttps - listen for incoming https connections.
    
    Example: allproxy --listen 8888

    Limitations

    1. Only HTTP/2 reverse proxy is supported. HTTP/2 forward proxy is not supported.

    License

    This code is licensed under the MIT License.

    image image image

    Install

    npm i allproxy

    DownloadsWeekly Downloads

    495

    Version

    2.14.8

    License

    MIT

    Unpacked Size

    7.95 MB

    Total Files

    135

    Last publish

    Collaborators

    • davechri