/** * Copyright (c) Meta Platforms, Inc. and affiliates. * * This source code is licensed under the MIT license found in the * LICENSE file in the root directory of this source tree. * * @format * @lightSyntaxTransform * @oncall memory_lab */ import type { IHeapSnapshot, RawHeapSnapshot } from './Types'; /** * Remove user data from a heap snapshot while leaving it analyzable. * * A heap snapshot is a verbatim dump of everything the page had in memory, so * it carries message bodies, tokens, contact ids and serialized DOM. Sharing * one — with a colleague, in a task, with a model — publishes all of it. The * goal here is a capture that can be shared and still answers the questions * snapshots are taken to answer. * * **What makes that possible is that the format separates values from labels.** * Every entry in the shared `strings` table is reached in one of two ways: * * - as the `name` of a `string` / `concatenated string` / `sliced string` node * — that is the CONTENT of a JS string living on the heap, i.e. data; * - as an edge name, or the `name` of an object / closure / code / native node * — that is a LABEL: a class name, a function name, a property key. * * A retainer trace is built entirely out of labels. So redacting exactly the * first kind is a type test, not a heuristic, and it leaves every trace, * histogram, dominator and shape analysis fully readable. * * Two things that clean split does NOT cover, both of which this module also * handles, because a real capture leaks through both: * * 1. **A label can itself be data.** An object keyed by account id, order id or * session id turns user identifiers into property names — structurally a * label, semantically a payload. No node-type test can tell `.addListener` * from a key a database row supplied, so those are matched by shape against * internet-standard formats. For identifier schemes private to one * application, which no pattern list can anticipate, the report names what * it could not classify and {@link AnonymizeOptions.shouldRedact} is the * seam for acting on it. * 2. **`native` node names can hold serialized DOM.** Browser engines write * element descriptions that on one measured capture reached 78 KB of * `outerHTML`, base64-inlined images and user-visible text included. * * @internal */ /** * How redacted text is generated. * * - `stable` — length-preserving, and derived from the value, so equal inputs * stay equal and distinct inputs stay distinct. Duplication, interning and * dedup analyses therefore keep reporting the truth. * - `uniform` — length-preserving fill with a single repeated character. Leaks * strictly less (not even equality), but it collapses every distinct value of * the same length into one, which MANUFACTURES string duplication: on one * measured capture 272,234 distinct values collapsed to 607, and duplication * tools then reported tens of megabytes of savings that do not exist. */ export type AnonymizationMode = 'stable' | 'uniform'; /** * Options accepted by {@link anonymizeHeapSnapshot}. */ export type AnonymizeOptions = { /** * how replacement text is generated, defaults to `stable` * (see {@link AnonymizationMode}) */ mode?: AnonymizationMode; /** * salt mixed into `stable` replacements. The default is the empty string, * which is deterministic ACROSS FILES — the same value anonymizes to the * same token in every capture, so a ladder of snapshots stays diffable. That * also means a deterministic token is confirmable by anyone holding a * candidate value; pass an explicit salt for anything leaving your trust * boundary, and reuse that one salt across every file in the set. */ salt?: string; /** * also redact node names that look like serialized DOM, defaults to `true` */ redactDomText?: boolean; /** * also redact string table entries whose CONTENT looks like an identifier, * wherever they are referenced — including as property names, defaults to * `true` */ redactIdentifierKeys?: boolean; /** * how many consecutive digits make a string an identifier rather than an * array index, defaults to `9`. Chosen from the data: V8 emits exhaustive * runs of short numeric index names (10 one-digit, 90 two-digit, 900 * three-digit ... 138,432 six-digit on one capture) and then the count falls * off a cliff, so a floor in that gap separates indices from ids. */ minDigitRunLength?: number; /** extra patterns to redact, matched against the string table entry */ extraPatterns?: RegExp[]; /** patterns that must NEVER be redacted; these win over every built-in rule */ keepPatterns?: RegExp[]; /** * the final say on any entry, consulted BEFORE every built-in rule. * * No fixed rule set can know an identifier scheme private to one application, * and guessing at one inside memlab would mean shipping other people's * formats to everybody. This is the seam for that instead: return `true` to * redact, `false` to protect, or `undefined` to let the built-in rules * decide. `AnonymizeReport.unclassifiedLabelFamilies` is the companion — it * names the shapes still in the clear, which is where a caller finds out what * their own scheme looks like. * * ```typescript * anonymizeHeapSnapshot(heap, { * // this app keys caches by order id: ORD- * shouldRedact: (value, ctx) => * ctx.isLabel && value.startsWith('ORD-') ? true : undefined, * }); * ``` */ shouldRedact?: (value: string, context: RedactionContext) => boolean | undefined; }; /** * A family of labels left in the clear that share one machine-generated shape. * * This is how the tool generalizes past its own pattern list. No fixed set of * formats can know an identifier scheme private to one application, so rather * than guess, the report names what it could not classify and lets the caller * decide. A family here is a prompt to look, not a finding: `d.d.d` is a * version number in one app and an account id in another. */ export type UnclassifiedLabelFamily = { /** * character-class shape with runs collapsed, e.g. `d@a` for `4155551234@ex` */ shape: string; /** how many distinct labels in the string table share it */ count: number; /** up to three of them, verbatim, so the shape can be recognized */ examples: string[]; }; /** * What is known about one string table entry when {@link AnonymizeOptions.shouldRedact} * is asked to judge it. */ export type RedactionContext = { /** * true when this entry is the CONTENT of a string on the heap. Redacting one * of these is what the node-type rule already does by default. */ isValue: boolean; /** * true when this entry is used as a class name, function name, property key, * closure variable or context slot — i.e. as part of the vocabulary a * retainer trace is written in. Redacting one of these costs debuggability, * so it is the decision worth thinking about. */ isLabel: boolean; /** * how many edges in the whole snapshot use this entry as their name. A * programmer-written property name is reused; an identifier minted per record * is used once or twice. Useful for telling one from the other without * knowing the format. */ labelUseCount: number; /** * character-class shape with runs collapsed, e.g. `d@a` for `4155551234@ex` * or `dadada-ada-da` for a UUID prefix. Lets a caller match a scheme by shape * instead of writing a precise regex. */ shape: string; }; /** One rule's contribution, as reported by {@link AnonymizeReport}. */ export type AnonymizeRuleCount = { /** the rule that matched, e.g. `dom-text` or `digit-run` */ rule: string; /** how many distinct string table entries it matched */ count: number; }; /** * What {@link anonymizeHeapSnapshot} did, and — just as importantly — what it * left behind. */ export type AnonymizeReport = { /** the mode that was applied */ mode: AnonymizationMode; /** whether a non-empty salt was used */ salted: boolean; /** number of entries in the string table before anonymization */ stringTableSize: number; /** string values redacted because they are the content of a string node */ valuesRedacted: number; /** * how many redacted values were written to an APPENDED table entry rather * than over the original. The string table is deduplicated, so one entry can * be both a string's value and a property name; splitting is what keeps * redaction from destroying the label. */ entriesSplit: number; /** entries redacted everywhere because their content looked sensitive */ contentRedacted: number; /** the per-rule breakdown of `contentRedacted` */ contentRedactedByRule: AnonymizeRuleCount[]; /** * machine-generated-looking labels still in the clear, most common first. * Review these: anything here that is an identifier in YOUR application is a * residual leak, and the fix is to pass it as an `extraPatterns` entry. See * {@link UnclassifiedLabelFamily}. */ unclassifiedLabelFamilies: UnclassifiedLabelFamily[]; }; /** * Rewrite a parsed heap snapshot in place so it no longer carries user data. * * Redacts the content of every string on the heap, plus any string table entry * whose text looks like an identifier, a credential or serialized DOM. Class * names, function names and ordinary property keys are left alone, so retainer * traces, class histograms, dominator trees and shape analyses all still work * on the result. * * The snapshot is modified in place and its parsed view updates with it — node * names are read from the string table on each access rather than cached. * Persist the result with {@link serializeHeapSnapshot}. * * This does not defeat a determined attacker who already knows what they are * looking for: lengths are preserved exactly (they have to be, or `self_size` * stops matching), and in `stable` mode equal values stay equal. It removes the * content, not the shape of the content. * * @param snapshot the parsed heap snapshot to rewrite in place * @param options see {@link AnonymizeOptions} * @returns a summary of what was redacted, per rule; see * {@link AnonymizeReport} * * * **Examples**: * ```typescript * import type {IHeapSnapshot} from '@memlab/core'; * import { * dumpNodeHeapSnapshot, * anonymizeHeapSnapshot, * serializeHeapSnapshot, * } from '@memlab/core'; * import {getFullHeapFromFile} from '@memlab/heap-analysis'; * * (async function () { * const file = dumpNodeHeapSnapshot(); * const heap: IHeapSnapshot = await getFullHeapFromFile(file); * * const report = anonymizeHeapSnapshot(heap); * console.log(`redacted ${report.valuesRedacted} string values`); * * serializeHeapSnapshot(heap, '/tmp/shareable.heapsnapshot'); * })(); * ``` */ export declare function anonymizeHeapSnapshot(snapshot: IHeapSnapshot, options?: AnonymizeOptions): AnonymizeReport; /** * The in-place rewrite, against the raw snapshot data. * * @param raw the raw snapshot data to rewrite * @param options see {@link AnonymizeOptions} * @returns a summary of what was redacted; see {@link AnonymizeReport} * * @internal */ export declare function anonymizeRawHeapSnapshot(raw: RawHeapSnapshot, options?: AnonymizeOptions): AnonymizeReport; /** * Read a snapshot file into its raw arrays, WITHOUT building the object graph. * * `HeapParser.parse` additionally computes referrers, dominators, detachedness * and node indices — on a 7.1M-node capture that is the part that costs ~15 * seconds and several gigabytes. Anonymization needs none of it: it works off * node types, edge names and the string table. Reading the arrays and stopping * there is the difference between "shareable in a moment" and "load the whole * heap first". * * @param file absolute path of the `.heapsnapshot` file to read * @returns the snapshot's raw arrays * * @internal */ /** * The three phases {@link anonymizeHeapSnapshotFile} moves through. Reading is * the slow one on a large capture — a multi-hundred-MB `.heapsnapshot` spends * most of its wall clock in the parse, before anything is redacted. */ export type AnonymizePhase = 'read' | 'anonymize' | 'write'; /** * Called as each phase STARTS, so a caller can show which one is running. * * Phase-level rather than byte-level on purpose: the parse is a single * `JSON.parse` over the non-typed-array remainder, so there is no honest * intermediate percentage to report from inside it. Saying "reading" and * meaning it beats a bar that fabricates progress. */ export type AnonymizeProgressCallback = (phase: AnonymizePhase, step: number, totalSteps: number) => void; export declare function readRawHeapSnapshot(file: string): Promise; /** * Anonymize a `.heapsnapshot` file and write the result to another file. * * The file-to-file form of {@link anonymizeHeapSnapshot}, and the one to reach * for when the capture is only being shared rather than analyzed here: it skips * building the object graph on the way in, and streams on the way out, so * neither the input nor the output is ever held as one string. * * @param inputFile absolute path of the capture to read * @param outputFile absolute path to write the anonymized capture to; an * existing file at that path is overwritten * @param options see {@link AnonymizeOptions} * @returns a summary of what was redacted, and what was left in the clear; see * {@link AnonymizeReport} * * * **Examples**: * ```typescript * import {anonymizeHeapSnapshotFile} from '@memlab/core'; * * (async function () { * const report = await anonymizeHeapSnapshotFile( * '/tmp/capture.heapsnapshot', * '/tmp/shareable.heapsnapshot', * ); * console.log(`redacted ${report.valuesRedacted} string values`); * for (const family of report.unclassifiedLabelFamilies) { * console.log(`still in the clear: ${family.count} x ${family.shape}`); * } * })(); * ``` */ export declare function anonymizeHeapSnapshotFile(inputFile: string, outputFile: string, options?: AnonymizeOptions, onProgress?: AnonymizeProgressCallback): Promise; /** * Report what anonymizing a capture WOULD remove, and what it would leave, * without writing anything. * * Point it at a capture someone already anonymized to find out whether they * missed something: `unclassifiedLabelFamilies` names the identifier-shaped * text still in the clear. Run against one already-anonymized capture, this is * what showed its author had removed every string VALUE and left 26,303 account * handles behind as property names. * * @param inputFile absolute path of the capture to inspect * @param options see {@link AnonymizeOptions} * @returns the same summary {@link anonymizeHeapSnapshotFile} returns, for a * run that was not written to disk * * * **Examples**: * ```typescript * import {auditHeapSnapshotFile} from '@memlab/core'; * * (async function () { * const report = await auditHeapSnapshotFile('/tmp/shared.heapsnapshot'); * console.log(report.unclassifiedLabelFamilies); * })(); * ``` */ export declare function auditHeapSnapshotFile(inputFile: string, options?: AnonymizeOptions, onProgress?: AnonymizeProgressCallback): Promise; /** * Canonical form of a path, for deciding whether two of them are the same file. * * A string comparison is not enough, and the cost of it being wrong here is the * original capture: `a.heapsnapshot` and `./a.heapsnapshot`, an absolute and a * relative spelling, or a symlink and its target are all distinct strings * naming one file. `realpathSync` resolves all three. * * The output file usually does not exist yet, which makes `realpathSync` throw * on it — so its DIRECTORY is canonicalized instead and the basename appended. * That still catches a symlinked parent, which a plain `path.resolve` would * miss. Falls back to `path.resolve` when even the directory is absent, since * at that point the two cannot be the same existing file anyway. * * @param file the path to canonicalize * @returns a path safe to compare against another canonicalized path * * @internal */ export declare function resolveForComparison(file: string): string; //# sourceMappingURL=HeapAnonymizer.d.ts.map