Java programs
Wirescry's Java agent sends a Java program's HTTP and HTTPS traffic through Wirescry, and makes the program trust Wirescry's certificate, even when the program chose its own trust store. Start a program with the agent, or attach it to a program that's already running. Java 8 and later. This is part of the free app, from Wirescry 0.1.30. Jetty and Reactor Netty are covered from 0.1.31. It's under Setup → Java programs.
Without the agent, a Java program started from a Wirescry terminal still uses Wirescry's proxy settings, but only where the program and its libraries read them (see What's covered). The agent reaches the rest of the clients below, and certificates the program checks itself.
What it covers
| Client | Covered |
|---|---|
HttpURLConnection | Yes. |
Java's HttpClient (java.net.http) | Yes. |
| OkHttp | Yes. |
| Apache HttpClient 4 and 5 | Yes, including the default clients, which ignore Java's proxy settings. |
Jetty's HttpClient, 9.4.25 and later (10, 11 and 12 included) | Yes, over HTTP/1.1, and from Jetty 10 HTTP/2 for HTTPS. Jetty 9.4 before 9.4.25 isn't covered: its requests go direct. |
Reactor Netty's HttpClient, 1.0 to 1.3 | Yes, over HTTP/1.1, and HTTP/2 for HTTPS. It needs Netty's proxy support (netty-handler-proxy) in the program, as most do; without it, its requests go direct. Reactor Netty before 1.0 isn't covered: its requests go direct, and the list says nothing about it. |
| Libraries built on these | Yes, such as Spring's RestTemplate, and WebClient on its default Reactor Netty connector. |
| A library that bundles its own renamed copy of Apache HttpClient, Jetty or Reactor Netty | Not reached. |
HTTPS works when the program trusts certificates through Java's usual checks: Java's own trust store, or one the program loads itself. Certificate pinning, trust managers a program writes itself that don't ask Java's, and certificate revocation checks a program turns on still refuse Wirescry's certificate, as do TLS libraries that check certificates with their own trust manager in place of Java's. Programs running under a Java SecurityManager are left alone.
Some connections can't go through Wirescry's proxy, so they go direct, as they would without the agent:
- Apache HttpClient 5's HTTP/2-only client (
H2AsyncClientBuilder). - With Apache HttpClient 5, Jetty and Reactor Netty: Unix domain sockets.
- With Jetty and Reactor Netty: plain-http HTTP/2 (h2c), and HTTP/3.
- With Jetty:
ws://WebSockets (wss://is captured), its HTTP/2-only, FastCGI and HTTP/3 transports, and clients that use the PROXY protocol.
What it leaves alone
- Requests to this computer (
localhost,127.0.0.1and the like). - Hosts in the program's
http.nonProxyHosts. - A proxy the program chose itself, such as a company proxy, and a proxy given for one request. Hosts that proxy excludes go direct, not through Wirescry. With Reactor Netty,
.noProxy()and aproxyWhenthat picks no proxy aren't told apart from choosing none: those requests are captured. - Other connections, such as databases.
With Apache HttpClient, a connection limit the program set for one host doesn't apply while its requests go through Wirescry; the client's default limit per host does. With Jetty and Reactor Netty, connections through Wirescry and direct ones are pooled apart, so a limit the program set counts each pool on its own. With Jetty 12.1, those count toward a maxDestinations the program set; once it's reached, a new host fails with "Max destinations exceeded".
Programs started from Wirescry terminals
Turn on Load the agent in Java programs started from Wirescry terminals, or with the option below. It's off until you do. From then on, terminals Wirescry opens, and the setup lines for a terminal that's already open, add the agent to JAVA_TOOL_OPTIONS, after any options you set there yourself. (Command Prompt's setup lines replace your options.) Every java command then prints a "Picked up JAVA_TOOL_OPTIONS" line: that's Java confirming it.
- Your shell profile may set
JAVA_TOOL_OPTIONStoo. In terminals Wirescry opens on macOS and Linux, the profile runs after Wirescry's setup, so its value replaces Wirescry's. Set yours in the terminal instead, or after the setup line. - Java 8 ignores
JAVA_TOOL_OPTIONSentirely when it's over 1,024 bytes, and reads no more than 64 options, so Wirescry leaves the agent out when it would go over. The proxy settings stay. - Containers you start from the terminal don't get the agent: its file isn't in the container. They get the proxy settings, as described in Docker containers.
Programs started elsewhere
Once the setting is on, Programs started elsewhere shows a -javaagent option. Add it to the program's Java command, or to the VM options of its run configuration in your IDE. Where a setting takes each option as one argument, such as Gradle's jvmArgs, use the second form, without quotes.
The option names a file in Wirescry's data folder. A program started with it is captured whenever Wirescry is running with this setting on; while Wirescry isn't, the agent does nothing and the program connects directly. Remove the option before deleting Wirescry's data folder, or Java won't start the program.
Programs that won't start with it
Java 7 and older, and programs that ship their own trimmed Java runtime without agent support, refuse to start with the agent. Remove the option for them. In a Wirescry terminal, start one with JAVA_TOOL_OPTIONS= in front of its command, or turn the setting off and open a new terminal.
Programs already running
Running programs lists the Java programs you're running, with their process ids, and their Java versions once the agent is in them. Attach loads the agent into one without restarting it, and its traffic goes through Wirescry from its next connection; Detach turns it off again. Check again looks for programs started since, and Attach by process id takes a program that isn't listed.
- You need a JDK on this computer, a full JDK and not just a runtime: 17 or later, or 11 or later on Windows. Attaching runs a short Java program from it. Wirescry looks in
JAVA_HOME, then yourPATH, and on macOS also the JDKs macOS knows. On Windows and Linux, restart Wirescry after installing one. - It works for programs you run, on HotSpot-based Java 8 and later (OpenJDK, Temurin, Oracle's and most others).
- It doesn't work for programs in containers, programs run as administrator or by another user, GraalVM native images, OpenJ9, or programs started with
-XX:+DisableAttachMechanismor-XX:-EnableDynamicAgentLoading. - Java 21 and later print a warning when an agent is attached to a running program ("WARNING: A Java agent has been loaded dynamically…"). The program carries on as before. Wirescry asks before the first time.
- Security software on Windows may flag attaching, since it acts on another program.
What the list says
Under each program, Running programs says what its agent is doing. Most often it's "Sending its traffic through Wirescry". Others:
- "Updating to Wirescry’s current settings…": for a moment after Wirescry starts, or after its port or certificate changes.
- "This program chooses its own proxy, which the agent leaves alone": see what it leaves alone.
- "The agent can’t use Wirescry’s certificate yet": HTTPS may be refused until it can.
- "This program’s Jetty is older than the agent covers": Jetty 9.4 before 9.4.25. Its Jetty requests go direct.
- "Some of its Jetty clients can’t go through a proxy, and connect directly": clients on a transport listed above, or that use the PROXY protocol or a Unix socket. The note stays until the program ends.
- "Its Reactor Netty requests connect directly: it lacks Netty’s proxy support": add
io.netty:netty-handler-proxy, the same version as the program's other Netty jars, to capture them. - "The agent couldn’t set itself up in this program" or "This program’s Java is newer than Wirescry’s agent supports": part of the agent couldn't start, so some of the program's traffic may not reach Wirescry. Report it, with the program's Java and library versions.
An agent can't be removed from a running program: Detach turns it off, and puts back what it changed. A detached program stays detached when Wirescry restarts. An attached program goes on sending its traffic through Wirescry whenever Wirescry runs, until you detach it or it ends.
When Wirescry quits
The agent turns off within a second, and programs connect directly again, instead of to Wirescry's closed proxy. A request made in that second may be refused. If Wirescry stops any other way, such as a crash or an update, programs on Java 8 take about 15 seconds to notice.
When Wirescry runs again, programs started with the agent are captured again if the setting is on, and programs you attached are captured again unless you detached them.