> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traversal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Redaction

> Scrub sensitive information from your data before it leaves your environment. Configurable and customizable.

Both the Traversal Connector and the Traversal Processor support redaction: a regex-based pipeline that rewrites sensitive text in your data before it is forwarded to Traversal. Rules are defined in a TOML file you author.

## How it works

When a rules file is configured, the payload of each request is scanned against your rules in order. Each rule is a named regex pattern with a replacement string. Rules are applied sequentially. The output of one rule becomes the input to the next. Thus, ordering matters when patterns could overlap.

Redaction which operates on JSON payloads replaces patterns in JSON keys *and* values while preserving the structure of the payload.

## Rules file format

```toml theme={null}
version = "v1"

# Optional. Fallback replacement for rules that omit their own.
# Defaults to [REDACTED] if not set.
default_replacement = "[REDACTED]"

[[rules]]
name        = "email"
type        = "regex-structured-data"
pattern     = '[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,6}'
# Uses default_replacement

[[rules]]
name        = "ssn"
type        = "regex-structured-data"
pattern     = '\b\d{3}-\d{2}-\d{4}\b'
replacement = "[SSN]"
```

### Fields

| Field                 | Required | Description                                                                                                                  |
| :-------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------- |
| `version`             | Yes      | Schema version. Use `"v1"`.                                                                                                  |
| `default_replacement` | No       | Fallback replacement for rules that omit `replacement`. Defaults to `[REDACTED]`.                                            |
| `rules[].name`        | Yes      | Human-readable label for the rule. Appears in logs and metrics.                                                              |
| `rules[].type`        | Yes      | `"regex-structured-data"` for the Processor (walks JSON fields). Rules with an unrecognised type are skipped with a warning. |
| `rules[].pattern`     | Yes      | Regex pattern. All matches in the string value are replaced.                                                                 |
| `rules[].replacement` | No       | Text substituted for each match. Falls back to `default_replacement`.                                                        |

<Note>
  The regex engine does not support lookaheads, lookbehinds, or backtracking. Patterns using those features will cause startup to fail with a parse error.
</Note>

### Field filtering

The redaction engine supports two optional per-rule fields that restrict which fields a rule applies to:

| Field                   | Description                                                                                          |
| :---------------------- | :--------------------------------------------------------------------------------------------------- |
| `rules[].redact_fields` | Allowlist of field names this rule applies to. When set, the rule only fires on fields in this list. |
| `rules[].skip_fields`   | Blocklist of field names this rule skips. When set, the rule never fires on fields in this list.     |

These rules can be combined on the same rule in tandem. When `skip_fields` and `redact_fields` are set, both must pass for the rule to fire on a given field. Rules without either filter apply to all fields.

```toml theme={null}
[[rules]]
name          = "card-number"
type          = "regex-structured-data"
pattern       = '\b\d{16}\b'
replacement   = "[CARD]"
redact_fields = ["message", "body"]   # only apply to these fields
```