SSL Proxying

HTTPS is encrypted between your app and the server. A proxy can only look inside it if you let it. SSL Proxying is where you say which hosts that applies to. Hosts you have not listed still appear in the capture as tunnels, with their host, port, timing and byte counts, but no headers and no bodies.

How decryption works#

When an app connects to a host on your Include list, WireLens answers the handshake itself with a certificate for that host, signed by your WireLens certificate. It then makes its own secure connection to the real server and passes everything through, recording both sides on the way.

That works only if the device trusts the WireLens certificate. If you have not done that yet, start with The WireLens root certificate.

Add a host from the traffic#

The quickest way is from a row you already captured:

• Mac: right-click a flow, or a domain in the sidebar, and choose Enable SSL Proxying for ‹host›.
• iPhone and iPad: long-press a host or a request and choose Enable SSL Proxying.
• Android: long-press a host or a request and choose Enable SSL Proxying.

The next connection to that host is decrypted, with nothing to restart. An app that keeps its connection open sees the change once it reconnects: send the request again or reopen the app.

The Include list#

Patterns are host names only, with no scheme, port or path. Adding *, or a pattern broad enough to match sites across many domains such as *.com or www.*, decrypts every host, and does not use one of your include patterns. WireLens asks first, because apps that pin their certificates may stop working. The command line and MCP print the same warning.

An entry you switch off stays on the list without being used. Switch it back on when you need it again.

The Exclude list#

A host on the Exclude list is always tunnelled, even when the Include list matches it. Use it for anything that should pass through untouched, such as a service that pins its certificate, or a host whose traffic you would rather not record in detail. Its connections still appear in the capture as CONNECT rows.

WireLens also keeps its own list of Apple services and DNS-over-HTTPS hosts that break when decrypted, shown as System excludes on the Mac and System Excludes on iPhone. It applies on top of your Exclude list and does not count towards the free plan's Exclude limit.

Why a row was not decrypted#

A tunnelled row says why in its status chip:

Certificate pinning#

Some apps trust only their own certificate. When WireLens decrypts one of their hosts, the app refuses to connect and stops loading. That is the app protecting itself, and every debugging proxy runs into it.

• WireLens watches for it. A host that refuses the WireLens certificate twice is passed through for the rest of the session. The app keeps working, and the host is still captured as a tunnel, marked Pinned (Not trusted on Android).
• To make that permanent, leave those hosts off the Include list, or add them to Exclude.
• Decrypt the apps you build. Debug builds usually do not pin, or can be told not to.
• If a host starts failing right after you decrypt it, pinning is the likely reason.

Each platform has its own control for this:

• Mac: on by default. Apps that pin their certificates covers the two cases you can still decrypt: an app pinned to a certificate authority you control (import it as a custom root), and an app pinned to a certificate you hold (add a server certificate override). An app pinned to a key you do not have stays on passthrough.
• iPhone and iPad: the Auto-passthrough Pinned Hosts switch in Tools ▸ SSL Proxying. Turn it off when a failure should stay a failure, for example while you check that your app's pinning holds. Adding a host to Include again clears the mark and retries it.
• Android: the Keep apps working switch in Tools ▸ SSL Proxying, on by default. A host whose app refuses the certificate is passed through for that app. The hosts are listed under Refused the certificate, and Try decrypting them again forgets them.

Servers with self-signed certificates#

A development server or appliance with a self-signed or expired certificate fails WireLens's own check of the server. Add that host to the invalid origin certificate exceptions and WireLens decrypts it without checking the server's certificate. A bare * is refused. These exceptions share the free plan's Include allowance.

• iPhone and iPad: long-press the host and choose Allow Invalid Origin (Unsafe), or add it under Invalid Origin Certificates in Tools ▸ SSL Proxying with Allow Invalid Origin. Require Valid Origin Certificate takes the exception away.
• Mac: use wirelens rules insecure add <host> or the MCP tool set_invalid_origin_exceptions.

On the Mac#

Open Tools ▸ SSL Proxying (⇧⌘T opens the Tools window).

• Enable SSL Proxying is the master switch. The SSL Proxying button in the toolbar and the same item in the menu bar status menu are the same setting. While it is off, nothing is decrypted, not even hosts on the Include list, and every HTTPS row reads Decrypt off. The main window shows a banner with a Turn On button for as long as it stays off.
• SSL Proxying List switches between Include List and Exclude List. Type a host or paste URLs into the field above the list and press Add, or use Browse Capture… to pick apps and domains this capture has seen. Patterns take * and ?.
• An app can go on either list. An app on the Include list has everything it sends decrypted, and one on the Exclude list is never decrypted. An app on the Include list takes one of the free plan's Include slots.
• Seen in this capture, not decrypted suggests hosts you can add with one click.
• Check a host says whether a host would be decrypted right now, and which entry decides it.
• Match the client's TLS fingerprint is covered in TLS fingerprint.

On iPhone and iPad#

Open Tools ▸ SSL Proxying. The screen has the Include List, the Exclude List, Invalid Origin Certificates, Auto-passthrough Pinned Hosts and System Excludes. The + menu offers Add Include, Add Exclude and Allow Invalid Origin.

Decryption needs full trust for the certificate in Settings ▸ General ▸ About ▸ Certificate Trust Settings. Until it is on, the list says so at the top. If SSL Proxying itself is off, the same place shows Turn On SSL Proxying.

* covers every host name, but not a connection made straight to an IP address. Add the IP itself for that.

On Android#

Open Tools ▸ SSL Proxying. Under Decryption, the SSL Proxying switch turns decryption on and off, and Keep apps working handles apps that refuse the certificate. Under Lists are Include and Exclude. Why some apps stay encrypted explains which apps trust a certificate you installed. To make your own app trust it, see Things Android decides.

To stop decrypting a host from the traffic, long-press it and choose Don't Decrypt Host. That adds it to the Exclude list.

Free and Pro#

The same on all three platforms:

From the command line#

On the Mac, wirelens ships inside the app and is not on your PATH until you link it once.

wirelens rules ssl add api.example.com
wirelens rules ssl rm api.example.com
wirelens rules bypass add pinned.example.com
wirelens rules insecure add dev.example.com

rules bypass adds to the Exclude list. The MCP server offers the same lists as set_ssl_include, toggle_ssl_host and set_invalid_origin_exceptions. See Command line and MCP for AI agents.