{"id":13481708,"url":"https://github.com/google/martian","last_synced_at":"2025-05-14T22:05:39.726Z","repository":{"id":33854686,"uuid":"37560275","full_name":"google/martian","owner":"google","description":"Martian is a library for building custom HTTP/S proxies","archived":false,"fork":false,"pushed_at":"2024-12-18T22:05:20.000Z","size":23558,"stargazers_count":2021,"open_issues_count":44,"forks_count":249,"subscribers_count":64,"default_branch":"master","last_synced_at":"2025-05-07T21:15:43.611Z","etag":null,"topics":["golang","http","middleware","proxy","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-16T22:54:05.000Z","updated_at":"2025-05-01T13:01:23.000Z","dependencies_parsed_at":"2025-01-04T12:14:48.865Z","dependency_job_id":"7d975f8b-d5fa-4d1c-8c03-6c3168fa30ea","html_url":"https://github.com/google/martian","commit_stats":{"total_commits":297,"total_committers":45,"mean_commits":6.6,"dds":0.6936026936026936,"last_synced_commit":"0f7e6797a04da412118541344bbe0d65945e24c9"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fmartian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fmartian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fmartian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fmartian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google","download_url":"https://codeload.github.com/google/martian/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254077052,"owners_count":22010649,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","http","middleware","proxy","testing"],"created_at":"2024-07-31T17:00:54.512Z","updated_at":"2025-05-14T22:05:39.686Z","avatar_url":"https://github.com/google.png","language":"Go","readme":"# Martian Proxy [![Build Status](https://travis-ci.org/google/martian.svg?branch=master)](https://travis-ci.org/google/martian)\n\nMartian Proxy is a programmable HTTP proxy designed to be used for testing.\n\nMartian is a great tool to use if you want to:\n\n* Verify that all (or some subset) of requests are secure\n* Mock external services at the network layer\n* Inject headers, modify cookies or perform other mutations of HTTP requests\n  and responses\n* Verify that pingbacks happen when you think they should\n* Unwrap encrypted traffic (requires install of CA certificate in browser)\n\nBy taking advantage of Go cross-compilation, Martian can be deployed\nanywhere that Go can target.\n\n## Latest Version\n\nv3.0.0\n\n## Requirements\n\nGo 1.11\n\n## Go Modules Support\n\nMartian Proxy added support for Go modules since v3.0.0.  If you use a Go version that does not support modules, this will break you.  The latest version without Go modules support was tagged v2.1.0.\n\n## Getting Started\n\n### Installation\nMartian Proxy can be installed using `go install`\n\n    go get github.com/google/martian/ \u0026\u0026 \\\n    go install github.com/google/martian/cmd/proxy\n\n### Start the Proxy\nAssuming you've installed Martian, running the proxy is as simple as\n\n    $GOPATH/bin/proxy\n\nIf you want to see system logs as Martian is running, pass in the verbosity\nflag:\n\n    $GOPATH/bin/proxy -v=2\n\nBy default, Martian will be running on port 8080, and the Martian API will be running on 8181\n. The port can be specified via flags:\n\n    $GOPATH/bin/proxy -addr=:9999 -api-addr=:9898\n\n### Logging\nFor logging of requests and responses a [logging\nmodifier](https://github.com/google/martian/wiki/Modifier-Reference#logging) is\navailable or [HAR](http://www.softwareishard.com/blog/har-12-spec/) logs are\navailable if the `-har` flag is used.\n\n#### HAR Logging\nTo enable HAR logging in Martian call the binary with the `-har` flag:\n\n    $GOPATH/bin/proxy -har\n\nIf the `-har` flag has been enabled two HAR related endpoints will be\navailable:\n\n    GET http://martian.proxy/logs\n\nWill retrieve the HAR log of all requests and responses seen by the proxy since\nthe last reset.\n\n    DELETE http://martian.proxy/logs/reset\n\nWill reset the in-memory HAR log. Note that the log will grow unbounded unless\nit is periodically reset.\n\n### Configure\nOnce Martian is running, you need to configure its behavior. Without\nconfiguration, Martian is just proxying without doing anything to the requests\nor responses. If enabled, logging will take place without additional\nconfiguration.\n\nMartian is configured by JSON messages sent over HTTP that take the general\nform of:\n\n    {\n      \"header.Modifier\": {\n        \"scope\": [\"response\"],\n        \"name\": \"Test-Header\",\n        \"value\": \"true\"\n      }\n    }\n\nThe above configuration tells Martian to inject a header with the name\n\"Test-Header\" and the value \"true\" on all responses.\n\nLet's break down the parts of this message.\n\n* `[package.Type]`: The package.Type of the modifier that you want to use. In\n  this case, it's \"header.Modifier\", which is the name of the modifier that\n  sets headers (to learn more about the `header.Modifier`, please\n  refer to the [modifier reference](https://github.com/google/martian/wiki/Modifier-Reference)).\n\n* `[package.Type].scope`: Indicates whether to apply to the modifier to\n  requests, responses or both. This can be an array containing \"request\",\n  \"response\", or both.\n\n* `[package.Type].[key]`: Modifier specific data. In the case of the header\n  modifier, we need the `name` and `value` of the header.\n\nThis is a simple configuration, for more complex configurations, modifiers are\ncombined with groups and filters to compose the desired behavior.\n\nTo configure Martian, `POST` the JSON to `http://martian.proxy/modifiers`. You'll\nwant to use whatever mechanism your language of choice provides you to make\nHTTP requests, but for demo purposes, curl works (assuming your configuration\nis in a file called `modifier.json`).\n\n        curl -x localhost:8080 \\\n             -X POST \\\n             -H \"Content-Type: application/json\" \\\n             -d @modifier.json \\\n                \"http://martian.proxy/configure\"\n\n### Intercepting HTTPS Requests and Responses\nMartian supports modifying HTTPS requests and responses if configured to do so.\n\nIn order for Martian to intercept HTTPS traffic a custom CA certificate must be\ninstalled in the browser so that connection warnings are not shown.\n\nThe easiest way to install the CA certificate is to start the proxy with the\nnecessary flags to use a custom CA certificate and private key using the `-cert`\nand `-key` flags, or to have the proxy generate one using the `-generate-ca-cert`\nflag.\n\nAfter the proxy has started, visit http://martian.proxy/authority.cer in the\nbrowser configured to use the proxy and a prompt will be displayed to install\nthe certificate.\n\nSeveral flags are available in `examples/main.go` to help configure MITM\nfunctionality:\n\n    -key=\"\"\n      PEM encoded private key file of the CA certificate provided in -cert; used\n      to sign certificates that are generated on-the-fly\n    -cert=\"\"\n      PEM encoded CA certificate file used to generate certificates\n    -generate-ca-cert=false\n      generates a CA certificate and private key to use for man-in-the-middle;\n      most users choosing this option will immediately visit\n      http://martian.proxy/authority.cer in the browser whose traffic is to be\n      intercepted to install the newly generated CA certificate\n    -organization=\"Martian Proxy\"\n      organization name set on the dynamically-generated certificates during\n      man-in-the-middle\n    -validity=\"1h\"\n      window of time around the time of request that the dynamically-generated\n      certificate is valid for; the duration is set such that the total valid\n      timeframe is double the value of validity (1h before \u0026 1h after)\n\n### Check Verifiers\nLet's assume that you've configured Martian to verify the presence a specific\nheader in responses to a specific URL.\n\nHere's a configuration to verify that all requests to `example.com` return\nresponses with a `200 OK`.\n\n          {\n            \"url.Filter\": {\n              \"scope\": [\"request\", \"response\"],\n              \"host\" : \"example.com\",\n              \"modifier\" : {\n                \"status.Verifier\": {\n                  \"scope\" : [\"response\"],\n                  \"statusCode\": 200\n                }\n              }\n            }\n          }\n\nOnce Martian is running, configured and the requests and resultant responses you\nwish to verify have taken place, you can verify your expectation that you only\ngot back `200 OK` responses.\n\nTo check verifications, perform\n\n    GET http://martian.proxy/verify\n\nFailed expectations are tracked as errors, and the list of errors are retrieved\nby making a `GET` request to `host:port/martian/verify`, which will return\na list of errors:\n\n      {\n          \"errors\" : [\n              {\n                  \"message\": \"response(http://example.com) status code verify failure: got 500, want 200\"\n              },\n              {\n                  \"message\": \"response(http://example.com/foo) status code verify failure: got 500, want 200\"\n              }\n          ]\n      }\n\nVerification errors are held in memory until they are explicitly cleared by\n\n    POST http://martian.proxy/verify/reset\n\n## Martian as a Library\nMartian can also be included into any Go program and used as a library.\n\n## Modifiers All The Way Down\nMartian's request and response modification system is designed to be general\nand extensible. The design objective is to provide individual modifier\nbehaviors that can arranged to build out nearly any desired modification.\n\nWhen working with Martian to compose behaviors, you'll need to be familiar with\nthese different types of interactions:\n\n* Modifiers: Changes the state of a request or a response\n* Filters: Conditionally allows a contained Modifier to execute\n* Groups: Bundles multiple modifiers to be executed in the order specified in\n  the group\n* Verifiers: Tracks network traffic against expectations\n\nModifiers, filters and groups all implement `RequestModifier`,\n`ResponseModifier` or `RequestResponseModifier` (defined in\n[`martian.go`](https://github.com/google/martian/blob/master/martian.go)).\n\n```go\nModifyRequest(req *http.Request) error\n\nModifyResponse(res *http.Response) error\n```\n\nThroughout the code (and this documentation) you'll see the word \"modifier\"\nused as a term that encompasses modifiers, groups and filters. Even though a\ngroup does not modify a request or response, we still refer to it as a\n\"modifier\".\n\nWe refer to anything that implements the `modifier` interface as a Modifier.\n\n### Parser Registration\nEach modifier must register its own parser with Martian. The parser is\nresponsible for parsing a JSON message into a Go struct that implements a\nmodifier interface.\n\nMartian holds modifier parsers as a map of strings to functions that is built\nout at run-time. Each modifier is responsible for registering its parser with a\ncall to `parse.Register` in `init()`.\n\nSignature of parse.Register:\n\n```go\nRegister(name string, parseFunc func(b []byte) (interface{}, error))\n```\n\nRegister takes in the key as a string in the form `package.Type`. For\ninstance, `cookie_modifier` registers itself with the key `cookie.Modifier` and\n`query_string_filter` registers itself as `querystring.Filter`. This string is\nthe same as the value of `name` in the JSON configuration message.\n\nIn the following configuration message, `header.Modifier` is how the header\nmodifier is registered in the `init()` of `header_modifier.go`.\n\n    {\n      \"header.Modifier\": {\n        \"scope\": [\"response\"],\n        \"name\" : \"Test-Header\",\n        \"value\" : \"true\"\n      }\n    }\n\nExample of parser registration from `header_modifier.go`:\n\n```go\nfunc init() {\n  parse.Register(\"header.Modifier\", modifierFromJSON)\n}\n\nfunc modifierFromJSON(b []byte) (interface{}, error) {\n  ...\n}\n```\n\n### Adding Your Own Modifier\nIf you have a use-case in mind that we have not developed modifiers, filters or\nverifiers for, you can easily extend Martian to your very specific needs.\n\nThere are 2 mandatory parts of a modifier:\n\n* Implement the modifier interface\n* Register the parser\n\nAny Go struct that implements those interfaces can act as a `modifier`.\n\n## Contact\nFor questions and comments on how to use Martian, features announcements, or\ndesign discussions check out our public Google Group at\nhttps://groups.google.com/forum/#!forum/martianproxy-users.\n\nFor security related issues please send a detailed report to our private core\ngroup at martianproxy-core@googlegroups.com.\n\n## Disclaimer\nThis is not an official Google product (experimental or otherwise), it is just\ncode that happens to be owned by Google.\n","funding_links":[],"categories":["Go","\u003ca id=\"9eee96404f868f372a6cbc6769ccb7f8\"\u003e\u003c/a\u003e新添加的","\u003ca id=\"d03d494700077f6a65092985c06bf8e8\"\u003e\u003c/a\u003e工具","testing"],"sub_categories":["\u003ca id=\"31185b925d5152c7469b963809ceb22d\"\u003e\u003c/a\u003e新添加的","\u003ca id=\"0ff94312f3ab4898f5996725133ea9d1\"\u003e\u003c/a\u003e未分类"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fmartian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle%2Fmartian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fmartian/lists"}