Audience: Immuta users

Content Summary: This page details how to install the Immuta CLI and tab completions.

1 - Install the Immuta CLI

Download the binary that corresponds to your operating system.

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_linux_amd64 && chmod +x immuta

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_linux_arm64 && chmod +x immuta

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_darwin_amd64 && chmod +x immuta

curl -Lo immuta https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_darwin_arm64 && chmod +x immuta

The SHA 256 checksum is available to verify the file at https://immuta-platform-artifacts.s3.amazonaws.com/cli/latest/immuta_cli_SHA256SUMS.

2 - Configure the CLI with Your Immuta Tenant

1. Run immuta configure.

2. Enter the URL of your Immuta tenant in the interactive prompt.

3. Enter your Immuta API Key in the interactive prompt:

$ immuta configure
? What is the url of the immuta instance you use?: https://your.instance.url.com/
? What is the api key of your immuta user account?:  ***************************Updated the config at /Users/user/.immutacfg.yaml

Below is the configuration file that will be saved at ~/.immutacfg.yaml:

default:

  api_key: <apiKey>

  host: https://your.immuta.url.com

3 - Install Tab Completions

To generate shell completion scripts for Immuta CLI commands, run immuta completion [bash|zsh|fish|powershell]. You can opt to specify -h or --help for instructions on installing tab completions for Bash, Zsh, Fish, and PowerShell commands and flags.

Use the tabs below for specific instructions for each of these shells.

immuta completion fish > ~/.config/fish/completions/immuta.fish

The exact configuration file locations might vary based on your system. Make sure to restart your shell before you test whether completions are working.

Audience: Data Owners and Governors

Content Summary: This page details the immuta command, its subcommands and arguments, and the workflow for cloning a tenant and using the Immuta API.

Command Overview: immuta

This command allows you to manage your Immuta tenant by creating data sources, projects, policies, and purposes. The table below illustrates the immuta subcommands and arguments.

To view a list of the commands available in your current Immuta CLI version, run immuta with no additional arguments.

Options

Options you can specify with the immuta command include

• --config string: Specify the configuration file name and where it will be saved. (The default is $HOME/.immutacfg.yaml.)

• -h or --help: Get more information about the command.

• -p or --profile string: Specify the profile for what tenant or API the CLI will use.

Clone Your Tenant: immuta clone

If you have an Immuta tenant that was set up without using the API, you can use the immuta clone command to save all your data sources, projects, policies, and purposes as payloads:

immuta clone <outputDirPath>

This command will create valid V2 API YAML files for all your data sources, projects, policies, and purposes. Within these files, database passwords and user files (such as a BigQuery auth file) will be removed; instead passwords will appear as {{EnvVar "dbPass"}}. The CLI will then read the environment variable dbPass to fill in the password if you use the cloned payload to create or update a data source. File contents will appear as {{ReadFile "<filePath>"}}, and then the CLI will read the file at the path and replace the value when commands are run.

Options

• --force: Overwrite existing output directory targets. If this flag is omitted, you will receive an error when the output directory exists and is not empty.

• -h or --help: Get details about the command.

Limitations

• Tags for data sources and projects are not returned.

• Data sources will not have the sources field, so if these payloads are used in create commands, all possible tables will be created as data sources.

immuta api

This command makes an authenticated HTTP(s) request to the Immuta API and prints the response. The default HTTP request method is GET, but POST is used if any parameters were added. You can override the method with --method:

immuta api <endPoint> [--method httpMethod] [--input <filePath>] [--body body] [--data key=value] [--raw-data key=value] [--header key:value] [--query key=value] [--path-param key=value] [--outputTemplate string]

Options

• -b, --body string: Unmodified string to be sent as payload body.

• -d, --data key=value: Add a typed parameter in key=value format. The --data flag behaves like --raw-data, with type conversion based on the format of the value. Literal values, true, false, null, and integers are converted to appropriate JSON types. This will be sent in as the request payload.

• --data-raw key=value: Add a string parameter in key=value format. The --data flag behaves like --raw-data, with type conversion based on the format of the value. Literal values, true, false, null, and integers are converted to appropriate JSON types. This will be sent in as the request payload.

• -H, --header key:value: Add an HTTP request header in key:value format.

• -h, --help: Get details about the command.

• --input <filepath>: A raw request body may be passed from the outside via the file specified to use as body for the HTTP request. Pass in '-' for standard input.

• -X, --method string: The HTTP method for the request (default GET).

• -P, --path-param key=value: Add a string parameter in key=value format. Will replace {key} in the url with value.

• -q, --query key=value: Add a string parameter in key=value format. The key value pairs are serialized into URL query parameters.

• -t, --outputTemplate string: Format the response using a Go template. The provided Go template is rendered using the JSON data as input. For the syntax of Go templates, see this document.

Examples

The documentation below provides descriptions and examples of immuta api options.

# list tags
$ immuta api tag

