---
title: "scrub | Speedscale Docs"
description: "Use the scrub transform in Speedscale to replace a specific value with a masked substitute across the entire current RRPair body, improving responder signature match rates by blanking out rotating values."
canonical: "https://docs.speedscale.com/guides/transformation/transforms/scrub/"
---

[Documentation index](https://docs.speedscale.com/guides/llms.txt) | [Markdown](https://docs.speedscale.com/guides/transformation/transforms/scrub/index.md) | [Canonical page](https://docs.speedscale.com/guides/transformation/transforms/scrub/)

# scrub

The `scrub` transform takes a value extracted by the chain and rewrites every occurrence of that value across the **current RRPair's JSON bodies** with a replacement string (default `*`). It is purpose-built for "blank this rotating value out everywhere it appears so the responder can match the request" workflows — request IDs, correlation IDs, dynamic tokens that change every call but should not affect signature matching.

It is **not** a scoped substitution. Even when the chain only extracts one field, `scrub` walks both the request and response bodies (depending on `selector`) and replaces every occurrence of the extracted value as a substring inside any JSON string value.

*   **Transform type name (config/API):** `scrub`
*   **Shorthand format:** `scrub(ignore=...,new=...)`

<a id="quick-start"></a>

## Quick Start

Blank out a rotating request ID:

```json
"type": "scrub",
"config": {}
```

```text
req_body() → json_path(path="requestId") → scrub()
```

This extracts `requestId` from the request body and replaces every occurrence of that value across the JSON body with `*`. Combine with [`smart_replace_recorded`](https://docs.speedscale.com/guides/transformation/transforms/smart_replace_recorded/) when you also need the responder to **remember** the new value for downstream RRPairs (see Example 4 below).

<a id="how-it-works"></a>

## How It Works

`scrub` runs in two phases.

1.  **First phase** — receive the extracted token (the "old value"), and register a deferred substitution against the current RRPair's request body, response body, or both (controlled by `selector`). The transform returns the configured `new` value so the rest of the chain sees the post-scrub form.
2.  **Second phase** — no-op. The deferred substitution registered in the first phase runs after the chain completes and walks the JSON body, replacing every occurrence of the old value (as a substring) inside any non-ignored field's string value with `new`.

<a id="substring-replacement"></a>

### Substring Replacement

The replacement is a substring scan within each JSON string value, not a whole-field equality check. If the extracted value is `SCRUB_ME`:

*   `"name": "SCRUB_ME"` becomes `"name": "*"`.
*   `"email": "myname@SCRUB_ME.com"` becomes `"email": "myname@*.com"`.
*   `"FirstName": "FirstSCRUB_ME"` becomes `"FirstName": "First*"`.

This is what makes the transform useful for partial-match scrubbing — but it also means a short or common extracted value (e.g. `false`, `1`, `e`) will collide with unrelated text. Pick an extraction path whose value is unique enough to scrub safely.

<a id="scope-current-rrpair-only"></a>

### Scope: Current RRPair Only

`scrub` only touches the current RRPair's JSON body. It does **not**:

*   Walk URL path segments, query strings, or HTTP headers.
*   Cross over into other RRPairs in the replay session.
*   Operate on non-JSON bodies.

If you need cross-RRPair propagation, use [`smart_replace`](https://docs.speedscale.com/guides/transformation/transforms/smart_replace/) (live values) or [`smart_replace_recorded`](https://docs.speedscale.com/guides/transformation/transforms/smart_replace_recorded/) (recorded → live mapping).

<a id="configuration"></a>

## Configuration

```json
"type": "scrub",
"config": {
    "ignorePaths": "<comma-separated key names>",
    "new": "<replacement string>",
    "selector": "<request|response|both>"
}
```

| Parameter | Required | Default | Description |
| --- | --- | --- | --- |
| `ignorePaths` | No | empty | Comma-separated list of JSON key names to skip. Matched against the **last key** in the path only — `"foo"` skips any field named `foo` at any depth. |
| `new` | No | `*` | The replacement string that overwrites occurrences of the extracted value. |
| `selector` | No | `request` | Which side of the RRPair the substitution targets. `request` (default), `response`, or `both`. |

<a id="ignorepaths-matching"></a>

### `ignorePaths` Matching

The match is a **last-segment exact string compare**, not a JSONPath. Given a body like `{"user": {"profile": {"name": "..."}}}`, `ignorePaths=name` skips the `name` field regardless of nesting depth. You do not need (and cannot use) the full dotted path — just the leaf key name.

<a id="selector-behavior"></a>

### `selector` Behavior

| Value | Scope |
| --- | --- |
| `request` (default) | Only the request body of the current RRPair is scrubbed. |
| `response` | Only the response body of the current RRPair is scrubbed. |
| `both` | Both the request and response bodies are scrubbed. |

<a id="examples"></a>

## Examples

<a id="example-1--blank-out-a-request-id"></a>

### Example 1 — Blank out a request ID

```json
{
    "type": "scrub",
    "config": {}
}
```

```text
req_body() → json_path(path="requestId") → scrub()
```

If the request body contains `{"requestId": "req_abc123", "data": {"correlationId": "req_abc123"}}`, both occurrences become `*`.

<a id="example-2--custom-replacement-and-ignored-fields"></a>

### Example 2 — Custom replacement and ignored fields

```json
{
    "type": "scrub",
    "config": {
        "ignorePaths": "userId,version",
        "new": "REDACTED"
    }
}
```

```text
res_body() → scrub(selector=response, ignorePaths="userId,version", new="REDACTED")
```

Walks the response body and replaces the extracted value everywhere except in any `userId` or `version` field. Common when you want a scrubbed value for matching but still need a particular field (a stable user ID, an API version) preserved.

<a id="example-3--scrub-both-sides"></a>

### Example 3 — Scrub both sides

```json
{
    "type": "scrub",
    "config": {
        "selector": "both",
        "new": "*"
    }
}
```

Useful when the same dynamic value appears in both the request and the response and you want symmetric scrubbing for matching.

<a id="example-4--pairing-with-smart_replace_recorded"></a>

### Example 4 — Pairing with smart\_replace\_recorded

```text
smart_replace_recorded() → req_body() → json_path(path="requestId") → scrub()
```

`smart_replace_recorded` records the mapping `recorded_requestId → live_requestId` so the responder can rewrite the recorded value to the live one in subsequent RRPairs. `scrub` then blanks out the live `requestId` in the current request so the signature match isn't sensitive to the rotating value. This is the canonical "match-and-learn" pattern.

<a id="common-misconceptions"></a>

## Common Misconceptions

1.  **"`scrub` only changes the extracted field."** No. It rewrites every substring occurrence of the extracted value across the chosen sides of the RRPair body.
    
2.  **"`ignorePaths` accepts full JSONPaths."** No. Only the last key name is matched. `ignorePaths=metadata` ignores any field named `metadata` at any depth; `ignorePaths=data.metadata` matches no field at all.
    
3.  **"`scrub` works on headers, URL, or non-JSON bodies."** No. The deferred substitution runs against the RRPair's JSON request/response bodies only. Headers and URL components are not touched.
    
4.  **"`scrub` propagates to other RRPairs."** No. The substitution is scoped to the current RRPair. For cross-RRPair behavior, see [`smart_replace`](https://docs.speedscale.com/guides/transformation/transforms/smart_replace/).
    
5.  **"The match is a whole-field equality check."** No. It is a substring replacement. Be careful with extracted values that are short or appear inside larger strings unintentionally.
    

<a id="troubleshooting"></a>

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Body unchanged after the transform | The body wasn't valid JSON, or the extracted value never appears in the body | Confirm the body is JSON and the extracted value matches at least one substring |
| Unintended fields got scrubbed | Extracted value is short or common, hitting unrelated substrings | Choose a more unique extraction, or add the affected key to `ignorePaths` |
| Response body wasn't scrubbed | `selector` defaults to `request` | Set `selector=response` or `selector=both` |
| `ignorePaths` not honored | Used a dotted path instead of a leaf key | Use just the last key name (e.g. `metadata`, not `data.metadata`) |
| Wanted both scrub and downstream propagation | `scrub` is single-RRPair only | Combine with [`smart_replace_recorded`](https://docs.speedscale.com/guides/transformation/transforms/smart_replace_recorded/) for cross-RRPair learning |

<a id="related-transforms"></a>

## Related Transforms

*   [`scrub_date`](https://docs.speedscale.com/guides/transformation/transforms/scrub_date/) — sibling transform that targets any date-shaped value in the body. Use when the goal is to neutralize timestamps, not a specific extracted value.
*   [`smart_replace_recorded`](https://docs.speedscale.com/guides/transformation/transforms/smart_replace_recorded/) — pair with `scrub` to remember the live value before blanking it out.
*   [`smart_replace`](https://docs.speedscale.com/guides/transformation/transforms/smart_replace/) — for cross-RRPair propagation of live values.
*   [`dlp_field`](https://docs.speedscale.com/guides/transformation/transforms/dlp_field/) — when the goal is policy-driven redaction (PII, secrets), not match-rate improvement.
*   [`constant`](https://docs.speedscale.com/guides/transformation/transforms/constant/), [`replace`](https://docs.speedscale.com/guides/transformation/transforms/replace/) — for scoped substitution on a single field.

<a id="advanced-notes"></a>

## Advanced Notes

*   The substitution is registered as a finalizer on the current RRPair and runs after the chain completes, so transforms that follow `scrub` in the chain see the configured `new` value, not the original.
*   The substring scan walks JSON string scalars only. Numeric, boolean, and `null` values are not rewritten unless the extracted value's bytes happen to appear in the serialized output of a string field.
*   Errors decoding the body are swallowed silently — the transform may be running on a partial RRPair that only has one side, and the other side is allowed to be absent.
*   `scrub` does not require the recorded response to be present in the action file.
