{"id":17099574,"url":"https://github.com/zu1k/good-mitm","last_synced_at":"2025-05-15T13:07:32.336Z","repository":{"id":37046591,"uuid":"406197199","full_name":"zu1k/Good-MITM","owner":"zu1k","description":"Rule-based MITM engine. Rewriting, redirecting and rejecting on HTTP(S) requests and responses, supports JavaScript rule.","archived":false,"fork":false,"pushed_at":"2023-08-22T18:09:41.000Z","size":453,"stargazers_count":832,"open_issues_count":6,"forks_count":106,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-13T12:16:01.293Z","etag":null,"topics":["mitm","proxy","rewrite","rust"],"latest_commit_sha":null,"homepage":"https://good-mitm.zu1k.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zu1k.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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},"funding":{"github":null,"custom":["https://zu1k.com/donate/"]}},"created_at":"2021-09-14T02:27:25.000Z","updated_at":"2025-04-19T11:58:30.000Z","dependencies_parsed_at":"2024-10-29T20:51:49.535Z","dependency_job_id":null,"html_url":"https://github.com/zu1k/Good-MITM","commit_stats":{"total_commits":151,"total_committers":6,"mean_commits":"25.166666666666668","dds":0.3377483443708609,"last_synced_commit":"55920e86f0322771ceb8930efc1348f922a8dcfc"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zu1k%2FGood-MITM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zu1k%2FGood-MITM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zu1k%2FGood-MITM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zu1k%2FGood-MITM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zu1k","download_url":"https://codeload.github.com/zu1k/Good-MITM/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"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":["mitm","proxy","rewrite","rust"],"created_at":"2024-10-14T15:10:50.690Z","updated_at":"2025-05-15T13:07:27.320Z","avatar_url":"https://github.com/zu1k.png","language":"Rust","funding_links":["https://zu1k.com/donate/"],"categories":[],"sub_categories":[],"readme":"# Good Man in the Middle\n\n[![GitHub stars](https://img.shields.io/github/stars/zu1k/good-mitm)](https://github.com/zu1k/good-mitm/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/zu1k/good-mitm)](https://github.com/zu1k/good-mitm/network)\n[![Release](https://img.shields.io/github/release/zu1k/good-mitm)](https://github.com/zu1k/good-mitm/releases)\n[![GitHub issues](https://img.shields.io/github/issues/zu1k/good-mitm)](https://github.com/zu1k/good-mitm/issues)\n[![Build](https://github.com/zu1k/good-mitm/actions/workflows/build-test.yml/badge.svg)](https://github.com/zu1k/good-mitm/actions/workflows/build-test.yml)\n[![GitHub license](https://img.shields.io/github/license/zu1k/good-mitm)](https://github.com/zu1k/good-mitm/blob/master/LICENSE)\n[![Docs](https://img.shields.io/badge/docs-read-blue.svg?style=flat)](https://good-mitm.zu1k.com/)\n\n#### [中文版](https://github.com/zu1k/good-mitm/blob/master/README_zh.md)\n\nRule-based MITM engine. Rewriting, redirecting and rejecting on HTTP(S) requests and responses, supports JavaScript.\n\n## Features\n\n- Signing certificate automatically based on TLS ClientHello SNI extension\n- Support selective MITM for specific domains\n- Rule description language based on YAML format: rewrite, reject, redirect\n  - Flexible rule matching capabilities\n    - Domain name prefix/suffix/exact match\n    - Regular expression matching\n    - Multiple filter rules\n  - Flexible text content rewriting\n    - Erase/replace\n    - Regular expression substitution\n  - Flexible dictionary-based content rewriting\n    - HTTP header rewriting\n    - Cookie rewriting\n  - Support for multiple actions per rule\n- JavaScript script rules support (programmatic intervention)\n- Transparent proxy support\n- Support HTTPS and HTTP multiplexing on a single port\n- Install CA certificate to the system trust zone\n\n## Usage\n\n### Certificate Preparation\n\nDue to the requirement of the `MITM` technique, you need to generate and trust your own root certificate.\n\n#### Generate Root Certificate\n\nFor security reasons, please do not blindly trust any root certificate provided by strangers. You need to generate your own root certificate and private key.\n\nExperienced users can use OpenSSL to perform the necessary operations. However, for users without experience in this area, you can use the following command to generate the required content. The generated certificate and private key will be stored in the `ca` directory.\n\n```shell\ngood-mitm.exe genca\n```\n\nAfter using the proxy provided by Good-MITM in your browser, you can directly download the certificate by visiting [http://cert.mitm.plus](http://cert.mitm.plus). This is particularly useful when providing services to other devices.\n\n#### Trusting the Certificate\n\nYou can add the root certificate to the trust zone of your operating system or browser, depending on your needs.\n\n### Proxy\n\nStart Good-MITM and specify the rule file or directory to use.\n\n```shell\ngood-mitm.exe run -r rules\n```\n\nUse the HTTP proxy provided by Good-MITM in your browser or operating system: `http://127.0.0.1:34567`.\n\n#### Transparent Proxy\n\nSee https://docs.mitmproxy.org/stable/howto-transparent/ for docs.\n\n```shell\nsudo sysctl -w net.ipv4.ip_forward=1\nsudo sysctl -w net.ipv6.conf.all.forwarding=1\nsudo sysctl -w net.ipv4.conf.all.send_redirects=0\n\nsudo useradd --create-home mitm\nsudo -u mitm -H bash -c 'good-mitm run -r rules/log.yaml -b 0.0.0.0:34567'\n\nsudo iptables -t nat -A OUTPUT -p tcp -m owner ! --uid-owner mitm --dport 80 -j REDIRECT --to-port 34567\nsudo iptables -t nat -A OUTPUT -p tcp -m owner ! --uid-owner mitm --dport 443 -j REDIRECT --to-port 34567\nsudo ip6tables -t nat -A OUTPUT -p tcp -m owner ! --uid-owner mitm --dport 80 -j REDIRECT --to-port 34567\nsudo ip6tables -t nat -A OUTPUT -p tcp -m owner ! --uid-owner mitm --dport 443 -j REDIRECT --to-port 34567\n```\n\n## Rule\n\n`Rule` is used to manipulate Good-MITM.\n\nA valid rule should include the following components:\n\n- `Name`：Used to differentiate different rules for easier maintenance.\n- [`Filter`](#filter)：Used to select the content to be processed from a set of `requests` and `responses`.\n- [`Action`](#action)：Used to perform desired actions, including `redirect`, `reject`, `modification`, etc.\n- Optionally, specify the domain name that requires MITM.\n\n```yaml\n- name: \"Block YouTube tracking\"\n  mitm: \"*.youtube.com\"\n  filter:\n    url-regex: '^https?:\\/\\/(www|s)\\.youtube\\.com\\/(pagead|ptracking)'\n  action: reject\n```\n\nAdditionally, a valid rule should meet the following requirements:\n\n- Focus: Each rule should be designed to perform a single task.\n- Simplicity: Use straightforward methods for processing to ensure easy maintenance.\n- Efficiency: Use efficient methods whenever possible, such as using domain suffixes and prefixes instead of complex regular expressions for domain matching.\n\n### Filter \u003cspan id=\"filter\"\u003e\u003c/span\u003e\n\n`Filter`is used to select the requests and responses that need to be processed.\n\n#### Available Options\n\nCurrently, `Filter` includes the following types:\n\n- All\n- Domain(String)\n- DomainKeyword(String)\n- DomainPrefix(String)\n- DomainSuffix(String)\n- UrlRegex(fancy_regex::Regex)\n\n\u003e **Note**  \n\u003e In the current version, the `domain` related types match the `host` field, which usually does not affect the results.\n\u003e If a website is using a non-standard port, the rule needs to specify the port.\n\u003e This behavior will be optimized in future versions.\n\n##### All\n\nWhen specifying the filter as `all`, it will match all requests and responses. This is typically used for performing logging actions.\n\n```yaml\n- name: \"log\"\n  filter: all\n  action:\n    - log-req\n    - log-res\n```\n\n##### Domain\n\n`domain` performs a full match against the domain name.\n\n```yaml\n- name: \"redirect\"\n  filter:\n    domain: 'none.zu1k.com'\n  action:\n    redirect: \"https://zu1k.com/\"\n```\n\n##### DomainKeyword\n\n`domain-keyword` performs a keyword match against the domain name.\n\n```yaml\n- name: \"reject CSDN\"\n  filter:\n    domain-keyword: 'csdn'\n  action: reject\n```\n\n##### DomainPrefix\n\n`domain-prefix` performs a prefix match against the domain name.\n\n```yaml\n- name: \"ad prefix\"\n  filter:\n    domain-prefix: 'ads' // example: \"ads.xxxxx.com\"\n  action: reject\n```\n\n##### DomainSuffix\n\n`domain-suffix` performs a suffix match against the domain name.\n\n\n```yaml\n- name: \"redirect\"\n  filter:\n    domain-suffix: 'google.com.cn'\n  action:\n    redirect: \"https://google.com\"\n```\n\n##### UrlRegex Url\n\n`url-regex` performs a regular expression match against the entire URL.\n\n```yaml\n- name: \"youtube tracking\"\n  mitm: \"*.youtube.com\"\n  filter:\n    url-regex: '^https?:\\/\\/(www|s)\\.youtube\\.com\\/(pagead|ptracking)'\n  action: reject\n```\n\n#### Multiple Filter\n\nThe `filters` field supports both single filters and multiple filters, with the relationship between multiple filters being `OR`.\n\n```yaml\n- name: \"youtube-2\"\n  mitm:\n    - \"*.youtube.com\"\n    - \"*.googlevideo.com\"\n  filters:\n    - url-regex: '^https?:\\/\\/[\\w-]+\\.googlevideo\\.com\\/(?!(dclk_video_ads|videoplayback\\?)).+(\u0026oad|ctier)'\n    - url-regex: '^https?:\\/\\/(www|s)\\.youtube\\.com\\/api\\/stats\\/ads'\n    - url-regex: '^https?:\\/\\/(www|s)\\.youtube\\.com\\/(pagead|ptracking)'\n    - url-regex: '^https?:\\/\\/\\s.youtube.com/api/stats/qoe?.*adformat='\n  action: reject\n```\n\nMultiple rules with the same action can be aggregated into a single rule for easier maintenance.\n\n### Action \u003cspan id=\"action\"\u003e\u003c/span\u003e\n\n`Action` is used to perform operations on requests or responses.\n\n#### Available Options\n\nCurrently, `Action` includes the following options:\n\n- Reject\n- Redirect(String)\n- ModifyRequest(Modify)\n- ModifyResponse(Modify)\n- LogRes\n- LogReq\n\n##### Reject\n\nThe `reject` type directly returns `502` status code, which is used to reject certain requests. It can be used to block tracking and ads.\n\n```yaml\n- name: \"reject CSDN\"\n  filter:\n    domain-keyword: 'csdn'\n  action: reject\n```\n\n##### Redirect\n\nThe `redirect` type directly returns `302` status code for redirection.\n\n```yaml\n- name: \"youtube-1\"\n  filter:\n    url-regex: '(^https?:\\/\\/(?!redirector)[\\w-]+\\.googlevideo\\.com\\/(?!dclk_video_ads).+)(ctier=L)(\u0026.+)'\n  action:\n    redirect: \"$1$4\"\n```\n\n##### ModifyRequest\n\n`modify-request` is used to modify the request. For specific modification rules, refer to the [Modify](#modify) section.\n\n##### ModifyResponse\n\n`modify-response` is used to modify the response. For specific modification rules, refer to the [Modify](#modify) section.\n\n##### Log\n\n`log-req` is used to log the request, and `log-res` is used to log the response.\n\n#### Multiple Action\n\nThe `actions` field supports both single actions and multiple actions. When multiple actions need to be performed, an array should be used.\n\n```yaml\n- name: \"youtube-1\"\n  filter:\n    url-regex: '(^https?:\\/\\/(?!redirector)[\\w-]+\\.googlevideo\\.com\\/(?!dclk_video_ads).+)(ctier=L)(\u0026.+)'\n  actions:\n    - log-req:\n    - redirect: \"$1$4\"\n```\n\n### Modify \u003cspan id=\"modify\"\u003e\u003c/span\u003e\n\nModify are used to perform modification operations, including modifying requests and modifying responses.\n\n#### Available Options\n\nBased on the location of the content to be modified, the modifiers can be categorized as follows:\n\n- Header(MapModify)\n- Cookie(MapModify)\n- Body(TextModify)\n\n##### TextModify\n\n`TextModify` is mainly used for modifying text. Currently, it supports two methods:\n\n- Setting the text content directly.\n- Simple replacement or regular expression replacement.\n\n###### Setting Text Directly\n\nFor the plain type, the content will be directly set to the specified text.\n\n```yaml\n- name: \"modify response body plain\"\n  filter:\n    domain: '126.com'\n  action:\n    modify-response:\n      body: \"Hello 126.com, from Good-MITM\"\n```\n\n###### Replacement\n\nReplacement supports both simple replacement and regular expression replacement.\n\nSimple Replacement\n\n```yaml\n- name: \"modify response body replace\"\n  filter:\n    domain-suffix: '163.com'\n  action:\n    modify-response:\n      body:\n        origin: \"NetEase homepage\"\n        new: \"Good-MITM homepage\"\n```\n\nRegular expression replacement.\n\n```yaml\n- name: \"modify response body regex replace\"\n  filter:\n    domain-suffix: 'zu1k.com'\n  action:\n    - modify-response:\n        body:\n          re: '(\\d{4})'\n          new: 'maybe $1'\n\n```\n\n##### MapModify\n\n`MapModify` is a modifier used to modify dictionary-type locations, such as `header` and `cookies`.\n\nThe `key` represents the key in the dictionary and must be specified.\n\nThe `value` is of type `TextModify` and follows the methods mentioned above.\n\nIf `remove` is set to `true`, the key-value pair will be removed.\n\n```yaml\n- name: \"modify response header\"\n  filter:\n    domain: '126.com'\n  action:\n    - modify-response:\n        header:\n          key: date\n          value:\n            origin: \"2022\"\n            new: \"1999\"\n    - modify-response:\n        header:\n          key: new-header-item\n          value: Good-MITM\n    - modify-response:\n        header:\n          key: server\n          remove: true\n```\n\n##### Header Modification\n\nRefer to the methods in the `MapModify` section.\n\n##### Cookie Modification\n\nSame as the Header modification method.\n\nIf `remove` is set to `true`, the corresponding `set-cookie` item will also be removed.\n\n##### Body Modification\n\nRefer to the methods in the `TextModify` section.\n\n## License\n\n**Good-MITM** © [zu1k](https://github.com/zu1k), Released under the [MIT](./LICENSE) License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzu1k%2Fgood-mitm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzu1k%2Fgood-mitm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzu1k%2Fgood-mitm/lists"}