# list tags use query string to filter results
$ immuta api tag -q searchText=Discovered -q limit=10

# template the response using a Go template. This will print all tags new line separated.
$ immuta api tag -q limit=10 --template \
    '{{range .}}{{.name}}{{"\n"}}{{end}}'

# Run column detection on specified table
$ immuta api dataSource/detectRemoteChanges -X PUT -d table=tableName -d schema=schemaName

# the above command is the same as
$ immuta api dataSource/detectRemoteChanges -X PUT --body '{"table": "tableName", "schema", "schemaName"}'

# set a user's current project - replace templated values in path
$ immuta api project/current/{projectId} -P projectId=1 -X POST

# the above command is the same as
$ immuta api project/current/1 -X POST

Audience: Immuta users

Content Summary: The Immuta CLI allows users to interact with their Immuta tenant using the command line to manage data sources, projects, policies, and purposes. This feature allows you to have all of your Immuta tenant information in a Git repository and use the CLI to sync your Immuta tenant with the files in your Git repository. To install the Immuta CLI, follow this installation guide.

Section Overview

You can navigate this section of documentation in two different ways: by workflow or by command.

Workflow

The navigation in the left pane is organized by major workflows you would use in Immuta. Each workflow contains relevant commands. Follow this chronological outline to find commands relevant to your workflow.

1. Install and Configure the Immuta CLI.

2. Manage Your Immuta Tenant.

3. Create and Manage Data Sources.

4. Create and Manage Global Policies.

5. Create and Manage Purposes.

6. Create and Manage Projects.

Commands

Below is a list of major commands available in the Immuta CLI. Click a command to navigate to its corresponding page that details subcommands, options, and arguments.

• immuta: Interact with your Immuta tenant to create data sources, projects, policies, and purposes.

• immuta api: Make an authenticated Immuta API request. This command will let you hit any endpoint in the Immuta API, including version 1 endpoints. For example, immuta api /tag will hit the v1 endpoint to list tags. This allows you to use the immuta api command instead of something like Postman or cURL to interact with the V1 API.

• immuta clone: Clone all data sources, projects, purposes, and policies information into files.

• immuta completion: Generate shell completion scripts.

• immuta configure: Specify an Immuta tenant url and API key to be saved to the Immuta configuration file.

• immuta datasource: Manage data sources.

• immuta policy: Manage Global Policies.

• immuta project: Manage projects.

• immuta purpose: Manage purposes.

Prerequisite

Sensitive data discovery must be enabled.

Command overview: immuta sdd classifier

This command allows you to manage rules that will apply tags to data that matches patterns you specify during SDD. The table below illustrates subcommands and arguments.

Options

Use these options to get more details about the sdd classifier command or any of its subcommands:

• -h

• --help

$ immuta sdd classifier -h
Manage Sensitive Data Discovery Classifiers

Usage:
  immuta sdd classifier [command]

Available Commands:
  create      Create an SDD classifier
  delete      Delete the passed SDD classifier
  get         Get an SDD classifier
  search      Search all classifiers
  update      Update an SDD classifier

Flags:
  -h, --help   Help for classifier

Global Flags:
      --config string    Config file (default $HOME/.immutacfg.yaml)
  -p, --profile string   Specifies the profile for what instance/api the cli will use (default "default")

Use "immuta sdd classifier [command] --help" for more information about a command.

Create a rule

1. Save your rule to a valid YAML or JSON file using these attributes.

   Examples are provided below.

2. Run immuta sdd classifier create <filepath> [flags], referencing the file you just created. The options you can specify include

   • -h or --help: Get more information about the command.

   • -o or --output json | yaml: Specify the output format.

   • --outputTemplate string: Format the response using a Go template.

{
  "name": "MY_REGEX_RULE",
  "displayName": "My Regex Rule",
  "description": "A rule using regex pattern",
  "type": "regex",
  "config": {
    "regex": "^[A-Z][a-z]+",
    "tags": ["Discovered.regex-example"]
  }
}

{
  "name": "MY_DICTIONARY_RULE",
  "displayName": "My Dictionary Rule",
  "description": "A rule using dictionary pattern",
  "type": "dictionary",
  "config": {
    "values": ["Bob", "Eve"],
    "caseSensitive": true,
    "tags": ["Discovered.dictionary-example", "Discovered.dictionary-pattern-example"]
  }
}

{
  "name": "MY_COLUMN_NAME_REGEX_RULE",
  "displayName": "My Column Name Regex Rule",
  "description": "A rule using column name regex pattern",
  "type": "columnNameRegex",
  "config": {
    "columnNameRegex": "ssn|social ?security",
    "tags": ["Discovered.column-name-regex-example"]
  }
}

Example

$ immuta sdd classifier create ./account-classifier.json
Creating classifier from ./account-classifier...
Create successful.

Get a rule

Run immuta sdd classifier get <classifierName> [flags], specifying the name of the rule you would like to get. Options you can specify include

