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 destination

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:

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 outside the four above never becomes an entry.

WebRTC and WebSockets

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.

WebSocket destinations are ordinary origins, such as wss://chat.example.net. They get their own section to make them easy to review, and each one is allowed or rejected like any other destination. A WebSocket subdomain can still join a site section when its site qualifies for a pattern.

Site patterns

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 https:// and wss:// 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.

Noise

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.

Browser extension destinations

A report that names a browser extension URL never becomes a destination. An extension runs on the visitor's machine, and a list entry for it would mean nothing. The builder sets these destinations aside, and a note under the review table gives their count. To drop them before they are stored, refer to Drop reports from browser extensions.

Starting options

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 writes

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 browser extension destination.
• 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" "wss://chat.example.net"); redirects=allow; webrtc=allow; report-to=centralcsp

Periods and limits

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 steps

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