Ruleset

• Overview
• Add a new ruleset
• View and edit ruleset
• Ruleset YAML editor
  • Ruleset YAML editor shortcuts
  • Windows and Linux
  • Mac OS
  • Command palette
  • Viewing all tasks in a ruleset
  • Schema validation
  • Ruleset Libraries
  • Hovers
  • Formatting
  • Folding
  • YAML with Comments
• Upload, download or copy ruleset
• Clone a ruleset
• Delete ruleset
• Push/Pull a ruleset
• Seed Files
• JSON Mask Generator

Overview

Masking rulesets are YAML-based instructions that describe how the tables in your database will be masked. Each masking run applies a single ruleset to a single database connection. However, the same ruleset can be applied to many databases by performing multiple masking runs.

For a brief introduction to the YAML syntax that is used to write rulesets, see: https://learnxinyminutes.com/docs/yaml/.

See the Ruleset YAML Specification guide for a complete reference on the instructions available for writing rulesets.

Add a new ruleset

To add a ruleset, click on the    button on the Rulesets panel of the Database Masking Dashboard or File Masking Dashboard. This takes you to the Ruleset Generator or File Ruleset Generator page.

If you prefer to write a ruleset in YAML, click on the Skip to YAML Editor button at the top of the page. The ruleset YAML editor will be opened and initialised with a placeholder ruleset for you to edit.

Develop your ruleset in the YAML editor and click the SAVE AND EXIT button when you are finished. Refer to the Ruleset YAML Specification for more information on the available functionality and syntax.

View and edit ruleset

To edit a ruleset, click the edit () button for the ruleset you wish to edit in the Rulesets panel of the Database Masking Dashboard. The ruleset YAML editor will be opened for editing.

Validation errors may be shown as described in Schema validation. These must be corrected before the ruleset is saved.

Once you have modified the ruleset, click the SAVE AND EXIT button.

Ruleset YAML editor

The ruleset editor is based on the same text editor underlying Microsoft's Visual Studio Code and includes much of the same functionality. The ruleset editor comes with advanced editing features including real-time ruleset validation and auto-completion.

Ruleset YAML editor shortcuts

As our Ruleset editor is based on Visual Studio code, there are a number of helpful shortcuts that can be used within our Ruleset editor.

Windows and Linux

The shortcuts detailed here apply to both Windows and Linux.

