Rules and matching

Every debugging tool except No Caching and DNS Spoofing works with rules. A rule has a name, an on/off checkbox and a matcher that decides which requests it applies to. This page explains matchers, the order rules and tools run in, and how to create rules from captured traffic and share them as JSON.

The matcher

Every rule editor starts with a Rule section: a name field and the matcher.

12345

The matcher is the same in every tool: method, URL pattern, mode, subpaths and a live tester.

1. Method: ANY or one HTTP method.
2. URL pattern.
3. Mode: Wildcard or Regex.
4. Include subpaths (wildcard mode only).
5. Test a URL: shows Matches or No match as you type.

×

Field	Options	What it does
Name	Any text	Shown in the rule list, in the Breakpoint window, in alert notifications and in the script console.
Method	ANY, GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS	ANY matches every method. Any other choice matches only that method (case doesn’t matter).
URL	A pattern, for example https://api.example.com/v1/*	The pattern to match. An empty URL matches nothing.
Mode	Wildcard (default), Regex	How the URL is read.
Include subpaths (adds a trailing *)	On (default for new rules) or off	Wildcard mode only. Also matches everything below the URL.

Matching is always case-insensitive. The URL a rule sees is the full request URL: scheme, host, a port when it isn’t the default (:443 for HTTPS, :80 for HTTP), path and query string.

Match with wildcards

In Wildcard mode, the pattern must match the whole URL, and * stands for any run of characters, including / and ?. Every other character, including ? and ., is literal.

