proxy

Documentation

Overview

proxy is an HTTP/S proxy configurable via an HTTP API.

It can be dynamically configured/queried at runtime by issuing requests to proxy specific paths using JSON.

Supported configuration endpoints:

POST http://martian.proxy/configure

sets the request and response modifier of the proxy; modifiers adhere to the following top-level JSON structure:

{
  "package.Modifier": {
    "scope": ["request", "response"],
    "attribute 1": "value",
    "attribute 2": "value"
  }
}

modifiers may be "stacked" to provide support for additional behaviors; for example, to add a "Martian-Test" header with the value "true" for requests with the domain "www.example.com" the JSON message would be:

{
  "url.Filter": {
    "scope": ["request"],
    "host": "www.example.com",
    "modifier": {
      "header.Modifier": {
        "name": "Martian-Test",
        "value": "true"
      }
    }
  }
}

url.Filter parses the JSON object in the value of the "url.Filter" attribute; the "host" key tells the url.Filter to filter requests if the host explicitly matches "www.example.com"

the "modifier" key within the "url.Filter" JSON object contains another modifier message of the type header.Modifier to run iff the filter passes

groups may also be used to run multiple modifiers sequentially; for example to log requests and responses after adding the "Martian-Test" header to the request, but only when the host matches www.example.com:

{
  "url.Filter": {
    "host": "www.example.com",
    "modifier": {
      "fifo.Group": {
        "modifiers": [
          {
            "header.Modifier": {
              "scope": ["request"],
              "name": "Martian-Test",
              "value": "true"
            }
          },
          {
            "log.Logger": { }
          }
        ]
      }
    }
  }
}

modifiers are designed to be composed together in ways that allow the user to write a single JSON structure to accomplish a variety of functionality

GET http://martian.proxy/verify

retrieves the verifications errors as JSON with the following structure:

{
  "errors": [
    {
      "message": "request(url) verification failure"
    },
    {
      "message": "response(url) verification failure"
    }
  ]
}

verifiers also adhere to the modifier interface and thus can be included in the modifier configuration request; for example, to verify that all requests to "www.example.com" are sent over HTTPS send the following JSON to the configuration endpoint:

{
  "url.Filter": {
    "scope": ["request"],
    "host": "www.example.com",
    "modifier": {
      "url.Verifier": {
        "scope": ["request"],
        "scheme": "https"
      }
    }
  }
}

sending a request to "http://martian.proxy/verify" will then return errors from the url.Verifier

POST http://martian.proxy/verify/reset

resets the verifiers to their initial state; note some verifiers may start in a failure state (e.g., pingback.Verifier is failed if no requests have been seen by the proxy)

GET http://martian.proxy/authority.cer

prompts the user to install the CA certificate used by the proxy if MITM is enabled

passing the -cors flag will enable CORS support for the endpoints so that they may be called via AJAX

The flags are:

-addr=":8080"
  host:port of the proxy
-api="martian.proxy"
  hostname that can be used to reference the configuration API when
  configuring through the proxy
-cert=""
  PEM encoded X.509 CA certificate; if set, it will be set as the
  issuer for dynamically-generated certificates during man-in-the-middle
-key=""
  PEM encoded private key of cert (RSA or ECDSA); if set, the key will be used
  to sign dynamically-generated certificates during man-in-the-middle
-generate-ca-cert=false
  generates a CA certificate and private key to use for man-in-the-middle;
  the certificate is only valid while the proxy is running and will be
  discarded on shutdown
-organization="Martian Proxy"
  organization name set on the dynamically-generated certificates during
  man-in-the-middle
-validity="1h"
  window of time around the time of request that the dynamically-generated
  certificate is valid for; the duration is set such that the total valid
  timeframe is double the value of validity (1h before & 1h after)
-cors=false
  allow the proxy to be configured via CORS requests; such as when
  configuring the proxy via AJAX