# Scope

> List the hosts and paths you may test. Cloak Proxy filters traffic, Insights and exports by it, can block the rest, and keeps every security tool inside it.

Source: https://docs.subcloak.com/cloak-proxy/security/scope/

Added in Cloak Proxy 0.5.1.

A scope is the list of hosts and paths an engagement covers: `api.example.com`, everything under `example.com` except the payment processor, a staging address range. Set one and Cloak Proxy uses it everywhere:

- The traffic list, Insights, the Authorization Matrix, token inspection and exports can show **only what's in scope**.
- Traffic outside it can still be recorded, or **not recorded**, or **blocked** outright.
- Tools that send requests stay inside it. Replays, Repeat and the Authorization Matrix refuse out-of-scope targets while the scope guards them. The request fuzzer and active checks **only ever** send to hosts in the active scope, and don't run without one.

It doubles as a guardrail: with a scope set, nothing you or an AI assistant starts from Cloak Proxy reaches a host you didn't list.

*[Screenshot: The Scope window. A list on the left with ShopApp API test (active, 4 included, 2 excluded) and Staging smoke test. On the right the ShopApp API test scope: its name, Use this scope turned on, notes about the test window, an Include section with https api.example.com, example.com and subdomains under /account, 203.0.113.0/24 and localhost port 8080, an Exclude section with payments.example.com and /v2/admin/* on api.example.com. At the bottom: Outside the active scope set to Don't record it, Keep replays and the Authorization Matrix in scope checked, and Show only in-scope traffic.. A scope for one engagement: what's included, what's excluded (excludes win), and what happens to everything else.]*

## Make a scope

The quickest way is from the traffic you already have:

1. Right-click a request in the traffic list and choose **Scope › Add api.example.com to Scope**, or **Add https://api.example.com/v1 to Scope** for just that URL's folder. In the sidebar, right-click a host for **Scope › Add example.com and Subdomains to Scope**.

2. With no scope yet, Cloak Proxy makes one named after the site and makes it active. Later additions go into the active scope.

3. Open **Tools › Scope…** (<kbd>⇧</kbd> <kbd>⌥</kbd> <kbd>⌘</kbd> <kbd>S</kbd>) to review it, add excludes, and choose what happens outside it.

You can also start in the Scope window: **Create Scope**, then **Add Include**, **Paste a List…** (one host or URL per line, straight from a statement of work), **From Traffic** (the busiest hosts not in scope yet), or **Import…** a file.

*[Screenshot: The Scope window with no scope: a scope icon, No scope yet, an explanation that the fuzzer and active checks only send requests to hosts in the active scope, Create Scope and Import buttons, and a list of hosts from the traffic with request counts and an Add to Scope button each.. Before there's a scope: create one, import one, or start from the hosts in your traffic.]*

### Rules

Each rule has a kind (include or exclude), a scheme, a host, a port and a path. An empty field matches anything.

| Field | Examples | Matches |
|---|---|---|
| Scheme | Any, HTTPS, HTTP | HTTPS also covers `wss://`, HTTP covers `ws://` |
| Host | `api.example.com` | That host only (case and a trailing dot don't matter) |
| | `api.example.com` with **Subdomains** | The host and every name under it: `eu.api.example.com` |
| | `*.example.com` | Any subdomain, but not `example.com` itself |
| | `203.0.113.0/24`, `198.51.100.7` | An IPv4 range or one address |
| | `*` | Every host |
| Port | `8443` | Only that port. Default ports count: `443` covers `https://api.example.com/` |
| Path | `/api` | `/api`, `/api/` and everything under it, but not `/apiv2` |
| | `/v*/orders/*` | Wildcards; `/api/*` also covers `/api` itself. Paths ignore case, and the query string is never compared |

Switch a rule to **Regular expressions** (its **⋯** menu) to write the host and path as regexes, the way Burp Suite's advanced scope does. The host must match the whole expression; the path matches from its start.

A request is in scope when an enabled include covers it **and no enabled exclude does**: excludes win. A scope with no enabled include covers nothing. Encrypted tunnels Cloak Proxy doesn't decrypt have no path, so they count by host: in scope when an include covers the host and no exclude covers the whole host.

**Test a URL** at the bottom of the editor tells you whether a URL or host is in scope and which rule decided. The inspector's **Summary** tab shows the same for the selected request.

### Several scopes

Keep one scope per engagement, client or environment. Only one is active at a time: turn **Use this scope** on in its editor, or right-click it in the list for **Make Active**. Right-click for **Duplicate**, **Export…** and **Delete** too. The scope's **Notes** are a good place for who authorized the test, the test window and contacts.

## What the scope does

### The traffic list

While a scope is active, the filter bar shows an **In Scope** tab. Turn it on to see only in-scope requests, in every tab and Split View pane. **Reset** turns it off with the other filters.

### Out-of-scope traffic

**Outside the active scope** at the bottom of the Scope window:

| Choice | What happens |
|---|---|
| **Record it** (default) | Everything is recorded as usual; use **In Scope** to hide the rest |
| **Don't record it** | Out-of-scope requests still go through Cloak Proxy and its tools, they just aren't listed (like a muted app) |
| **Block it** | Out-of-scope requests get a `403` from Cloak Proxy (tagged **Out of Scope**, with `X-Cloak-Proxy: out-of-scope`), and tunnels to hosts outside the scope are refused |

> **Block applies to everything through Cloak Proxy:**
> **Block it** refuses every out-of-scope request from every app and device using the proxy, including your browser's other tabs and the Mac's own services when macOS traffic is captured. Use it in a [Capturing Browser](https://docs.subcloak.com/cloak-proxy/devices/capturing-browser/) or with only the app under test pointed at Cloak Proxy. While recording is paused hands-off, nothing is blocked.

### Tools that send requests

With **Keep replays and the Authorization Matrix in scope** on (the default) and a scope active:

- **Repeat**, **Edit and Repeat**, Compose, Repeat Advanced and the `replay_request` and `edit_and_replay` tools don't send out-of-scope requests. The traffic list shows the attempt as failed: "Not sent: api.other.example is outside the scope…".
- The [Authorization Matrix](https://docs.subcloak.com/cloak-proxy/testing/authorization-matrix/) skips endpoints outside the scope ("Outside the active scope; not sent"), and its **Scope** picker gains **In scope**.

The request fuzzer and active checks don't depend on this setting: they need an active scope and only send to hosts in it. To test something on your own Mac, add `localhost` (with its port) to the scope.

### Insights, tokens and exports

- Insights' **Analyze** menu gains **In scope**. [API Scan](https://docs.subcloak.com/cloak-proxy/insights/api-scan/) follows it too; the scan only reads captured traffic and sends nothing, so it never needs a scope to run.
- [Tokens and sign-in](https://docs.subcloak.com/cloak-proxy/security/tokens-and-sign-in/) has an **In scope** checkbox, and marks each place a token went as in or out of scope.
- **File › Export** exports the visible requests, so turn **In Scope** on first; `export_session` takes `in_scope: true`.

## Share a scope

**Export** (the share button, or right-click a scope) saves it as a `.cloakscope.json` file to put in a repository or send to a teammate. **Import…** reads:

- Cloak Proxy scope files.
- **Burp Suite** scopes: a project options file with `target` › `scope` include and exclude lists. Plain host regexes become ordinary rules; anything else stays a regex. A port regex Cloak Proxy can't express skips that include (it's listed after the import) and makes an exclude cover every port.
- A plain list, one per line: `api.example.com`, `*.example.com`, `.example.com` (the name and its subdomains), `https://api.example.com/v1/`, `203.0.113.0/24`, or `re:` and a host regex. A leading `-` or `!` makes a line an exclude; `#` starts a comment.

An imported scope isn't active until you make it so.

An engagement's scope in **Tools › Findings** uses the same rule syntax, and a new engagement starts from the active scope. See [Findings and reports](https://docs.subcloak.com/cloak-proxy/security/findings/).

## AI assistants

Two MCP tools: `scope_status` returns the active scope, its rules, the other scopes and the settings, and with `check` tells whether URLs or hosts are in scope. `update_scope` changes it, but only narrowing applies at once: an exclude, removing or turning off an include, a new inactive scope, a rename. Anything that lets tools reach more (an include in the active scope, activating or turning off a scope, **Block it**, letting replays leave the scope) appears at the top of the Scope window, and nothing changes until you click **Allow**.

*[Screenshot: The top of the Scope window with a banner: Claude Code asks to change the scope. Add https://search.example.com to the scope ShopApp API test. A note that widening the scope lets tools send requests to more hosts, and Deny and Allow buttons.. An assistant asked to widen the scope: nothing changes until you allow it.]*

## Command line

```sh
cloakctl scope                                   # the active scope and its rules
cloakctl scope check https://api.example.com/v1/orders cdn.example.com
cloakctl scope create "ShopApp API test" api.example.com .shop.example.com
cloakctl scope import engagement-scope.json      # Cloak Proxy, Burp Suite or a host list
cloakctl scope exclude payments.example.com
cloakctl scope activate "ShopApp API test"       # Cloak Proxy asks you to allow it
cloakctl scope out-of-scope dontRecord
```

For CI or a headless proxy, `cloakctl run --scope FILE` records only what the scope file includes; add `--out-of-scope block` to refuse the rest. See [cloakctl](https://docs.subcloak.com/cloak-proxy/automation/cloakctl/).

> **On Linux:**
> The scope is part of the settings the engine saves, so the rules, recording, blocking and the guards above work the same. Until the Linux app has a Scope window, manage it with `cloakctl scope` or the `scope_status` and `update_scope` MCP tools: your own `cloakctl` changes apply at once there. An assistant's request to widen the scope (through MCP) waits and isn't applied.

## Related

  - [Request fuzzer](https://docs.subcloak.com/cloak-proxy/security/request-fuzzer/): The fuzzer only sends to hosts in the active scope.
  - [Tokens and sign-in](https://docs.subcloak.com/cloak-proxy/security/tokens-and-sign-in/): Every token in the traffic, and where it went in and out of scope.
  - [Authorization Matrix](https://docs.subcloak.com/cloak-proxy/testing/authorization-matrix/): Replay endpoints as other users, inside the scope.
  - [Findings and reports](https://docs.subcloak.com/cloak-proxy/security/findings/): Record what you find, with the engagement's scope in the report.