• Shift + Tab: De-indents the current line, or any selected content.
• Ctrl + ] / Ctrl + [: Indent/de-indent the current line.
• CTRL + /: Convert the current line into a comment, or any currently highlighted text.
• Ctrl + F: Find all instances of the selected text.
• Ctrl + H: Replace all instances of the selected text.
• Ctrl + L: Selects the current line.
• Ctrl + Shift + L: Selects all occurrences of the current selected content. If changes are made while selecting, this will affect all instances that match.
• Ctrl + F2: Select all occurrences of the current word. If changes are made while selecting, this will affect all instances that match.
• Ctrl + Space: Auto suggest a parameter to fill the current word.
• Ctrl + Shift + [: Folds the current uncollapsed code block.
• Ctrl + Shift + ]: Unfolds the current code block if it is collapsed.

Mac OS

The following shortcuts can be used on a Mac operating system.

• Shift + Tab: De-indents the current line, or any selected content.
• ⌘ + Fn + ] / ⌘ + Fn + [: Indent/de-indent the current line.
• ⌘ + /: Convert the current line into a comment, or any currently highlighted text.
• ⌘ + F: Find all instances of the selected text.
• ⌘ + L: Selects the current line.
• Ctrl + Space: Auto suggest a parameter to fill the current word.
• ⌥ + ⌘ + [: Folds the current uncollapsed code block.
• ⌥ + ⌘ + ]: Unfolds the current code block if it is collapsed.

Command Palette

The ruleset editor's Command Palette can be displayed by pressing F1 or right-clicking on the editor and selecting the Command Palette option.

 

Please refer to https://code.visualstudio.com/docs/editor/codebasics for more information about how to use each of the features in the Command Palette.

Viewing all tasks in a ruleset

In order to view all tasks being performed in a ruleset follow these steps.

• Collapse all code blocks. This can be done by folding all code blocks, with either Ctrl + K + 0 on Windows or Linux, or ⌘ + K + 0 on MacOS.
• Once the ruleset has been completely folded, expand the tasks block by clicking on the > beside it in the editor to show all tasks being performed by the ruleset.
• Unfold the entire ruleset again with Ctrl + K + J on Windows or Linux, or ⌘ + K + J on MacOS.

Schema validation

The ruleset editor performs schema-based validation of the ruleset as you type. Errors in your ruleset are highlighted with red squiggle underlines. Hover over the error with your mouse to view the error details. If there are any errors within the YAML the "STATUS" box at the top right of the page will be red, if there are no errors the "STATUS" will be green.

 

The validation detects configuration errors, such as when:

• A required property has not been provided
• An invalid property name has been provided
• The value of a property is invalid

Validation on saving and at the start of a masking run

When you save a ruleset (or create one via the API), DataMasque validates it against the ruleset schema. A ruleset must pass validation against the schema before you can use it in a masking run.

While a ruleset is being edited, the status shown at the top right of the editor page changes to an unknown state (shown as a question mark icon).

Validation on save

Rulesets are validated when they are saved. If the ruleset imports ruleset libraries, validation also checks that all imported libraries exist and are valid, and that all $ref references resolve correctly.

However, if the ruleset is large, validation can take a long time. To avoid a slow response time in the UI or timing out the API request, DataMasque runs the validation in the background for any ruleset more than 60KB in size. These rulesets are marked with an ellipsis icon, as shown in the picture below.

Rulesets which haven't been validated yet, or have had their ruleset validation interrupted are marked with an information icon, as shown in the picture below. Hovering over the icon displays a tooltip explaining that the ruleset will only be validated when used in a masking run.

If you start a masking run while validation is still in progress, the run waits for validation to complete before proceeding. Once the ruleset has been checked against the schema (whether successfully or unsuccessfully), the ruleset's status is updated to reflect this, and is visible in the UI. Provided the ruleset's content does not change, DataMasque will not re-run the validation process on any subsequent masking runs.

Ruleset Libraries

Rulesets can import ruleset libraries to reuse common masks, rules, and tasks across multiple rulesets. A ruleset that imports libraries is only considered valid if all of its dependent libraries are also valid. If a library becomes invalid or is deleted, any rulesets that depend on it will also become invalid.

Hovers

Hover over a ruleset property in the editor to quickly view documentation for that property.

Autocomplete

For properties and values for YAML data, the editor will offer autocomplete suggestions as you type. A dropdown menu of options will be automatically displayed for fields with value enumeration, such as the task type property, mask type property, and transform_case transform property:

You can also manually trigger autocomplete suggestions using the 'Trigger Suggestions' command (⌃Space or Ctrl + Space). This can be used to provide contextual property name suggestions in case you have forgotten the specific name for a certain property. Suggestions will vary based on indentation level of the cursor (and therefore context).

 

Formatting

The YAML document can be auto-formatted using ⇧⌥F for macOS or Shift + Alt + F on Linux and Windows.

Folding

You can fold / collapse blocks of YAML using the folding icons in the gutter between line numbers and line start. Code folding may be useful to reduce visual clutter when creating complex or deeply nested YAML structures.

YAML with Comments

YAML supports single line comments. To quickly comment a block, select the YAML block, and use CTRL + / on Linux and Windows and ⌘ + / for macOS.

Upload, Download or Copy ruleset

Open the ruleset for editing and use the icon buttons in the top right of the Ruleset Editor:

       

Clone a ruleset

To clone a ruleset, click on the    button for the ruleset you wish to clone in the Rulesets panel of the Database Masking Dashboard or File Masking Dashboard. An editable clone of the ruleset will be created with a timestamp appended to the name. If the ruleset name is longer than 52 characters, it will be truncated during clone to comply with ruleset name length limit of 64 characters. Rulesets can also be cloned directly from the dashboard.

 

Delete ruleset

To delete a ruleset, open the ruleset for editing (see View and edit ruleset) and click the Delete button. You will be prompted for confirmation before the ruleset is deleted. A ruleset can also be deleted from the dashboard by clicking the trashcan icon.

Push/Pull a ruleset

This feature allows you to push the content of a ruleset to a Git source code repository, and to pull the content of a ruleset from a specific commit.

Prerequisites

• You must have configured a Git repository where you want to push and pull the ruleset file. Refer to Git Repository Settings.
• You must have uploaded your Git SSH key on the My Account page. Refer to Git SSH Key Information.
• The ruleset name must be specified at the top of the YAML editor.

Push a ruleset

To push the ruleset file to the remote repository at a specified path, follow these steps:

1. Click the Git button to open the Push/Pull Ruleset dialog, and navigate to the Push tab.
2. Choose the file with the desired extension that you want to push to the remote repository.
3. Enter the commit message in the provided field.
4. Click the Push button to proceed. The current content of the YAML editor will be pushed to the remote repository.

Note that at least one change to the ruleset YAML is required for the push to succeed. DataMasque will reject any attempt to push a ruleset that is identical to the latest version in the repository.

Pull a ruleset

To fetch the content of the ruleset file from the remote repository at a specified path and commit, follow these steps:

1. Click the Git button to open the Push/Pull Ruleset dialog, and navigate to the Pull tab.
2. In the dropdown box, you will see a list of ruleset files present in the remote directory path. Only files with .yml or .yaml extensions are shown. Choose the desired file, and the commit versions for that file will be displayed in the table below. You can reload the file list and commit versions by clicking the button.
3. Choose the desired version of the selected file from the list.
4. Optionally, check the checkbox to overwrite the current ruleset name. If left unchecked, the current ruleset name will be retained.
5. Click the Pull button.
6. Upon a successful pull operation, the content of the selected remote file version will replace the existing content in the YAML editor.

Seed Files

The available seed files can be viewed the by clicking on the Show Available Seed Files text above the ruleset editor. A panel named Seed File Help appears to the right, with a list of all seed files currently available in the DataMasque instance. Hovering over a seed file's name gives you some options: the first 50 lines of the seed file can be previewed by clicking on the eye icon, and the name of the seed file can be copied to the clipboard by clicking on the clipboard icon.

New seed files can also be uploaded via the Upload File button.

JSON Mask Generator

The ruleset generator does not support generating mask rules for JSON or XML data in columns. JSON rules can be generated from an example document by using the JSON Mask Generator. This can be found on the Ruleset Editor page.

The json mask is generated from fields in an example document that has been pasted into the JSON Data field.