Protegrity Agent

• 1: Prerequisites
• 2: Roles and Permissions
• 2.1: Required Roles and Permissions
• 2.2: Working with Roles
• 3: Installing Protegrity Agent
• 3.1: Installing Protegrity Agent
• 4: Configuring Protegrity Agent
• 5: Using Protegrity Agent
• 5.1: Accessing Protegrity Agent UI
• 5.2: Working with Protegrity Agent
• 5.3: Samples for using Protegrity Agent
• 6: Uninstalling Protegrity Agent
• 7: Appendix - Features and Capabilities and Limitations
• 8: Appendix - Backup and Restore

1 - Prerequisites

The following requirements are met before installing Protegrity Agent with PPC.

• The jumpbox is registered and prepared.
  For more information about registering a jumpbox, refer to Configuring Authentication for Protegrity AI Team Edition.

• Ensure that a PPC cluster is installed and accessible.
  For more information about installing a PPC, refer Installing PPC.

• Ensure that the Protegrity Policy Manager is installed. Install the Policy Workbench to deploy the Protegrity Policy Manager.

  For more information about installing the Policy Workbench, refer to the section Installing Protegrity Policy Manager.
  

• Ensure to have access to OpenAI API keys. These are required to during the installation process.

• The agent_admin role must be available.
  For more information about creating a role, refer Working with Roles.

2 - Roles and Permissions

2.1 - Required Roles and Permissions

The Protegrity Agent uses role-based access control (RBAC) to govern access to its features. The Protegrity Policy Cloud gateway enforces all permissions through JSON Web Token (JWT) authentication. The Agent API does not perform permission checks internally.

Roles

The following table lists the permissions assigned to the roles.

For more information about creating the role, refer to Working with Roles.

Permissions

Protegrity Agent API Permissions

These permissions control access to the core Agent endpoints. All endpoints are authenticated using the jwt_token method.

Workbench Permissions

These permissions control access to Workbench features such as policy management and package distribution.

Insight Permissions

These permissions control access to the Insight dashboard.

Administrative Permissions

These permissions control token creation and user management.

2.2 - Working with Roles

This section describes about creating roles and users for the Protegrity Agent on a Protegrity Policy Cloud cluster. Roles define the features that a user can access. Users inherit permissions from their assigned roles.

For more information about permissions, refer to Required Roles and Permissions.

Prerequisites

• A running PPC cluster with the Protegrity Agent deployed.
• kubectl is configured and is accessible for the target PPC cluster.
• An admin account on the PPC cluster with required permissions to create roles and users.

Retrieving the Gateway Host

To store the PPC gateway address in a shell variable, run the following command .

export GW_HOST="$(kubectl get gateway pty-main -n api-gateway -o jsonpath='{.status.addresses[0].value}')"

The GW_HOST variable is used in every subsequent command.

Generate a JWT Token

Ensure to authenticate as the PPC admin user to obtain a JSON Web Token (JWT). All role and user creation commands require this token.

TOKEN=$(curl -k -s "https://$GW_HOST/api/v1/auth/login/token" \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "loginname=admin" \
  -d "password=Admin123!" \
  -D - -o /dev/null 2>&1 \
  | grep -i 'pty_access_jwt_token:' \
  | sed 's/pty_access_jwt_token: //' \
  | tr -d '\r') && echo "${TOKEN:0:10}"

A successful response prints the first 10 characters of the token. If the output is empty, verify the admin credentials and gateway address.

Creating Agent Roles

Create one or more roles that bundle the permissions that are required by the users.

This section provides two recommended role skeletons:

• Administrator with complete access permissions
• Viewer with read-only permissions

Complete-Access Role (agent_admin)

This role grants read-write access to all Agent, Workbench, and Insight features.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_admin",
    "description": "Administrator role",
    "permissions": [
      "proagent_conversations_permission",
      "proagent_doc_permission",
      "proagent_health_permission",
      "proagent_liveness_permission",
      "proagent_log_permission",
      "proagent_readiness_permission",
      "proagent_responses_permission",
      "proagent_ui_permission",
      "proagent_version_permission",

      "workbench_certificate_export",
      "workbench_package_export_dynamic",
      "workbench_package_export_encrypted",
      "workbench_policy_manage",
      "workbench_policy_view",

      "insight_admin",
      "insight_viewer",

      "can_create_token"
    ]
  }'

This user inherits all permissions from the agent_admin role.

