Language Configuration

Some language-specific environment configuration may be necessary but you should not need to modify your application code to use proxymock.

Configuring the Proxy

As the name implies, proxymock is a proxy which works by routing traffic from your application through proxymock before it goes to the final destination.

warning

99% of the time proxy configuration does not require a code change, but some HTTP client libraries have their own proxy configuration that may override or ignore environment variables. Check the documentation for your specific library.

Record inbound traffic by setting the --app-port flag and making requests to port 4143 instead of your application's port.

Go

Go respects proxy environment variables.

export HTTP_PROXY=http://localhost:4140
export HTTPS_PROXY=http://localhost:4140
export NO_PROXY=localhost,127.0.0.1

Use the SOCKS proxy to capture database traffic:

export ALL_PROXY=socks5://localhost:4140

Java

Java supports -D flags to set system properties, which can be set in an environment variable.

export JAVA_TOOL_OPTIONS="-Dhttp.proxyHost=localhost -Dhttp.proxyPort=4140 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=4140"

Use the SOCKS proxy to capture database traffic:

export JAVA_TOOL_OPTIONS="-DsocksProxyHost=localhost -DsocksProxyPort=4140"

With authentication and TLS certificates:

export JAVA_TOOL_OPTIONS="-Dhttp.proxyHost=localhost -Dhttp.proxyPort=4140 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=4140 -Djavax.net.ssl.trustStore=$HOME/.speedscale/certs/cacerts.jks -Djavax.net.ssl.trustStorePassword=changeit"

Bypass proxy for specific hosts:

-Dhttp.nonProxyHosts="localhost|127.0.0.1|*.internal.domain"

warning

Support across runtimes or libraries may vary. For example, Maven requires that -D flags are set through -Dspring-boot.run.jvmArguments.

note

These options include the -D flags for TLS. See the Decrypting-TLS section below.

Python

Python respects proxy environment variables.

export HTTP_PROXY=http://localhost:4140
export HTTPS_PROXY=http://localhost:4140
export NO_PROXY=localhost,127.0.0.1

Use the SOCKS proxy to capture database traffic (requires PySocks package):

export ALL_PROXY=socks5://localhost:4140

Node.js

Node.js HTTP libraries handle proxies differently. Environment variables are NOT automatically used by most libraries.

For axios (requires explicit configuration or https-proxy-agent):

const axios = require('axios');

// Option 1: Direct configuration
axios.get('https://example.com', {
  proxy: {
    protocol: 'http',
    host: 'localhost',
    port: 4140
  }
});

// Option 2: Using https-proxy-agent
const HttpsProxyAgent = require('https-proxy-agent');
const agent = new HttpsProxyAgent('http://localhost:4140');

axios.get('https://example.com', {
  httpsAgent: agent
});

To respect environment variables with axios:

export HTTP_PROXY=http://localhost:4140
export HTTPS_PROXY=http://localhost:4140

Then use a library like https-proxy-agent to read them.

Use the SOCKS proxy to capture database traffic (requires socks-proxy-agent):

const SocksProxyAgent = require('socks-proxy-agent');
const agent = new SocksProxyAgent('socks5://localhost:4140');

Ruby

Ruby's Net::HTTP does not automatically use proxy environment variables by default, but :ENV can be passed to Net::HTTP.new:

export http_proxy=http://localhost:4140
export https_proxy=http://localhost:4140
export no_proxy=localhost,127.0.0.1

require 'net/http'

# This will use environment variables
Net::HTTP.new('example.com', nil, :ENV).start do |http|
  # Uses proxy from env vars if set
end

# Or with URI
uri = URI('https://example.com')
Net::HTTP.start(uri.host, uri.port, :p_addr => :ENV) do |http|
  # Uses proxy from env vars if set
end

PHP

PHP does not automatically use environment variables so it must be set explicitly. There multiple ways to configure proxies depending on the method used.

Using cURL:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://example.com");
curl_setopt($ch, CURLOPT_PROXY, "http://localhost:4140");
// For SOCKS proxy
// curl_setopt($ch, CURLOPT_PROXY, "socks5://localhost:4140");

// With authentication
curl_setopt($ch, CURLOPT_PROXYUSERPWD, "username:password");

$response = curl_exec($ch);
curl_close($ch);

Using stream context:

$context = stream_context_create([
    'http' => [
        'proxy' => 'tcp://localhost:4140',
        'request_fulluri' => true,
    ],
    'ssl' => [
        'verify_peer' => false,  // Only for testing
    ]
]);

$response = file_get_contents('https://example.com', false, $context);

Set default proxy for all stream operations:

stream_context_set_default([
    'http' => ['proxy' => 'tcp://localhost:4140']
]);

C#/.NET

.NET Core/5+ respects proxy environment variables:

