UI capture privacy: what the SDK masks and what it still records
The capture SDK, @keploy/capture-sdk, masks personal data in your visitors' browsers before anything is sent. This page is for the developer who sets it up and for the privacy or security reviewer who signs it off: what each privacy mode masks, what every mode still records, and how to mask, block or declare more. It describes SDK 3.1.0. The package's README on npm states every rule in full.
Where masking happens
Masking happens in the browser, before the SDK sends anything. Nothing can be unmasked later, because Keploy's server never receives the original. The SDK sends what it records only to the endpoint you configure; What leaves the browser lists what each request carries.
Choose a privacy mode
privacyMode sets what is recorded of the page. A masked value is recorded as asterisks, one per character, so its length is kept.
| What the visitor typed or sees | "balanced" (default) | "strict" | "off" |
|---|---|---|---|
password and hidden inputs | masked | masked | masked |
color, date, datetime-local, email, file, month, number, range, search, tel, text, time, url, week | masked | masked | kept |
<textarea>, <select> | masked | masked | kept |
| Visible text | kept | masked | kept |
"balanced"masks every typed value and keeps the page's visible text. It is the default."strict", for public sites, records no page text: it also masks every visible text node, blanks every attribute,<meta>content and comment that holds text, records no request or response body, and replaces every query value in a URL. See What strict records."off"masks only password and hidden fields.
A hidden field is masked in every mode, because it holds the page's own machinery, such as a CSRF token, and never what a person typed. A file input's value is the name of the file the person picked (C:\fakepath\Resume_John_Smith.pdf), so it follows the mode like any other typed value.
The values of radio buttons, checkboxes and submit, button, reset and image inputs are not in the table: they are recorded as written under "balanced" and "off", and blanked under "strict". Their value is usually a label, but not always. To keep one that holds personal data out of the recording, such as a checkbox whose value is an email address, list it in privacy.blockSelectors.
In every mode, "off" included, the SDK replaces every JWT and every key whose prefix names its provider (a Keploy kep_ key, GitHub, Stripe, AWS and others) with [REDACTED] in the page's text and attribute values.
What strict records, and what it doesn't
Under "strict", an attribute keeps its value only when its name describes the page's structure: id, class, role, name, type, data-testid, ARIA state and relationships (aria-expanded, aria-labelledby), form and layout attributes (for, disabled, colspan, width), and SVG geometry and paint (d, viewBox, fill). A URL attribute, such as href, src or a lazy loader's data-src, data-href and data-srcset, keeps its URL with every query value replaced, and a style attribute keeps its CSS. Every other value is recorded as "": title, alt, placeholder, aria-label and the other aria-* text, every other data-* attribute but data-testid, every value attribute rrweb would record in the clear, and each ARIA attribute that reflects what the visitor chose, such as aria-valuenow or aria-checked.
What strict still records, so never put a visitor's data there:
- URL paths. Only query values and fragment-pair values are replaced, so
/search/<term>and a#/search/<q>route are recorded with the term. idandclassvalues, and a field'sname.data-testidvalues, as written. Replays find elements by them, so strict keeps them. An app that builds one from user data, such asrow-${email}, records that data. Never build adata-testidfrom user data.- SVG geometry. A signature pad's strokes are its paths'
dvalues. - Text under
unmaskSelectors.
On the network, strict records no request or response body (each is recorded as [MASKED]), replaces every query value in every recorded URL, and keeps only the values of headers that describe the exchange rather than the person: accept, accept-encoding, accept-ranges, age, cache-control, connection, content-encoding, content-language, content-length, content-type, date, etag, expires, keep-alive, last-modified, pragma, transfer-encoding and vary. Every other header's value is replaced with [REDACTED], and its name is kept.
Strict reads attributes with an allow-list that is a chunk of its own, which init() loads beside rrweb. Strict records nothing until both have loaded. If the allow-list cannot load, because of a Content-Security-Policy, a network failure or a deployment that dropped the file, the capture ends before anything is recorded or sent, with KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE. Setting privacy.maskNetworkBodies: false beside "strict" asks for the bodies strict leaves out, so the SDK refuses that configuration with KUI_E_PRIVACY_CONFLICT before it records anything.
A strict recording also replays with less of the page's look. CSS keyed on a data-* attribute or a title no longer matches ([data-theme=dark], a component's data-state=open), and a <progress> or <meter> shows no value. A control whose only name is its aria-label has no name in a strict recording, so give it a data-testid.
Mask, unmask and block elements
maskSelectorsmasks the text of the elements its CSS selectors match, and of everything below them.unmaskSelectorskeeps the text below the elements it matches in the clear, overridingmaskSelectorsand"strict".privacy.blockSelectorskeeps the elements it matches out of the recording altogether. rrweb records an empty box of the same size in their place, so use it for a video, a chat widget or a list of customers' names. The network calls the blocked element's code makes are still recorded.
maskSelectors and unmaskSelectors act on text only: no selector un-masks an input's value, which privacyMode alone decides. Each can be given at the top level of the options or under privacy, and the two lists are merged.
The React sample shop masks its order confirmation, which repeats the email the shopper typed, and blocks its reviews, which carry people's names:
await KeployCapture.init({
endpoint,
apiKey,
// The default, written out: every typed value is masked, and the page's
// visible text is kept. "strict" also masks all visible text and records
// no request or response body.
privacyMode: "balanced",
privacy: {
// Text that repeats what the shopper typed: the order confirmation
// shows their email, so its text is masked.
maskSelectors: ["[data-testid=order-confirmation]"],
// Never recorded: the reviews (people's names) are replaced by an
// empty box of the same size.
blockSelectors: ["[data-testid=reviews]"],
// A route whose path holds a credential, such as an invite link, is
// declared so its value is kept out of every event. The shop has none:
// secretRoutes: ["/invites/:key"],
},
onError(err) {
// The visitor's browser sends Do Not Track or Global Privacy Control:
// nothing is recorded, and nothing needs fixing.
if (err.code === "KUI_E_CAPTURE_DECLINED") return;
console.error(`[shop] Keploy UI capture stopped: ${err.code}`, err.message);
},
});
Rich-text editors
Text typed into a contenteditable element, such as a TipTap, Quill, Lexical or ProseMirror editor, is typed text: it is masked under "balanced" and "strict" as an input's value is, whatever unmaskSelectors says, and recorded under "off".
Visitors' privacy signals
The SDK honours Do Not Track and Global Privacy Control by default: honorPrivacySignals is true from SDK 3.1.0. When a visitor's browser sends either signal, init() records nothing, patches nothing and sends nothing for that visitor. Brave and DuckDuckGo send Global Privacy Control by default, so visits from those browsers never appear in your flows.
The signals the SDK reads are navigator.globalPrivacyControl === true and navigator.doNotTrack === "1", as well as Do Not Track as older browsers spell it: navigator.doNotTrack === "yes" (Firefox before 32), window.doNotTrack === "1" (Safari, Internet Explorer 11) and navigator.msDoNotTrack === "1" (Internet Explorer 10).
For a declined visitor, the SDK calls your onError with KUI_E_CAPTURE_DECLINED in a task after init(), never inside it, and writes one console.info line per page. It is not a failure, so keep it out of your error tracking, as the sample shop's onError does:
onError(err) {
// The visitor's browser sends Do Not Track or Global Privacy Control:
// nothing is recorded, and nothing needs fixing.
if (err.code === "KUI_E_CAPTURE_DECLINED") return;
console.error(`[shop] Keploy UI capture stopped: ${err.code}`, err.message);
},
Set honorPrivacySignals: false only where your site has its own lawful basis to record such visitors and says so in its privacy policy. An init() called again with the same options is declined again.
When you try capture on your own site, use a browser that sends neither signal: in one that does, the SDK records nothing.
Network calls: headers, credentials, bodies
Every recorded call keeps its method, URL, status and duration. Its headers and bodies are redacted by these rules; Network calls and bodies explains how the SDK reads a body and what a large one looks like.
- Headers. The values of
Authorization,Cookie,Set-Cookie,X-API-Key,X-Auth-TokenandProxy-Authorizationare always replaced with[REDACTED], and so is the value of any header whose name reads as a credential's, such asX-Csrf-Token,X-Session-IdorOcp-Apim-Subscription-Key.privacy.sensitiveHeadersadds names to that list; it cannot remove the six. Every other header value is scanned for the patterns below and otherwise recorded as it is, so name inprivacy.sensitiveHeadersany header your own code fills with what a person typed. - Credential names. One rule reads every name the SDK records a value under: a JSON body's key, a form field, a multipart part, a
name=valuepair in a text body, a header, and a URL's query or fragment parameter. A value under a credential's name, such aspassword,token,secret,apikey,session,pin,ssn,cardnumberorcvv, or a name ending intoken,secretorpassword, is replaced with[REDACTED]. A paging cursor, such aspageTokenornextPageToken, is not a credential and is kept. The page's own URL and the URLs in its DOM keepauth,session,cookie,pinandsigby name, as an app's own parameters, and replace such a value only when it looks generated, so?pin=4821in the page's URL is recorded. - Pairs in a text body. In a body that is neither JSON nor a form, such as one sent as
text/plain, aname=valuepair is found only where one can start, such as at the body's start or after?,&,;, a line break or a space; its name must be made of letters, digits,_,-,%and closed brackets; and its value ends at the first space, quote, backtick, bracket, backslash,&,;or comma. Sopassword=correct horseis recorded aspassword=[REDACTED] horse, anduser.password=…is not found at all. Send a form with its form content type, and the whole value is replaced. - Bodies. A JSON body is parsed, every value under a credential's name is replaced, and the JSON stays valid. Every string value in it, and every other body as text, is then scanned for JWTs, keys whose prefix names their provider, email addresses, US phone numbers, US social security numbers, IPv4 addresses and card numbers, and each match is replaced with
[REDACTED]. The code of an OAuth token exchange is replaced too.
Everything else in a body is recorded as it was sent. Under "balanced", a checkout request's shipping address, or a profile response's name, is recorded unless a credential's name or a pattern covers it. To record no body, set privacy.maskNetworkBodies: true, which records every body as [MASKED], or use "strict", which sets it. To replace values of a shape you know, add your own patterns.
Values in URLs
The SDK keeps a URL's path, because the path is what a replay matches requests by; it replaces only a credential it recognises there (below). What happens to the rest of a URL depends on the mode:
"balanced"and"off"keep every query value whose name is not a credential's. A visitor's search is masked in the search box, but when your app puts it in a URL, the URL carries it: the sample shops record their search forkettleasGET /api/products?q=kettle. A request's URL is judged by its parameter names alone, never by what a value looks like, so an email address in a request's query is recorded too.- The page's own URL, and the URLs in its DOM, are also scrubbed by shape: a value shaped like a token, or one a built-in pattern matches, such as
?email=ada%40x.com, is replaced. "strict"replaces every query value, whatever its name, and keeps every name:/search?q=ada%40example.com&page=2is recorded as/search?q=[REDACTED]&page=[REDACTED].- In every mode, a user name and password in a URL are dropped, a request's fragment (
#...) is dropped, and the page's fragment is kept only when it is a hash router's route, such as#/cart.
So keep personal data out of URL paths in every mode, and out of query values unless you use "strict".
Credentials in URLs: secretRoutes and keepRoutes
A credential in the page's URL, such as a reset link's ?token= or an OAuth callback's code, is replaced with [REDACTED] in that URL. The SDK recognises such a credential by its parameter's name, by a value that looks generated, and by the words of the path before it, as in /reset-password/<token> or /invitations/<uuid>/accept.
A value that looks generated, 8 or more characters mixing two of lower case, upper case and digits, is also replaced in every other event the SDK sends, wherever the page copies it: into links, the DOM or its requests. A word, digits alone, such as a six-digit code, or a value shorter than 8 characters is replaced only in the URL that names it. A credential in a path segment can be declared with secretRoutes, as below: one of 6 or more characters is then kept out of every event. A query value cannot be declared, so keep such codes out of your URLs.
Recognition misses some credentials, such as a 10-character /invites/<key>, and takes some app ids for one, such as /teams/invite/<id>. Declare both:
await KeployCapture.init({
endpoint,
apiKey,
privacy: {
secretRoutes: ["/invites/:key", "/*/change-email/:token"],
keepRoutes: ["/teams/invite/:teamId", "/invites/settings"],
},
});
- A route is
/-separated segments from the start of the path. Each segment is a literal, matched in any case,*for any one segment, or:namefor the value the route names. A route matches a path that begins with it, a hash router's route (#/...), and a URL nested in a query parameter. secretRoutesnames the routes whose segments are credentials: it must name at least one:name. The value is kept out of the recorded URL and out of every event: the DOM, inputs, requests and responses. A value of 6 or more characters is scrubbed wherever it appears, whatever its letters, so a page of your own that a secret route also matches, such as/invites/notificationsunder/invites/:key, hasnotificationsscrubbed from every later event of the page until you declare it inkeepRoutes. A shorter value is scrubbed only as the path segment after its route's segment.keepRoutesnames the routes whose segments are your app's own ids: it must have at least one literal. What its:namesegments name is never taken for a token, unless a credential's name or a secret route names it too.- A route outside these rules refuses the capture with
KUI_E_PRIVACY_ROUTE_INVALID, on every page load, whateversampleRatesays. - Routes are read when a capture starts and kept for the page. A second
init()while a capture is live returns that capture and adds no routes.
Your own patterns
privacy.piiPatterns adds your own patterns as { name, pattern } objects, where pattern is a regular expression. They run over network data only: over header values, over the string values inside JSON bodies, over form bodies as sent and decoded, and over every other body as text. They do not run over the page's text or attributes. Every match is replaced with [REDACTED], whether or not the pattern has the g flag. A pattern never changes a JSON key or a number, so a JSON body still parses.
They do not run over URLs, on purpose: a URL's path and query values are what a replay matches requests by, so rewriting them would make the recording unmatchable. Put an identifier that must be scrubbed by pattern in a header or the body instead.
Try your configuration
The SDK exports its PrivacyEngine, so you can run the same masking on your own strings:
import {PrivacyEngine} from "@keploy/capture-sdk";
new PrivacyEngine().maskText("contact user@example.com now"); // "contact [REDACTED] now"
new PrivacyEngine(privacy, privacyMode) takes your privacy options and your privacy mode. Its maskNetworkData(event) masks a network event's headers and URL as a capture does. It redacts the event's bodies only once a capture on the page has loaded the SDK's body code; until then it records each body as [MASKED], never in the clear.
What leaves the browser
Each request the SDK sends to your endpoint carries:
- the session id;
- a batch of events: rrweb's DOM events and the masked network calls, each with its method, URL, headers, bodies, status and duration;
- the page's metadata: its URL, the user agent, the viewport, the referrer, the language, the device pixel ratio and the start time;
- the SDK's name and version;
- the capture identity that lets Keploy join this recording to a backend recording of the same requests: the session id, the page's origin, a start time and a random nonce.
Each request also carries the ingest key in its X-API-Key header and a random batchId. The metadata and the capture identity ride on every batch. A batch is gzipped when the browser has CompressionStream and gzip makes it smaller. Each recorded input event also says whether the visitor made it (userTriggered: true) or the page's script wrote the value. The SDK sends nothing to anyone but your endpoint, and keeps nothing in cookies, localStorage or sessionStorage: it carries no identity of the visitor from one page load to the next.
What the dashboard, REST and MCP show
- The dashboard shows a flow to everyone who can view its app. A flow's page lists its steps, with a typed value as it was recorded (a masked one as asterisks), and its network calls with their method, recorded URL, status and time. The page shows no headers or bodies, but Keploy stores each call's headers and bodies, as the SDK recorded them, with its flow, because a replay serves them, and anyone who can view the app can read them through the dashboard's own API.
- The REST API and MCP return less, because their answers go into an AI agent's context: no typed values, no headers or bodies, no query strings, fragments or credentials in URLs, and a path segment that reads as a secret or a person's data replaced with
REDACTED. What an agent sees lists the rules.
Recognition, not a guarantee
The SDK finds credentials and personal data by their names, their shapes and patterns, and it cannot recognise every one. A credential in a shape the rules do not know is recorded: an unusual parameter name, a token that is a dictionary word or digits alone, a token in a path shorter than 16 characters (20 after a word such as invitations or verification), or a UUID or an ObjectId after such a word, as in /invitations/<uuid>. Where a value could be a credential or an app's own id, the SDK treats it as a credential: an id scrubbed by mistake can be kept with keepRoutes, but a credential recorded by mistake cannot be taken back.
So declare your secret routes, name a credential parameter like one (anything ending in token), and remember what every mode records as it is: URL paths, data-testid, id and class values, and under "balanced" query values and the parts of bodies no rule covers. Use "strict" for a public site, privacy.blockSelectors for an area that must never be recorded, and privacy.maskNetworkBodies when no body should leave the browser.