For more information about the available permissions for agent_admin, refer to Roles.

Read-Only Role (agent_reader)

This role restricts access to read-only operations. The user can view conversations and policies but cannot modify or export them.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent_reader",
    "description": "Read-only role",
    "permissions": [
      "proagent_conversations_permission",
      "proagent_doc_permission",
      "proagent_health_permission",
      "proagent_liveness_permission",
      "proagent_log_permission",
      "proagent_readiness_permission",
      "proagent_responses_permission",
      "proagent_ui_permission",
      "proagent_version_permission",

      "workbench_policy_view",

      "insight_viewer",

      "can_create_token"
    ]
  }'

This role excludes workbench_policy_manage, all package export permissions, and insight_admin. The user can view policies and the Insight dashboard but cannot make changes.

For more information about the available permissions for agent_reader, refer to Permissions.

Building a Custom Role

To create a role with any subset of the available permissions, select the required permission from Protegrity Agent Permissions Reference . The JSON payload follows the same structure shown above. Replace the name, description, and permissions array with your values.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<name of custom the role>",
    "description": "<description custom the role>",
    "permissions": [
      <permission 1>,
      <permission 2>,
      <permission 3>
    ]
  }'

Validate Role Creation

To list all roles and confirm your new roles exist, run the following command .

curl -sk -X GET "https://$GW_HOST/pty/v1/auth/roles" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN"

The response includes every role on the PPC cluster. Ensure that agent_admin and agent_reader roles appear in the list.

Create Agent Users

Create user accounts and assign them to the required roles.

Admin User

This user inherits all permissions from the agent_admin role. To create an agent_admin, run the following command.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/users" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent_admin",
    "email": "agent_admin@example.com",
    "firstName": "Agent",
    "lastName": "Admin",
    "enabled": true,
    "password": "Admin123!",
    "roles": [
      "agent_admin"
    ]
  }'

Read-Only User

This user inherits the read-only permissions from the agent_reader role. To create an agent_reader, run the following command.

curl -sk -X POST "https://$GW_HOST/pty/v1/auth/users" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent_reader",
    "email": "agent_reader@example.com",
    "firstName": "Agent",
    "lastName": "Reader",
    "enabled": true,
    "password": "Admin123!",
    "roles": [
      "agent_reader"
    ]
  }'
```=

#### User Skeleton Structure

Every user creation request follows the same JSON structure.

```json
{
  "username": "<unique-username>",
  "email": "<email-address>",
  "firstName": "<first-name>",
  "lastName": "<last-name>",
  "enabled": true,
  "password": "<password>",
  "roles": [
    "<role-name-1>",
    "<role-name-2>"
  ]
}

A user can hold multiple roles. The effective permission set is the union of all permissions from every assigned role. For example, assigning both agent_reader and a custom role that includes workbench_policy_manage grants the user both read and write access to policies.

Note: Change the default passwords before deploying to a production environment.

Verify the User Configuration

After creating the users, log in with the new credentials to confirm the accounts are accessible.

curl -k -s "https://$GW_HOST/api/v1/auth/login/token" \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "loginname=agent_admin" \
  -d "password=Admin123!" \
  -D - -o /dev/null 2>&1 \
  | grep -i 'pty_access_jwt_token:'

A successful response returns a pty_access_jwt_token header. An empty response indicates incorrect credentials or a missing role.

3 - Installing Protegrity Agent

The Protegrity Agent can be installed using helm chart. The helm chart deploys the following components.

3.1 - Installing Protegrity Agent

To install the Protegrity Agent run the following command.

• Installing Protegrity Agent
  • Before you begin
  • Installing Protegrity Agent
• Verifying Protegrity Agent installation
• Creating Protegrity Agent Role and User

Installing Protegrity Agent

Before you begin

The my-values.yaml file must provide the OPENAI keys.

For OpenAI LLM endpoint, provide the following details. This is essential for the Agent to work. The my-values.yaml file should appear as mentioned below.

proagentService:
 
 secrets:
    # Main Endpoint
   OPENAI_API_ENDPOINT: ""
   OPENAI_API_KEY: ""
   OPENAI_API_VERSION: ""
   OPENAI_LLM_MODEL: ""
 
   # Embeddings 
   OPENAI_EMBEDDINGS_API_ENDPOINT: ""
   OPENAI_EMBEDDINGS_API_KEY: ""
   OPENAI_EMBEDDINGS_API_VERSION: ""
   OPENAI_EMBEDDING_MODEL: ""

