Delphix Masking Helper

English · Português (BR) · Español

🌐 Website — what it does, and the full algorithm reference, in three languages.

A local companion for the Delphix masking plugin, covering an algorithm's whole life. It helps you understand how each masking framework behaves, test an algorithm against real values, build a configured algorithm from a problem described in plain language, and sync with a Masking Engine — pulling its algorithms down to work on and pushing yours back up. All without creating a Rule Set or running a masking job.

Independent project, and it needs an active Delphix licence

No affiliation with Delphix. This is an independent open source project. It is not built, endorsed, reviewed or supported by Delphix or its owners, and nothing here is an official product. Delphix and the product names used here are trademarks of their respective owners.

An active Delphix licence is required. The masking algorithms live in Delphix product jars, which are licensed and are not distributed here — this project neither ships nor replaces them. You must already be entitled to them and able to obtain the Masking Devkit (SDK) from Delphix, normally through an active licence and your account team. Drop fifteen jars into lib/ — see Delphix libraries below. Reference: Compliance Algorithm SDK.

_{Three things, in order: asking the assistant for an algorithm and watching it build and validate one; running an algorithm against a real value; importing from a Delphix engine and sending one back. Recorded against the default local provider (Ollama · llama3.1:8b) on an M1 Pro — the model's reply is time-lapsed, since locally it takes around a minute. Every masked value is real output from the plugin, and the engine is a real one.}

How it works

The Node server exposes a REST API that delegates every operation to AlgorithmRunner.jar, which loads and runs the algorithms through reflection. The React frontend is served by Vite in development (with hot-reload) and by Express in production.

Algorithm guide

📖 Browse the algorithm reference online — the same content as the PDFs, in three languages.

Every algorithm opens with two tabs: Test and Documentation. The Documentation tab shows that algorithm's section of the reference guide, in the interface language — the same content as the PDFs below, read from the same source, so the two never disagree.

The docs/ directory holds a reference guide for the plugin's 31 algorithms, in three languages:

Language	File
English	docs/delphix-algorithms-guide.en.pdf
Português (BR)	docs/delphix-algorithms-guide.pt-BR.pdf
Español	docs/delphix-algorithms-guide.es.pdf

For each algorithm the guide covers what it does, input → output examples, and an explanation of every configuration parameter. Algorithms are grouped by the same categories used in the UI sidebar. There are also three appendices: cross-cutting concepts (determinism, the role of the key, algorithms that may not mask anything), the catalog of the 62 dlpx-core: instances embedded in the plugin, and the limitations of the standalone runner.

Every input → output pair was generated by actually running the algorithms in AlgorithmRunner — none of them are illustrative.

Regenerating the PDFs

The sources live in docs/src/ (one HTML per language + a shared guide.css). After editing, rebuild:

./docs/build.sh            # all languages
./docs/build.sh pt-BR es   # only the given languages

The build uses headless Chrome and fonts installed on macOS (Iowan Old Style, Seravek, Menlo), so the PDFs should be regenerated on a Mac to preserve the typography.

Delphix libraries

The tester runs the real algorithms out of the Delphix masking plugin, so it needs a handful of jars from the Delphix product. They are not distributed with this repository — they are licensed Delphix files. You supply them yourself, once.

1. Request the Masking Devkit (SDK) for your Masking Engine version from Delphix, through your account team or the support portal. Delphix documents the SDK here: Compliance Algorithm SDK.
2. Unpack it and copy these fifteen jars from sdkTools/lib/ into lib/:

delphix-algorithm-plugin-*.jar	masking-extensibility-api-*.jar
jackson-annotations-*.jar	jackson-core-*.jar
jackson-databind-*.jar	jackson-datatype-jdk8-*.jar
jackson-datatype-jsr310-*.jar	jackson-module-jsonSchema-*.jar
guava-*.jar	failureaccess-*.jar
ant-*.jar	commons-codec-*.jar
commons-compiler-*.jar	commons-lang-*.jar
janino-*.jar

Versions do not need to match anything in particular — the server matches by filename prefix, so whatever ships in your SDK works. Everything else under sdkTools/lib/ belongs to the SDK's own CLI and is not needed; copying it all also works, it just bloats the classpath.

If a jar is missing, the server says so on startup and names what it could not find, and the UI shows the same message instead of failing silently. To point at a plugin jar outside lib/, set DLPX_PLUGIN_JAR to its full path.

See lib/README.md for what each jar is for.

Install

macOS / Linux

curl -fsSL https://adelbs.github.io/delphix-masking-helper/install.sh | bash

Windows — in PowerShell, not the Command Prompt: irm is a PowerShell command, and cmd.exe answers 'irm' is not recognized.

irm https://adelbs.github.io/delphix-masking-helper/install.ps1 | iex

If that fails with Could not create SSL/TLS secure channel, PowerShell is negotiating TLS 1.0, which GitHub no longer accepts — older Windows, Server 2016 among them. Run this first, in the same window, and then the line above:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Prefer to read it first? That is the same thing in two steps:

curl -fsSL https://adelbs.github.io/delphix-masking-helper/install.sh -o install.sh
less install.sh && bash install.sh

The script asks where to install, checks that Node, Java and git are present — it never installs them, it only tells you what is missing — clones the newest release, builds it, and puts a dlpx-helper command on your PATH.

dlpx-helper	start it and open the browser
dlpx-helper stop	stop it
dlpx-helper status	is it running?
dlpx-helper logs	follow the log
dlpx-helper update	move to the newest release and rebuild
dlpx-helper uninstall	remove it (asks first)

Installs are pinned to a release, not to the tip of main. The script asks the remote for the newest vX.Y.Z tag and checks that out, so a commit pushed after the last release never reaches you; pre-release tags such as v2.0.0-rc1 are skipped too. Set DLPX_REF to override it — DLPX_REF=v1.0.0 pins an older release, and a branch name follows that branch instead. If the repository has no release tags at all, the script falls back to the default branch and says so.

Running the script again on a machine that already has it offers update or remove. Updating never touches db/, where your saved algorithms and settings live. Uninstalling deletes everything, so it warns first — export from Saved Tests/Algorithms → Export if you want to keep anything.

Or do it by hand

The script does nothing you cannot do yourself:

git clone https://github.com/adelbs/delphix-masking-helper.git
cd delphix-masking-helper
npm install && npm install --prefix frontend
npm run build
npm start          # http://localhost:3000

Either way, the last step is the same and only you can do it: copy the jars from your Masking Devkit into lib/. The app lists exactly which ones when you open it.

Requirements

• Node.js 22+ (uses the native node:sqlite)
• Java 11+
• The Delphix jars above, in lib/

Getting started

# Install dependencies (root + frontend)
npm install
npm install --prefix frontend

# Development: Express (port 3000) + Vite (port 5173) in parallel
npm run dev
# Open: http://localhost:5173

# Production: builds the frontend and starts Express
npm start
# Open: http://localhost:3000

# Build the frontend only
npm run build

AI assistant

The home screen has a chat that helps you two ways: explaining how an algorithm works and which one fits a situation, and building a ready-to-use algorithm from a problem you describe in plain language. You do not need to know which framework to use — that is what it works out.

For example:

I need to mask a numeric field in a CHAR column, left-padded with zeros. The column is 15 characters, and I need a random number that keeps the same number of leading zeros as the original value.

The assistant picks Character Mapping with preserveLeadingZeros, configures it, and saves it under Saved Tests/Algorithms, ready to run.

Before saving, the server actually runs the algorithm with the configuration the model produced. If the runner rejects it — an invented parameter, an invalid combination — nothing is saved and the error is shown in the chat. A hallucinated configuration never becomes a saved test.

The assistant knows every one of the 31 algorithms: its system prompt is built from the same descriptions the UI shows, plus the real JSON Schema of each algorithm read from the plugin.

Configuring it

Go to Settings → AI, pick a provider and fill in the fields. The status card at the bottom tells you whether the provider is reachable.

Provider	Endpoint	Credential	Example model
Ollama (local) — default	http://localhost:11434	none	llama3.1
Claude / Anthropic	— (official SDK)	API key from console.anthropic.com	claude-opus-5
Google Gemini	https://generativelanguage.googleapis.com	API key from Google AI Studio	gemini-2.5-pro
GitHub Models (Copilot)	https://models.github.ai/inference	GitHub token with the models:read scope	gpt-4o

The default is Ollama, which runs entirely on your machine — nothing leaves it. To use it:

brew install ollama     # or download from ollama.com
ollama serve
ollama pull llama3.1

API keys are stored in db/tests.db and are never sent back to the browser: once saved, the field shows a mask and you replace the key by typing a new one.

"GitHub Models (Copilot)" is the OpenAI-compatible endpoint that comes with a GitHub account. GitHub Copilot itself has no public chat API for third-party applications.

On local models. The algorithm catalog takes about 12k tokens of context. That is comfortable for Claude and Gemini, but tight for small local models — one with an 8k window will truncate the catalog and pick the wrong algorithm. Prefer a model with a large context.

Syncing with a Masking Engine

Point the tool at a Delphix engine under Settings → Delphix — address, user and password — and press Test connection; it answers before anything is saved.

Importing. Saved Tests/Algorithms → Import from Delphix lists what the engine has. Anything built on a framework this tool cannot run locally is shown but not selectable, so you never end up with a saved algorithm that cannot be tested.

Lookup files. A file uploaded to the engine stays in the engine's file store: an algorithm carries only a reference to it (delphix-file://upload/…/NAMES.txt), and importing brings the reference down, never the contents. The import dialog says which files an algorithm reads that this machine does not have, and the algorithm imports either way — it just cannot run until a copy exists. Add one under Files, keeping the engine's file name, and the imported algorithm runs unchanged.

Any list with the right shape is enough to see the algorithm work. To reproduce what the engine produces, the file has to match it line for line: an algorithm that picks a substitute by hashing the input selects by position, so a different list is a different result.

Exporting. Each saved algorithm has a Send to Delphix button. One that came from the engine is updated there; one you built here is created. The tool remembers where each algorithm came from, so exporting twice never leaves a duplicate behind.

Round trip. Testing an imported algorithm with a local file does not change what goes back to the engine: the reference is stored as the engine wrote it, and the local copy is only resolved when the algorithm runs here. Adjust any parameter, send it back, and the engine keeps reading its own file. The one way to break that is to pick another file in the configuration form — that replaces the reference. The form shows an engine-held file as name (on the engine) so it is never mistaken for an empty field, and exporting a configuration that points at a path on this machine warns that the engine has no such path.

Naming. On the engine an algorithm's name is its identity and cannot be changed, so the tool follows the same rule: names are not editable. To work under a different name, use Duplicate and give the copy its name — the copy is unlinked, so sending it creates a new algorithm.

If the engine's masking plugin is older than the one in lib/, some frameworks will not exist there; exporting such an algorithm fails with a message saying so.

If you would rather not keep the password on disk, set DLPX_ENGINE_PASSWORD in the environment — it takes precedence and the field is then shown as read-only.

Interface language

The UI is available in English, Portuguese (BR) and Spanish. By default it follows your browser language; to pin one, click a flag at the bottom of the sidebar. It applies immediately. Once you have pinned a language an auto link appears next to the flags, which goes back to following the browser. The choice is stored server-side, so it applies on every browser that opens the app.

AlgorithmRunner

AlgorithmRunner.java is a short-lived Java process (forked per request) that:

1. Reads JSON from stdin with command, algorithm, config, input, key
2. Instantiates the algorithm class through reflection
3. Applies the configuration via ComponentConfigurator.applyConfiguration
4. Builds a minimal ComponentService with a CryptoService derived from the key
5. Calls setup() recursively, then validate(), then mask(input)
6. Returns the result as JSON on stdout

Compiling the AlgorithmRunner

If you modify AlgorithmRunner.java:

cd java-runner
javac --release 11 -cp "$(ls ../lib/*.jar | tr '\n' ':')" AlgorithmRunner.java
jar cfe AlgorithmRunner.jar AlgorithmRunner *.class

--release 11 matters: the jar is committed and nothing rebuilds it on the machine that installs the tool, so this bytecode is what every user runs. Without the flag javac targets whatever JDK you happen to have, and anyone on an older Java hits UnsupportedClassVersionError on their first masking operation. Java 11 is the floor the prerequisites and the installers promise.

License

Mozilla Public License 2.0. Modifications to this project's files stay open; you can combine it with code under other licenses. The Delphix jars it loads at runtime are not covered by this license and are not distributed here.

Trademarks and affiliation. Delphix, Delphix Continuous Compliance and any other product names referenced here are trademarks of their respective owners. This project is independent: it is not affiliated with, endorsed by or supported by them, and using it does not grant any right to the Delphix software it loads.