Web SDK security

Understand how public app ID and domain whitelisting secure Web SDK session uploads, and how to configure your Content Security Policy.

Public app ID and domain whitelisting

Without a matching public app ID and whitelisted domain, the SDK cannot upload recorded sessions.

You manage the public app ID and whitelisted domains in the SDK settings of the Bug Capture web dashboard.

Common configuration scenarios

Whitelist subdomains

To whitelist subdomains of a domain, for example so that the SDK works in all dynamic pull request preview environments, use the * operator in place of the dynamic part of the domain.

For example, to whitelist the SDK on app.birdeatsbug.com, sdk.birdeatsbug.com, and all other subdomains ending with birdeatsbug.com, whitelist *.birdeatsbug.com.

To whitelist nested subdomains, combine multiple *. For example, to whitelist https://staging.temporary123.birdeatsbug.com/index.html and https://release.sdk.birdeatsbug.com with one entry, use the pattern *.*.birdeatsbug.com. For more precise whitelisting, you can instead add multiple entries, such as staging.*.birdeatsbug.com and release.*.birdeatsbug.com.

Whitelist localhost or other URLs that include a port

To whitelist SDK uploads from URLs that include a port, such as http://localhost:3000/index.html, include the port in the whitelist entry, for example localhost:3000.

To whitelist all ports of a domain, such as http://localhost:3000/index.html and http://localhost:8080/index.html, use the * operator as the value for the port. This yields the pattern localhost:*.

Security implications

The goal of the public app ID and domain whitelisting is that only the SDK using your public app ID, embedded on a domain explicitly whitelisted for it, can upload sessions to your workspace. Combining these two data points is a standard industry practice for SDKs embedded into public pages.

The goal of requiring knowledge of both data points is to minimize the likelihood that bad actors upload sessions to your workspace from somewhere else. However, while public app ID and domain whitelisting increase the friction of such abuse, they are not an absolute guarantee against it, as described below.

The API endpoint to which sessions are uploaded from the SDK inspects whether the attached public app ID has been configured, and then checks the referer HTTP header and the origin HTTP header as a fallback. The API then verifies that the request’s referer or origin is one of the whitelisted domains. If neither factor matches, the request is rejected.

The public app ID is, as the name implies, a public key embedded in the front-end code of your site and attached to session upload requests. It can be extracted by anyone inspecting your site’s publicly hosted source code.

Browsers automatically attach the referer and origin headers, and neither can be faked from within the browser. Since the SDK is embedded in a site executed in a browser, this header check is normally impossible to circumvent. However, an attacker could trigger a session upload request from outside the browser, attaching the extracted public app ID and setting the referer or origin header to one of your whitelisted domains.

If the payload of such a forged session upload request matched the schema of regular session upload requests, the API would upload the fake session to your workspace, and your workspace would experience spam uploads. If you experience this kind of abuse, get in touch with support.

Content Security Policy

If your site uses a Content Security Policy (CSP), enable the following policies:

With these policy changes, the preview of the screen recording might still not fully work, for example, it might look broken or throw CSP errors. If that happens, get in touch with support to discuss whether additional CSP changes are required.

You can host the SDK files yourself to avoid whitelisting third-party domains, but you then need to keep the SDK files up to date on your own, and Bug Capture cannot guarantee that a self-hosted SDK will not break due to being outdated.

Third-party code

Bug Capture minimizes the amount of third-party code included in the SDK, reducing the attack vector as much as possible. Automated systems are in place to flag vulnerabilities in that third-party code. Read more about these security practices on the Bird Eats Bug security and privacy page.