• -h or --help: Get more information about the command.

• -o or --output json | yaml: Specify the output format.

• --outputTemplate string: Format the response using a Go template.

Example

The example below illustrates a user getting a rule called ACCOUNT_NUMBER_RULE.

$ immuta sdd classifier get ACCOUNT_NUMBER_RULE
Getting classifier ACCOUNT_NUMBER_RULE...
{
  "createdBy": {
    "id": 1,
    "name": "Example User",
    "email": "user@example.com"
  },
  "name": "ACCOUNT_NUMBER_RULE",
  "displayName": "Account Number Rule",
  "description": "This rule recognizes account numbers using a regex pattern",
  "type": "regex",
  "config": {
    "tags": [
      "Discovered.account-number"
    ],
    "regex": "^[0-9]{9}-[0-9]{3}-[0-9]{1}$"
  },
  "id": 69,
  "createdAt": "2022-03-28T14:52:14.004Z",
  "updatedAt": "2022-03-28T14:52:14.004Z"
}

Search rules

Run immuta sdd classifier search [string] [flags] to list all rules or search rules by name. Options you can specify include

• -h, --help: Help for search.

• --limit int The search limit for pagination (default 25).

• --offset int: The search offset for pagination.

• --order asc | desc: The sort order.

• -o, --output json | yaml: The output format.

• --outputTemplate string: Format the response using a Go template.

• -s, --sort id | name | displayName | type | createdAt | updatedAt: Field to sort by.

• --type regex | columnNameRegex | dictionary | builtIn: Limit results to the specified pattern type.

Example

The example below illustrates a user searching all rules containing account.

$ immuta sdd classifier search account
Searching all classifiers...
ACCOUNT_NUMBER_RULE This rule recognizes account numbers using a regex pattern.

Update a rule

1. Update your rule in a valid YAML or JSON file using these attributes:
2. Run immuta sdd classifier update <classifierName> <filepath> [flags], referencing the file you just updated. The options you can specify include

   • -h or --help: Get more information about the command.

   • -o or --output json | yaml: Specify the output format.

   • --outputTemplate string: Format the response using a Go template.

Example

The example below illustrates a user updating a rule named ACCOUNT_NUMBER_RULE.

$ immuta sdd classifier update ACCOUNT_NUMBER_RULE ./account-classifier -o json
{
  "createdBy": {
    "id": 1,
    "name": "Example User",
    "email": "user@example.com"
  },
  "name": "ACCOUNT_NUMBER_RULE",
  "displayName": "Account Number Rule",
  "description": "This rule recognizes account numbers using a regex pattern.",
  "type": "regex",
  "config": {
    "tags": [
      "Discovered.account-number"
    ],
    "regex": "^[0-9]{9}-[0-9]{3}-[0-9]{1}$"
  },
  "id": 69,
  "createdAt": "2022-03-28T14:52:14.004Z",
  "updatedAt": "2022-03-28T15:25:28.575Z"
}

Delete a rule

Run immuta sdd classifier delete <classifierName> [flags] to delete the rule. The options you can specify include

• -h or --help: Get more information about the command.

• -o or --output json | yaml: Specify the output format.

• --outputTemplate string: Format the response using a Go template.

Example

$ immuta sdd classifier delete ACCOUNT_NUMBER_RULE -o json
{
  "createdBy": {
    "id": 1,
    "name": "Example User",
    "email": "user@example.com"
  },
  "name": "ACCOUNT_NUMBER_RULE",
  "displayName": "Account Number Rule",
  "description": "This rule recognizes account numbers using a regex pattern.",
  "type": "regex",
  "config": {
    "tags": [
      "Discovered.account-number"
    ],
    "regex": "^[0-9]{9}-[0-9]{3}-[0-9]{1}$"
  },
  "id": 69,
  "createdAt": "2022-03-28T14:52:14.004Z",
  "updatedAt": "2022-03-28T15:25:28.575Z"
}

Audience: Data Owners and Governors

Content Summary: This page details the immuta project command, its subcommands and arguments, and the workflow for creating, renaming, and deleting projects.

Command: immuta project

This command allows you to list, save, delete, and rename projects in your instance of Immuta. The table below illustrates subcommands and arguments.

Options

Use these options to get more details about the project command or any of its subcommands:

• -h

• --help

Manage Projects

Usage:
  immuta project [command]

Available Commands:
  delete      Delete a project by project key
  list        List all policy keys
  rename      Rename the project key
  save        Create/Update a Project in Immuta

Flags:
  -h, --help   help for project

Global Flags:
      --config string    config file (default $HOME/.immutacfg.yaml)
  -p, --profile string   specifies the profile for what instance/api the cli will use (default "default")

Use "immuta project [command] --help" for more information about a command.

Create Project: immuta project save

