Build Status Published Version

21.09.2019 - Frank Ganske, about this abandoned repository and new versions

Unfortunately I've lost my PGP private key for uploading Maven artifacts to the Central Repository. So version 1.1.0 will be the last I think.

LittleProxy - Man-In-The-Middle

LittleProxy-mitm is an extension for LittleProxy which provides all the filter capabilities of LittleProxy with HTTPS sites too. It aims to support every Java platform including Android. To answer HTTPS while offline for caching purposes consider to use ganskef/LittleProxy-parent. See Aldo Cortesi for a detailed description of proxy interception processes.

Get it up and running

Java is required to be installed on the system, then execute this commands:

$ java -jar littleproxy-mitm-1.1.0-shade.jar
$ curl --cacert littleproxy-mitm.pem --verbose --proxy localhost:9090 https://github.com/

The first run creates the key store for your Certificate Authority. It's used to generate server certificates on the fly. The littleproxy-mitm.pem file have to be imported in your browser or within the systems certificates, Mozilla for example:

You have to set your browsers proxy settings to 9090. It's hard coded in the simple Launcher class. You may chose an other implementation, of course.

Important Security Note

Please use your browser directly for every security-critical transmission. Mozilla Firefox and Google Chrome implements her own certificate handling for a reason. Handling security in Java like here must be less secure in most situations. See http://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf "The Most Dangerous Code in the World: Validating SSL Certificates in Non-Browser Software".

Getting the library

Add this dependency to your Maven build:

<dependency>
   <groupId>com.github.ganskef</groupId>
   <artifactId>littleproxy-mitm</artifactId>
   <version>1.1.0</version>
</dependency>

The version corresponds to LittleProxy since the intention was to integrate it as a module.

Wiring everything together

Once you've included LittleProxy-mitm, you can start the server with the following:

HttpProxyServer server =
    DefaultHttpProxyServer.bootstrap()
        .withPort(9090) // for both HTTP and HTTPS
        .withManInTheMiddle(new CertificateSniffingMitmManager())
        .start();

Please give an Authority in the constructor to personalize your application. You impersonate certificates which is normally a bad thing. You have to describe the reason for.

Please refer to the documentation of LittleProxy and Netty especially the Javadoc of org.littleshoot.proxy.HttpFiltersSource, org.littleshoot.proxy.HttpFilters and io.netty.channel.ChannelPipeline to filter HTTP/S contents. FAQ: #25, #32

Resolving URI in case of HTTPS

Mostly you will need an URL to handle content in your filters. With HTTP it's provided by originalRequest.getUri(), but with HTTPS you have to get the host name from the initiating CONNECT request. Therefore you have to do something like this in your HttpFiltersSource implementation:

    private static final AttributeKey<String> CONNECTED_URL = AttributeKey.valueOf("connected_url");

    @Override
    public HttpFilters filterRequest(HttpRequest originalRequest, ChannelHandlerContext clientCtx) {
        String uri = originalRequest.getUri();
        if (originalRequest.getMethod() == HttpMethod.CONNECT) {
            if (clientCtx != null) {
                String prefix = "https://" + uri.replaceFirst(":443$", "");
                clientCtx.channel().attr(CONNECTED_URL).set(prefix);
            }
            return new HttpFiltersAdapter(originalRequest, clientCtx);
        }
        String connectedUrl = clientCtx.channel().attr(CONNECTED_URL).get();
        if (connectedUrl == null) {
            return new MyHttpFilters(uri);
        }
        return new MyHttpFilters(connectedUrl + uri);
    }

Workarounds for Known Problems

FAQ - Answered Questions

Issues labeled with question which could be interesting for you too.