{"id":19738273,"url":"https://github.com/httptoolkit/jvm-http-proxy-agent","last_synced_at":"2025-04-06T08:13:28.434Z","repository":{"id":45232497,"uuid":"340001522","full_name":"httptoolkit/jvm-http-proxy-agent","owner":"httptoolkit","description":"A JVM agent that automatically forces a proxy for HTTP(S) connections and trusts MitM certificates, for all major JVM HTTP clients","archived":false,"fork":false,"pushed_at":"2025-03-18T15:57:18.000Z","size":308,"stargazers_count":79,"open_issues_count":4,"forks_count":22,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-30T07:11:18.145Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","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/httptoolkit.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":"2021-02-18T09:40:32.000Z","updated_at":"2025-03-22T16:24:30.000Z","dependencies_parsed_at":"2024-10-28T15:49:32.879Z","dependency_job_id":"2d81a01f-7842-4bfd-97e6-c22fd8e14d73","html_url":"https://github.com/httptoolkit/jvm-http-proxy-agent","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httptoolkit%2Fjvm-http-proxy-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httptoolkit%2Fjvm-http-proxy-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httptoolkit%2Fjvm-http-proxy-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httptoolkit%2Fjvm-http-proxy-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/httptoolkit","download_url":"https://codeload.github.com/httptoolkit/jvm-http-proxy-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247451665,"owners_count":20940944,"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":[],"created_at":"2024-11-12T01:13:44.978Z","updated_at":"2025-04-06T08:13:28.416Z","avatar_url":"https://github.com/httptoolkit.png","language":"Java","readme":"# jvm-http-proxy-agent\n\n\u003e _Part of [HTTP Toolkit](https://httptoolkit.com): powerful tools for building, testing \u0026 debugging HTTP(S)_\n\nA JVM agent that automatically forces a proxy for HTTP(S) connections, and trusts a given additional HTTPS certificate authority, for all major JVM HTTP clients.\n\nThis agent lets you intercept all HTTP(S) from any JVM application automatically, with no code changes, so you can inspect, debug \u0026 mock this traffic using an HTTPS proxy, such as [HTTP Toolkit](https://httptoolkit.com) or any other HTTPS MitM proxy.\n\nYou can either launch the application with this agent from the start, or it can attach to and take over HTTP(S) from an already running JVM application.\n\nTraffic can be captured from at least:\n\n- [x] Java's built-in HttpURLConnection\n- [x] Java 11's built-in HttpClient\n- [x] Apache HttpClient v3, v4 \u0026 v5\n- [x] Apache HttpAsyncClient v4 \u0026 v5\n- [x] OkHttp v2, v3 \u0026 v4\n- [x] Retrofit\n- [x] Jetty-Client v9, v10 \u0026 v11\n- [x] Async-Http-Client\n- [x] Reactor-Netty v0.9 \u0026 v1+\n- [x] Spring WebClient\n- [x] Ktor-Client\n- [x] Akka-HTTP v10.1.6+\n- [x] Vert.x HttpClient and WebClient\n\nThis will also capture HTTP(S) from any downstream libraries based on each of these clients, and many other untested clients sharing similar implementations, and so should cover a very large percentage of HTTP client usage.\n\nThis agent supports at least Oracle \u0026 OpenJDK v8+ when starting the application with the agent, or v11+ for application that the agent will attach to.\n\nIt's likely that this supports many other HTTP client configurations \u0026 JVMs too. If you find a case that isn't supported, or isn't supported correctly, please [file an issue](https://github.com/httptoolkit/jvm-http-proxy-agent/issues/new).\n\n## Usage\n\nThis agent can either be attached when the process is started, or attached later to a running process.\n\nIn each case, the agent must be configured with the proxy host (e.g. 127.0.0.1), the proxy port (e.g. 8000) and the absolute path to the HTTPS certificate to be trusted.\n\n### Attaching at startup\n\nTo attach at startup, pass this JAR using the `javaagent` option, e.g:\n\n```\njava -javaagent:./agent.jar=\"127.0.0.1|8000|/path/to/cert.pem\" -jar ./application.jar\n```\n\n### Attaching to a running process\n\nTo attach to a process, first launch the target process, and then run:\n\n```\njava -jar ./agent.jar 1234 127.0.0.1 8000 /path/to/cert.pem\n```\n\nwhere 1234 is the pid of the target process. This will exit successfully \u0026 immediately if attachment succeeds, or with a non-zero exit code if not.\n\nYou can also query the available JVM processes ids, like so:\n\n```\n\u003e java -jar ./agent.jar list-targets\n589739:./application.jar\n404401:com.intellij.idea.Main\n453889:org.jetbrains.kotlin.daemon.KotlinCompileDaemon --daemon-runFilesPath ...\n413868:org.gradle.launcher.daemon.bootstrap.GradleDaemon 6.7\n```\n\nWhen attached from startup all clients will always be intercepted. When attached later, both newly created HTTP clients and already existing instances will be intercepted, but it's possible that in some cases already established connections may not be immediately captured. Typically though these will eventually close and be reconnected, and at that point the connection is always intercepted.\n\n### Testing attachment capabilities\n\nNot all JDKs provide the instrumentation \u0026 attachment APIs required to support this process, although all Oracle \u0026 OpenJDK v9+ versions should do so.\n\nTo check this, you can test whether the `java` in your $PATH is capable of attaching to and intercepting a target process using the self-test command, like so:\n\n```bash\njava -Djdk.attach.allowAttachSelf=true -jar ./agent.jar self-test\n```\n\n### Contributing\n\nContributions are very welcome! Reports of scenarios that aren't currently supported are helpful (please [create an issue](https://github.com/httptoolkit/jvm-http-proxy-agent/issues/new), including any errors, and preferably steps to reproduce the issue) but patches to fix issues are even better.\n\nBe aware that for all contributors to HTTP Toolkit components, including this, [HTTP Toolkit Pro is totally free](https://github.com/httptoolkit/httptoolkit/#contributing-directly) - just [get in touch](https://httptoolkit.com/contact) after your contribution is accepted with the email you'd like to use to claim your Pro account.\n\nTo contribute a patch:\n\n* Fork this repo\n* Clone your fork: `git clone git@github.com:$YOUR_GITHUB_USERNAME/jvm-http-proxy-agent.git`\n* Create a new branch: `git checkout -B my-contribution-branch`\n* Check the existing tests pass locally: `./gradlew quickTest`\n  * N.B. this requires Java 11+ - while some features are supported in older JVM versions, development requires a modern JVM\n* For library-specific issues:\n  * Add/edit a test case in [/test-app/src/main/java/tech/httptoolkit/testapp/cases](https://github.com/httptoolkit/jvm-http-proxy-agent/tree/main/test-app/src/main/java/tech/httptoolkit/testapp/cases) to reproduce your issue\n  * Add that case to [the list](https://github.com/httptoolkit/jvm-http-proxy-agent/blob/459b931a2eebd486261f296418aa028e4b2fb7e9/test-app/src/main/java/tech/httptoolkit/testapp/Main.java#L17-L36) if you created a new case.\n  * Check that `./gradlew quickTest` now fails.\n* For more general changes:\n  * Either add a test case (as above) or add a new standalone test in https://github.com/httptoolkit/jvm-http-proxy-agent/blob/main/src/test/kotlin/IntegrationTests.kt\n* Make your changes within the [advice classes](https://github.com/httptoolkit/jvm-http-proxy-agent/tree/main/src/main/java/tech/httptoolkit/javaagent/advice) and [injection setup code](https://github.com/httptoolkit/jvm-http-proxy-agent/tree/main/src/main/kotlin/tech/httptoolkit/javaagent) to fix your issue/add your feature.\n* Test that `./gradlew quickTest` now passes.\n* If you've changed any functionality, consider adding it to the docs here.\n* Commit your change, push it, and open a PR here for review.\n\nIf you have any issues, or if you want to discuss a change before working on it (recommended for large/complex changes), please [open an issue](https://github.com/httptoolkit/jvm-http-proxy-agent/issues/new).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhttptoolkit%2Fjvm-http-proxy-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhttptoolkit%2Fjvm-http-proxy-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhttptoolkit%2Fjvm-http-proxy-agent/lists"}