1. Add your project information in a valid YAML file for the V2 API. Additional payload examples for creating projects can be found here:

   Copy

   name: Demo Project
   projectKey: demo project
   description: "Users need approval to join this project"
   allowMaskedJoins: true
   subscriptionPolicy:
       type: approval
       approvals:
       - requiredPermission: GOVERNANCE
           specificApproverRequired: false
       - requiredPermission: ADMIN
           specificApproverRequired: false

2. Run immuta project save <filepath> [--dryRun] [--deleteWorkSpaceDataSources], referencing the file you just created. The options you can specify include

   • --deleteWorkSpaceDataSources: Delete all data and the data sources associated with a project workspace when the workspace is deleted.

   • -d or --dryRun: No updates will be made.

   • -h or --help: Get more information about the command.

Example

The example below illustrates a user listing all projects and then creating the project demo project.

$ immuta project list
Public

$ immuta project save test-project.yml
{"dryRun":false,"creating":true,"updating":false,"numberOfDataSourcesAdded":0,"numberOfDataSourcesRemoved":0,"creatingWorkspace":false,"deletingWorkspace":false,"projectId":3}

$ immuta project list
Public
demo project

Rename a Project Key: immuta project rename

1. Opt to list all project keys to identify which project you would like to rename by running immuta project list. Options you can specify include

   • -h or --help: Get more information about the command.

   • -v or --verbose: Print response as JSON.

2. Rename the project key by running immuta project rename <old project key> <new project key>, enclosing the name of the project key in quotation marks. Options you can specify to get more information about this command include -h or --help.

Example

The example below illustrates a user renaming the demo project project key to data analytics team.

$ immuta project list
Public
demo project

$ immuta project rename "demo project" "Data Analytics Team"
{"oldProjectKey":"demo project","newProjectKey":"Data Analytics Team"}

$ immuta project list
Data Analytics Team
Public

Delete a Project: immuta project delete

1. Opt to list all project keys to determine which project key you would like to delete by running immuta project list. Options you can specify include

   • -h or --help: Get more information about the command.

   • -v or --verbose: Print response as JSON.

