Updating Python Modules

This document provides guidance on migrating from the Protegrity AI Developer Edition to the Protegrity AI Team Edition (Cloud Protectors) using the Python SDK.

Prerequisites

• Install and set up the Protegrity Provisioned Cluster (PPC) and AI Team Edition using the steps from the PPC documentation and the respective feature documentation.
• Install and set up a compatible Cloud Protector for Protegrity AI Team Edition.

Move to Protegrity AI Team Edition using one of the following approaches:

• CLI tool: For an automated CLI-based migration, refer to Using the CLI tool.
• Python SDK: To migrate manually using the AI Team Edition Python SDK, refer to Using the Python SDK of AI Team Edition.

Scenario 1: Using the CLI Tool

Protegrity AI Developer Edition version 1.2.0 includes a CLI to make the Protegrity AI Developer Edition (DE) → Protegrity AI Team Edition (TE) transition mechanical rather than manual. Install the Python package and use the CLI tool to verify the migration and to create the required policies on PPC.

1. Set Team Edition environment variables for the SDK on the application host:

   export PTY_CP_HOST=<your-cloud-protect-invoke-url>
   export PTY_AUTH_MODE=aws_iam        # or cognito, bearer_token, mtls, none
   

2. Set PPC credentials. This is used by both check and create-policy:

   export PTY_PPC_HOST=<your-ppc-host>
   export PTY_PPC_PASSWORD=<admin-password>
   

   Both commands also accept --ppc-host <host> and --ppc-password <password> flags if you prefer to pass them explicitly per invocation. Environment variables are recommended to keep credentials out of shell history.

   As an alternative, every pty-migrate and SDK setting can also reside in ~/.protegrity/config.yaml. The resolution order: CLI flag > env var > YAML file > default. Storing passwords in the file requires allow_secrets_in_file: true AND chmod 600 on the file. This is the same model as ~/.pgpass. For the full key list, refer to config.yaml.template in the protegrity-ai-developer-python package.

3. Run a readiness check to view any missing requirements:

   pty-migrate check
   

   By default, this verifies only the data elements and users present in the local usage stats. Add --full to verify the entire bundled Protegrity AI Developer Edition policy instead.

   The output lists each item, such as the SDK version, endpoint reachability, PPC data elements, datastore export key, and role members, with ✓ or ✗ and a concrete remediation command for anything missing.

4. Deploy the policy to PPC. This is only needed the first time, or after a PPC reset:

   pty-migrate create-policy
   

   By default, the CLI deploys only the data elements that usage stats show are used. Add --full to deploy the complete bundled Developer Edition policy. This is recommended for QA, training, or demo environments that should mirror Protegrity AI Developer Edition.

5. Register the datastore export key so the Policy Agent can sync the policy to Cloud Protect. The exact curl command with the right datastore id is printed at the end of create-policy. Supply the KMS public key (PEM); the fingerprint returned must match PTY_DATASTORE_KEY on the Policy Agent Lambda.

6. Trigger the Policy Agent Lambda or wait for its hourly schedule to push the policy from PPC to Cloud Protect.

7. Re-run pty-migrate check. If required, add --full if earlier deployed with --full. When every line shows ✓, the application’s existing sample-app-protection.py / sample-app-protection.sh commands will work unchanged against Protegrity AI Team Edition with the same policy_user and same data_element names.

Note: The same data elements, role names, and policy users you used in Protegrity AI Developer Edition, such as superuser, admin, name, address, text, ccn, and so on, are preserved on Protegrity AI Team Edition by create-policy. No application code changes are required to switch environments.

Configuration Reference

All settings can be supplied using environment variables, a YAML file at ~/.protegrity/config.yaml (override path with PTY_CONFIG_FILE), or built-in defaults - resolved in that order. A starter template is available at config.yaml.template in the protegrity-ai-developer-python package.

# ~/.protegrity/config.yaml - keys mirror the PTY_* env vars but lowercased
protect_host: https://cp.example.com/pty
auth_mode: bearer_token
request_timeout: 30
max_retries: 3
# static_token: eyJhbGciOi...   # see security note below

Note: Secret keys, such as static_token and client_secret are loaded from the YAML file. This is only if the file is chmod 600, that is, owner read/write only the same rule ssh and ~/.pgpass enforce. If the file is group-readable or world-readable, secret keys are dropped at load time and a warning is printed to stderr; non-secret keys still load normally. On Windows, the POSIX permission check is skipped.

Usage Statistics

appython writes anonymous local counters, such as operation type, data element, and day, to ~/.protegrity/stats.json after every protect/unprotect/reprotect call. The file never leaves your machine and contains no payloads or credentials. Disable with PTY_DISABLE_USAGE_STATS=1.

Note: PTY_PROTECT_HOST from earlier 1.2.0 pre-releases was renamed to PTY_CP_HOST to avoid confusion with PTY_PPC_* (Policy Console) variables. Update any scripts before upgrading.

The pty-migrate CLI

Installed automatically with the package.

Run the following three subcommands to help you create the required policies and migrate:

pty-migrate check          # Pre-flight readiness validation
pty-migrate create-policy  # Create the equivalent DE policy on your PPC
pty-migrate stats          # View local usage statistics

• pty-migrate check validates SDK version, PTY_CP_HOST, auth credentials, and (optionally) round-trips a real protect call against your Cloud Protect endpoint. Run it once after exporting your env vars; it prints actionable hints for each missing piece.
• pty-migrate create-policy talks to your Protegrity Provisioned Cluster (PPC) using PTY_PPC_HOST, PTY_PPC_USER, PTY_PPC_PASSWORD, and PTY_WORKBENCH_PASSWORD, then creates a TE policy whose data elements match the ones DE provided out of the box (ccn, ssn, name, email, …). It is safe to re-run this command.
• pty-migrate stats prints a per-data-element, per-day breakdown so you can size your TE deployment based on real DE usage.

Note: Storing PPC passwords in the YAML file is supported but off by default. To opt in, add allow_secrets_in_file: true to ~/.protegrity/config.yaml and chmod 600 the file; only then will ppc_password and workbench_password be read from it. Without both, pty-migrate ignores those keys and prints a remediation hint - the same model as ~/.pgpass and ~/.npmrc. CLI flags (--ppc-password) and env vars (PTY_PPC_PASSWORD) always take precedence and need no opt-in.

Scenario 2: Using the AP Python module of AI Team Edition

Note: When the policy is set up on the AI Team Edition, ensure that the same data elements added for the AI Developer Edition are used. For more information about the data elements policy, refer to Policy Definition.
If you use different data elements while creating the policy, then modify the data elements used in the AI Developer Edition accordingly before running the modules.

1. Select the venv where protegrity-ai-developer-python is installed.

2. Install Application Protector Python using the steps from the Application Protector Python documentation.

   Note:
   When prompted for the ESA IP address, enter the hostname of the PPC. Similarly, when prompted for the ESA listening port number, enter 25400. This enables the protector to integrate with the PPC.
   After installation, the AP Python module of AI Developer Edition is replaced with the AP Python module of AI Team Edition.

3. Run the samples.