export HTTP_PROXY=http://localhost:4140
export HTTPS_PROXY=http://localhost:4140
export NO_PROXY=localhost,127.0.0.1

Rust

Rust with the reqwest crate respects proxy environment variables by default:

export HTTP_PROXY=http://localhost:4140
export HTTPS_PROXY=http://localhost:4140
export NO_PROXY=localhost,127.0.0.1

Use the SOCKS proxy to capture database traffic (requires socks feature in Cargo.toml):

export ALL_PROXY=socks5://localhost:4140

Then modify Cargo.toml to:

reqwest = { version = "your_version_here", features = ["socks"] }

Decrypting TLS

proxymock attempts to automatically configure TLS on the desktop so manual configuration is only necessary in special environments like CI/CD or when TLS decryption does not work out of the box.

Commands and flags should be run in the environment where your application is running.

Go

export SSL_CERT_FILE="${HOME}/.speedscale/certs/tls.crt"

Go applications using OpenSSL will respect the SSL_CERT_FILE environment variable to locate trusted root certificates. This environment variable will be automatically populated by the Speedscale operator.

Node.js

export NODE_EXTRA_CA_CERTS="${HOME}/.speedscale/certs/tls.crt"

For Node.js applications newer than v7.3.0.

Ruby

export SSL_CERT_FILE="${HOME}/.speedscale/certs/tls.crt"

Ruby applications using OpenSSL will respect the SSL_CERT_FILE environment variable to locate trusted root certificates. This environment variable will be automatically populated by the Speedscale operator.

.NET

export SSL_CERT_FILE="${HOME}/.speedscale/certs/tls.crt"

info

.NET Core uses OpenSSL on Linux and Mac which respects default settings. The default Microsoft .NET Docker base images are Linux based which means these settings apply, however running Windows based workloads may require additional configuration.

Java

Java applications utilize a truststore to specify certificates to be trusted.

On desktop:

Create the keystore with Speedscale certs.

proxymock certs --jks

Then apply these flags when running your app:

java \
  -Djavax.net.ssl.trustStore=/etc/ssl/speedscale/jks/cacerts.jks \
  -Djavax.net.ssl.trustStorePassword=changeit \
	-jar app.jar

In cluster:

During Operator installation a secret called speedscale-jks will be created that contains the speedscale-certs root CA along with a standard set of CA certs used by openjdk. This secret is automatically mounted when the tls-out setting is configured as shown below. The Java app itself needs to be configured to use this secret as well which requires configuring your JVM to use the truststore with these settings:

These can be automatically applied by adding to your JVM by setting JAVA_TOOL_OPTIONS. This can be set on your workload by adding the sidecar.speedscale.com/tls-java-tool-options: "true" annotation. Read more about this setting here.

When running in-cluster, these flags are also surfaced as an environment variable SPEEDSCALE_JAVA_OPTS if you need to merge with your own existing sets of Java flags.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: spring-boot-app
  annotations:
    sidecar.speedscale.com/inject: "true"
    sidecar.speedscale.com/tls-out: "true"
    sidecar.speedscale.com/tls-java-tool-options: "true"

If you already have a custom JKS

Sometimes your code is already using a Custom JKS, so you need to merge your current JKS with the one from Speedscale. In that case what you can do is import the Speedscale TLS cert into your existing JKS. Here is how to do that:

# 1) Make a copy of your existing keystore
cp custom.jks custom-with-speedscale.jks

# 2) Import Speedscale Root CA into the copy (non-interactive)
keytool -importcert \
  -noprompt \
  -alias speedscale-root \
  -file "$HOME/.speedscale/certs/tls.crt" \
  -keystore custom-with-speedscale.jks \
  -storepass changeit

# 3) Verify the Speedscale cert is present
keytool -list -keystore custom-with-speedscale.jks -storepass changeit | grep -i speedscale

# 4) Use the merged truststore when running your app
java \
  -Djavax.net.ssl.trustStore=custom-with-speedscale.jks \
  -Djavax.net.ssl.trustStorePassword=changeit \
  -jar app.jar

Notes:

• If your truststore is PKCS12 instead of JKS, add -storetype pkcs12 to the keytool commands.
• If the alias already exists, either choose a different alias (e.g., -alias speedscale-root-2) or remove the old one with: keytool -delete -alias speedscale-root -keystore "$KEYSTORE_OUT" -storepass "$KEYSTORE_PASS".

C++

export SSL_CERT_FILE="${HOME}/.speedscale/certs/tls.crt"

C++ applications using OpenSSL will respect the SSL_CERT_FILE environment variable to locate trusted root certificates. This environment variable will be automatically populated by the Speedscale operator.

Python

export REQUESTS_CA_BUNDLE="${HOME}/.speedscale/certs/tls.crt"

Python applications (including the popular requests library and many others) will use the REQUESTS_CA_BUNDLE environment variable to locate trusted root certificates.