246 lines
8.1 KiB
TypeScript
246 lines
8.1 KiB
TypeScript
/**
|
|
* PII-scrubbing OpenTelemetry SpanProcessor.
|
|
*
|
|
* Decorator pattern: wraps an existing {@link SpanProcessor} (e.g. a
|
|
* {@link BatchSpanProcessor}) and redacts sensitive span attributes during
|
|
* `onEnd()` before delegating. The processor is structurally typed so that
|
|
* `@hivegrid/observability` does not need to take a hard dependency on the
|
|
* OpenTelemetry SDK packages — runtimes that already depend on
|
|
* `@opentelemetry/sdk-trace-base` (api, worker, web) pass their `BatchSpanProcessor`
|
|
* instances in directly.
|
|
*
|
|
* Scrubbing rules (see {@link redactSpanAttributes}):
|
|
* - `http.url`, `http.target` and the OTel v1.20+ aliases `url.full`,
|
|
* `url.path` get their query-string replaced with `?[scrubbed]`; fragments
|
|
* are removed and `url.query` is redacted wholesale. Customer-portal
|
|
* capability segments are redacted in URL attributes and span names.
|
|
* - HTTP request/response headers are filtered through {@link HEADER_ALLOWLIST}.
|
|
* Anything outside the allowlist (notably `authorization`, `cookie`,
|
|
* `set-cookie`, `x-api-key`) is dropped.
|
|
* - `db.statement` and `db.query.text` literal-string parameters (`'...'`
|
|
* and `"..."`) are rewritten to `?` (defense-in-depth — Prisma already
|
|
* parametrises).
|
|
* - `messaging.message_payload` is dropped entirely; the payload-size
|
|
* attribute (if present) is preserved.
|
|
*
|
|
* The processor MUST be registered BEFORE the exporter in the span-processor
|
|
* chain — typically by wrapping the exporter's `BatchSpanProcessor`:
|
|
*
|
|
* ```ts
|
|
* spanProcessors: [new PIISpanProcessor(new BatchSpanProcessor(otlpExporter))]
|
|
* ```
|
|
*/
|
|
|
|
/**
|
|
* Structural shape of an OpenTelemetry span passed to a SpanProcessor.
|
|
* Only the fields we mutate / read are typed here so we don't need to take
|
|
* a runtime dependency on `@opentelemetry/sdk-trace-base`.
|
|
*/
|
|
export interface PiiScrubableSpan {
|
|
name?: string | undefined;
|
|
attributes?: Record<string, unknown> | undefined;
|
|
}
|
|
|
|
/**
|
|
* Structural shape of `SpanProcessor` from `@opentelemetry/sdk-trace-base`.
|
|
* Async `forceFlush()` / `shutdown()` are declared as `Promise<void>` here
|
|
* to match the SDK shape exactly so a `BatchSpanProcessor` is assignable to
|
|
* `DelegateSpanProcessor`.
|
|
*/
|
|
export interface DelegateSpanProcessor {
|
|
onStart(span: PiiScrubableSpan, parentContext: unknown): void;
|
|
onEnd(span: PiiScrubableSpan): void;
|
|
forceFlush(): Promise<void>;
|
|
shutdown(): Promise<void>;
|
|
}
|
|
|
|
export const HEADER_ALLOWLIST: ReadonlySet<string> = new Set(
|
|
[
|
|
"content-type",
|
|
"user-agent",
|
|
"accept-language",
|
|
"accept-encoding",
|
|
"x-request-id",
|
|
].map((name) => name.toLowerCase()),
|
|
);
|
|
|
|
const QUERY_STRING_PLACEHOLDER = "?[scrubbed]";
|
|
|
|
const URL_LIKE_ATTRIBUTES = ["http.url", "http.target", "http.route", "url.full", "url.path", "url.query"] as const;
|
|
|
|
const PORTAL_CAPABILITY_ROUTE_PATTERN =
|
|
/((?:\/__portal)?\/[a-z0-9][a-z0-9-]{1,62}\/(?:login\/magic|setup|verify-email|reset-password)\/)[A-Za-z0-9_-]+/giu;
|
|
|
|
const DB_STATEMENT_ATTRIBUTES = ["db.statement", "db.query.text"] as const;
|
|
|
|
const DROP_ATTRIBUTES = ["messaging.message_payload"] as const;
|
|
|
|
const HEADER_PREFIXES = ["http.request.header.", "http.response.header."] as const;
|
|
|
|
/**
|
|
* Strips the query-string from a URL-like attribute, replacing it with
|
|
* `?[scrubbed]`, and redacts customer-portal capability path segments.
|
|
*/
|
|
export function scrubUrlQuery(value: string): string {
|
|
const queryIndex = value.indexOf("?");
|
|
const fragmentIndex = value.indexOf("#");
|
|
if (queryIndex < 0 && fragmentIndex < 0) return redactPortalCapabilityTokens(value);
|
|
if (queryIndex >= 0 && (fragmentIndex < 0 || queryIndex < fragmentIndex)) {
|
|
return `${redactPortalCapabilityTokens(value.slice(0, queryIndex))}${QUERY_STRING_PLACEHOLDER}`;
|
|
}
|
|
return redactPortalCapabilityTokens(value.slice(0, fragmentIndex));
|
|
}
|
|
|
|
/** Redacts customer-portal one-time credentials from span/transaction names. */
|
|
export function scrubSpanName(value: string): string {
|
|
return scrubUrlQuery(value);
|
|
}
|
|
|
|
/**
|
|
* Replaces all single-/double-quoted string literals in a SQL statement
|
|
* with `?`. Used as defense-in-depth on top of Prisma's parameterisation.
|
|
*/
|
|
export function scrubDbStatement(statement: string): string {
|
|
// Walk character-by-character so we handle escaped quotes and avoid
|
|
// catastrophic backtracking on adversarial input.
|
|
let out = "";
|
|
let i = 0;
|
|
while (i < statement.length) {
|
|
const ch = statement.charAt(i);
|
|
if (ch === "'" || ch === '"') {
|
|
const quote = ch;
|
|
let j = i + 1;
|
|
while (j < statement.length) {
|
|
const inner = statement.charAt(j);
|
|
if (inner === "\\" && j + 1 < statement.length) {
|
|
j += 2;
|
|
continue;
|
|
}
|
|
if (inner === quote) {
|
|
break;
|
|
}
|
|
j += 1;
|
|
}
|
|
out += "?";
|
|
i = j + 1;
|
|
continue;
|
|
}
|
|
out += ch;
|
|
i += 1;
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/**
|
|
* Returns whether a span attribute key targets an HTTP header.
|
|
* Both `http.request.header.<name>` and `http.response.header.<name>`
|
|
* are matched (per OTel HTTP semantic conventions v1.20+).
|
|
*/
|
|
export function isHeaderAttribute(key: string): { isHeader: true; name: string } | { isHeader: false } {
|
|
for (const prefix of HEADER_PREFIXES) {
|
|
if (key.startsWith(prefix)) {
|
|
return { isHeader: true, name: key.slice(prefix.length).toLowerCase() };
|
|
}
|
|
}
|
|
return { isHeader: false };
|
|
}
|
|
|
|
/**
|
|
* Mutates the given attribute bag in-place to apply the PII-scrubbing rules.
|
|
* Exported for unit-tests so we can verify each rule independently of the
|
|
* full SpanProcessor lifecycle.
|
|
*/
|
|
export function redactSpanAttributes(attributes: Record<string, unknown> | undefined): void {
|
|
if (!attributes) return;
|
|
|
|
for (const key of Object.keys(attributes)) {
|
|
// Drop disallowed attributes wholesale.
|
|
if ((DROP_ATTRIBUTES as readonly string[]).includes(key)) {
|
|
delete attributes[key];
|
|
continue;
|
|
}
|
|
|
|
// Strip query-strings from URL-like attributes.
|
|
if ((URL_LIKE_ATTRIBUTES as readonly string[]).includes(key)) {
|
|
const value = attributes[key];
|
|
if (typeof value === "string") {
|
|
attributes[key] = key === "url.query" ? (value ? "[scrubbed]" : "") : scrubUrlQuery(value);
|
|
}
|
|
continue;
|
|
}
|
|
|
|
// Scrub SQL literals from current and legacy database statement fields.
|
|
if ((DB_STATEMENT_ATTRIBUTES as readonly string[]).includes(key)) {
|
|
const value = attributes[key];
|
|
if (typeof value === "string") {
|
|
attributes[key] = scrubDbStatement(value);
|
|
}
|
|
continue;
|
|
}
|
|
|
|
// Allowlist-filter HTTP request/response headers.
|
|
const header = isHeaderAttribute(key);
|
|
if (header.isHeader) {
|
|
if (!HEADER_ALLOWLIST.has(header.name)) {
|
|
delete attributes[key];
|
|
}
|
|
continue;
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Decorator SpanProcessor that scrubs PII from every ended span before
|
|
* forwarding to a delegate (typically a `BatchSpanProcessor`).
|
|
*/
|
|
export class PIISpanProcessor implements DelegateSpanProcessor {
|
|
constructor(private readonly delegate: DelegateSpanProcessor) {}
|
|
|
|
onStart(span: PiiScrubableSpan, parentContext: unknown): void {
|
|
this.delegate.onStart(span, parentContext);
|
|
}
|
|
|
|
onEnd(span: PiiScrubableSpan): void {
|
|
if (!redactSpanName(span)) {
|
|
return;
|
|
}
|
|
try {
|
|
redactSpanAttributes(span.attributes);
|
|
} catch {
|
|
// Telemetry is optional; privacy is not. Replace the entire attribute bag
|
|
// on scrubber failure, or drop the span when even that is impossible.
|
|
try {
|
|
span.attributes = {};
|
|
} catch {
|
|
return;
|
|
}
|
|
}
|
|
this.delegate.onEnd(span);
|
|
}
|
|
|
|
forceFlush(): Promise<void> {
|
|
return this.delegate.forceFlush();
|
|
}
|
|
|
|
shutdown(): Promise<void> {
|
|
return this.delegate.shutdown();
|
|
}
|
|
}
|
|
|
|
function redactPortalCapabilityTokens(value: string): string {
|
|
return value.replace(PORTAL_CAPABILITY_ROUTE_PATTERN, "$1redacted");
|
|
}
|
|
|
|
function redactSpanName(span: PiiScrubableSpan): boolean {
|
|
if (typeof span.name !== "string") return true;
|
|
const sanitized = scrubSpanName(span.name);
|
|
if (sanitized === span.name) return true;
|
|
try {
|
|
span.name = sanitized;
|
|
return span.name === sanitized;
|
|
} catch {
|
|
// A credential-bearing immutable span name cannot be exported safely.
|
|
return false;
|
|
}
|
|
}
|