Working with Protegrity Agent

This section walks through each step of creating a complete, working protection policy. The example protects three types of sensitive data: credit card numbers, Social Security numbers (SSN), and email addresses.

Each step can be run as an individual request, or the agent can build the entire setup in a single conversation.

PIM uses unique identifiers (UIDs) to reference resources. When you create a resource, PIM assigns it a UID. The Protegrity Agent tracks these UIDs across steps within the same conversation, so you can refer to resources by name.

Step 1: Create Data Elements

Data elements define how Protegrity protects a specific type of data. Each data element specifies one protection method. It is recommended to create data elements first because the rules might reference them later.

Data elements cannot change their protection method after creation. To change a protection method, create a new data element.

Caution: Deleting a data element destroys its cryptographic material. Data protected with a deleted data element can not be recovered.

Create a Credit Card Data Element

Request the agent to create a data element that tokenizes credit card numbers.

Create a data element named CC_Token that tokenizes credit card numbers
using the SLT_1_3 tokenizer.

The agent creates a data element with credit card tokenization. This protection method preserves the format of the card number and produces a token that passes Luhn validation.

Create a Social Security Number Data Element

Request the agent to create a data element that tokenizes numeric data for SSN values.

Create a data element named SSN_Token that uses numeric tokenization
with the SLT_1_3 tokenizer.

The agent creates a numeric tokenization data element. The token output contains only digits and preserves the original length.

Create an Email Data Element

Request the agent to create a data element that tokenizes email addresses.

Create a data element named Email_Token that uses email tokenization
with the SLT_1_3 tokenizer.

The Protegrity Agent creates an email tokenization data element. The token preserves the email format, including the @ symbol and domain structure.

Other Protection Methods

Protegrity supports several additional protection methods. The agent supports questions related to any of the following.

Request the agent for details on any method:

What tokenization options are available for numeric data?

Step 2: Create a Mask

Masks define how to partially reveal protected data for display. Rules can optionally reference a mask to control what users see when they access data without full unprotect permission.

Create a mask named CC_Show_Last_4 that shows the last 4 characters
and masks the rest with asterisks.

The Protegrity Agent creates a mask that displays the last four digits while replacing the remaining characters with * symbols. For example, a credit card number appears as ************1234 in the output.

Mask parameters:

Step 3: Create a Role

Roles define who can access protected data. Every rule in a policy requires a role.
Ensure to create roles before creating rules.

Create a Role With Full Access

For a simple setup, create a role with the allowAll flag. This role grants access to all users without requiring a member source.

Create a role named DataAnalyst with manual mode and allow all users.

The agent creates a manual role where all authenticated users receive access.

Create a Role With Restricted Access

For more fine-grained control, create a role that restricts access to specific users or groups from a member source.

Create a role named PCI_Auditor with manual mode. Do not allow all users.

After the role is created, members can be added from a member source.
For more information about setting up member source, refer Create a Member Source.

Role Modes

Step 4: Create a Member Source (Optional)

Member sources connect PIM to an identity directory. Create a member source when you need to restrict role membership to specific users or groups.

This step is optional if allowAll roles are used.

Create a file-based member source named LocalUsers.

The agent creates a member source. Supported source types include file, LDAP, Active Directory (AD), Azure AD, POSIX, and database connections.

After creating a member source, add members to a role.

Add a group member from the LocalUsers source to the PCI_Auditor role.

Step 5: Create a Policy

Policies group rules that govern protect, unprotect, and reprotect operations. Ensure to create the policy container before adding rules.

Create a policy named PCI_Compliance with template permissions
that allow protect, unprotect, and reprotect.

The agent creates an empty policy with default permissions. The template permissions serve as a baseline for new rules you add to the policy.

Step 6: Add Rules to the Policy

Rules bind a data element, a role, and a set of permissions within a policy. Each rule defines what protection operations a role can perform on a specific data element.

Add a Credit Card Rule With Masking

Add a Credit Card Rule With Masking

Add a rule to the PCI_Compliance policy for the DataAnalyst role and
CC_Token data element. Use the CC_Show_Last_4 mask. Allow protect and
reprotect, but deny unprotect. Set the no-access operation to
NULL_VALUE. Enable auditing for all operations.

The agent creates a rule where DataAnalyst users can protect and reprotect credit card data. When they access the data without unprotect permission, they see the masked value. The no-access operation returns a null value for unauthorized users.

Add a Social Security Number Rule

Add a Social Security Number Rule

Add a rule to the PCI_Compliance policy for the DataAnalyst role and
SSN_Token data element. Allow protect, unprotect, and reprotect.
Set the no-access operation to EXCEPTION.

The agent creates a rule granting full access to SSN data. Unauthorized access raises an exception.

Add an Email Rule

Add an Email Rule

Add a rule to the PCI_Compliance policy for the DataAnalyst role and
Email_Token data element. Allow protect and unprotect. Deny reprotect.

Rule Permissions

Each rule controls the following three operations independently.

No-Access Operations

When a user without permission accesses protected data, PIM returns one of these values.

Step 7: Create a Data Store and Deploy

Data stores define where protectors retrieve their policies. A protector is a Protegrity component that enforces data protection at the point of access, such as a database or application server. Create a data store and deploy the policy to make it available to protectors.

Create a Data Store

Create a default data store named Production_DS with the description
"Production data store for PCI compliance."

A default data store allows any server to connect. For restricted access, create a non-default data store and add allowed server ranges:

Create a data store named Restricted_DS.
Add an allowed server range from 10.30.0.1 to 10.30.0.50
to the Restricted_DS data store.

Only one default data store can exist in a PIM instance.

Deploy the Policy

Deploy the Policy

Deploy the PCI_Compliance policy to the Production_DS data store.

The agent binds the policy to the data store. Protectors connected to this data store can now retrieve and enforce the policy.

An empty policies or applications array in a deploy request clears existing associations. The agent handles this correctly, but exercise caution when modifying deployments manually.

Trusted Applications (Optional)

If the environment uses Application Protector, create a trusted application to authorize a specific application and user pair. Include trusted applications in the deploy step alongside policies.

Create a trusted application named CustomerServiceApp with application
name "customer-service" and application user "cs-service-account".

Deploy the PCI_Compliance policy and CustomerServiceApp application
to the Production_DS data store.

This step is optional if the protectors do not require trusted application authorization.

Complete Setup in One Request

The agent can build an entire policy configuration in a single request. It creates a plan and works through each step.

Set up a complete PCI compliance configuration:
1. Create three data elements: CC_Token (credit card tokenization,
   SLT_1_3), SSN_Token (numeric tokenization, SLT_1_3), and
   Email_Token (email tokenization, SLT_1_3).
2. Create a mask named CC_Show_Last_4 that shows the last 4 characters.
3. Create a role named DataAnalyst with manual mode and allow all users.
4. Create a policy named PCI_Compliance.
5. Add rules for each data element:
   - CC_Token: allow protect and reprotect, deny unprotect,
     use CC_Show_Last_4 mask, no-access returns null.
   - SSN_Token: allow all operations, no-access raises exception.
   - Email_Token: allow protect and unprotect, deny reprotect.
6. Create a default data store named Production_DS.
7. Deploy PCI_Compliance to Production_DS.

The agent creates a multi-step plan and executes each step in sequence. It reports progress and the final results.