Configure browser-traffic inspection
Set the inspection policy an SWG or the inline proxy is held to — which hostnames are inspected, who may call in, and what happens on timeout.
- Version: 0.4
- Feature: icap
- Role: admin_user
- Type: task
Browser Inspection is where you set the policy that governs traffic arriving from a secure web gateway (SWG) over Internet Content Adaptation Protocol (ICAP) or the HTTP callout, and from the built-in mitmproxy forward proxy. The detections it produces land in All detections.
What do I need?
- Licence
- Any
- Role
admin_user
Prerequisites
- You are signed in as the superadmin. An admin_user can read this page, but saving the appliance-wide policy is refused for anyone else.
- An SWG that can call ICAP or an HTTP callout, or the inline-proxy compose profile running on the appliance.
- The addresses your SWG dials the ICAP listener from, if you intend to restrict them.
- For mTLS, a reverse proxy in front of the gateway that verifies the client certificate and forwards its subject DN.
/assets/screenshots/inspection@0.4.pngSet the inspection policy
Open the page
Select Detection & Filtering → Browser Inspection.
Connected SWG sources lists callouts received in the last hour — the fastest check that the SWG side is reaching this appliance at all — and LLM-frontend adapter coverage lists the web front-ends the appliance knows how to parse.
Name the hostnames to inspect
In Policy configuration, list one hostname per line under Enabled hostnames.
These should match the URL category configured on the SWG side. A fresh appliance is pre-filled with the common LLM front-ends.
Name the hostnames never to inspect
List banking, payroll, HR and legal hosts under Bypass hostnames.
A bypassed host is not inspected even when the SWG sends it.
Restrict who may connect to the ICAP listener
Enter the SWG's addresses in Allowed ICAP peer IPs / CIDRs, comma-separated.
Read the next section before you fill this in: the list replaces the default rather than adding to it.
Set the timeout and the failure mode
Set Inspection timeout (ms) — the hard ceiling on the synchronous check, minimum 50 — and
leave Fail closed (BLOCK) on timeout on.
Inspection runs no background work, so this timeout is the whole budget. Fail-closed means a timed-out check blocks rather than releases.
Require a client certificate, if you use mTLS
Enter the expected subject in mTLS client subject DN, for example
CN=swg.acme.com,O=Acme Corp. Leave it empty if mTLS is not in use.
This is an additional constraint on the HTTP callout path. Neither a bearer token nor network position substitutes for it, and a request that arrives without a DN when one is configured is refused.
Save
Turn Policy active on and select Save policy.
An Inspection policy updated toast confirms it.
Who may call in
The two ingress paths authorise differently, because ICAP gives the gateway much less to work with.
HTTP callout (/inspect/v1) accepts a valid cid_key_ bearer token, which also resolves the
tenant. A keyless call is accepted only from private address space and only when the request did
not arrive through a reverse proxy — that is how the local inline-proxy sidecar works without a
key while the public edge cannot. Arrival through a proxy is detected two ways, either sufficient:
the public-edge stamp the shipped nginx and Caddy configurations set, and the presence of any
forwarded-for header.
The ICAP listener cannot authenticate its peer at all. None of the SWG products CID integrates with — FortiProxy, FortiSASE, Forcepoint, Symantec ProxySG, Cisco WSA, McAfee/Skyhigh, Zscaler ZIA — exposes a credential or custom-header field on its ICAP profile, so there is nothing for a peer to send. Admission is by address alone, and an admitted peer is believed: the listener takes its word for the authenticated user it claims.
| Allowed ICAP peer IPs / CIDRs | Who may connect |
|---|---|
| Empty | Any address in private space — the historical default |
| Non-empty | Exactly the listed addresses, and nothing else |
Danger
The list replaces the private-range default rather than intersecting with it. It must therefore name every peer, on-premises appliances included — not only the cloud SWG egress ranges you are adding. A list that names nothing that can match takes inspection offline.
Entries may mix bare addresses, CIDRs and IPv6 literals. The list is cached, refreshed every five minutes and immediately on a save; a failed refresh keeps the previous list rather than changing who may connect. The check runs at TCP connect time, so tightening the list does not refuse connections a pooling SWG already holds open — bounce its ICAP connections and confirm from the gateway log rather than assuming the new list is in force. The list does not gate the HTTP callout path.
Warning
Both Allowed ICAP peer IPs / CIDRs and mTLS client subject DN were stored, displayed and read by nothing before this release. Because a value on an existing appliance has therefore never been applied, the upgrade clears both and records the previous values in the event log — re-enter them deliberately, on a running system, where the effect is visible.
Check that the listener can see who is calling
Source-IP admission is worth nothing if every peer arrives as the same address, and in a same-host VM lab it does. The source network's own NAT rewrites the source before the packet reaches the listener, so two SWG VMs both arrive as the container bridge gateway; an allowlist then refuses everyone, or admits everyone. An SWG on a physical LAN keeps its address and the allowlist works.
The listener detects the condition and logs it the first time a peer arrives as its own default gateway. Read that log before trusting any source-IP control — see ICAP peers all arrive as the docker bridge.
Attribute traffic to people
SWG callouts carry no identity of their own unless the SWG supplies one, so an unattributed row is
the normal failure. Resolution takes the first hit: the authenticated-user header the SWG sends
(normalised, so ACME\sarah, WinNT://ACME/sarah and sarah@acme.local all become one person),
then the attribution rules you maintain here.
Map an address to a person
Select Add attribution, then enter the IP address or CIDR range, the tenant, a human label and any notes.
The row decides whose name appears on inspection events from that address.
Load many at once
Select Import CSV.
The bulk import is all-or-nothing, capped at 2000 rows, and a malformed CIDR fails the whole request with a 400.
Or let the domain controller do it
Select DC agent script to download the Windows User-ID script.
The agent reports directory logons, so attribution follows people rather than desks. See User-ID attribution.
Attribution rows name people, so they are scoped: an admin_user reads and writes rows for its own
department only, and an out-of-scope write is refused rather than silently retargeted.
Roll out the inline proxy's root CA
The Root CA certificate & PAC tile applies to the built-in mitmproxy forward proxy only.
Confirm the proxy is running
Read the tile.
When it runs, the tile shows the CA fingerprint (SHA-256). Otherwise it says Inline proxy is not running on this appliance and the download buttons are disabled — the certificate is created the first time the proxy starts, and the dashboard cannot start it.
Download the certificate
Select cid222-root.crt, .pem or .cer.
Distribute it to managed endpoints by Group Policy so browsers accept the leaf certificates the proxy issues.
Point managed browsers at the proxy
Select Copy PAC URL and set it as the auto-proxy script for managed Chrome.
LLM hostnames route through the inline proxy on port 8443; everything else goes direct. The PAC is cached client-side for five minutes.
Warning
Three certificates get confused here. This tile is only the inline-proxy root CA — not the appliance's own HTTPS certificate, and not the per-device CA an endpoint agent generates. Customers who inspect through their own SWG never need it: their SWG has its own.
Fields reference
| Field | Rule | What it does |
|---|---|---|
| Enabled hostnames | One per line | Hostnames routed through inspection. Should match the SWG-side URL category |
| Bypass hostnames | One per line | Never inspected, even when the SWG sends them |
| Allowed ICAP peer IPs / CIDRs | Addresses, CIDRs or IPv6 literals, comma- or newline-separated | Who may connect to the ICAP listener. Empty means any private-space host. Non-empty replaces that default entirely |
| Inspection timeout (ms) | Integer, minimum 50 | Ceiling on the synchronous check |
| mTLS client subject DN | Max 512 characters | Required client-certificate subject on the HTTP callout path. Empty disables the check |
| Fail closed (BLOCK) on timeout | Default on | Whether a timed-out check blocks or releases the request |
| Policy active | Default on | Whether this policy is applied at all |
Host-level settings
These are not on the page. They are set on the appliance host and take effect at restart.
| Variable | Effect |
|---|---|
ICAP_PUBLISH | The address the ICAP listener binds. Keep it on loopback where the real peer address cannot be seen, and firewall the port instead |
CID_RESUMABLE_UPLOAD_POLICY | What happens to a fragment of a chunked or resumable upload. Defaults to blocking it |
CID_INSPECT_FAIL_OPEN | Whether the inline proxy releases traffic when the gateway cannot be reached |
DEFAULT_INSPECTION_TENANT_ID | The tenant unattributed inspection events are filed under. Must not name a real person |
Warning
A fragment of a multi-request upload cannot be inspected — OCR sees a slice of a file — so all three capture paths refuse them by default. Reassembly is not implemented, which means a user sending a large file through a resumable upload gets a refusal rather than a redaction.
Verify
- Send test traffic through the SWG. A row appears in Connected SWG sources with the source address, the inferred vendor and a last-seen inside the hour.
- Open All detections with Source set to Browser inspection and confirm the detection is there.
- Saving the policy writes a
POLICY_PROTECTION_CHANGEDrow per protection-bearing field that moved — switching Policy active off, or Fail closed (BLOCK) on timeout off, is recorded with the value before and after. Timeouts that fail closed and errors are recorded asINSPECTION_TIMEOUT,INSPECTION_ERRORandINSPECTION_REDACTION_FAILED. - After tightening the allowlist, force the SWG to reconnect and confirm from the gateway log that the refusal names the address you expect.
If it fails
- allowed_source_ips contains entries that can never match: … Use an IPv4 address (10.0.5.42), an IPv4 CIDR (10.0.5.0/24), or an IPv6 literal (::1). — an entry is a typo, a hostname or an impossible prefix. The DTO refuses it, because with these semantics a list of typos would refuse every peer.
- Only a superadmin may change the appliance-wide inspection policy — this page always writes the appliance-wide row, and that row is the posture every user inherits. Escalate; do not look for a per-department version of this form.
- The SWG reports ICAP failures and nothing appears in Connected SWG sources — the peer was refused at connect time. Rejection is a socket close with no ICAP response, plus a warning in the gateway log naming the peer and the rule that refused it.
- Every peer shows the same source address — see ICAP peers all arrive as the docker bridge.
- Every
/inspect/v1caller starts returning 403 after an upgrade — a stale mTLS client subject DN is being enforced for the first time. Clear it, or fix the DN your terminator forwards. - Detections arrive with no user — attribution failed. Add an attribution row, deploy the DC agent, or set the default inspection tenant so the rows are at least filed somewhere.
Next steps
- All detections — read what inspection is catching.
- User-ID attribution — replace hand-maintained address rows with directory logons.
- Security filters — the rules inspection applies are the same rules managed chat uses.
Last updated on