Security #

Public app ID & domain whitelisting #

Without matching public app ID and whitelisted domain, it is not possible to upload sessions recorded with SDK.

Common configuration scenarios #

Whitelist all subdomains #

To whitelist all subdomains of a domain, e.g. so that the SDK works in all dynamic pull request preview environments, just whitelist the domain.

Example: To whitelist SDK on app.birdeatsbug.com, sdk.birdeatsbug.com, and all other subdomains ending with birdeatsbug.com, whitelist birdeatsbug.com.

Whitelist localhost or other URLs which include the port #

To whitelist SDK uploads from URLs which include the port, like http://localhost:3000/index.html, it is required to include the port to whitelist the domain. Example: localhost:3000.

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 such two data points is a standard industry practice for SDKs embedded into public pages.

The goal of requiring knowledge of those two data points is to minimize the likelihood that bad actors upload sessions to your workspace from somewhere else. But while public app ID and domain whitelisting increase friction of such abuse, they are no absolute guarantee against this scenario, as described below:

The API endpoint to which sessions are uploaded from SDK inspects whether the attached public app ID has been configured, and then checks the referer HTTP header and verifies that the referer is one of the whitelisted domains. If one of those two factors does not match, the request is rejected.

The public app ID is - as the name implies - a public key, embedded into 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.

All browsers automatically attach the referer header to all requests, and it can't be faked from within the browser. Since the SDK is embedded into a site executed in a browser, this referer check normally is impossible to fake. However, an attacker could trigger a session upload request from outside their browser, attaching the extracted public app ID and setting the referer 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. Your workspace would experience "spam uploads". If you experience such abuse, please get in touch with us.

Content Security Policy #

If your site is using CSP, you need to enable the following policies:

1. 1. If your page is served statically: Compute the hash of the SDK JS snippet (e.g. with this tool).
   2. If your page is server-side rendered, you could instead generate a different random nonce on every page load, and add it to the SDK JS snipped script tag in the nonce="" attribute.
2. To the script-src, add https://sdk.birdeatsbug.com, and also the hash or nonce from the previous step.
3. To your CSP's style-src, add https://sdk.birdeatsbug.com. For the screen recording preview to play back, you also need to add 'unsafe-inline'.
4. To your CSP's connect-src, add https://api.birdeatsbug.com.

With these policy changes, the preview of the screen recording might still not fully work (look broken, throw CSP errors). If that's the case, please get in touch to discuss whether additional CSP changes are required.

Theoretically you can host the SDK files yourself to avoid whitelisting 3rd party domains, but then you will have to keep the SDK files up to date on your own, and we cannot guarantee that the self-hosted SDK will never break due to being outdated.

3rd party code #

We try to minimize the amount of 3rd party code included in the SDK, reducing the attack vector as much as possible. We have automated systems in place to notify us of vulnerabilities in said 3rd party code. Read more about our security practices here.