For more information on additional configurations, refer to Configuring Protegrity Agent.

These values can be provided during installation with -f my-values.yaml.

Important: The current version of Protegrity Agent requires GPT 5.2 main endpoints and GPT 4o embeddings endpoint.

Installing Protegrity Agent

To install the Protegrity Agent, run the following command.

helm upgrade --install protegrity-agent \
oci://<container_registry_path>:9443/protegrity-agent/1.0/helm/protegrity-agent \
--set karpenterResources.nodeClass.amiId="<ami-id>" \
--version 1.0.0 \
--namespace pty-protegrity-agent \
--create-namespace \
-f my-values.yaml

Ensure that in the preceding command is replaced with a valid AMI ID for the AWS region in use.

The following table provides the list of AMI IDs

Verifying Protegrity Agent installation

To verify whether the Protegrity Agent is successfully installed, run the following command:

kubectl get pods -n pty-protegrity-agent

The output should be similar to the following:

NAME                                             READY   STATUS    RESTARTS   AGE
database-statefulset-0                           1/1     Running   0          3m6s
protegrity-agent-db-backup-init-r1-n5bwl         1/1     Running   0          3m6s
protegrity-agent-deployment-7488c88f6d-rgclq     1/1     Running   0          3m6s
protegrity-agent-ui-deployment-c8f848d57-mrm4r   1/1     Running   0          3m6s

Creating Protegrity Agent Role and User

To use Protegrity Agent, a user must have certain roles. Run the following commands to create administrator role and user:

# Get Token
export GW_HOST="$(kubectl get gateway pty-main -n api-gateway -o jsonpath='{.status.addresses[0].value}')"
echo $GW_HOST

TOKEN=$(curl -k -s "https://$GW_HOST/pty/v1/auth/login/token" \
 -X POST \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d "loginname=admin" \
 -d "password=Admin123!" \
 -D - -o /dev/null 2>&1 \
 | grep -i 'pty_access_jwt_token:' \
 | sed 's/pty_access_jwt_token: //' \
 | tr -d '\r') && echo "${TOKEN:0:10}"

# Create Admin Role
curl -sk -X POST "https://$GW_HOST/pty/v1/auth/roles" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "agent_admin",
   "description": "Administrator role",
   "permissions": [
     "proagent_conversations_permission",
     "proagent_doc_permission",
     "proagent_health_permission",
     "proagent_liveness_permission",
     "proagent_log_permission",
     "proagent_readiness_permission",
     "proagent_responses_permission",
     "proagent_ui_permission",
     "proagent_version_permission",

     "workbench_certificate_export",
     "workbench_package_export_dynamic",
     "workbench_package_export_encrypted",
     "workbench_policy_manage",
     "workbench_policy_view",

     "insight_admin",
     "insight_viewer",

     "can_create_token"
   ]
 }'

# Create Admin User
curl -sk -X POST "https://$GW_HOST/pty/v1/auth/users" \
 -H "Accept: application/json" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "username": "agent_admin",
   "email": "agent_admin@example.com",
   "firstName": "Agent",
   "lastName": "Admin",
   "enabled": true,
   "password": "Admin123!",
   "roles": [
     "agent_admin"
   ]
 }'

For more information about managing Protegrity Agent different roles and users, including their creation, refer to Working with Roles.

4 - Configuring Protegrity Agent

API Service Endpoints

This section provides an overview of the service API endpoints exposed by Protegrity Agent.

Protegrity Agent Configurations

In addition to the OpenAI endpoints, the following parameters are configurable through a user-provided my-values.yaml file, supplied during deployment using the helm upgrade ... -f my-values.yaml command.

Updating the Deployment

To update the deployed cluster it is recommended to create a my-values.yaml and then helm upgrade ... -f my-values.yaml.

helm upgrade --install protegrity-agent \
oci://<container_registry_path>:9443/protegrity-agent/1.0/helm/protegrity-agent \
--set karpenterResources.nodeClass.amiId="<ami-id>" \
--version 1.0.0 \
--namespace pty-protegrity-agent \
--create-namespace \
-f my-values.yaml

Ensure that in the preceding command is replaced with a valid AMI ID for the AWS region in use.

The following table provides the list of AMI IDs

After upgrading the parameters successfully, execute the following command.

kubectl rollout restart protegrity-agent -n pty-protegrity-agent

