Data Masking

Rewrite sensitive values in the response, in memory, before they reach the client.

A query runs against real production data and returns real production data. Data Masking sits on the way back: the Sidecar decodes the response as it streams, finds sensitive values, and rewrites them before the client ever sees them.

Nothing is copied, staged or transformed at rest. The masking happens in memory, in real time, at the protocol layer — so it works the same for psql, for an ORM, for a dashboard and for an agent.

Masking runs on responses only. Requests are never rewritten: changing the statement the upstream executes is a correctness change wearing a privacy label.

Free tier: one Data Masking rule and one Guardrail per Sidecar are free, forever. Running more than one rule per feature, or managing rules centrally across Sidecars, requires Enterprise.

---

Configuration

One block. mask says what to rewrite, and a mask block carrying rules masks — there is no second switch to set.

config.yaml

mask:
  rules:
    - {name: emails, entities: [EMAIL_ADDRESS], strategy: redact}
    - {name: ssn,    entities: [US_SSN], strategy: partial, keep_last: 4}

entities is a list, even for one type, and one rule can name several:

- {name: national-ids, entities: [US_SSN, BR_CPF], strategy: redact}

Detection needs no configuration of its own: omit pii and every supported entity is enabled. Add the section only to narrow the set, which also makes it exhaustive — a mask rule naming a type outside the list is then refused at startup rather than silently masking nothing.

config.yaml

pii:                              # optional
  entities: [EMAIL_ADDRESS, US_SSN, CREDIT_CARD, BR_CPF, IBAN_CODE]

The same query now comes back rewritten:

     name     |          email           |     ssn     |          iban
--------------+--------------------------+-------------+------------------------
 Ada Lovelace | [REDACTED:EMAIL_ADDRESS] | ***-**-6789 | ******************5432
 Grace Hopper | [REDACTED:EMAIL_ADDRESS] | ***-**-4321 | ******************3000

Breadth has a cost. US_SSN carries no checksum, so nine digits in a legal range is a valid one as far as any detector can tell, and a mask rule naming it rewrites ordinary numeric columns:

{"order_id": 457555462, "customer_id": 123456781}

Both are reported as US_SSN. Prefer a columns rule for a column you can name, and reach for a narrowing pii.entities list when a lane’s data makes a type genuinely ambiguous.

Rule fields

Field	Meaning
entities	List of entity types to rewrite wherever they appear. A list, even for one type. Required unless columns is set.
columns	Result-set column names to mask outright, compared case-insensitively.
strategy	redact, mask, partial or hash. Empty means redact.
keep_last	Tail length for partial. Default 4.
mask_char	Replacement character for mask and partial. Default *.

Strategies

Strategy	4111111111111111 becomes
redact	[REDACTED:CREDIT_CARD]
mask	****************
partial	************1111
hash	sha256:<first 16 hex>

hash is the one worth knowing about: equal inputs give equal outputs, so a masked column still works as a join key. An analyst can group by customer without ever seeing a customer.

---

Entity rules and column rules

Two ways to name what gets masked, and they fail in opposite directions.

Entity rules mask by detection. They work anywhere a value appears, including inside an opaque HTTP body where the protocol names nothing — and they miss whatever the detector does not recognize.

Column rules mask by position. They cannot miss, because they never guess — and they only work where the protocol names its values, which means result sets, not payloads.

postgres  SELECT ssn FROM customers   →  ***-**-6789   column rule caught it
HTTP      POST {"x":"123-45-6789"}    →  123-45-6789   no detection, no column

Use column rules for the columns you know, and entity rules for everything else.

---

Inheritance: a listener’s mask block replaces the defaults

This is the single most common way a working config quietly stops masking:

config.yaml

mask:                                    # top-level defaults
  rules:
    - {name: emails, entities: [EMAIL_ADDRESS], strategy: redact}
    - {name: ssn, entities: [US_SSN], strategy: partial, keep_last: 4}

listeners:
  - name: appdb
    protocol: postgres
    listen: 0.0.0.0:15432
    upstream: appdb:5432
    mask:
      rules:
        - {name: ssn-column, columns: [ssn], strategy: partial, keep_last: 4}
        - {name: emails, entities: [EMAIL_ADDRESS], strategy: redact}   # relisted on purpose

A listener’s mask block replaces the top-level list rather than extending it. Adding one column rule drops every inherited entity rule, so list those again alongside it. This is deliberate: a rule owns an entity type, and two concatenated lists would leave two rules competing for one entity.

guardrails.rules behaves the opposite way — it concatenates.

---

Verify what actually resolved

The admin API reports the resolved state per listener, which is the only place the merge above is visible:

hoop start sidecar --config config.yaml --validate

config OK: 1 listener(s)
  appdb            postgres  1 rule(s) + masking

curl -s localhost:19000/config | python3 -m json.tool

If a value comes back unmasked, the detector probably refused it rather than missed it — obvious test fixtures like 123-45-6789 are deliberately not reported. Add a columns rule, or check whether a pii.entities list is narrowing detection past the type you expected.

---

Looking for masking on the Hoop Gateway instead? That is a different implementation, configured in the web app with DLP providers and per-resource roles. See Live Data Masking.

Next

Guardrails

Control what reaches the resource, not just what comes back.

Config File Reference

Every field, the full entity list, and what startup refuses.