Docs

Appearance

Security ​

Public app ID & domain whitelisting ​

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

public app ID and whitelisted domains are managed in the SDK settings of the Bird Eats Bug web dashboard.

Common configuration scenarios ​

Whitelist subdomains ​

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

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

Example 2: To whitelist nested subdomains, combine multiple *. This means to whitelist SDK on https://staging.temporary123.birdeatsbug.com/index.html and https://release.sdk.birdeatsbug.com. with one entry, use the pattern *.*.birdeatsbug.com. To have whitelist more precisely, you can also add multiple entries instead, like staging.*.birdeatsbug.com and release.*.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.

To whitelist all ports of a domain, e.g. http://localhost:3000/index.html and http://localhost:8080/index.html, use the * operator as 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 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 the origin HTTP header as fallback. The API then verifies that the request referer / origin 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.

Browsers automatically attach the referer / origin headers, and neither can't be faked from within the browser. Since the SDK is embedded into 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 their 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. 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. 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 img-src, add data: so that screenshots can be displayed.
  5. To your CSP's media-src, add blob: for video recordings to be displayed.
  6. To your CSP's connect-src, add https://api.birdeatsbug.com. For the upload of sessions with screenshot files to work, also add data:. For the upload of sessions with video files, also add blob:.

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.