stoplightio/goproxy

An HTTP proxy library for Go

Introduction

NOTICE: this is a fork of the original elazarl/goproxy with some radical API changes. - abourget

Package goproxy provides a customizable HTTP proxy library for Go (golang),

It supports regular HTTP proxy, HTTPS through CONNECT, "hijacking" HTTPS connection using "Man in the Middle" style attack, and SNI sniffing.

The intent of the proxy, is to be usable with reasonable amount of traffic yet, customizable and programable.

The proxy itself is simply a net/http handler.

In order to use goproxy, one should set his browser to use goproxy as an HTTP proxy. Here is how you do that in Chrome and in Firefox.

For example, the URL you should use as proxy when running ./bin/basic is localhost:8080, as this is the default binding for the basic proxy.

Mailing List

New features would be discussed on the mailing list before their development.

Latest Stable Release

Get the latest goproxy from gopkg.in/elazarl/goproxy.v1.

Why not Fiddler2?

Fiddler is an excellent software with similar intent. However, Fiddler is not as customable as goproxy intend to be. The main difference is, Fiddler is not intended to be used as a real proxy.

A possible use case that suits goproxy but not Fiddler, is, gathering statisitics on page load times for a certain website over a week. With goproxy you could ask all your users to set their proxy to a dedicated machine running a goproxy server. Fiddler is a GUI app not designed to be ran like a server for multiple users.

A taste of goproxy

To get a taste of goproxy, a basic HTTP/HTTPS transparent proxy

import (
    "github.com/elazarl/goproxy"
    "log"
    "net/http"
)

func main() {
    proxy := goproxy.NewProxyHttpServer()
    proxy.Verbose = true
    log.Fatal(proxy.ListenAndServe(":8080"))
}

This line will add X-GoProxy: yxorPoG-X header to all requests sent through the proxy

proxy.HandleRequestFunc(func(ctx *goproxy.ProxyCtx) goproxy.Next {
    ctx.Req.Header.Set("X-GoProxy","yxorPoG-X")
    return goproxy.NEXT  // continue on with next handlers
    // or, return goproxy.FORWARD  // to short circuit other handlers, and continue on with forwarding
})

Here is a more complex/complete example:

proxy.HandleConnectFunc(func(ctx *goproxy.ProxyCtx) goproxy.Next {
    if ctx.SNIHost() == "secure.example.com:443" {
        return goproxy.MITM
    }
    return goproxy.REJECT
})
proxy.HandleRequestFunc(func(ctx *goproxy.ProxyCtx) goproxy.Next {
    if ctx.IsThroughMITM {
        ctx.Req.Header.Set("X-Snooped-On", "absolutely")
    }
    return goproxy.NEXT  // continue on with next handlers
    // or, return goproxy.FORWARD  // to short circuit other handlers, and continue on with forwarding
})

By setting Request Handlers, you can set a response directly and have it short-circuit the proxying to a remote server:

proxy.HandleRequestFunc(func(ctx *goproxy.ProxyCtx) goproxy.Next {
    if ctx.URL.Path == "/super/bob" {
        //ctx.NewResponse(...)
        //ctx.NewHTMLResponse("<strong>welcome home</strong>")
        ctx.NewTextResponse("welcome home")
    }
    return goproxy.FORWARD
})

See additional examples in the examples directory.

What's New

1. Major overhaul of API. Pretty much everything will break if you merely try this version.

2. Ability to do optional SNI sniffing, and take action based on that information.

3. Ability to FakeDestinationDNS() and SetDestinationHost().. to redirect requests.

4. Ability to save network flows in .har format. See http://www.softwareishard.com/har/viewer/ and view with this tool: http://ericduran.github.io/chromeHAR/

5. Ability to Hijack CONNECT requests. See the eavesdropper example

6. Transparent proxy support for http/https including MITM certificate generation for TLS. See the transparent example.

License

I put the software temporarily under the Go-compatible BSD license, if this prevents someone from using the software, do let mee know and I'll consider changing it.

At any rate, user feedback is very important for me, so I'll be delighted to know if you're using this package.

Beta Software

I've received a positive feedback from a few people who use goproxy in production settings. I believe it is good enough for usage.

I'll try to keep reasonable backwards compatability. In case of a major API change, I'll change the import path.