• Leave out the scheme to match both http and https. A pattern like api.example.com/v1/* is compared with the URL minus its http:// or https://.
• Include subpaths adds a * to the end of the pattern (unless it already ends with one), so the rule also matches longer paths and any query string.
• Without subpaths, the query string is ignored: the pattern is compared with the URL up to the ?. If your pattern contains a ? itself, the query is kept so you can match it.

Pattern	Subpaths	Matches	Doesn’t match
api.example.com/v1/*	Either	https://api.example.com/v1/users, http://api.example.com/v1/users?page=2	https://api.example.com/v2/users
https://api.example.com/v1/users	Off	https://api.example.com/v1/users, https://api.example.com/v1/users?page=2	https://api.example.com/v1/users/42, http://api.example.com/v1/users
https://api.example.com/v1/users	On	https://api.example.com/v1/users/42, https://api.example.com/v1/users?page=2, and also https://api.example.com/v1/users-archive	https://api.example.com/v1/teams
https://api.example.com/v1/users/	On	https://api.example.com/v1/users/42	https://api.example.com/v1/users-archive
*.example.com/*	Either	https://cdn.example.com/app.js, https://staging.example.com/	https://example.com/ (no subdomain)
api.example.com/search?q=*	Off	https://api.example.com/search?q=shoes	https://api.example.com/search
localhost:3000/*	Either	http://localhost:3000/api/users	http://localhost:8080/api/users

Tip

With subpaths on, end the pattern with / to stay inside a folder. …/v1/users also matches …/v1/users-archive; …/v1/users/ doesn’t.

Match with a regular expression

In Regex mode, the pattern is a regular expression searched for anywhere in the full URL, case-insensitive. It isn’t anchored, so example matches any URL containing that word. Add ^ and $ to anchor it. Include subpaths is hidden in this mode.

Pattern	Matches
^https://api\.example\.com/v[12]/users	Users endpoints in v1 and v2 of the API.
/orders/\d+(\?.*)?$	A single order by numeric ID, with or without a query string.
graphql	Any URL containing graphql.
^http://	Every plain-HTTP request.

Escape dots (\.) when you mean a literal dot. A pattern that isn’t a valid regular expression matches nothing.

Test a pattern

Type or paste a full URL, including its scheme, into the Test a URL field under the pattern. Cloak Proxy shows Matches in green or No match in red, and updates as you edit the pattern, mode or subpaths setting. The tester checks the URL only; the method isn’t part of the test.

Manage rules

To	Do this
Add a rule	Click + under the rule list, or Add Rule when the list is empty.
Delete a rule	Select it and click −, or right-click it and choose Delete.
Duplicate a rule	Select it and click the duplicate button, or right-click it and choose Duplicate. The copy gets “ copy” added to its name.
Turn one rule off	Clear its checkbox. The tool’s other rules keep working.
Turn the whole tool off	Use the On/Off switch in the tool’s header. Rules are kept.
Change the order	Drag rules up or down in the list.

New rules are named after the tool (New Breakpoint, New Map Local, New Map Remote, New Script, New Block Rule, New Allow Rule, New Condition, New Alert) and start with an empty URL.

Rule order inside a tool

Rules are checked from the top of the list to the bottom. Whether one rule or all matching rules apply depends on the tool:

Tool	Which rules apply
Breakpoint	The first enabled rule that matches. Its Pause on settings decide whether the request, the response, or both pause.
Map Local	The first matching rule. If it’s a Directory rule with no file for the path, the request carries on as if Map Local hadn’t matched; later Map Local rules aren’t tried.
Map Remote	The first matching rule.
Scripting	Every matching script, top to bottom. Each script receives the output of the one before it.
Block List	The first matching rule.
Allow List	Any matching rule. The request is recorded if at least one matches.
Network Conditions	The first matching rule.
DNS Spoofing	One address per host. If the same host appears twice, the lower row wins.
Mock Sets	The first set (top to bottom) that has a recording for the request, or that answers it with an offline 404.
Alerts	Every matching rule fires.

Tip

Put specific rules above general ones. A Map Local rule for api.example.com/v1/users/42 must sit above one for api.example.com/v1/*, or the general rule always wins.

What happens when several tools match

One request can match rules in several tools. Cloak Proxy runs them in this order:

Step	Tool	Effect on the rest
1	Block List	A match answers with 403 or drops the connection. Nothing after this runs.
2	Network Conditions: packet loss	If the request is chosen to be lost, the connection is dropped after the rule’s latency. Nothing after this runs.
3	Scripting: onRequest	Every matching script with Run onRequest on, top to bottom.
4	Breakpoint: request	Pauses for you. Abort ends the request here.
5	Map Local	A match answers the request locally. Steps 6 to 10 are skipped.
6	Mock Sets	A recorded response (or an offline 404) answers the request. Steps 7 to 10 are skipped.
7	Map Remote	Rewrites the URL and, unless you keep it, the Host header.
8	No Caching: request	Removes conditional headers and adds Cache-Control: no-cache and Pragma: no-cache.
9	Network Conditions: upload	Waits half the latency plus the upload time for the body.
10	DNS Spoofing	Connects to the spoofed IP address for the host, and the request goes to the server.
11	No Caching: response	Removes ETag, Last-Modified and Expires, and sets Cache-Control: no-store, no-cache, must-revalidate.
12	Scripting: onResponse	Every matching script with Run onResponse on, top to bottom.
13	Breakpoint: response	Pauses for you. Abort closes the app’s connection.
14	Network Conditions: download	Waits half the latency plus the download time for the body, then sends the response to the app.
15	Allow List and Alerts	The request is recorded if the Allow List lets it through, and alert rules check the finished request.

Steps 11 to 14 run for every response, including those from Map Local and Mock Sets. So you can pause or script a mocked response, and it is still slowed by Network Conditions. A Block List 403 skips them.

Which URL each step sees

Scripts and breakpoints can change a request’s URL. Later steps see the change only where it matters:

Steps	Match against
Block List, Network Conditions, request scripts, request breakpoint, Allow List	The request as the app sent it.
Map Local, Mock Sets, Map Remote	The request after request scripts and the request breakpoint.
Response scripts, response breakpoint	The request as the app sent it, so editing the URL earlier doesn’t skip them.
Alerts	The request as it was finally sent, after Map Remote.

Note

Requests you send with Repeat, Edit and Repeat or Compose go through the same steps as live traffic.

Create a rule from a request

Right-click a captured request in the traffic list, choose Tools, then a tool. The new rule matches that request and opens in the Tools window. With several requests selected, Mock Sets records all of them.

You can also search for New … Rule from Selection or Mock Selected Responses in Search Everything. The Tools submenu isn’t available for encrypted tunnels, and No Caching isn’t in it because it has no rules.

Menu item	The new rule	Tool switched on
Breakpoint…	Matches the request’s method and URL without its query string, subpaths off. Pauses request and response.	Yes
Map Local…	Same exact match. Status code, body (decoded, JSON pretty-printed) and useful headers are copied from the captured response. See Map Local.	Yes
Map Remote…	Matches the URL without its query, any method, subpaths on. Host is prefilled with the current host for you to change.	Yes
Scripting…	Exact match, with the starter script.	Yes
Block List…	Matches the URL without its query, any method, subpaths on. Returns 403.	Yes
Allow List…	Matches the whole host (https://api.example.com/), any method, subpaths on. Named after the host.	No: switch the Allow List on yourself.
Network Conditions…	Matches the whole host. Uses the 3G profile. Named after the host.	Yes
DNS Spoofing…	A row for the request’s host pointing at 127.0.0.1.	No change
Mock This Response / Mock N Responses	A mock set with the response of each selected request.	Yes
Alerts…	Exact match with the request’s method, condition Any error (4xx, 5xx or failure). Named “… fails”.	Yes, and macOS asks for notification permission

Rules made this way are named after the request, for example GET api.example.com/v1/users.

Export and import rules

Rules are saved on your Mac. To share them with a teammate, keep them in a repository or use them in CI, export them to JSON.

1. Choose Tools › Export Rules….

2. Pick where to save. The suggested name is Cloak Proxy Rules.json.

3. To load rules, choose Tools › Import Rules… and pick a JSON file. Cloak Proxy reports Imported N rules from ….

What’s in the file and what import reads:

Part	Exported	Imported
Breakpoint, Map Local, Map Remote, Scripting, Block List, Allow List, Network Conditions and DNS Spoofing rules	Yes	Yes. They are added to your current rules; a rule with the same id as an existing one replaces it.
On/off state of each tool, and No Caching	Yes	No. Your current switches stay as they are.
Mock Sets, including recorded response bodies	Yes	No
Alerts	Yes	No

The file is pretty-printed JSON with sorted keys. Each rule has an id, name, isEnabled and matcher, plus the tool’s own fields. An excerpt:

Cloak Proxy Rules.json (excerpt)

{
  "blockList" : [
    {
      "action" : "forbidden",
      "id" : "6F1C2A3B-0000-4000-8000-00000000AB12",
      "isEnabled" : true,
      "matcher" : {
        "includeSubpaths" : true,
        "method" : "ANY",
        "mode" : "wildcard",
        "url" : "ads.example.com/"
      },
      "name" : "Block ads"
    }
  ],
  "blockListEnabled" : true
}

Tip

Rules need every field their tool uses. Instead of writing a file by hand, create the rules in the app, export them, and edit the export. If a file can’t be read, Cloak Proxy says That file isn’t a Cloak Proxy rules export with the reason.

Exports can contain secrets

An export holds everything in your rules: Map Local bodies and headers, scripts, and every response recorded in your mock sets. These can include tokens, cookies and personal data. Read the file before you share or commit it.

The same file works with cloakctl run --tools for headless runs.

Related

Debugging toolsEvery tool, the Tools window and the status bar.

ScriptingChange requests and responses with JavaScript.

Headless and CIRun tests through Cloak Proxy with exported rules.

Search and command paletteCreate rules and toggle tools from the keyboard.