Builder decision rules

The Connection-Allowlist builder suggests every entry from rules you can check. Knowing them tells you when to trust a default and when to overrule it.

From a report to a destinationCopy Anchor Link

Each Connection-Allowlist report names a connection the browser blocked, or would have blocked in report-only mode. The builder turns it into a destination you can allow:

Browsers report only http: and https: URLs and WebRTC connections. They never check data: or blob: URLs, and they report a WebSocket under http: or https:. CentralCSP discards any other Connection-Allowlist report, such as one naming a browser extension URL.

The builder writes bare origins, with no path. An entry with no path matches every path on that origin, so one entry per destination keeps the list short, and it stays valid when a vendor moves an endpoint. The Blocked URLs section of the details panel still shows the full URLs, so you can see which endpoint your pages call.

Reports can be forged, so the builder checks every destination before it can reach the header. A value with a quote, a bare * host, or a scheme other than http or https never becomes an entry.

Blocked redirectsCopy Anchor Link

Your starting list allows every direct request to the destinations it names, and response-origin allows your own origin. A report that names one of those destinations therefore comes from a redirect, which the list blocks by default. The browser reports the URL the page requested, not where the redirect led.

While redirects are blocked, the builder flags each such row Redirect blocked, next to Already allowed. An alert above the Redirects card, Redirects were likely blocked, gives the number of reports behind those rows. WebRTC rows never carry the flag.

To find the redirect, open the row and read its Blocked URLs. Then remove the redirect from your site, or allow redirects in the Redirects card. For what redirects=allow permits, refer to Redirects.

WebRTCCopy Anchor Link

A WebRTC connection has no destination URL, so the list cannot name one. The builder groups every reported WebRTC connection into a single row. Allowing it writes webrtc=allow, which lets every WebRTC connection through, from any script on your pages. Leave it rejected unless your pages make video or voice calls, or other peer-to-peer connections. The CSP webrtc directive, which would cover this channel, has no browser support yet.

WebSocketsCopy Anchor Link

The browser checks a WebSocket as an https: or http: URL, and reports it that way. A connection to wss://chat.example.net arrives as https://chat.example.net, and the builder treats it like any other destination of that origin. Allowing https://chat.example.net allows the WebSocket too.

A ws: or wss: entry never matches in the browser, so the builder never adds one. If you paste a list that holds one, the builder keeps the entry but flags it Never matches, and its details panel names the https: or http: origin to allow instead. The builder does not count the entry as allowing anything, so the WebSocket destination it was meant for stays listed for you to decide. Replace the entry with that origin.

Site patternsCopy Anchor Link

A site is the last two labels of a host, such as example.com for api.example.com. Under a country code with a common second level, such as co.uk, the site keeps three labels, such as example.co.uk. The scheme is part of the site, so http:// and https:// subdomains of the same domain never share a pattern. IP addresses never form a site.

The builder offers one pattern for a site once browsers reported three or more of its subdomains on the default port:

• The pattern is the site with a *. wildcard, such as https://*.example.com, flagged Recommended.
• It starts added when three or more of those subdomains are allowed, noise left out.
• While it is added, it allows every subdomain it covers, and those rows are locked as Allowed by the site pattern.
• It never covers the site itself (https://example.com) or a subdomain on another port (https://api.example.com:8443). Those keep their own entry.

A pattern also allows subdomains of the site that nobody reported. That is what keeps it short, and also why you should reject it on a domain where other people can create subdomains.

NoiseCopy Anchor Link

Noise is a reported destination your pages most likely do not need. The builder flags a destination as noise when browsers reported it fewer than 10 times in the period. Noise starts rejected, unless your starting list already allows it.

The Why it looks like noise section of the details panel says why, with the report count behind it. It can also say that only one browser reported the destination while your site sees several. That line never makes a destination noise on its own: only Chromium-based browsers send Connection-Allowlist reports, so most sites see a single browser.

Noise is only a default. A page few people open, such as a yearly campaign, can produce few reports and still be real. Check the Noise filter before you deploy.

Starting optionsCopy Anchor Link

The builder offers two starting points:

response-origin allows the origin each page is served from, whichever of your hosts that is. Your pages can always call back to their own server, so nothing your site serves itself breaks.

When you paste a list, the builder keeps every entry it can read, and its redirects and webrtc settings. It drops what it cannot use: duplicate entries, entries outside the URL pattern grammar, and a bare wildcard such as https://*, which would allow every destination. Its report-to parameter is replaced by report-to=centralcsp. An entry with a path is kept as it is, but the builder does not treat it as allowing any destination, so the destinations it covers stay listed for you to decide.

The builder never starts from a list read out of the reports. Anyone who knows your reporting endpoint can send a report, so a list found in reports could be forged, and starting from it would allow destinations an attacker chose.

What the builder never writesCopy Anchor Link

The list on the deploy step leaves out:

• redirects=block and webrtc=block. They are the browser's defaults, so the builder writes only redirects=allow or webrtc=allow.
• A path on a destination it added. Every added destination is a bare origin or a site pattern.
• An entry outside the URL pattern grammar, or a wildcard host with nothing after it.
• A ws: or wss: entry, unless your pasted list holds one.
• A second copy of an entry.

The value always ends with report-to=centralcsp, the group the Reporting-Endpoints header declares. With both redirects and WebRTC allowed, a list looks like this example:

Connection-Allowlist-Report-Only: (response-origin "https://*.example.com" "https://chat.example.net"); redirects=allow; webrtc=allow; report-to=centralcsp

Periods and limitsCopy Anchor Link

The builder reads up to the last 30 days of reports. A website that sends a very large volume of reports is limited to 7 days at a time.

On such a website, the Period step says This website sends a lot of reports, so the builder reads only its last 7 days, and the 14 days and 30 days options are hidden. If a period holds more reports than the builder can read in time, the page shows This period holds too many reports to analyze in time. Pick a shorter period. Pick fewer days and continue.

The API applies the same limits. The Build a recommended Connection-Allowlist endpoint defaults to the last 7 days, covers up to 30, and each user can call it 10 times per minute. It applies the builder's defaults with no review: every destination that is not noise is added, and three or more allowed subdomains of one site become a pattern. Refer to the API reference.

Next stepsCopy Anchor Link

• Review destinations
• Get started
• Connection-Allowlist reports
• Connection-Allowlist reference