mask

Documentation

Overview

Package mask applies PII redaction to result rows before they leave the egress network.

Two layers compose:

• Remote (default) — calls an external analyze/anonymize service to detect and redact PII.
• Overlay (caller-defined) — a column->token map you supply, off by default, layered on top.

The agent runs these locally so raw values are redacted at the source; only masked bytes are forwarded back to the client.

Index

• type Chain
  • func NewChain(maskers ...Masker) *Chain
  • func (c *Chain) MaskRow(ctx context.Context, cols []Column, row [][]byte) ([][]byte, error)
• type Column
• type Masker
• type Noop
  • func (Noop) MaskRow(_ context.Context, _ []Column, row [][]byte) ([][]byte, error)
• type Overlay
  • func NewOverlay(rules map[string]string) *Overlay
  • func (o *Overlay) Enabled() bool
  • func (o *Overlay) MaskRow(_ context.Context, cols []Column, row [][]byte) ([][]byte, error)
  • func (o *Overlay) Replace(rules map[string]string)
• type Remote
  • func NewRemote(cfg RemoteConfig) *Remote
  • func (r *Remote) Enabled() bool
  • func (r *Remote) MaskRow(ctx context.Context, cols []Column, row [][]byte) ([][]byte, error)
• type RemoteConfig

Types

type Chain

type Chain struct {
	// contains filtered or unexported fields
}

Chain applies maskers in order (e.g. the remote masker, then the column overlay). The first error short-circuits. Nil maskers are skipped.

func NewChain

func NewChain(maskers ...Masker) *Chain

NewChain composes maskers left-to-right.

func (*Chain) MaskRow

func (c *Chain) MaskRow(ctx context.Context, cols []Column, row [][]byte) ([][]byte, error)

MaskRow implements Masker.

type Column

type Column struct {
	// Name is the column/field name as reported by the server (used by the column-aware overlay).
	Name string
	// Text is true when the value bytes are text-format and therefore safe to inspect/redact.
	// Binary-format values are passed through untouched (decoding them is engine-specific).
	Text bool
}

Column describes one result column for masking decisions.

type Masker

type Masker interface {
	MaskRow(ctx context.Context, cols []Column, row [][]byte) ([][]byte, error)
}

Masker transforms a single result row. Implementations MUST return a slice the same length as row; a nil element represents SQL NULL and should stay nil. Implementations should be best-effort: on any internal error they may return the row unchanged rather than failing the whole session (the caller still checks the error).

type Noop

type Noop struct{}

Noop returns rows unchanged. It is the default when no masking is configured.

func (Noop) MaskRow

func (Noop) MaskRow(_ context.Context, _ []Column, row [][]byte) ([][]byte, error)

MaskRow implements Masker.

type Overlay

type Overlay struct {
	// contains filtered or unexported fields
}

Overlay is the caller-defined layer: a PII schema projected onto column names. It is OFF by default (an empty rule set is a no-op) and is applied on top of the default remote masker. Keys are matched case-insensitively against the column name.

The rule set is hot-swappable via Replace so a control-plane poller (see the agent's overlay source) can refresh it while sessions are in flight; reads are lock-free via an atomic pointer.

func NewOverlay

func NewOverlay(rules map[string]string) *Overlay

NewOverlay builds an Overlay from a column->token map. A nil/empty map yields a no-op overlay (which can later be populated via Replace).

func (*Overlay) Enabled

func (o *Overlay) Enabled() bool

Enabled reports whether any overlay rules are currently configured.

func (*Overlay) MaskRow

func (o *Overlay) MaskRow(_ context.Context, cols []Column, row [][]byte) ([][]byte, error)

MaskRow implements Masker by replacing values whose column name matches a configured rule.

func (*Overlay) Replace

func (o *Overlay) Replace(rules map[string]string)

Replace atomically swaps the active rule set. Safe to call concurrently with MaskRow.

type Remote

type Remote struct {
	// contains filtered or unexported fields
}

Remote is the default masker. It calls an external PII detection/anonymization HTTP service (an "analyze" endpoint that returns detected spans and an "anonymize" endpoint that rewrites them) to redact sensitive values in text fields. Any service that implements these two JSON endpoints can be used.

It is best-effort: a detection miss or transport error never fails the session; the value is forwarded unchanged. The masker is a no-op when the analyze/anonymize URLs are empty.

func NewRemote

func NewRemote(cfg RemoteConfig) *Remote

NewRemote builds a remote masker. If cfg.AnalyzeURL is empty the masker is a no-op.

func (*Remote) Enabled

func (r *Remote) Enabled() bool

Enabled reports whether the remote masking service is configured.

func (*Remote) MaskRow

func (r *Remote) MaskRow(ctx context.Context, cols []Column, row [][]byte) ([][]byte, error)

MaskRow implements Masker by anonymizing each eligible text value.

type RemoteConfig

type RemoteConfig struct {
	AnalyzeURL   string // e.g. http://127.0.0.1:3000/analyze
	AnonymizeURL string // e.g. http://127.0.0.1:3001/anonymize
	Language     string // default "en"
	MinLen       int    // skip values shorter than this (numbers/short codes); default 4
	Timeout      time.Duration
}

RemoteConfig configures the remote masking service client.