HTTPS Capture Rules: Rewrite, Mock, Route and Intercept Live Traffic

The Rules page is where HTTPS Capture stops being a viewer and becomes a debugger. From the Capture tab, tap Rules to open a hub of rule types that can rewrite headers and bodies, block or redirect URLs, mock responses without a server, forward requests to a different backend, replay recorded sessions offline, pause requests for editing, simulate slow networks and decrypt AES payloads — all applied live to the running capture.

Profiles: the container for rules

Every rule lives in a profile. A profile bundles all rule types together — rewrite rules, scripts, filters, hosts, mock responses, forwarding, replay settings, breakpoints, AES keys — plus the network simulation configuration. Switch profiles from the menu at the top of the Capture tab; each context you debug (a test environment, a client project, a demo) can have its own set.

The rules described here edit the current profile. When you connect to a different Wi-Fi or reinstall the app, profiles sync through iCloud, rules included.

How rules take effect — and in what order

Rule edits save to the profile and publish immediately to the capture engine: no VPN restart is needed. A request that is already in flight keeps the old behavior; the next request sees the new rules.

When a request arrives, the engine evaluates the rule types in a fixed order. The first stage that produces a local response short-circuits everything after it:

1. Capture scripts run first and may rewrite routing (see Capture Scripts).
2. Request Map serves a local mock response if a rule matches — no connection to a real server is made.
3. URL Rewrite intercept actions (Reject, Drop Connection, redirects) answer or kill the request locally.
4. Server Replay returns a recorded response if the request matches the active replay library.
5. Map Remote forwards the request to a different server.
6. Breakpoint may pause the request for manual editing.
7. The request finally goes upstream, where URL Rewrite header/body rules, Hosts resolution and Network Simulation shape what is actually sent.

To see which rules would fire for a given URL, open Rules → Test Rule Matching (in the Diagnostics section). Enter a URL and method — or pick one of your captured requests — and the preview lists every script, mock, rewrite and forwarding rule with URL match / No match / Disabled outcomes, without sending any traffic. It even previews whether header values would change for the selected request.

URL Rewrite

Rules → URL Rewrite edits request and response headers, rewrites text bodies, and blocks or redirects matched URLs. Each rule has three parts:

• URL Match — a URL Pattern plus a match type: Contains (substring anywhere in the request URL) or Regex (regular expression, any hit counts). An empty pattern matches nothing, so a rule can never silently apply to all traffic.
• Rewrite Type — which part of the exchange the rule touches: URL, Request Header, Request Body, Response Header or Response Body.
• Action — what to do.

Rule order matters

Rules apply in list order. Drag the handles in edit mode to rearrange:

• Header rules stack: every enabled matching header rule applies, one after another. Use several rows to add one header and rewrite another.
• Body and URL actions are first-wins: the first matching rule that can act on the phase finishes it. Later rules on the same phase are skipped.

Actions by rewrite type

URL — answer or kill the request without contacting any server:

Action	Effect
Reject	Returns a plain “Rejected” page. Optional Status Code field (100–599) lets you answer 403, 500, 444-like codes and more
Reject (Tiny GIF)	Returns a 1×1 transparent GIF — classic image-ad blocker
Reject (Empty Object)	Returns {} with application/json
Reject (Empty Array)	Returns [] with application/json
Drop Connection	Sends nothing at all and closes the connection — the client sees a reset, like nginx’s 444
Redirect 301 / 302 / 307	Answers with that status plus a Location header set to the Replace value

Request Header / Response Header:

Action	Fields	Effect
Add / Overwrite	Name, Replace	Sets the header, replacing any existing values
Remove	Name	Deletes the header
Replace	Name, Match, Replace	Rewrites the value only when it exactly equals Match
Replace (Regex)	Name, Match, Replace	Rewrites matched parts of the value; $1-style group references work in Replace

Request Body / Response Body: text-level Replace (exact string) and Replace (Regex). The engine decompresses gzip/deflate/brotli, performs the replacement on the text, recompresses and recalculates Content-Length for you.

Validation and limits

The editor refuses to save a rule with an empty URL pattern, an uncompilable regex, an invalid header name or an out-of-range status code — dead rules cannot sneak into the list. At runtime:

• Body rewriting works on UTF-8 text up to 4 MB; larger or binary bodies pass through untouched.
• A header rule alone never blocks a response body rule: both either apply or both pass through, so you never get a half-rewritten response.
• Redirect targets and header values containing line breaks are rejected — header injection is not possible.
• HEAD requests skip body rules (nothing to rewrite).