5 - Using Protegrity Agent

Protegrity Agent is a conversational AI assistant that helps to manage Protegrity data protection products.

It supports three main categories of tasks.

Answer Questions About Protegrity Products

Enquire about Protegrity concepts, configurations, and best practices. The agent searches the Protegrity documentation library to find accurate answers.

Example questions:

• “What is a data element in Protegrity?”
• “How do policies and rules relate to each other?”
• “What tokenization methods does Protegrity support?”
• “Explain the difference between masking and encryption.”

Manage PIM Resources

Enquire to create, view, update, or delete resources in PIM. The Protegrity Agent finds the correct application programming interface (API) schema, builds the request, and executes it in real-time.

The agent supports the following PIM resource types:

The agent verifies each operation and reports the outcome.
For multi-step tasks, it creates a plan and works through each step.

Look Up API and Product Details

Enquire about PIM API endpoints, schemas, or product concepts.

Example requests:

• “What fields do I need to create a policy?”
• “Show me the schema for adding a rule to a policy.”
• “What tokenizer types can I use for credit cards?”

5.1 - Accessing Protegrity Agent UI

Accessing the Dashboard

Access the PPC using the FQDN provided during the installation process.

Enter the username and password for the admin user to log in.

If Protegrity Agent is installed, then the Protegrity Agent dashboard appears. If Protegrity Agent is not installed, then the Insight Dashboard is available.

Afetr logging in successfully, a Welcome message is displayed prompting users to start a conversation.

The left panel contains Ongoing Conversation and Chat History icons.

Click Chat History to refer to previous requests and results.

The Protegrity Agent version is displayed at the bottom-right of the page. Currently, Protegrity Agent is on version 1.0.

Starting a Conversation

Get started with Protegrity Agent by typing a question in the Start your conversation here… textbox. The Protegrity Agent breaks down the request into actionable steps and executes them, providing live updates in the Canvas.

Once the Agent starts processing the query, the stop icon is enabled. Use this icon to stop the Agent from proceeding with the request.

Interacting with the Agent

The following are the best practices while interacting with the agent.

Be Specific

Provide clear instructions. Include resource names, values, and desired outcomes.

Understanding the Canvas

The attributes displayed in the canvas response along with their description are listed below.

If the response from the Agent is text information only, the Canvas does not display any output.

5.2 - 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.

5.3 - Samples for using Protegrity Agent

A few sample queries for interacting with the Protegrity Agent are listed below. Expand the sample queries below for detailed information

Sample Query 1

In the Start your conversation here… textbox type the query.

Query 1

Explain Protegrity terms such as data protection policy, data element, data type, tokenization and how they integrate with each other.

Sample Output

Protegrity Agent Response:

Below is a conceptual, system level explanation of the core Protegrity terms you asked about, and how they fit together in practice. I’ll stay out of API mechanics and focus on meaning and flow.

1. Data Type (business meaning of the data) What it is A data type is not a concrete object in Protegrity. It’s the business classification of data. Examples: • Credit Card Number • Social Security Number • Email Address • Customer Name Think of data types as answering: “What kind of sensitive data is this?” They are how security and compliance teams reason about risk and requirements.

1. Data Element (how a data type is protected) What it is A Data Element is a concrete protection definition in Protegrity. It operationalizes a data type by defining how that data is protected cryptographically. You typically create: • One Data Element per data type Examples: • Data Element: CreditCardNumber_Tokenized • Data Element: CustomerName_FPE • Data Element: Email_Masked A Data Element defines: • Protection method (tokenization, encryption, masking, etc.) • Cryptographic parameters • Format preservation behavior • Optional output character rules (alphabets) Key properties: • Immutable after creation (except description) • Reused across many policies and systems • The foundation of enforcement In short: Data type = what the data is Data element = how that data is protected

1. Tokenization (one protection method) What it is Tokenization is a protection method where: • Sensitive data is replaced with a token • The token has no mathematical relationship to the original value • Re identification is possible only via Protegrity Example: Original: 4111 1111 1111 1111 Token: 8394 5521 9012 4478 Why tokenization is commonly used: • Preserves length and often format • Reduces compliance scope (e.g., PCI) • Tokens are safe to store and process In Protegrity: • Tokenization is configured inside a Data Element • Different tokenizers exist depending on format and length needs • Tokenization is applied consistently wherever the Data Element is used Tokenization answers: “How do we protect this data while keeping it usable?”

