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
GET http://martian.proxy/logs
retrieves the HAR logs for all requests and responses seen by the proxy if the HAR flag is enabled
DELETE http://martian.proxy/logs/reset
reset the in-memory HAR log; note that the log will grow unbounded unless it is periodically reset
passing the -cors flag will enable CORS support for the endpoints so that they may be called via AJAX
Sending a sigint will cause the proxy to stop receiving new connections, finish processing any inflight requests, and close existing connections without reading anymore requests from them.
The flags are:
-addr=":8080" host:port of the proxy -api-addr=":8181" host:port of the proxy API -tls-addr=":4443" host:port of the proxy over TLS -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 -har=false enable logging endpoints for retrieving full request/response logs in HAR format. -traffic-shaping=false enable traffic shaping endpoints for simulating latency and constrained bandwidth conditions (e.g. mobile, exotic network infrastructure, the 90's) -skip-tls-verify=false skip TLS server verification; insecure and intended for testing only -v=0 log level for console logs; defaults to error only.