# Network Proxy

> CatSuite Network Proxy: how to configure the MITM proxy, the CA certificate, Full Capture of HTTP and HTTPS, the replacement rules and response pausing.

- Language: en
- Canonical URL: https://netcattest.com/catsuite/en/docs/modules/proxy
- Section: Modules
- Updated: 2026-10-06
- Other language (pt-BR): https://netcattest.com/catsuite/docs/modulos/proxy

The **Network Proxy** is the module that turns your Android device into an **MITM proxy** for HTTP and HTTPS in the lab. It opens a listener on the local network, decrypts authorized traffic with its **own exportable certificate authority (CA)**, offers **Full Capture of HTTP and HTTPS**, lets you define **replacement rules** on requests, responses, headers and cookies, and supports **response pausing for editing**. The captured traffic feeds the [Interceptor](https://netcattest.com/catsuite/en/docs/modules/interceptor) and [History](https://netcattest.com/catsuite/en/docs/modules/history) in real time. This page explains each concept, each option and how to use and configure the Network Proxy step by step, always against authorized targets.

> [!WARNING]
> Install the lab CA only on test devices you control and remove it when you are done. Capture, decrypt and modify only traffic from targets you have written authorization to test. See [Security and responsible use](https://netcattest.com/catsuite/en/docs/security).

## What the Network Proxy is and what it is for

A proxy is a middleman: the client device sends its requests to CatSuite, which forwards them to the destination and returns the response. Because the Network Proxy sits **in the middle** of the conversation (MITM, _man-in-the-middle_), it can **read, log and alter** every message before forwarding. That is how you observe, in the lab, exactly what an app or browser on another device sends and receives.

The module solves a practical problem: not all traffic comes from the built-in [Browser](https://netcattest.com/catsuite/en/docs/modules/browser). Phones, tablets or other apps on the same local network can point their proxy to this device, and from then on all authorized traffic shows up in CatSuite. Typical use cases:

- Capture the HTTP and HTTPS traffic of a second test device pointed at the proxy.
- Inspect what a native app sends, not just the browser.
- Automatically rewrite a header, a cookie or a body snippet with **replacement rules**.
- Pause a response to edit it before the client receives it.
- Forward interesting requests to the [Repeater](https://netcattest.com/catsuite/en/docs/modules/repeater) and the [Intruder](https://netcattest.com/catsuite/en/docs/modules/intruder).

The listener runs **only while the CAT Suite is in the foreground**. When the app loses focus, the service is suspended and resumes automatically when it returns — it never stays hidden in the background.

## Essential Network Proxy concepts

Before you configure anything, it helps to understand the terms on screen. Each concept below maps directly to a panel, button or option in the module.

### MITM proxy and the capture pipeline

When the proxy is active, each authorized connection enters a **pipeline**: the connection is received, the request is read, the applicable **replacement rules** run, the message goes to the [Interceptor](https://netcattest.com/catsuite/en/docs/modules/interceptor) (which can pause it) and, finally, it is forwarded to the destination. The response travels the reverse path. All of this happens inside the device, with no intermediate servers.

### Certificate authority (CA) and why you install it

To read the content of an **HTTPS** connection, the proxy must present the client a certificate it trusts. CatSuite generates its own **certificate authority (CA)** and, at connection time, mints an on-the-fly certificate for the visited host, signed by that CA. The client only accepts this certificate if the **CA is installed as trusted** on its system.

That is why the CA is the central step for HTTPS: without installing it, the client refuses the certificate and the TLS handshake fails. The CA is **created when the proxy is first started**, can be **exported** as a `.crt` file, has a **fingerprint** for verification, and can be **regenerated** when needed.

> [!IMPORTANT]
> A CA installed as trusted allows intercepting that device's HTTPS. Treat the lab CA as a secret: install it only where you control and need it, and remove it as soon as you finish the work.

### Device pairing and credentials

Before accepting traffic, each device must be **paired**. Pairing generates a credential with three parts: a **temporary code**, a **username** and a **password**. The code authorizes the device's **IP** during the session; the username and password remain as an alternative credential for compatible tools. The password is shown **only at pairing time**. There is also a **QR Code**, which fills in the pairing quickly without sending the password. Each device gets its own credential, which can be **revoked** at any time.

### Full Capture of HTTP and HTTPS

**Full Capture** is the mode that makes **all** authorized HTTP and HTTPS traffic flow through the proxy and be recorded, rather than a one-off interception. Combined with the **Save to history** option, it keeps request, response and metadata in the shared [History](https://netcattest.com/catsuite/en/docs/modules/history). Full Capture is available **only on Android**.

### Replacement rules

A **replacement rule** rewrites traffic automatically as it passes through the proxy. You create the rules in **Settings > Replacement rules** and choose **which part of the traffic** each rule changes: the **request**, the **response**, the **headers**, the **Cookie** header or the **first line** of the request. Each rule has a **Find** field and a **Replace** field and can be **literal** (swap the exact text) or a **regular expression**. When a rule is enabled, it enters the traffic flow automatically. Matching rules run **top to bottom**, and you set each one's position in the sequence.

> [!NOTE]
> When there are [extensions](https://netcattest.com/catsuite/en/docs/extensions) processing the proxy, the applicable replacement rules run before the handlers, and manual editing in the [Interceptor](https://netcattest.com/catsuite/en/docs/modules/interceptor) prevails over both.

### Response pausing for editing

With response interception on, the **MITM proxy pauses every response at its headers**: the response is held so you can review and edit status, headers and body before delivering it to the client. Streaming bodies and large downloads are preserved without editing and shown as **read-only**. The editing happens in the [Interceptor](https://netcattest.com/catsuite/en/docs/modules/interceptor).

### Bypassed hosts and CONNECT ports

Not every destination should be decrypted. In **Bypassed hosts** you list the hosts that should pass **in a tunnel** (no MITM), one per line, accepting wildcards like `*.example.com`. The **CONNECT ports** define which ports are accepted for the HTTPS tunnel (the `CONNECT` method); the default covers the most common secure ports.

## The Network Proxy screen: dashboard, pages and tabs

The module has an **operational dashboard** and a **settings hub** with five pages. You open the settings from the dashboard's gear icon and return with the back button on each page.

### Operational dashboard

It is the first screen. From top to bottom it gathers: the **header** (service state in one line), the **operation card**, the **statistics grid**, the **diagnostics card** and the **quick access** (shortcuts to Trusted clients and to HTTPS and certificates).

### Operation card and proxy address

Shows the current state — **SERVICE ACTIVE**, **SERVICE SUSPENDED** or **SERVICE INACTIVE** — and the **PROXY ADDRESS** (in `address:port` format) that clients should use. With the proxy active, the setup page URL appears, along with the **copy** address button and the **Open setup page** button. The main button toggles between **START NETWORK PROXY** and **STOP NETWORK PROXY**.

### Session statistics

Five indicators track the service in real time: **Clients with active traffic**, **Active connections**, **Requests this session**, **Connections received** and **Traffic received / sent** (in human-readable bytes).

### Diagnostics card

Summarizes forwarding health in one line (for example, _Waiting for a device_, _Setup page reachable_, _Device authorized_, _Proxy working_) and, with the proxy active, shows three badges: **HTTP**, **HTTPS** and **INTERNET**, each marked `OK` or `PENDING`. It is the quick way to know whether the client reached the listener, whether HTTPS was validated and whether the destination is reachable.

### Settings hub

Opens five pages: **SERVICE**, **LOCAL NETWORK**, **HTTPS AND CERTIFICATES**, **TRUSTED CLIENTS** and **HISTORY AND PRIVACY**. Port, interface and HTTPS rules can only be changed with the **proxy stopped**; the pages warn when an option is locked.

## Network Proxy options and how to configure them

The table gathers the options from the settings pages, with values, default and effect.

| Option | Values | Default | What it does |
| --- | --- | --- | --- |
| Start automatically | On, Off | Off | Starts the proxy when CAT Suite opens, if the module is active |
| Proxy port | 1024 to 65535 | 8080 | Local port where the listener accepts connections |
| Network interface | Automatic or a detected Wi-Fi/Ethernet interface | Automatic | Local address the proxy listens on |
| Intercept HTTPS traffic | On, Off | On | Decrypts HTTPS with the CA; off keeps the destination in a tunnel |
| Bypassed hosts | list of hosts, one per line (accepts `*.domain`) | empty | Hosts that pass in a tunnel, without decrypting |
| CONNECT ports | comma-separated ports | 443, 8443, 9443 | Ports accepted for the HTTPS tunnel (`CONNECT` method) |
| Save to history | On, Off | On | Keeps request, response and metadata in the shared History |
| Mask sensitive data | On, Off | On | Hides known credentials in the view and common exports |
| Stored body limit | 256 KiB, 1 MiB, 4 MiB, 8 MiB | 1 MiB | Maximum stored body size; above it the content is truncated |
| Storage quota | 250 MiB, 500 MiB, 1 GiB, 2 GiB | 1 GiB | Total space reserved for captured bodies |
| Maximum records | 1,000, 5,000, 10,000, 25,000, 50,000 | 10,000 | Maximum number of entries kept |
| History retention | Current session, 1 day, 7 days, 30 days, Manual | 7 days | How long the captures stay saved |

### Service

On the **SERVICE** page, turn on **Start automatically** if you want the proxy to come up with the app (only when the module is active). The action card shows **PROXY RUNNING** or **PROXY STOPPED** and offers **START NOW** / **STOP NOW**, mirroring the dashboard button. Remember that the listener only works while the app is open.

### Local network

On **LOCAL NETWORK**, set the **Proxy port** (a value between 1024 and 65535; the default is 8080) and the **Network interface**. Leave it on **Automatic** to let CatSuite pick the appropriate local interface, or select a specific Wi-Fi/Ethernet one by name and address. Both options can only be changed with the proxy stopped; the listener binds to a single local interface, never to every network on the device.

### HTTPS and certificates

On **HTTPS AND CERTIFICATES**, the **Intercept HTTPS traffic** switch turns decryption on or off: on, the proxy uses this installation's CA; off, it keeps destinations in a tunnel. Under **Bypassed hosts**, enter one host per line (wildcards like `*.example.com` are accepted) to keep sensitive destinations out of the MITM. Under **CONNECT ports**, list, comma-separated, the HTTPS ports accepted for the tunnel. At the bottom of the page is the **CERTIFICATE AUTHORITY** card, with the CA's name and **fingerprint** and the **COPY FINGERPRINT**, **EXPORT CA** and **REGENERATE CA** buttons. These HTTPS options require the proxy stopped.

### History and privacy

The **HISTORY AND PRIVACY** page controls what stays saved, without changing forwarding. **Save to history** keeps the captures in the [History](https://netcattest.com/catsuite/en/docs/modules/history). **Mask sensitive data** hides known credentials in the view and common exports. The **Stored body limit**, **Storage quota**, **Maximum records** and **History retention** selectors set the maximum size of each body, the total space, the number of entries and how long everything is kept. Bodies above the limit are forwarded normally and stored as truncated content.

## Buttons and actions

| Button | Where | What it does |
| --- | --- | --- |
| START / STOP NETWORK PROXY | Dashboard and Service page | Brings up or shuts down the listener |
| Copy | Dashboard (proxy active) | Copies the proxy address |
| Open setup page | Dashboard (proxy active) | Opens the proxy's web setup page |
| EXPORT CA | HTTPS and certificates | Shares the CA certificate (`.crt`) to install on the client |
| COPY FINGERPRINT | HTTPS and certificates | Copies the CA fingerprint for verification |
| REGENERATE CA | HTTPS and certificates | Creates a new CA and invalidates current clients and certificates |
| PAIR NEW DEVICE | Trusted clients | Generates code, username, password and QR Code for the device |
| OPEN QR CODE | Credentials dialog | Shows the temporary pairing QR Code |
| Revoke client | Trusted clients | Removes a paired device's authorization |

## Step by step

### 1. Start the proxy and read the address

1. Open the **Network Proxy** and tap **START NETWORK PROXY**.
2. Check the **SERVICE ACTIVE** state and copy the **PROXY ADDRESS** shown (`address:port`).
3. If the start fails, read the message: port in use, interface unavailable or local-network access denied tell you what to adjust.

### 2. Generate, export and install the CA

1. Once the proxy has started at least once, the CA is prepared automatically.
2. Go to **HTTPS AND CERTIFICATES** and tap **EXPORT CA** to share the `.crt` file.
3. On the client device, install the file as a **trusted CA** (see [Getting started](https://netcattest.com/catsuite/en/docs/getting-started)).
4. Confirm the **fingerprint** with **COPY FINGERPRINT** to be sure you installed the right CA.

### 3. Pair a device

1. On **TRUSTED CLIENTS**, tap **PAIR NEW DEVICE** and give it an easy-to-recognize name.
2. Note the **Temporary code**, the **Username** and the **Password** (the password appears only now).
3. Tap **OPEN QR CODE** to pair quickly, or type the code on the device's setup page.
4. On the client, set a manual proxy with the address and port copied from the dashboard.

### 4. Capture HTTP and HTTPS with Full Capture

1. Keep **Intercept HTTPS traffic** on and **Save to history** on.
2. Generate traffic on the client device pointed at the proxy.
3. Watch the **HTTP**, **HTTPS** and **INTERNET** badges on the diagnostics card until they read `OK`.
4. Analyze the captures in the [Interceptor](https://netcattest.com/catsuite/en/docs/modules/interceptor) and the [History](https://netcattest.com/catsuite/en/docs/modules/history).

### 5. Create a replacement rule

1. Go to **Settings > Replacement rules** and create a rule.
2. Choose the scope (request, response, headers, Cookie or first line).
3. Fill in **Find** and **Replace** and select literal or regular expression.
4. Enable the rule and adjust its position in the sequence; rules run top to bottom.

### 6. Pause and edit a response

1. In the [Interceptor](https://netcattest.com/catsuite/en/docs/modules/interceptor), turn on response interception.
2. Generate the request on the client; the response stops at its headers.
3. Edit status, headers and body and forward. Streaming or very large bodies stay read-only.

### 7. Regenerate or remove the CA

1. On **HTTPS AND CERTIFICATES**, tap **REGENERATE CA** to create a new CA.
2. Confirm in the warning: all current clients and certificates will no longer be trusted.
3. Install the new CA and pair the devices again.
4. When you finish the work, remove the lab CA from the test devices.

## Examples

Proxy address and setup page URL shown on the dashboard while the service is active:

```text
192.168.0.42:8080
http://192.168.0.42:8080/
```

Manual proxy configuration on the client device:

```text
Server: 192.168.0.42
Port: 8080
```

List of hosts kept in a tunnel, without decrypting:

```text
*.google.com
accounts.example.com
10.0.0.5
```

Literal replacement rule that rewrites an origin header:

```text
Scope: headers
Find: X-Forwarded-For: 127.0.0.1
Replace: X-Forwarded-For: 203.0.113.9
```

Response paused in the Interceptor, ready for editing before forwarding:

```http
HTTP/1.1 200 OK
Content-Type: application/json

{"profile":"default"}
```

## Common problems and FAQ

**The proxy does not start.** Read the message: _port in use_ (pick another between 1024 and 65535), _no local Wi-Fi or Ethernet interface available_, _Android did not allow local-network access_ or _the capture pipeline is not ready yet_ (try again).

**HTTPS does not validate (HTTPS badge `PENDING`).** The client reached the proxy, but CA trust or the TLS handshake failed. Confirm the CA was installed as trusted on the client and that the host is not in the bypass list.

**The device does not show as authorized.** The client reached the listener but was not authorized in this session yet. Validate the **temporary code** on the device's setup page.

**No traffic arrives at all.** Check that both devices are on the same local network and use exactly the IP and port shown on the dashboard. The **INTERNET** badge at `PENDING` means the destination was not reached over the chosen interface.

**The service stopped by itself.** The Network Proxy is suspended when CAT Suite leaves the foreground and resumes when it returns. It never runs hidden in the background.

**I need to change the port or interface and the fields are locked.** Stop the Network Proxy before changing port, interface or HTTPS rules.

**I switched networks and pairing stopped working.** The interface or address changed. Start the proxy again and pair the devices once more.

## Best practices and security

> [!DANGER]
> Decrypting third-party HTTPS without authorization is illegal and unethical. Pair, decrypt and modify traffic only from devices and targets you are authorized to test. Misuse can cause blocks, instability or violation of applicable rules and contracts.

- Install the lab CA only on test devices you control and remove it when you are done.
- Keep the **Bypassed hosts** list for sensitive destinations that should not be decrypted.
- Leave **Mask sensitive data** on when sharing screens or exporting captures.
- Revoke credentials of devices no longer in use.
- Tune retention, quota and maximum records to the size of the job so storage does not fill up.

## Next step

- [Interceptor](https://netcattest.com/catsuite/en/docs/modules/interceptor)
- [History and notes](https://netcattest.com/catsuite/en/docs/modules/history)
- [Browser](https://netcattest.com/catsuite/en/docs/modules/browser)
- [SSL/TLS](https://netcattest.com/catsuite/en/docs/modules/ssl-tls)
- [Security, vault and data protection](https://netcattest.com/catsuite/en/docs/security)
- [Getting started](https://netcattest.com/catsuite/en/docs/getting-started)