1. Data Protection Policy (who can do what) What it is A Data Protection Policy defines access rules for protected data. It does not define cryptography. It defines authorization and behavior. A policy answers: “Who is allowed to protect, unprotect, or see this data?” A policy contains rules, and each rule links: • A Role (who) • A Data Element (what data) • Permissions (what actions are allowed) Example rules: • App role can tokenize and detokenize credit cards • Analytics role can only see masked values • Everyone else gets no access Important: • Policies reference Data Elements • Policies are enforced at runtime by protectors • Policies are deployed to environments via data stores

1. How they all come together (end to end flow) Here is the mental model that ties everything together: Step 1: Classify the data You identify a data type: • “This column is a credit card number” Step 2: Define protection You create a Data Element: • Uses tokenization • Preserves format • Meets compliance requirements Now Protegrity knows how to protect that type of data. Step 3: Define access You create a Data Protection Policy: • Application role can tokenize and detokenize • Support role can only see masked values • Others have no access Now Protegrity knows who can do what with that data. Step 4: Enforcement at runtime When an application: • Calls protect → Protegrity uses the Data Element’s tokenization • Calls unprotect → Protegrity checks the policy rules • Returns clear, masked, or blocked data accordingly

Everything flows through: Data Type ↓ Data Element (protection method, e.g. tokenization) ↓ Policy Rule (role + permissions) ↓ Runtime enforcement by protectors

One sentence summary • Data type: what the data represents (business meaning) • Data element: how that data is protected (cryptography) • Tokenization: one way a data element protects data • Data protection policy: who is allowed to protect or see the data • Together: Protegrity separates what the data is, how it’s protected, and who can access it so security is consistent, centralized, and enforceable everywhere If you want, next we can: • Walk through a concrete example (e.g., credit card in an app) • Compare tokenization vs encryption vs FPE • Explain roles and masking in more depth

Sample Query 2

Query

In the Start your conversation here… textbox type the query.

Create a new DataElement named UserContact_AES256 for encrypting user contact details using aes256CbcEnc with ivType SYSTEM_APPEND, checksumType CRC32, and cipherFormat INSERT_KEYID_V1.

Sample Output

Protegrity Agent Response:

Created the Data Element UserContact_AES256 for encrypting user contact details. Details: • Protection method: AES-256 CBC encryption • IV type: SYSTEM_APPEND • Checksum type: CRC32 • Cipher format: INSERT_KEYID_V1 • Description: “Encrypt user contact details using AES-256 CBC” • Assigned UID: 6 The payload was validated and successfully created in PIM. This Data Element is now available to be referenced in policy rules.

Click View JSON. The following is a sample information that displays.

{
  "type": "attestation",
  "id": "attest_ff4b147f-a09a-4182-b0a4-3e56f00fdbb2",
  "claim": "POST /dataelements → 201 (success)",
  "confidence_level": 1,
  "evidence_data": {
    "source": "POST /dataelements",
    "collected_at": "2026-03-09T13:54:14.019243Z",
    "data": {
      "method": "POST",
      "endpoint": "dataelements",
      "action": "send",
      "ok": true,
      "status_code": 201,
      "response_body": "{\"uid\":\"6\",\"name\":\"UserContact_AES256\",\"description\":\"Encrypt user contact details using AES-256 CBC\",\"aes256CbcEnc\":{\"ivType\":\"SYSTEM_APPEND\",\"checksumType\":\"CRC32\",\"cipherFormat\":\"INSERT_KEYID_V1\"}}"
    }
  },
  "evidence_type": "execution_log",
  "verification_method": "http_status_code",
  "created_at": "2026-03-09T13:54:14.019266Z"
}

Sample Query 3

In the Start your conversation here… textbox type the query.

Query

Enable GDPR-compliant analytics access for the MyCompanyDataLake so Marketing_Analytics can only view masked users data while Security_Compliance retains full unmasked access, create a policy if you need, validate effective access, and confirm rollback readiness.

Sample Output

Protegrity Agent Response:

