{"id":15014235,"url":"https://github.com/danthe1st/https-intercept","last_synced_at":"2025-04-12T07:42:06.673Z","repository":{"id":224792002,"uuid":"764234371","full_name":"danthe1st/HTTPs-intercept","owner":"danthe1st","description":"A simple program that intercepts HTTPs traffic using Netty and BouncyCastle","archived":false,"fork":false,"pushed_at":"2024-12-21T15:52:38.000Z","size":126,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T02:51:12.989Z","etag":null,"topics":["bouncycastle","https","java","man-in-the-middle","man-in-the-middle-attack","netty","netty-client","netty-http","netty-server","ssl","tls"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danthe1st.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}},"created_at":"2024-02-27T18:06:12.000Z","updated_at":"2024-12-21T15:52:34.000Z","dependencies_parsed_at":"2024-03-08T20:05:14.605Z","dependency_job_id":"a689ff6c-30a6-44a8-8571-4e228e184a03","html_url":"https://github.com/danthe1st/HTTPs-intercept","commit_stats":{"total_commits":50,"total_committers":2,"mean_commits":25.0,"dds":"0.020000000000000018","last_synced_commit":"f325d3196c99c5a5d40cf7e557889d9ee6e35e82"},"previous_names":["danthe1st/https-intercept"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danthe1st%2FHTTPs-intercept","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danthe1st%2FHTTPs-intercept/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danthe1st%2FHTTPs-intercept/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danthe1st%2FHTTPs-intercept/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danthe1st","download_url":"https://codeload.github.com/danthe1st/HTTPs-intercept/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248536981,"owners_count":21120683,"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":["bouncycastle","https","java","man-in-the-middle","man-in-the-middle-attack","netty","netty-client","netty-http","netty-server","ssl","tls"],"created_at":"2024-09-24T19:45:21.411Z","updated_at":"2025-04-12T07:42:06.651Z","avatar_url":"https://github.com/danthe1st.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HTTPs intercept\nA simple program that intercepts HTTPs traffic using Netty and BouncyCastle\n\n## Disclaimer\n\u003e [!Warning]\n\u003e ONLY USE THIS TOOL FOR EDUCATIONAL PURPOSES!  \n\u003e DO NOT USE IT ON DEVICES OF PEOPLE WITHOUT THEIR INFORMED CONSENT!\n\nThis program has capabilities that can be used to perform a Man-In-The-Middle-Attack on HTTPs traffic\nallowing to read or modify all communication done with it.\n\nFurthermore, it is dangerous to import CA certificates into the trust store of a browser or Operating System.  \nIf a malicous entity gets access to the key,\nthey can read or change most encrypted communication performed using the device trusting the certificate.\n\n## How does it work?\nThe `certs.sh` script creates a CA certificate and exports it into the file `root.pem` and `root.crt`.\nThese files can then be imported in trust stores of browsers or Operating Systems.\nAdding a CA certificate to the Linux trust store is explained [here](https://askubuntu.com/a/94861/966107) (though it would be necessary to use the `root.pem` here).\n\nThe Java program loads the keys and certificate and when it receives an HTTPs request,\nit decrypts the request, encrypts it again for the specified server and forwards it.\nResponses from the server are also decrypted and re-encrypted before being sent to the client.\nThis is commonly known as a \"Man in the Middle\" attack.\n\nWhen an HTTPs request is received, the program uses the unencrypted Server Name Identification (SNI) part\nof the Client Hello TLS packet in order to identify both the server to send it to\nas well as the host to target when signing the generated certificate.\n\nFurthermore, the script `reroute.sh` can configure `iptables` to route all traffic of a specified user\nthrough the program such that that traffic is intercepted.\n\n## Setup\n- run the `certs.sh` script in order to generate a CA certificate.\n  This generates the following files:\n  - `root.pem` and `root.crt` containing the CA certificate\n  - `interceptor.jks` containing the keystore with the private key and certificate - This file is PRIVATE\n  - `.secrets` containing the passphrases for the keystore and private key - This file is PRIVATE\n- Run the program (the main class is `io.github.danthe1st.httpsintercept.HttpsIntercept`)\n  This requires the files `interceptor.jks` and `.secrets` to be located in the current working directory.\n- The program should listen on port `1337` and forward requests to port `443`.\n  In order to make a request to `example.com` using `curl`, the following command can be used:\n  ```bash\n  curl --connect-to example.com:1337:127.0.0.1 https://example.com:1337 --cacert root.pem\n  ```\n  If the certificate is installed into the operating system truststore, the argument `--cacert root.pem` is not necessary.\n\nIt is also possible to add the certificate to the truststore of a JDK using a command similar to the following:\n```bash\nsudo keytool -keystore $JAVA_HOME/lib/security/cacerts -import interceptCert -file root.crt\n```\n\nWith this, it will be able to intercept HTTPs traffic from Java applications as long as\n- the truststore is installed to the JVM used for running the application\n  (installing the certificate to another truststore doesn't make this work)\n- the application uses the default truststore\n\n### Binaries\nA sample binary is automatically build [with GitHub Actions](https://github.com/danthe1st/HTTPs-intercept/actions?query=branch%3Amaster)\nwhen a commit is pushed.\nThe build script can be found in the file [.github/workflows/build.yml](./.github/workflows/build.yml).\n\n#### building binaries\n\nThe command `mvn package` generates a JAR file at a location\nsimilar to `target/https-intercept-VERSION-jar-with-dependencies.jar`.\nThis JAR file can be run using `java -jar`.\n\nA native binary can also be built using `mvn -Pnative package`.\nThis requires GraalVM and [some additional prerequisites](https://www.graalvm.org/latest/reference-manual/native-image/#prerequisites).\n\nIn order to customize the image build, it is possible to supply extra arguments using the property `native.extraArgs`.\nFor example, the following command can be used to allow device-specific optimizations:\n```bash\nmvn package -Pnative -Dnative.extraArgs=\"--march=native\"\n```\n\n### Systemd setup\n\nIt is possible to create a systemd service definition with this program similar to this\n\n```\n[Unit]\nDescription=HTTPs intercept: https://github.com/danthe1st/HTTPs-intercept\n\n[Service]\nType=simple\nExecStartPre=+/home/HTTPS_INTERCEPT_USER/HTTPS_INTERCEPT_DIRECTORY/reroute.sh enable USER_TO_INTERCEPT\nExecStart=/home/HTTPS_INTERCEPT_USER/HTTPS_INTERCEPT_DIRECTORY/https-intercept\nExecStopPost=+/home/HTTPS_INTERCEPT_USER/HTTPS_INTERCEPT_DIRECTORY/reroute.sh disable USER_TO_INTERCEPT\nRestart=on-failure\nUser=HTTPS_INTERCEPT_USER\nWorkingDirectory=/home/HTTPS_INTERCEPT_USER/HTTPS_INTERCEPT_DIRECTORY\n\n[Install]\nWantedBy=multi-user.target\n```\n\nIn this example\n- before starting forwards all traffic of the user `USER_TO_INTERCEPT`\n  is changed to be forwarded through the program for interception\n  - This is done by executing the `reroute.sh` script as root which sets up corresponding rules using `iptables`\n- The program is started as the user `HTTPS_INTERCEPT_USER`\n- This assumes the following files to be located in `/home/HTTPS_INTERCEPT_USER/HTTPS_INTERCEPT_DIRECTORY`:\n  - `reroute.sh`: The script configuring rules with `iptables`\n  - `https-intercept`: The built binary or a script executing the program\n  - `interceptor.jks` and `.secrets` as created by `certs.sh`\n\n# Configuration\nThis program can be configured by creating a file called `intercept.yaml` in the working directory.\n```yaml\nignoredHosts: []\npreForwardRules: []\npostForwardRules: []\n```\n\n## ignored hosts\nUsing the configuration entry `ignoredHosts`, one can configure hostnames that should not be intercepted.\nRequests to these hosts are forwarded as-is without decrypting the request.\nIt is possible to specify hostnames that must match exactly, parts of the hierarchy or regexes:\n```yaml\nignoredHosts:\n  exact:\n  # This matches example.com but not somesubdomain.example.com\n  - example.com\n  partial:\n  # This matches example.com and all subdomains\n  - example.com\n  # This matches all hosts ending with `.local`\n  - local\n  regex:\n  # This matches all domains matching the given regex, e.g. example.com or example.org but not host.example.com\n  - example\\\\.[a-zA-Z]*\n```\n\n## pre-forward rules\nWith the entry `preForwardRules`, it is possible to configure rules that happen before forwarding the request.\nPre-forward rules can access the request but not the response.\nThe rules are identified using a `type` parameter.\nAll rules have a `hostMatcher` parameter configuring in the same format as `ignoredHosts` which hosts they should apply to.\n\nCurrently, the only implemented rule (`setHeader`) allows setting HTTP request headers.\n```yaml\npreForwardRules:\n# set a header for all requests\n# in this case, we are setting the \"Referer\" header to \"localhost\"\n- type: setHeader\n  headers:\n    Referer: localhost\n# set a header for requests to example.com\n- type: addHeader\n  hostMatcher:\n    exact:\n    - example.com\n  headers:\n    X-My-Custom-Header: some-header-value\n```\n\n## post-forward rules\nSimilarlarly to `preForwardRules`, `postForwardRules` can be used to configure rules that are processed after forwarding the request.\nThese rules can access and modify the response.\nAs with Pre-forward rules, Post-forward rules are identified with a `type` parameter and can be filtered using a `ignoredHosts` specification.\n\nCurrently, the only implemented rule (`htmlBasedBlock`) blocks responses based on the HTML response.\nThis rule checks whether an element matching a CSS selector exists matching a regex.\n```yaml\n# This rule attempts to block rick rolls based on the \u003ctitle\u003e element\n# it is not very reliable as rickrolls may have different \u003ctitle\u003es and YouTube may load it in different ways\n- type: htmlBasedBlock\n  # This rule only applies to YouTube and its subdomains\n  hostMatcher:\n    partial:\n    - youtube.com\n  # if a \u003ctitle\u003e containing the text \"Never gonna give you up\" is found, the response is not sent to the client\n  selector: title\n  matcher: .*Never gonna give you up.*\n  # it is possible to set a custom HTTP status for the blocked response\n  status: 500\n  # a path to an HTML file containing the new response can be specified as follows\n  responsePath: /path/to/block/information.html\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanthe1st%2Fhttps-intercept","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanthe1st%2Fhttps-intercept","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanthe1st%2Fhttps-intercept/lists"}