github.com/coreos/goproxy@v0.0.0-20190513173959-f8dc2d7ba04e/README.md (about)

     1  # Introduction
     2  
     3  [![GoDoc](https://godoc.org/github.com/elazarl/goproxy?status.svg)](https://godoc.org/github.com/elazarl/goproxy)
     4  [![Join the chat at https://gitter.im/elazarl/goproxy](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/elazarl/goproxy?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
     5  
     6  Package goproxy provides a customizable HTTP proxy library for Go (golang),
     7  
     8  It supports regular HTTP proxy, HTTPS through CONNECT, and "hijacking" HTTPS
     9  connection using "Man in the Middle" style attack.
    10  
    11  The intent of the proxy, is to be usable with reasonable amount of traffic
    12  yet, customizable and programable.
    13  
    14  The proxy itself is simply a `net/http` handler.
    15  
    16  In order to use goproxy, one should set their browser to use goproxy as an HTTP
    17  proxy. Here is how you do that [in Chrome](https://support.google.com/chrome/answer/96815?hl=en)
    18  and [in Firefox](http://www.wikihow.com/Enter-Proxy-Settings-in-Firefox).
    19  
    20  For example, the URL you should use as proxy when running `./bin/basic` is
    21  `localhost:8080`, as this is the default binding for the basic proxy.
    22  
    23  ## Mailing List
    24  
    25  New features would be discussed on the [mailing list](https://groups.google.com/forum/#!forum/goproxy-dev)
    26  before their development.
    27  
    28  ## Latest Stable Release
    29  
    30  Get the latest goproxy from `gopkg.in/elazarl/goproxy.v1`.
    31  
    32  # Why not Fiddler2?
    33  
    34  Fiddler is an excellent software with similar intent. However, Fiddler is not
    35  as customable as goproxy intend to be. The main difference is, Fiddler is not
    36  intended to be used as a real proxy.
    37  
    38  A possible use case that suits goproxy but
    39  not Fiddler, is, gathering statisitics on page load times for a certain website over a week.
    40  With goproxy you could ask all your users to set their proxy to a dedicated machine running a
    41  goproxy server. Fiddler is a GUI app not designed to be ran like a server for multiple users.
    42  
    43  # A taste of goproxy
    44  
    45  To get a taste of `goproxy`, a basic HTTP/HTTPS transparent proxy
    46  
    47  
    48      package main
    49  
    50      import (
    51          "github.com/elazarl/goproxy"
    52          "log"
    53          "net/http"
    54      )
    55  
    56      func main() {
    57          proxy := goproxy.NewProxyHttpServer()
    58          proxy.Verbose = true
    59          log.Fatal(http.ListenAndServe(":8080", proxy))
    60      }
    61  
    62  
    63  This line will add `X-GoProxy: yxorPoG-X` header to all requests sent through the proxy
    64  
    65      proxy.OnRequest().DoFunc(
    66          func(r *http.Request,ctx *goproxy.ProxyCtx)(*http.Request,*http.Response) {
    67              r.Header.Set("X-GoProxy","yxorPoG-X")
    68              return r,nil
    69          })
    70  
    71  `DoFunc` will process all incoming requests to the proxy. It will add a header to the request
    72  and return it. The proxy will send the modified request.
    73  
    74  Note that we returned nil value as the response. Have we returned a response, goproxy would
    75  have discarded the request and sent the new response to the client.
    76  
    77  In order to refuse connections to reddit at work time
    78  
    79      proxy.OnRequest(goproxy.DstHostIs("www.reddit.com")).DoFunc(
    80          func(r *http.Request,ctx *goproxy.ProxyCtx)(*http.Request,*http.Response) {
    81              if h,_,_ := time.Now().Clock(); h >= 8 && h <= 17 {
    82                  return r,goproxy.NewResponse(r,
    83                          goproxy.ContentTypeText,http.StatusForbidden,
    84                          "Don't waste your time!")
    85              }
    86              return r,nil
    87      })
    88  
    89  `DstHostIs` returns a `ReqCondition`, that is a function receiving a `Request` and returning a boolean
    90  we will only process requests that matches the condition. `DstHostIs("www.reddit.com")` will return
    91  a `ReqCondition` accepting only requests directed to "www.reddit.com".
    92  
    93  `DoFunc` will recieve a function that will preprocess the request. We can change the request, or
    94  return a response. If the time is between 8:00am and 17:00pm, we will neglect the request, and
    95  return a precanned text response saying "do not waste your time".
    96  
    97  See additional examples in the examples directory.
    98  
    99  # What's New
   100  
   101    1. Ability to `Hijack` CONNECT requests. See
   102  [the eavesdropper example](https://github.com/elazarl/goproxy/blob/master/examples/goproxy-eavesdropper/main.go#L27)
   103  2.  Transparent proxy support for http/https including MITM certificate generation for TLS.  See the [transparent example.](https://github.com/elazarl/goproxy/tree/master/examples/goproxy-transparent)
   104  
   105  # License
   106  
   107  I put the software temporarily under the Go-compatible BSD license,
   108  if this prevents someone from using the software, do let mee know and I'll consider changing it.
   109  
   110  At any rate, user feedback is very important for me, so I'll be delighted to know if you're using this package.
   111  
   112  # Beta Software
   113  
   114  I've received a positive feedback from a few people who use goproxy in production settings.
   115  I believe it is good enough for usage.
   116  
   117  I'll try to keep reasonable backwards compatability. In case of a major API change,
   118  I'll change the import path.