Here’s a concise status summary of what was done and what’s in effect. What was implemented Datastore • Created MyCompanyDataLake (uid 1) and set it as the default datastore. Policy • Created MyCompany_GDPR_Analytics_Policy (uid 1) with protect / reProtect / unProtect enabled. Data element • Reused existing SreerajDataElement (uid 5) to represent user data, avoiding any irreversible data element changes. Mask • Created GDPR_User_Mask (uid 1) to enforce masked output for GDPR restricted access. Roles • Marketing_Analytics (uid 1) • Security_Compliance (uid 2) • Both roles are enabled for access (allowAll=true) to ensure the policy can be enforced. Policy rules • Marketing_Analytics: • unProtect = true • Mask applied = GDPR_User_Mask • Result: users see only masked user data. • Security_Compliance: • unProtect = true • No mask applied • Result: users see full, unmasked user data. Deployment • Deployed MyCompany_GDPR_Analytics_Policy to MyCompanyDataLake. • Deployment verified as active. Validation performed • Confirmed the datastore MyCompanyDataLake is bound to policy uid 1. • Retrieved and inspected policy rules: • Marketing_Analytics rule includes mask uid 1. • Security_Compliance rule has no mask. • This confirms effective GDPR compliant access separation: masked analytics vs full compliance access. Rollback readiness (confirmed) No pre existing policies or datastores existed, so rollback is clean and low risk:

1. Detach the policy from the datastore by redeploying MyCompanyDataLake with an empty policies list.
2. Optionally delete the two policy rules under policy uid 1.
3. Optionally delete MyCompany_GDPR_Analytics_Policy (uid 1).
4. Optionally revert or delete the two roles.
5. Delete GDPR_User_Mask (uid 1) once no rules reference it. This restores the system to its original empty state. Net result • Marketing analytics access is GDPR compliant and masked. • Security/compliance access retains full visibility. • Configuration is deployed, validated, and fully reversible.

Click View JSON. The following is a sample information that displays.

{
  "type": "attestation",
  "id": "attest_17829805-2e5d-4cbf-bc27-94eb60da6656",
  "claim": "GET /datastores/1 → 200 (success)",
  "confidence_level": 1,
  "evidence_data": {
    "source": "GET /datastores/1",
    "collected_at": "2026-03-09T13:45:50.703839Z",
    "data": {
      "method": "GET",
      "endpoint": "datastores/1",
      "action": "send",
      "ok": true,
      "status_code": 200,
      "response_body": "{\"description\":\"Datastore for MyCompany analytics and compliance workloads\",\"name\":\"MyCompanyDataLake\",\"default\":true,\"uid\":\"1\",\"policies\":[\"1\"],\"applications\":[]}"
    }
  },
  "evidence_type": "execution_log",
  "verification_method": "http_status_code",
  "created_at": "2026-03-09T13:45:50.703862Z"
}

Sample Query 4

Query

Set up a complete PIM environment from scratch, then modify and tear it down:

PHASE 1 — CREATE (respect dependency order):

1. Create three masks: “Show_Last_4” (fromLeft=0, fromRight=4, masked=false, character="#"), “Show_1st_Character” (fromLeft=1, fromRight=0, masked=false, character="*"), and “Mask_All” (fromLeft=0, fromRight=0, masked=true, character="#").
2. Create a FILE member source named “File_Member_Source” with userFile “exampleusers.txt” and groupFile “examplegroups.txt”.
3. Create two datastores: “CRM-Prod-DB” (description “Primary customer database”) and “DataLake” (description “Encrypted customer data lake for analytics”).
4. Create five data elements: “Name” (AES256 CBC encryption, ivType SYSTEM_APPEND, checksumType CRC32, cipherFormat INSERT_KEYID_V1), “Address” (same encryption settings), “DOB” (date tokenization with SLT_2_6), “CCN” (credit card tokenization with SLT_2_6, fromRight=4), and “SSN” (numeric FPE, fromRight=4, minLength=2, tweakMode EXT_INPUT).
5. Create twelve roles: “Address_Full”, “Name_Full”, “Name_Unprotect”, “DOB_Unprotect”, “SSN_Full”, “CCN_Masked”, “CCN_Full”, “DOB_Full”, “DOB_Protected”, “SSN_Masked”, “Name_Masked”, and “Address_Masked”.
6. Create two IP ranges: 10.20.0.50–10.20.0.150 assigned to CRM-Prod-DB, and 10.20.0.180–10.20.0.250 assigned to DataLake.
7. Create a USER member “CRM_Admins” in source “File_Member_Source” with all twelve roles assigned.
8. Create a trusted application “CRM” (applicationName “crm-backend”, applicationUser “crm-srv”).
9. Create policy “CDPP-001” with default template denying all access (protect=false, reProtect=false, unProtect=false), then add all twelve role mappings: Name_Full→Name (full access), Address_Full→Address (full access), DOB_Full→DOB (full access), CCN_Full→CCN (full access), SSN_Full→SSN (full access), Name_Masked→Name (protect+unprotect with Show_1st_Character mask), Address_Masked→Address (protect+unprotect with Mask_All mask), DOB_Protected→DOB (protect only), CCN_Masked→CCN (protect+unprotect with Show_Last_4 mask), SSN_Masked→SSN (protect only), Name_Unprotect→Name+Address (unprotect only), and DOB_Unprotect→DOB (unprotect only).*

