The Proxy Map Service listens for incoming TCP connections on one or more ports and redirects traffic to an external proxy server defined in the configuration (appsettings.json). The rules system allows blocking connections to certain hosts or establishing connections without using an external proxy server (this is called bypass). In bypass mode, the Proxy Map Service itself acts as the proxy server.
Proxy Map Service may be useful for:
- Blocking unwanted connections (e.g., tracking).
- Reducing (saving) traffic passing through an external (paid) proxy server.
- Adding the Proxy-Authorization HTTP header if the external proxy server requires authentication but the client software does not support it.
- Returning the correct error code (
407 Proxy Authentication Required) if authentication is required but theProxy-Authorizationheader is missing. This fixes incorrect behavior of some proxy servers that simply drop the connection when authentication is absent. - Allowing certain traffic that is blocked by your server’s IP (e.g., captcha-solving services) to bypass the external proxy.
For security, the Proxy Map Service only listens for incoming connections on the loopback interface (127.0.0.1).
Clone the repository from GitHub using the following command:
git clone https://github.com/optinsoft/ProxyMapService.git
cd ProxyMapServiceThe project requires .NET 8.0 SDK. To build a self-contained executable for Windows x64, run the following publish command:
dotnet publish .\ProxyMapService\ProxyMapService.csproj -c Release -r win-x64After a successful build, the executable ProxyMapService.exe will be located in the following directory:
ProxyMapService\bin\Release\net8.0\win-x64\publish\
Application settings are managed via appsettings.json. Instead of modifying the main configuration file directly, it is highly recommended to create an appsettings.Production.json file in the same directory and place your custom overrides there.
For your convenience, a sample file named appsettings.Production-Example.json is available in the publish directory. This file demonstrates how to properly configure the ProxyMappings rules. You can simply rename this file to appsettings.Production.json and modify it according to your needs.
Navigate to the publish directory and launch the executable:
ProxyMapService.exeUpon startup, the console will output security tokens and dashboard access information similar to this:
DEVELOPMENT TOKEN GENERATED: b0a24910a0884e08b3899a75748c120a
Dashboard URL: http://localhost:5000/ProxyMapDashboard/?token=b0a24910a0884e08b3899a75748c120a
Open the provided Dashboard URL in your web browser to access the management interface.
The ProxyMap Dashboard consists of three main tabs:
- Stats: Displays general service information (uptime), active LISTEN PORTS (port
5001is open by default as a proxy port inappsettings.json), data transfer counters (bytes sent/received), and current session details. - Event Log: Displays internal system logs. Click Resume Capture to start viewing live log messages.
- HTTP Traffic: Displays HTTP requests passing through the service. Click Resume Capture to enable live traffic monitoring.
To quickly verify your setup, configure your web browser to route traffic through the Proxy Map Service on port 5001.
For Google Chrome, you can create a dedicated desktop shortcut with specific launch arguments:
- Create a temporary profile folder on your drive (e.g.,
C:\Temp\chrome\proxymap). - Run Chrome from the command line or via a shortcut with the following parameters:
"C:\Program Files\Google\Chrome\Application\chrome.exe" --proxy-server="http://127.0.0.1:5001" --user-data-dir="C:\Temp\chrome\proxymap"- Open any website in this newly launched Chrome window.
- Check the ProxyMap Dashboard. You will immediately see live logs in the Event Log tab and captured traffic in the HTTP Traffic tab.
Note: At this stage, secure connections will only display basic tunneling information:
CONNECT | 200 Connection establishedto targets like://google.com. Detailed HTTP headers and request bodies will not be visible yet because SSL decryption is currently disabled.
By default, HTTPS traffic is forwarded without inspection. To view detailed HTTP headers and request/response bodies for secure connections, you must enable SSL decryption.
On its very first launch, the Proxy Map Service automatically generates a root certificate authority (CA) in the user's home directory under the .proxymap folder (e.g., C:\Users\Username\.proxymap\).
This directory contains three files:
ProxyMapService-ca.p12(Contains both the certificate and the private key)ProxyMapService-ca-cert.cer(Public certificate only)ProxyMapService-ca-cert.pem(PEM-formatted certificate)
You must install ProxyMapService-ca.p12 because it contains the private key required for encryption.
To install the certificate on Windows:
- Double-click the
ProxyMapService-ca.p12file to open the Certificate Import Wizard. - Select the desired Store Location (Current User or Local Machine) and click Next.
- Verify the file path and click Next.
- When prompted for a password, leave the password field blank (the private key has no password).
- Check the box "Enable all extended properties" and click Next.
- On the Certificate Store page, choose "Place all certificates in the following store".
- Click Browse, select "Trusted Root Certification Authorities", and click OK.
- Complete the wizard and confirm any security warnings to trust the certificate.
- If you haven't already, copy
appsettings.jsonand name itappsettings.Production.json. - Open
appsettings.Production.jsonin any text editor. - Locate the
ProxyMappingssection, find theListenconfiguration, and change theDecryptSSLvalue fromfalsetotrue:
"ProxyMappings": [
{
"Listen": {
"Port": 5001,
"RejectHttpProxy": false,
"StickyProxyLifetime": 0,
"Action": "Bypass",
"DecryptSSL": true,
"SslMode": "Auto",
"UpstreamSslMode": "Auto",
"IgnoreHostRules": false
},
"Authentication": {
"Required": false,
"Verify": false,
"SetAuthentication": false,
"RemoveAuthentication": false,
"ParseUsernameParameters": false,
"Username": "user",
"Password": "pass"
}
}
]- Restart the
ProxyMapService.exeapplication. - Note that a new Development Token is generated on every application startup.
- Copy the new Dashboard URL from the console and open it in your browser.
- Go to the HTTP Traffic tab and click Resume Capture.
- Launch your pre-configured Google Chrome proxy instance and browse any HTTPS website (e.g.,
https://google.com).
The dashboard will now display full HTTP details instead of basic generic CONNECT tunnels, allowing you to see and monitor completely decrypted traffic.
The global SslClientOptions (outgoing TLS connections) and SslServerOptions (incoming TLS connections when decryption is enabled) can be refined at two levels:
Listen— inside aProxyMappingsentry, applies to all traffic of that listening port range (e.g. a differentEnabledSslProtocolsset for a specific port);HostRule— inside theHostRulessection, applies only to connections to the matching host (e.g. a dedicated server certificate for a particular host).
Precedence: global SslClientOptions/SslServerOptions → Listen.SslClientOptions/Listen.SslServerOptions → HostRule.SslClientOptions/HostRule.SslServerOptions. Only the properties explicitly set in an override replace the inherited values; everything else is inherited from the level above. For HostRule the override is applied only when the rule matches the host and the rule's action is not Deny.
Example — stricter protocols for a specific listening port and a dedicated certificate for one host:
"ProxyMappings": [
{
"Listen": {
"Port": 5001,
"DecryptSSL": true,
"SslServerOptions": {
"EnabledSslProtocols": "Tls12,Tls13"
}
}
}
],
"HostRules": {
"Items": [
{
"HostName": "example.com",
"SslClientOptions": {
"TlsClientType": "BoringSsl"
},
"SslServerOptions": {
"ServerCertificate": {
"Path": "certs/example.com.pfx",
"Password": "secret"
}
}
}
]
}The override properties mirror the corresponding global section:
SslClientOptionsoverride:EnabledSslProtocols,CheckCertificateRevocation,ApplicationProtocols,TrustedCAs,TlsClientType;SslServerOptionsoverride:EnabledSslProtocols,ClientCertificateRequired,CheckCertificateRevocation,ApplicationProtocols,ServerCertificate(path/password or store-basedSslCertificateConfig),CACertificate.
The legacy HostRule-level CertificatePath/CertificatePassword properties have been removed in favor of SslServerOptions.ServerCertificate, which is more flexible (it also supports store-based certificates via StoreLocation/StoreName/Subject). Migrate old configurations as follows:
// before:
{
"HostName": "example.com",
"CertificatePath": "certs/example.com.pfx",
"CertificatePassword": "secret"
}
// after:
{
"HostName": "example.com",
"SslServerOptions": {
"ServerCertificate": {
"Path": "certs/example.com.pfx",
"Password": "secret"
}
}
}When SSL decryption is enabled, the Proxy Map Service terminates the client's TLS connection and opens its own TLS connection to the target server. By default, this upstream connection is made with the standard .NET SslStream, whose TLS handshake is easily recognizable as non-browser traffic — some servers and anti-bot systems flag such connections.
Proxy Map Service can make the upstream TLS handshake indistinguishable from a real browser's — either Google Chrome or Mozilla Firefox. For Chrome it uses BoringSslStream, a TLS stream backed by BoringSSL (the TLS library used by Chromium); for Firefox it uses NssStream, backed by NSS (the TLS library used by Firefox). The chosen implementation replicates the browser's ClientHello byte-for-byte, including cipher suites, extensions, GREASE, post-quantum key groups and ALPN/ALPS, so the connection gets a genuine browser JA4/JA3 fingerprint:
SslStream: t13d311100_e8f1e7e78f70_f6eeaf393d2e (default .NET TLS handshake)
BoringSslStream: t13d1517h2_8daaf6152771_cb7bf5808d99 (Chrome-like TLS handshake)
NssStream: t13d1616h2_86a278354501_0c27189014cf (Firefox-like TLS handshake)
Browser-like fingerprinting requires SSL decryption to be enabled (DecryptSSL: true, see Turning on SSL Decryption). Then set TlsClientType to "BoringSsl" for Chrome or "Nss" for Firefox in the SslClientOptions section of appsettings.Production.json:
"SslClientOptions": {
"EnabledSslProtocols": "Tls12,Tls13",
"CheckCertificateRevocation": true,
"ApplicationProtocols": "http/1.1,h2",
"TlsClientType": "BoringSsl"
}Restart the ProxyMapService.exe application for the change to take effect.
- The
TlsClientTypeoption (Native— defaultSslStream,BoringSsl— Chrome-like,Nss— Firefox-like) only affects the outgoing (upstream) TLS connections of decrypted traffic. It does not change how the proxy accepts client connections. - Because BoringSslStream and NssStream replicate the browser's ClientHello, the
EnabledSslProtocolssetting does not apply to them — the TLS versions and cipher suites are chosen exactly as the browser chooses them. TlsClientType: "Nss"uses NssStream — an NSS-backed TLS stream producing a Firefox-like ClientHello. On Linux the native binary links dynamically against the system NSS/NSPR libraries (libnss3, present on virtually every distribution); on Windows the required NSS/NSPR DLLs are shipped inside the NuGet package and are copied to the output directory automatically.- The Firefox-like ClientHello produced by NssStream depends on the version of the linked NSS: features unsupported by the linked NSS version (ECH GREASE, ML-KEM
X25519MLKEM768, ML-DSA signature algorithms, brotli) are silently skipped. For example, on NSS 3.98 the JA4 ist13d1616h2_86a278354501_0c27189014cf, while on NSS 3.101+ it includes ML-KEM and therefore differs. - The negotiated application protocol (ALPN) still follows the
ApplicationProtocolssetting, so HTTP/2 to the server keeps working as before. - Server certificate validation settings (
CheckCertificateRevocation,TrustedCAs, and theIgnoreCertificateErrorsmapping option) remain fully effective with BoringSslStream and NssStream. - The shipped NuGet packages include the native BoringSSL and NSS/NSPR binaries for Windows x64, Linux x64 and macOS ARM64, so no extra dependencies are required.
The repository includes an integration test that captures the TLS ClientHello sent to the upstream server and computes its JA4 fingerprint. Run the test proxy instance, then:
dotnet test ProxyMapService.Tests --filter "FullyQualifiedName~Ja4Fingerprint" -l "console;verbosity=detailed"The test output prints the JA4 fingerprint of the upstream ClientHello (e.g., t13d1517h2_8daaf6152771_cb7bf5808d99 with TlsClientType: "BoringSsl" — Chrome-like, or the NSS-produced fingerprint with TlsClientType: "Nss" — Firefox-like), along with the full list of offered cipher suites and extensions.
To check the JA4 fingerprint of a TLS library directly (as BoringSslStream or NssStream would produce it, without running the proxy), use the BoringSslJa4Probe and NssJa4Probe console utilities:
dotnet run --project BoringSslJa4Probe # Chrome-like: t13d1517h2_8daaf6152771_cb7bf5808d99
dotnet run --project NssJa4Probe # Firefox-like: t13d1616h2_86a278354501_0c27189014cfEach utility starts a local capture server, performs a TLS handshake against it (BoringSSL-backed or NSS-backed respectively), and prints the JA4 fingerprint of the ClientHello along with the full lists of cipher suites and extensions. The BoringSslStream fingerprint is deterministic (it replicates Chrome's ClientHello byte-for-byte); the NssStream fingerprint depends on the version of the linked NSS library.
Some DPI systems classify HTTPS traffic by inspecting the first outgoing TLS record — the ClientHello, which carries the SNI hostname in plaintext. Proxy Map Service can split this first TLS record into several separate TLS records (fragmentation at the TLS protocol level): the resulting records carry the same content type and version as the original record and together reassemble into the identical payload, so any RFC-conforming TLS server accepts them unchanged.
Set the TlsRecordSplit option in the Listen section of a ProxyMappings entry:
"ProxyMappings": [
{
"Listen": {
"Port": 5001,
"TlsRecordSplit": "1,0+sm"
}
}
]The value is a comma-separated list of split positions, each in the syntax offset[:repeats:skip][+flag1[flag2]]:
offset— split position relative to the start of the ClientHello (the TLS record payload, without the 5-byte record header); a negative offset without flags counts from the end of the ClientHello;repeats:skip— optional; repeat the splitrepeatstimes with askipbyte step (e.g.1:3:5splits at positions 1, 6 and 11);- flags:
+s— offset from the start of the SNI hostname;+e— offset from the end of the ClientHello (with+s— from the end of the SNI hostname);+m— offset from the middle of the ClientHello (with+s— from the middle of the SNI hostname);+n— zero offset (the position stays absolute).
Examples:
"1"— split after the first byte of the ClientHello;"3+s"— split 3 bytes after the start of the SNI hostname;"0+sm"— split in the middle of the SNI hostname;"-5"— split 5 bytes before the end of the ClientHello.
The setting can be overridden per host via a HostRule ("TlsRecordSplit": "..." next to DecryptSSL); when the rule does not set it, the Listen value is inherited.
- The split is applied to the outgoing (upstream) TLS connection and works in both modes:
- with SSL decryption enabled (
DecryptSSL: true) — the proxy generates the ClientHello itself (see Chrome-like and Firefox-like TLS Fingerprint) and the split is applied underneath the TLS implementation; - in passthrough mode (no decryption) — the client's own ClientHello travels through the tunnel and is re-chunked on the fly.
- with SSL decryption enabled (
- Each resulting TLS record is written separately, so DPI sees them as distinct packets rather than one reassembled ClientHello.
- Only the first TLS record (the ClientHello) is split; all subsequent records pass through unchanged.
- If the specification resolves to nothing to split (e.g. all positions reference the SNI hostname but the record has none, or a position falls on the record boundary), the record is sent as-is.
- When the split is active, the proxy logs it at debug level (enable TlsHandshakeLog to see it).