Common recipes

• Debug flag every request to an API: URL Match api.example.com, Type Request Header, Add / Overwrite X-Debug = 1.
• Kill an analytics SDK: Regex .*telemetry\.example\.com.*, Type URL, Reject (Tiny GIF).
• Point the app at staging: keep reading — that is Map Remote’s job, not a URL rule.
• Simulate a server error: Regex api\.example\.com/v1/payments, Type URL, Reject with Status Code 503.

URL Filter

Rules → URL Filter controls which URLs are captured — it never changes forwarding. Use a whitelist to record only the hosts you care about, or a blacklist to silence a noisy SDK. When the whitelist is enabled with active rules, only matching URLs are recorded; the blacklist then does not apply. Filtering only skips recording — the traffic itself still flows normally.

DNS queries participate in the same filter, matched as dns://<domain>.

Routing

Hosts

Rules → Hosts maps a domain to a different IP or hostname at the connection layer: *.api.example.com → 192.168.1.50. The Host header and TLS SNI keep the original domain, so virtual hosting and certificates still work — ideal for pointing an app at a test machine without touching DNS.

Request Map

Rules → Request Map serves a local response for a matched URL — a mock server without the server. Each rule defines status code, content type, custom headers, and either a text body or a binary file picked from Files or Photos, plus an optional response delay to simulate latency. The first matching rule wins. A matching Request Map bypasses rewrite interception, replay, forwarding and breakpoints entirely — the recorded entry even shows the local response like any other.

Map Remote

Rules → Map Remote forwards matched requests to a different server and relays responses back — the Charles-style map remote. The rule replaces the first occurrence of the matched substring (or regex match) in the URL, so:

• https://api.example.com → https://staging.example.com — switch environment
• /v1/ → /v2/ — path-level rewrite
• https:// → http://localhost:8080 — route through a local dev server

The session list keeps showing the original URL with a Mapped badge, and the detail view shows the actual destination. If a mapping produces an unusable URL, the rule fails open and the request simply goes to its original destination.

Server Replay

Rules → Server Replay turns a recorded session or an imported HAR file into an offline mock backend. Matching requests (method + URL, with sorted query comparison so reordered parameters still match) receive the recorded response — the real server is never contacted. Options control whether entries can be replayed repeatedly, whether date-like headers (Date, Expires, cookie expiry) are refreshed to the replay time, whether the request body must match, and what happens on a miss: forward to the real server, kill the connection, or answer a custom status code. Record once, then debug your app on a plane.

Network Simulation

Rules → Network Simulation degrades new upstream connections on demand: first-write latency, downlink/uplink bandwidth limits and a connection-failure rate, globally or per domain. Presets cover 3G, EDGE, LTE and a Very Bad 2000 ms / 10 % failure profile; Custom accepts latency up to 30 s, 1 Gbps limits and 0–100 % failure. The throttle applies per connection (an HTTP/2 multiplexed connection shares one budget) and only to connections established after saving.

Breakpoint

Rules → Breakpoint pauses matched requests or responses until you decide. While paused, the request appears in a pending queue with Pass / Drop buttons and an Edit & Pass editor where you can rewrite method, URL, headers, status and text bodies before releasing it. The engine auto-passes after 10 minutes so nothing hangs forever. Perfect for hand-crafting one specific error response exactly once.

AES Cipher

Rules → AES Cipher registers AES keys used to decrypt request or response bodies in the detail view only — the wire payload is never modified. Rules match by URL and direction; each rule specifies key and IV (raw or base64: prefixed), key length, CBC or ECB mode, and PKCS7 or no padding. When a captured body matches, the body view shows an AES Decrypt toggle.

Import and export

The menu at the top right of the Rules page exports the current profile’s complete ruleset — filters, rewrite rules, scripts, hosts, request maps, map remotes, network simulation, breakpoints, AES keys and the selected replay library — as a hand-editable .yaml file, or as a .zip (YAML plus binary attachments) when mock bodies or replay entries are attached. Import creates a new profile and never overwrites the current one, so you can share a debugging setup with teammates or keep per-client configurations in your repository.

Note that the export contains secrets in plain text — AES keys and script sources included — so share exports only over trusted channels.

Where to go next

• Capture Scripts — when rules are not enough: full JavaScript hooks that rewrite any part of a request or response.
• Quick Start — the setup path for the VPN tunnel and CA certificate if you skipped it.