**PHASE 2 — MODIFY: 10. Update the “DataLake” datastore description to “Decommissioned analytics lake — do not use”. 11. Update the “Mask_All” mask character from “#” to “X”. 12. Update mask “Show_Last_4” to reveal 6 characters from right instead of 4.

PHASE 3 — TEARDOWN (reverse dependency order): 13. Delete policy “CDPP-001”. 14. Delete member “CRM_Admins”. 15. Delete trusted application “CRM”. 16. Delete both IP ranges. 17. Delete all twelve roles. 18. Delete all five data elements. 19. Delete both datastores. 20. Delete member source “File_Member_Source”. 21. Delete all three masks.**

Confirm each operation succeeded before moving to the next.

Assume defaults, you dont need guidance, do not ask me for anything, be brave, go for it, you’re a lion, you have all the knowledge in you, just do it !

Sample Output

Here’s the concise end‑to‑end summary of what was executed and verified in your live PIM environment.

✅ PHASE 1 — CREATE (all dependencies respected) Masks

Created: Show_Last_4 (UID 16) Show_1st_Character (UID 17) Mask_All (UID 18) Member Source

Created FILE member source File_Member_Source (UID 6) userFile: exampleusers.txt groupFile: examplegroups.txt Datastores

Created: CRM-Prod-DB (UID 11) — “Primary customer database” DataLake (UID 12) — “Encrypted customer data lake for analytics” Data Elements

Created: Name (UID 22) — AES256 CBC encryption Address (UID 23) — AES256 CBC encryption DOB (UID 25) — DateTime tokenization (SLT_8_DATETIME) CCN (UID 26) — Credit card tokenization (SLT_2_6, fromRight=4) SSN (UID 24) — Numeric FPE (fromRight=4, minLength=2, EXT_INPUT) Roles

Created 12 roles (UIDs 50–61): Address_Full, Address_Masked Name_Full, Name_Masked, Name_Unprotect DOB_Full, DOB_Protected, DOB_Unprotect CCN_Full, CCN_Masked SSN_Full, SSN_Masked IP Ranges

CRM-Prod-DB: 10.20.0.50–10.20.0.150 (UID 9) DataLake: 10.20.0.180–10.20.0.250 (UID 10) Role Membership

Added USER member CRM_Admins (source UID 6) to all 12 roles Trusted Application

Created CRM (UID 5) applicationName: crm-backend applicationUser: crm-srv Policy and Rules

Created policy CDPP-001 (UID 6) with deny‑all template Added all 12 requested rule mappings, including: Full access rules Masked unprotect rules using correct masks Protect‑only and unprotect‑only rules All rules verified created successfully

✅ PHASE 2 — MODIFY Updated DataLake datastore description to: “Decommissioned analytics lake - do not use” (Adjusted to ASCII hyphen due to API constraints) Updated Mask_All: Mask character changed to “0” (alphabetic characters not allowed by API) Updated Show_Last_4: fromRight changed from 4 → 6 All updates confirmed applied.

✅ PHASE 3 — TEARDOWN (strict reverse order) Successfully deleted, in order:

Policy CDPP-001 CRM_Admins members from all roles Trusted application CRM Both IP ranges All 12 roles All 5 data elements Both datastores File member source File_Member_Source All 3 masks Every delete returned a successful confirmation.

🔎 Notable Findings (recorded in knowledge store) Tokenization data elements must use dateTimeToken and creditCardToken schemas — not generic fields. Mask characters are restricted to *, #, -, or digits 0–9. Datastore descriptions reject Unicode punctuation (e.g., em dashes).

✅ Final State Environment fully created, modified, and completely torn down. No residual resources remain. Plan completed exactly as requested, with every operation verified via API responses. Execution complete.

Click View JSON. The following is a sample information that displays.

