The IRI DarkShield Command-Line Interface (CLI) offers a powerful way to harness the data discovery and masking capabilities of DarkShield Version 5 outside the graphical IRI Workbench environment. This article introduces you to the DarkShield CLI, its requirements, and how to use it effectively.

What is the DarkShield CLI?

The DarkShield CLI is a Command-Line Interface utility for the IRI DarkShield v5 search and remediation engine. It enables you to execute and automate DarkShield operations without relying on the IRI Workbench GUI at runtime. 

The CLI operates on .dsc configuration files generated in IRI Workbench, which are produced through wizards in the DarkShield menu. The CLI option is particularly useful for integrating DarkShield jobs into automated workflows, CI/CD pipelines, or batch job automation tools.

The DarkShield CLI utilizes the same on-premise DarkShield API engine as the IRI Workbench does; i.e., it makes HTTP/S requests to your hosted DarkShield API for job execution. This ensures consistency in data masking results across different:

• DarkShield environments (GUI/CLI/API) 
• data source types (structured/semi-structured/unstructured) 
• IRI data masking products (FieldShield/DarkShield/CellShield).

Why Use the DarkShield CLI?

The DarkShield CLI is designed for users who need to systemize or embed DarkShield jobs. It has provides several advantages; including:

1. Automation: Easily integrate DarkShield operations into automated workflows, CI/CD pipelines, and batch applications using scripting or job schedulers.
2. Flexibility: Run masking jobs in environments where a graphical interface is not available or practical.
3. Consistency: Ensure that the same masking routines used in IRI Workbench can be executed in different environments, maintaining consistency in data protection strategies.

Getting Started

Before you start using the DarkShield CLI, ensure you have the following:

1. The right O/S: Windows or Linux (ask about macOS)
2. Java 17 (JRE): Java Runtime Environment (JRE) version 17 installed  
3. Valid DarkShield License: Obtain the back-end license required to run DarkShield from IRI. See “Setting up the Executable” below for more details.
4. DarkShield Job Config Files: Created your .dsc (DarkShield Configuration) files using the applicable DarkShield wizard(s) in IRI Workbench. For more information, see the DarkShield Product Overview booklet.
5. A running DarkShield API instance: This instance must be set up and running for the CLI to function; this is done 
6. The DarkShield CLI feature, if not already installed with your copy of Voracity/DarkShield – contact IRI if you are not sure.

Setting up the Executable

DarkShield relies on the masking routines found in the CoSort SortCL executable, so a license to use that executable in the DarkShield context is required to perform any masking operations. By default, DarkShield uses the COSORT_HOME environment variable to find the bin directory containing SortCL.

The DarkShield CLI uses the same engine as direct execution in IRI Workbench, which involves making web requests to the DarkShield API. A DarkShield API instance must be set up and running for a job to complete successfully. By default, the CLI will make requests to a URL at port 8959 of the localhost, but the URL of the DarkShield API instance for the job to contact is a configurable option.

The DarkShield API itself requires the SortCL executable to perform masking. This is the same program used by IRI FieldShield for masking, and thus when the same masking functions are used, the same ciphertext results can be produced from the same original plaintext values processed by either tool. 

Contact your IRI representative, and refer to the DarkShield instructions in the IRI software installation guide, to set up SortCL on your system(s) where data masking jobs will run. Note that everything will be included if you install IRI Voracity on Windows.

Command Line Operations

The DarkShield CLI client operates on the same .dsc (i.e. search and/or masking configuration) files which are created and used in the IRI Workbench version of DarkShield. 

Just as you can automate the execution of .dsc files built in IRI Workbench using the IRI Workbench task scheduler, you can use the CLI to execute the same jobs outside Workbench as a command task (see examples below) from: the O/S shell, an external batch program, CI/CD DevOps pipeline, an application system call, or any job scheduler you prefer.

Currently, the DarkShield job (.dsc) configuration files can only be created in IRI Workbench. For more details, see this page and the DarkShield Primer, as well as the internal documentation on DarkShield found within IRI Workbench.

DarkShield CLI Syntax

When you are on the command line, the syntax you would use to run your job is:

darkshield [[Path Mode [-u=URL] [-r] [-ae] [-ao=Audit Output Folder] [-hV]

The options, or flags that are parameters, to that command are as follows:     

Path  Path to the search/mask configuration (.dsc) file
Mode Type of job (search, mask, or search_mask for both)
-r, --results      If each masking job will produce a JSON audit report
-u, --url=URL      URL of the DarkShield API (Plankton) web service
-ae –audit-enabled   Turns on DarkShield job audit logging
-ao -audit-output Your target folder for the audit logs
-h, --help           Displays program description and these options
-V, --version        Prints version information and exits.

Examples

Here are some examples of DarkShield CLI invocations and their explanations:

darkshield C:\runtime-eclipse17\new_search_json-xml-delim_out\new_search_json-xml-delim_out.dsc SEARCH_MASK

Runs a DarkShield job in search_mask (SEARCH_MASK) mode, which searches and masks data in one-pass, using the Workbench-configured DarkShield .dsc job located at the path

‘C:\runtime-eclipse17\\new_search_json-xml-delim_out\new_search_json-xml-delim_out.dsc

darkshield

C:\runtime-eclipse17\new_search_json-xml-delim_out\new_search_json-xml-delim_out.dsc SEARCH 

Runs a DarkShield job in search mode using the Workbench-configured DarkShield .dsc job located at the path

‘C:\runtime-eclipse17\new_search_json-xml-delim_out\new_search_json-xml-delim_out.dsc

darkshield -u http://192.168.1.34:8959 -ae -ao /home/darkshield/logs -r new_search.dsc MASK

Runs a DarkShield job in mask mode (NOTE: a DarkShield job must have previously been run in search mode before running in mask mode) using the Workbench-configured DarkShield job named new_search.dsc, located in the current working directory. The URL of the DarkShield API is specified as http://192.168.1.34:8959 and the creation of a DarkShield job audit log is enabled. The output folder for an audit log of the DarkShield job is specified as /home/darkshield/logs. Production of detailed JSON-formatted results files, which audit masking results of each masking request to the DarkShield API, is also enabled. Note that a DarkShield job may consist of numerous requests to the DarkShield API for searching and/or masking.

darkshield --version

Prints the DarkShield product version in use: (e.g.) 5.0

darkshield --help

Displays the help messages above.

Conclusion

The DarkShield CLI provides a versatile and powerful way to manage data discovery and masking tasks outside the IRI Workbench GUI. Whether you’re looking to automate these workflows, integrate them into CI/CD pipelines, or simply prefer the command-line interface, the DarkShield CLI has you covered.

For help configuring or running DarkShield jobs, please email darkshield@iri.com.