2. Delete a project key by running immuta project delete <project key> [--dryRun] [--hardDelete, enclosing the project key in quotation marks. Options you can specify include

   • -d or --dryRun: No updates will be made.

   • --hardDelete: If this is set, it will delete everything related to the project in Immuta. If not set, it will only disable the project.

   • -h or --help: Get more information about the command.

Example

The example below illustrates a user first disabling and then deleting the project Data Analytics Team.

$ immuta project list
Data Analytics Team
Public

$ immuta project delete "Data Analytics Team"
{"dryRun":false,"deleting":"Data Analytics Team"}

$ immuta project list
Data Analytics Team
Public

$ immuta project delete "Data Analytics Team" --hardDelete
{"dryRun":false,"deleting":"Data Analytics Team"}

$ immuta project list
Public

Audience: Data Owners and Governors

Content Summary: This page details the immuta datasource command, its subcommands and arguments, and the workflow for creating, renaming, and deleting data sources.

Command Overview: immuta datasource

This command allows you to list, save, delete, and rename data sources in your instance of Immuta. The table below illustrates subcommands and arguments.

Options

Use these options to get more details about the datasource command or any of its subcommands:

• -h

• --help

Manage Data Sources

Usage:
  immuta datasource [command]

Available Commands:
  delete      Delete all datasources for the given connection key
  list        List Data Source keys and sources
  rename      Rename the connection key
  save        Create/Update all specified data sources in Immuta given connection info to the remote data base

Flags:
  -h, --help   help for datasource

Global Flags:
      --config string    config file (default $HOME/.immutacfg.yaml)
  -p, --profile string   specifies the profile for what instance/api the cli will use (default "default")

Use "immuta datasource [command] --help" for more information about a command.

Create a Data Source: immuta datasource save

1. Add your remote database's connection information in a valid YAML file for the V2 API. Additional payload examples for creating data sources can be found here:

   Copy

   connectionKey: 'a connection key'
   connection:
     ssl: true
     port: 5432
     hostname: immuta.db.com
     database: public
     schema: public
     username: user
     password: '{{EnvVar "myPassword"}}'
     handler: Snowflake

2. Run immuta datasource save <filepath> [--wait int] [--dryRun], referencing the file you just created. The options you can specify include

   • -d or --dryRun: No updates will actually be made to the data source(s).

   • -h or --help: Get more information about the command.

   • -w or --wait int: Specify how long to wait for data source creation.

Example

The following example illustrates a user saving an updated datasourceInfo.yaml file, first as a dry run and then by specifying that the data sources wait 5 seconds to be created.

$ immuta datasource save test.yml --dryRun
{"dryRun":true,"creating":["Public Credit Accounts","Public Credit Transactions","Public Fake Medical Claims 2017","Public Uciml Census Income Enriched"],"updating":[],"deleting":[],"noChange":[],"detectionRunning":false,"tagsUpdated":false,"connectionString":null}

$ immuta datasource save test.yml --wait 5
{"dryRun":false,"creating":["Public Credit Accounts","Public Credit Transactions","Public Fake Medical Claims 2017","Public Uciml Census Income Enriched"],"updating":[],"deleting":[],"noChange":[],"detectionRunning":false,"tagsUpdated":false,"connectionString":"immuta@snowflake.demo-databases.your.url.com:3306/public"}

Rename a Data Source Connection Key: immuta datasource rename

1. Run immuta datasource list keys to view a list of data source connection keys. Options you can specify include

   • -h or --help: Get more information about the command.

   • -v or --verbose: Print response as JSON.

2. To rename one of your data source connection keys, run immuta datasource rename <old connection key> <new connection key>. You can include the -h or --help options to get more information about this command.

Example

The following example illustrates a user renaming a data source connection key to demonstration.

$ immuta datasource list keys
snowflake.demo-databases.your.url.com:3306/public/public

$ immuta datasource rename snowflake.demo-databases.your.url.com:3306/public/public demonstration
{"oldConnectionKey":"snowflake.demo-databases.your.url.com:3306/public/public","newConnectionKey":"demonstration"}

$ immuta datasource list keys
demonstration

Delete Data Sources: immuta datasource delete

This command will delete all data sources for the connection key you specify.

1. Run immuta datasource list keys to view a list of data source connection keys. Options you can specify include

   • -h or --help: Get more information about the command.

   • -v or --verbose: Print response as JSON.

2. Opt to view a list of the data sources in this connection key by running immuta datasource list sources <connection key>.

3. Run immuta datasource delete <connection key> [--dryRun] to delete all of these data sources. Options you can specify include

   • -d or --dryRun: No updates will actually be made.

   • -h or --help: Get more information about the command.

Example

The following example illustrates a user deleting the demonstration connection key and all its data sources.

$ immuta datasource list keys

demonstration

$ immuta datasource delete demonstration
{"dryRun":false,"deleting":["Public Credit Transactions","Public Credit Accounts","Public Uciml Census Income Enriched","Public Fake Medical Claims 2017"]}

$ immuta datasource list sources demonstration
Error: status code: 404 message: The connection key "demonstration" was not found

Command overview: immuta sdd

This command allows you to customize and run SDD in your instance of Immuta. The table below illustrates subcommands and arguments.

Options

Use these options to get more details about the sdd command or any of its subcommands:

• -h

• --help

$ immuta sdd -h
Manage Sensitive Data Discovery

Usage:
  immuta sdd [command]

Available Commands:
  classifier  Manage Sensitive Data Discovery Classifiers
  run         Run Sensitive Data Discovery with provided options
  template    Manage Sensitive Data Discovery Templates

Flags:
  -h, --help   Help for sdd

Global Flags:
      --config string    Config file (default $HOME/.immutacfg.yaml)
  -p, --profile string   Specifies the profile for what instance/api the cli will use (default "default")

Use "immuta sdd [command] --help" for more information about a command.

SDD workflow

Two common workflows for using SDD are outlined below. The first illustrates how to apply a global framework to all data sources, while the second outlines how users can create and apply frameworks to data sources they own.

The tutorials linked below show how to use the CLI to complete this workflow. For an overview of how sensitive data discovery works, see this overview.

Workflow 1: Apply the global framework to all data sources

1. Data governor creates a framework using one or more rules.

2. System administrator adds this framework as the global framework so that it applies to all data sources.

3. Users trigger SDD on data sources.

Workflow 2: Apply a framework to a specific data source

1. Data governor creates one or more rules with patterns.

2. Data owner creates a framework containing one or more rules.

3. Data owner triggers SDD on one or more data sources and resulting tags are applied to columns where criteria were met and patterns were recognized.

Audience: Data Owners and Governors

Content Summary: This page details the immuta policy command, its subcommands and arguments, and the workflow for creating, renaming, cloning, and deleting Global Policies.

Command Overview: immuta policy

This command allows you to list, save, delete, and rename Global Policies in your instance of Immuta. The table below illustrates subcommands and arguments.

Options

Use these options to get more details about the policy command or any of its subcommands:

• -h

• --help

Create a Policy: immuta policy save

1. Add your policy information in a valid YAML file for the V2 API. Additional payload examples for creating policies can be found here:

   Copy

   name: Conditional Masking
   policyKey: data conditional masking
   type: data
   actions:
       - rules:
       - type: Masking
           config:
               fields:
               - type: columnTags
                   columnTag: Discovered.PII
               conditionalPredicate: "@columnTagged('Discovered.Country') = 'USA'"
               maskingConfig:
                   type: Hash
   circumstanceOperator: all
   circumstances:
       - type: columnTags
           columnTag: Discovered.PII
       - type: columnTags
           columnTag: Discovered.Country

2. Run immuta policy save <filepath> [--dryRun] [--reCertify], referencing the file you just created. The options you can specify include

   • -d or --dryRun: No updates will actually be made.

   • -h or --help: Get more information about the command.

   • --reCertify: If the certification has changed, someone will need to re-certify this policy on all impacted data sources.

Examples

The example below illustrates a user listing all policies and then creating a policy called data conditional masking.

$ immuta policy list
New Column Added

$ immuta policy save ./test-policy.yml
{"dryRun":false,"creating":true,"updating":false,"policyId":4}

$ immuta policy list
New Column Added
data conditional masking

Rename a Policy Key: immuta policy rename

1. Opt to list all policy keys to identify which policy you would like to rename by running immuta policy list. Options you can specify include

   • -h or --help: Get more information about the command.

   • -v or --verbose: Print response as JSON.

2. Rename the policy key by running immuta policy rename <old policy key> <new policy key>, enclosing the name of the policy key in quotation marks. Options you can specify to get more information about this command include -h or --help.

Example

The example below illustrates a user renaming the data conditional masking policy key to Data Masking.

$ immuta policy list
New Column Added
data conditional masking

$ immuta policy rename "data conditional masking" "Data Masking"
{"oldPolicyKey":"data conditional masking","newPolicyKey":"Data Masking"}

$ immuta policy list
Data Masking
New Column Added

Clone Global Policies: immuta policy clone

Clone and save all Global Policies to a file by running immuta policy clone <filepath>. Options you can specify include

• --force: Overwrite existing output directory targets. If this flag is omitted, you will receive an error when the output directory exists and is not empty.

• -h, --help: Get more information about the command.

• -v or --verbose: Print response as JSON.

Example

The example below illustrates cloning and saving all Global Policies to a policy folder. In this example, only one Global Policy existed: Test.

$ immuta policy clone ./your-file-path/policy-folder
Cloning all global policies...
Cloning: Test to Desktop/clone-policies/policy/Test.yaml

Delete a Policy: immuta policy delete

1. Opt to list all policy keys to determine which policy key you would like to delete by running immuta policy list. Options you can specify include

   • -h or --help: Get more information about the command.

   • -v or --verbose: Print response as JSON.

2. Delete a policy key by running immuta policy delete <policy key> [--dryRun]. Options you can specify include

   • -d or --dryRun: No updates will be made.

   • -h or --help: Get more information about the command.

Example

The example below illustrates a user deleting the Data Masking policy.

$ immuta policy list
Data Masking
New Column Added

$ immuta policy delete "Data Masking" --dryRun
{"dryRun":true,"deleting":"Data Masking"}

$ immuta policy delete "Data Masking"
{"dryRun":false,"deleting":"Data Masking"}

$ immuta policy list
New Column Added

Prerequisite

Sensitive data discovery must be enabled.

Command overview: immuta sdd template

This command allows you to manage identification frameworks, which are a collection of rules and settings used to drive the configuration of SDD runs. The table below illustrates subcommands and arguments.

Options

Use these options to get more details about the sdd template command or any of its subcommands:

• -h

• --help

$ immuta sdd template -h
Manage Sensitive Data Discovery Templates

Usage:
  immuta sdd template [command]

Available Commands:
  create      Create an SDD template
  delete      Delete the passed SDD template
  get         Get an SDD template
  global      Get the SDD global template
  search      Search all templates
  update      Update an SDD template

Flags:
  -h, --help   Help for template

Global Flags:
      --config string    Config file (default $HOME/.immutacfg.yaml)
  -p, --profile string   Specifies the profile for what instance/api the cli will use (default "default")

Use "immuta sdd template [command] --help" for more information about a command.

Create an identification framework

1. Save your framework to a valid YAML or JSON file using these attributes:

   An example is provided below.

   Copy

   {
     "name": "ACCOUNT_NUMBERS_FRAMEWORK",
     "displayName": "Account Numbers Framework",
     "description": "This framework contains the rule that recognizes account numbers.",
     "classifiers": [
       {
         "name": "ACCOUNT_NUMBER_RULE"
       }
     ]
   }

2. Run immuta sdd template create <filepath> [flags], referencing the file you just created. The options you can specify include

   • -h or --help: Get more information about the command.

   • -o or --output json | yaml: Specify the output format.

   • --outputTemplate string: Format the response using a Go template.

Example

$ immuta sdd template create ./account-template.json -o json
{
  "name": "ACCOUNT_NUMBERS_FRAMEWORK",
  "displayName": "Account Numbers Framework",
  "description": "This framework contains the rule that recognizes account numbers.",
  "createdBy": {
    "id": 1,
    "name": "Example User",
    "email": "user@example.com"
  },
  "id": 2,
  "createdAt": "2022-03-28T15:48:02.977Z",
  "updatedAt": "2022-03-28T15:48:02.977Z",
  "classifiers": [
    {
      "name": "ACCOUNT_NUMBER_RULE",
      "overrides": {}
    }
  ]
}

Get an identification framework

Run immuta sdd template get <frameworkName> [flags], specifying the name of the framework you would like to get. Options you can specify include

• -h or --help: Get more information about the command.

• -o or --output json | yaml: Specify the output format.

• --outputTemplate string: Format the response using a Go template.

Example

The example below illustrates a user getting a framework named ACCOUNT_NUMBERS_FRAMEWORK.

$ immuta sdd template get ACCOUNT_NUMBERS_FRAMEWORK
Getting template ACCOUNT_NUMBERS_FRAMEWORK...
{
  "name": "ACCOUNT_NUMBERS_FRAMEWORK",
  "displayName": "Account Numbers Framework",
  "description": "This framework contains the rule that recognizes account numbers.",
  "createdBy": {
    "id": 1,
    "name": "Example User",
    "email": "user@example.com"
  },
  "id": 2,
  "createdAt": "2022-03-28T15:48:02.977Z",
  "updatedAt": "2022-03-28T15:48:02.977Z",
  "classifiers": [
    {
      "name": "ACCOUNT_NUMBER_RULE",
      "overrides": {}
    }
  ]
}

Get the global framework

Run immuta sdd template global [flags], to get the global framework that has been configured for sensitive data discovery. Options you can specify include

• -h or --help: Get more information about the command.

• -o or --output json | yaml: Specify the output format.

• --outputTemplate string: Format the response using a Go template.

Example

The example below illustrates a user getting the global framework that had been configured in the Immuta UI by an administrator.

$ immuta sdd template global
Getting global template...
{
  "name": "ACCOUNT_NUMBERS_FRAMEWORK",
  "displayName": "Account Numbers Framework",
  "description": "This framework contains the rule that recognizes account numbers.",
  "createdBy": {
    "id": 1,
    "name": "Example User",
    "email": "user@example.com"
  },
  "id": 3,
  "createdAt": "2022-03-28T17:10:48.507Z",
  "updatedAt": "2022-03-28T17:10:48.507Z",
  "classifiers": [
    {
      "name": "ACCOUNT_NUMBER_RULE",
      "overrides": {}
    }
  ]
}

Search identification frameworks

Run immuta sdd template search [string] [flags] to list all identification frameworks or search identification frameworks by name. Options you can specify include

• --classifiers strings: Limit results to only frameworks that contain the specified rules.

• -h, --help: Help for search.

• --limit int The search limit for pagination (default 25).

• --offset int: The search offset for pagination.

• --order asc | desc: The sort order.

• -o, --output json | yaml: The output format.

• --outputTemplate string: Format the response using a Go template.

• -s, --sort id | name | displayName | type | createdAt | updatedAt: Field to sort by.

Example

The example below illustrates a user searching all frameworks containing the ACCOUNT_NUMBER_RULE.

$ immuta sdd template search --classifiers="ACCOUNT_NUMBER_RULE"
Searching all templates...
ACCOUNT_NUMBERS_FRAMEWORK This framework contains the rule that recognizes account numbers.
Displaying 1 of 1 templates

Update an identification framework

1. Update your framework in a valid YAML or JSON file using these attributes:
2. Run immuta sdd template update <frameworkName> <filepath> [flags], referencing the file you just updated. The options you can specify include

   • -h or --help: Get more information about the command.

   • -o or --output json | yaml: Specify the output format.

   • --outputTemplate string: Format the response using a Go template.

Example

The example below illustrates a user updating a framework named ACCOUNT_NUMBERS_FRAMEWORK.

$ immuta sdd template update ACCOUNT_NUMBERS_FRAMEWORK ./account-template -o json
{
  "name": "ACCOUNT_NUMBERS_FRAMEWORK",
  "displayName": "Account Numbers Framework",
  "description": "This framework contains the rule that recognizes account numbers.",
  "createdBy": {
    "id": 1,
    "name": "Example User",
    "email": "user@example.com"
  },
  "id": 2,
  "createdAt": "2022-03-28T15:48:02.977Z",
  "updatedAt": "2022-03-28T16:15:01.791Z",
  "classifiers": [
    {
      "name": "ACCOUNT_NUMBER_RULE",
      "overrides": {}
    }
  ]
}

Delete an identification framework

Run immuta sdd template delete <frameworkName> [flags] to delete the framework. The options you can specify include

• -h or --help: Get more information about the command.

• -o or --output json | yaml: Specify the output format.

• --outputTemplate string: Format the response using a Go template.

Example

$ immuta sdd template delete ACCOUNT_NUMBERS_FRAMEWORK -o json
{
  "name": "ACCOUNT_NUMBERS_FRAMEWORK",
  "displayName": "Account Numbers Framework",
  "description": "This framework contains the rule that recognizes account numbers.",
  "createdBy": {
    "id": 1,
    "name": "Example User",
    "email": "user@example.com"
  },
  "id": 2,
  "createdAt": "2022-03-28T15:48:02.977Z",
  "updatedAt": "2022-03-28T16:15:01.791Z",
  "classifiers": [
    {
      "name": "ACCOUNT_NUMBER_FRAMEWORK",
      "overrides": {}
    }
  ]
}

Audience: Data Owners and Governors

Content Summary: This page details the immuta purpose command, its subcommands and arguments, and the workflow for creating and deleting purposes.

Command: immuta purpose

This command allows you to list, save, and delete purposes in your instance of Immuta. The table below illustrates subcommands and arguments.

Options

Use these options to get more details about the purpose command or any of its subcommands:

• -h

• --help

Manage Purposes

Usage:
  immuta purpose [command]

Available Commands:
  delete      Delete a purpose by name
  list        List all purposes
  save        Create/update a purpose in Immuta

Flags:
  -h, --help   help for purpose

Global Flags:
      --config string    config file (default $HOME/.immutacfg.yaml)
  -p, --profile string   specifies the profile for what instance/api the cli will use (default "default")

Use "immuta purpose [command] --help" for more information about a command.

Create a Purpose: immuta purpose save

1. Add your purpose information in a valid YAML file for the V2 API. Additional payload examples for creating purposes can be found here.

2. Run immuta purpose save <filepath> [--dryRun] [--reAcknowledge], referencing the file you just created. The options you can specify include

   • --reAcknowledge: Require all users of any projects using this purpose to re-acknowledge any updated acknowledgement statements.

   • -d or --dryRun: No updates will be made.

   • -h or --help: Get more information about the command.

name: Demo Purpose
acknowledgement: You promise not to share this data outside the project.
description: This project is only to be used for departmental data.

Examples

The example below illustrates a user creating a purpose called Demo Purpose.

$ immuta purpose list
Re-identification Prohibited
Re-identification Prohibited.CCPA
Re-identification Prohibited.Safe Harbor Method
Use Case Outside De-identification

$ immuta purpose save test-purpose.yml
{"dryRun":false,"creating":true,"updating":false,"purposeId":8}

$ immuta purpose list
Demo Purpose
Re-identification Prohibited
Re-identification Prohibited.CCPA
Re-identification Prohibited.Safe Harbor Method
Use Case Outside De-identification

Delete a Purpose: immuta purpose delete

1. Opt to list all purposes to determine which purpose you would like to delete by running immuta purpose list. Options you can specify include

   • -h or --help: Get more information about the command.

   • -v or --verbose: Print response as JSON.

2. Delete a purpose by running immuta purpose delete <purpose name> [--dryRun], enclosing the purpose name in quotation marks. Options you can specify include

   • -d or --dryRun: No updates will be made.

   • -h or --help: Get more information about the command.

Example

The example below illustrates a user deleting the purpose Demo Purpose.

$ immuta purpose list
Demo Purpose
Re-identification Prohibited
Re-identification Prohibited.CCPA
Re-identification Prohibited.Safe Harbor Method
Use Case Outside De-identification

$ immuta purpose delete "Demo Purpose"
{"dryRun":false,"deleting":["Demo Purpose"]}

$ immuta purpose list
Re-identification Prohibited
Re-identification Prohibited.CCPA
Re-identification Prohibited.Safe Harbor Method
Use Case Outside De-identification

Prerequisite

.

Command Overview: immuta sdd run

This command allows you to run SDD on specific data sources or all data sources in your instance of Immuta.

Options

Use these options to get more details about the sdd run command or any of its subcommands:

• -h

• --help

Run SDD on Specific Data Sources

Run immuta sdd run <dataSourceName> [flags], naming the data source you want to run SDD on. The options you can specify include

• -d, --dryRun: No updates will actually be made.

• -f, --force: Do not prompt for confirmation when attempting to run SDD on all data sources.

• -h or --help: Get more information about the command.

• -o or --output json | yaml: Specify the output format.

• --outputTemplate string: Format the response using a Go template.

• -t, --outputTemplate string: Run SDD with this framework. This flag can only be used with the dryRun flag.

• -w, --wait int: The number of seconds to wait for the SDD job(s) to finish. Default is until the SDD job(s) finish (default -1).

Example

The example below illustrates a user running SDD on a single data source.

Run SDD on All Data Sources

1. Run immuta sdd run. The options you can specify include

   • -d, --dryRun: No updates will actually be made.

   • -f, --force: Do not prompt for confirmation when attempting to run SDD on all data sources.

   • -h or --help: Get more information about the command.

   • -o or --output json | yaml: Specify the output format.

   • --outputTemplate string: Format the response using a Go template.

   • -t, --outputTemplate string: Run SDD with this framework. This flag can only be used with the dryRun flag.

   • -w, --wait int: The number of seconds to wait for the SDD job(s) to finish. Default is until the SDD job(s) finish (default -1).

2. Confirm that you want to run SDD on all data sources.

Example