{
  "type": "attestation",
  "id": "attest_cf8b274b-a844-4158-92a8-581b232455c3",
  "claim": "DELETE /masks/18 → 204 (success)",
  "confidence_level": 1,
  "evidence_data": {
    "source": "DELETE /masks/18",
    "collected_at": "2026-03-24T12:19:51.661943Z",
    "data": {
      "method": "DELETE",
      "endpoint": "masks/18",
      "action": "send",
      "ok": true,
      "status_code": 204
    }
  },
  "evidence_type": "execution_log",
  "verification_method": "http_status_code",
  "created_at": "2026-03-24T12:19:51.661967Z"
}

6 - Uninstalling Protegrity Agent

To uninstall the Protegrity Agent, run the following command.

helm uninstall protegrity-agent -n pty-protegrity-agent
kubectl patch ec2nodeclass protegrity-agent-nodeclass -p '{"metadata":{"finalizers":[]}}' --type=merge
kubectl delete namespace pty-protegrity-agent

To verify the uninstallation is successfully completed, run the following command:

kubectl get all -n pty-protegrity-agent 2>/dev/null; kubectl get ec2nodeclass,nodepool,nodes

If the command returns no output, all tracked resources for the product are successfully removed from the cluster.

This operation might require few minutes for clearing all the resources.

7 - Appendix - Features and Capabilities and Limitations

ProAgent Singleton

Autonomous agent that orchestrates LLM-powered planning and execution within a single, persistent loop

• Maintains a per-conversation agent instance managed by an agent pool, ensuring full state isolation between concurrent conversations
• Runs a manual iteration loop with dynamic context re-injection: reads workspace knowledge, plan state, and domain-specific skills before every LLM call
• Routes queries via LLM classification between direct answers and structured plan-execute workflows
• Coordinates the planner and executor to decompose complex requests into atomic steps and execute them sequentially
• Dispatches tool calls for API interactions, file operations, knowledge updates, and human feedback requests
• Streams typed events in real time (plan created, step started, step executed, attestation, feedback request, final response) with keepalive signals to prevent idle timeouts
• Pauses execution on human feedback requests, resumes from the exact same state once the user responds
• Tracks UID mappings across multi-step operations so subsequent steps can reference resources created in earlier steps
• Detects non-recoverable failures (expired sessions, unreachable servers) and aborts gracefully
• Persists full conversation state to a database and per-conversation workspace files

Integrated Planning and Execution

The singleton agent handles planning and execution within a single, unified tool-calling loop — there are no separate planning or execution phases

• Plans are created and maintained through a built-in plan_update tool that the agent calls to set goals, define steps, track progress, and record results
• API calls are executed directly via a json_payload tool that sends requests to the PIM API
• Schema discovery is performed on demand through schema_lookup and vector_retrieve tools for semantic endpoint matching
• Workspace files store accumulated knowledge, plans, and execution artifacts across iterations
• The agent decides autonomously when to plan, execute, look up schemas, request feedback, or update knowledge — all within the same reasoning loop

Tool Palette

There are 10 built-in tools that the agent selects from on each iteration.

• plan_update — create and update execution plans with goals, steps, and status tracking
• json_payload — execute API calls against the PIM endpoint
• schema_lookup — retrieve API schema details for specific endpoints
• vector_retrieve — semantic search across the PIM API specification for endpoint discovery
• knowledge_update — persist learned context to the agent workspace for future iterations
• request_feedback — pause execution and request clarification from the user
• file_read, file_list, file_search, file_edit — workspace file operations for reading plans, skills, and stored results

Protegrity Policy Management Integration

ProAgent provides comprehensive access to Protegrity Policy Management APIs through 74 operations across 14 functional categories, based on the PIM API v2.12.3 specification.

8 - Appendix - Backup and Restore

Backup

The Protegrity Agent Helm chart includes automated Postgres backup and disaster recovery via Velero. Backup runs by default on every installation.

How It Works

A CronJob runs pg_dump every three hours to a dedicated Persistent Volume Claim (PVC). Velero snapshots that PVC to S3 thirty minutes later. This two-stage approach ensures database consistency.

Restore

To recover from a disaster, reinstall the chart with global.restore=true:

helm upgrade --install protegrity-agent \
  --namespace pty-protegrity-agent \
  --set global.restore=true \
  --timeout 15m

To restore a specific point-in-time backup, add --set backup.backupName=<name>.

After the restore completes, reinstall without the flag to resume normal backup operation.

Key Configuration