This is the multi-page printable view of this section. Click here to print.
Appendices
- 1: Integrating Cloud Protect with PPC (Protegrity Provisioned Cluster)
- 2: Configuring Regular Expression to Extract Policy Username
- 3: Sample Snowflake External Functions for Protegrity Integration
- 4: ARM Template Installation - Required Permissions
- 5: Associating ESA Data Store With Cloud Protect Agent
1 - Integrating Cloud Protect with PPC (Protegrity Provisioned Cluster)
This guide describes how to configure the Protegrity Policy Agent and Log Forwarder to connect to a Protegrity Provisioned Cluster (PPC), highlighting the differences from connecting to ESA.
Key Differences: PPC vs ESA
| Feature | ESA 10.2 | PPC (this guide) |
|---|---|---|
| Datastore Key Fingerprint | Optional/Recommended | Required |
| CA Certificate on Agent | Optional/Recommended | Optional/Recommended |
| CA Certificate on Log Forwarder | Optional/Recommended | Not supported |
| Client Certificate Authentication from Log Forwarder | Optional/Recommended | Not supported |
| IP Address | ESA IP address | PPC address |
Prerequisites
- Access to PPC and required credentials.
- Tools:
curl,kubectlinstalled.
Policy Agent Setup with PPC
Important
When connecting to PPC, the Policy Agent requires use of a datastore key fingerprint. For connecting to ESA 10.2 with Cloud Protect Policy Agent, the fingerprint is optional but recommended. See Policy Agent Installation for general setup steps.Follow these instructions as a guide for understanding specific inputs for Policy Agent integrating with PPC:
Obtain the Datastore Key Fingerprint
To retrieve the fingerprint for your Policy Agent:
Retrieve public key from the Cloud Provider Key Management service for the policy encryption key created in pre-configuration:
- Navigate to the Key Management Service in AWS console and open Customer Managed Keys
- Select the desired key
- Select the Public Key tab
- Select Download
- Navigate to the Key Vault in Azure console and open Objects>Keys
- Select the desired key
- Select the key indicated as CURRENT VERSION
- Select Download public key
- Navigate to Key Management in GCP console
- Select the desired key and open the Versions tab
- Select Get public key from the Actions column menu
- Select Download
Escape the new line characters in the downloaded public key for use in the next step - for example:
awk 'NF {printf "%s\\n",$0}' "<public_key_file>" > "new-line-escaped-public-key.pem" cat new-line-escaped-public-key.pemExport key fingerprint using the PPC API as indicated in the curl example below:
curl -k -H "Authorization: Bearer ${TOKEN}" -X POST https://${HOST}/pty/v2/pim/datastores/1/export/keys -H "Content-Type: application/json" --data '{ "algorithm": "RSA-OAEP-256", "description": "example-key-from-key-management", "pem": "<value of new-line-escaped-public-key>" }'Sample Output:
{"uid":"1","algorithm":"RSA-OAEP-256","fingerprint":"4c:46:d8:05:35:2e:eb:39:4d:39:8e:6f:28:c3:ab:d3:bc:9e:7a:cb:95:cb:b1:8e:b5:90:21:0f:d3:2c:0b:27","description":"example-key-from-kms"}Note
Alternatively, set using the PPC CLI utility. See the export key example in Create Datastores KeyRecord the value for
fingerprintand configure the Policy Agent:Set the environment variable
PTY_DATASTORE_KEYin the Policy Agent Lambda function to thefingerprintvalue.Set the environment variable
PTY_DATASTORE_KEYin the Policy Agent Function App to thefingerprintvalue.Set the variable in Policy Agent main.tf
pty_datastore_keyto thefingerprintvalue and apply the changes.
Retrieve the PPC CA Certificate
To obtain the CA certificate from PPC:
kubectl -n api-gateway get secret ingress-certificate-secret -o jsonpath='{.data.ca\.crt}' | base64 -d > CA.pemUse the
ProtegrityCA.pemthat was returned as described in Policy Agent Installation.Configure the PPC Address
Use the PPC address in place of the ESA IP address wherever required in your configuration.
Note
Use FQDN as described in the PPC Rest API documentation
Log Forwarder Setup with PPC
Note
When using PPC, certificate authentication and CA validation are not supported for the Log Forwarder. Configuration steps related to certificates in Log Forwarder Installation do not apply to PPC. If you attempt to use certificates provided by PPC, the Log Forwarder will not function correctly.- The Log Forwarder will proceed without certificates and will print a warning if
PTY_ESA_CA_SERVER_CERTis not provided. - No additional certificate or CA configuration is needed for PPC.
2 - Configuring Regular Expression to Extract Policy Username
Configuring Regular Expression to Extract Policy Username
Cloud Protect Function exposes USERNAME_REGEX configuration to allow extraction of policy username from user in the request.
USERNAME_REGEX Function Environment configuration
The USERNAME_REGEX environment variable can be set to contain regular expression with one capturing group. This group is used to extract the username. Examples below show different regular expression values and the resulting policy user.
USERNAME_REGEX | User in the request | Effective Policy User |
|---|---|---|
Not Set | ||
juliet.snow/ad_postfix | juliet.snow/ad_postfix | |
| juliet.snow | |
juliet.snow/ad_postfix | juliet.snow |
3 - Sample Snowflake External Functions for Protegrity Integration
Appendix A. Sample Snowflake External Function
Method: Tokenization | ||
Type: ALPHA | ||
| ||
Snowflake Data Types | Snowflake Max Size | Protegrity Max Size |
VARCHAR | 16M (16,777,216 bytes) | 4K (4,096 bytes) |
CHAR | ||
STRING | ||
TEXT | ||
| ||
External Function Sample Definitions: | ||
| ||
| ||
| ||
Sample EF Calls: | ||
| ||
| ||
| ||
Snowflake Masking Policy example: | ||
| ||
| ||
Method: Tokenization | ||
Type: NUMERIC | ||
| ||
Snowflake Data Types | Snowflake Max Size | Protegrity Max Size |
NUMBER |
|
|
DECIMAL | ||
INTEGER | ||
DOUBLE | ||
| ||
External Function Sample Definitions: | ||
| ||
| ||
| ||
Sample EF Calls: | ||
| ||
| ||
| ||
Snowflake Masking Policy example: | ||
| ||
| ||
Method: Tokenization | ||
Type: DATE YYYY-MM-DD | ||
| ||
Snowflake Data Types | Snowflake Max Size | Protegrity Max Size |
DATE (any supported format) | 10 bytes | 10 bytes |
| ||
External Function Sample Definitions: | ||
| ||
| ||
Sample EF Calls: | ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
Snowflake Masking Policy example: | ||
| ||
| ||
Cutover Dates of the Proleptic Gregorian Calendar: no issues (no conversions performed by Snowflake)
Method: Tokenization | ||
Type: DATETIME | ||
| ||
Snowflake Data Types | Snowflake Max Size | Protegrity Max Size |
DATE | 10 bytes | 29 bytes |
DATETIME | 29 bytes | |
TIMESTAMPNTZ* | ||
TIMESTAMP_NTZ* | ||
TIMESTAMP WITHOUT TIME ZONE* | ||
| ||
External Function Sample Definitions: | ||
| ||
| ||
Sample EF Calls: | ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
Snowflake Masking Policy example: | ||
| ||
| ||
Method: Tokenization | ||
Type: DECIMAL | ||
| ||
Snowflake Data Types | Snowflake Max Size | Protegrity Max Size |
NUMBER(N,M) | 38 digits | 36 digits |
NUMERIC(N,M)* | ||
DECIMAL(N,M)* | ||
| ||
External Function Sample Definitions: | ||
| ||
| ||
Sample EF Calls: | ||
| ||
| ||
| ||
Snowflake Masking Policy example: | ||
| ||
| ||
Method: Tokenization | ||
Type: INTEGER | ||
| ||
Snowflake Data Types | Snowflake Max Size | Protegrity Max Size |
NUMBER | 38 digits | 2 bytes 4 bytes 8 bytes |
NUMERIC* | ||
INT* | ||
INTEGER* | ||
BIGINT* | ||
SMALLINT* | ||
TINYINT* | ||
BYTEINT* | ||
| ||
External Function Sample Definitions: | ||
| ||
| ||
Sample EF Calls: | ||
| ||
| ||
| ||
Snowflake Masking Policy example: | ||
| ||
| ||
**Recommended approach for protecting whole numbers fields in Snowflake
| When values are | …then use the following Data Element: |
|---|---|
| Between -32768 and 32767 | INTEGER (2 bytes) |
| Between -2147483648 and 2147483647 | INTEGER (4 bytes) |
| Between -9223372036854775808 and 9223372036854775807 | INTEGER (8 bytes) |
| < -9223372036854775808 or > 9223372036854775807 | DECIMAL |
When in doubt, use DECIMAL for any numeric range.
4 - ARM Template Installation - Required Permissions
ARM Template Installation - Required Permissions
Permissions below are required to install Protegrity service using ARM template.
All permissions in the table must be granted with the Resource group scope.
Permissions | Description | Built-In Azure Role |
|---|---|---|
| Read access to monitoring data and settings | Monitoring Reader |
| Write and manage access to monitoring data and settings | Monitoring Contributor |
| Write and manage access to web apps | Website Contributor |
| Manage and assign managed identities NoteThese permissions are only required when user assigned identity is used. | Managed Identity Operator |
| Manage and validate deployments | Deployment Contributor |
Log Forwarder service ARM deployment requires additional permissions below:
Permissions | Description | Built-In Azure Role |
|---|---|---|
| Allow for the creation, update, and deletion of Event Hub namespaces, event hubs within those namespaces, and their network rule sets, enabling full management of Event Hub resources. Note: These permissions are only required when deploying new event Hub. | Event Hubs Contributor |
| Read monitoring data and metrics, including Event Hub namespace data. | Monitoring Reader |
The additional permissions listed below are required when API management is part of the deployment.
Permissions | Description | Built-In Azure Role |
|---|---|---|
| Create or update API Management service instances, APIs, diagnostics, API operations, operation policies, backends, loggers, tenant policies, and API diagnostics. | API Management Service Contributor |
| Read metadata for API Management service instances and get the status of long-running operations. | API Management Service Reader |
5 - Associating ESA Data Store With Cloud Protect Agent
Associating ESA Data Store With Cloud Protect Agent
ESA controls which policy is deployed to protector using concept of data store. A data store may contain a list of IP addresses identifying servers allowed to pull the policy associated with that specific data store. Data store may also be defined as default data store, which allows any server to pull the policy, provided it does not belong to any other data stores. Node registration occurs when the policy server (in this case the policy agent) makes a policy request to ESA, where the agent’s IP address is identified by ESA.
Note
For more information about ESA data store refer to Policy Management Section which is part of Protegrity ESA documentation.Policy agent function source IP address used for node registration on ESA depends on ESA hubcontroller configuration ASSIGN_DATASTORE_USING_NODE_IP and the PTY_ADDIPADDRESSHEADER configuration exposed by the agent function.
The function service uses multiple network interfaces, internal network interface with ephemeral IP range of 169.254.x.x and external network interface with IP range described in Function app outbound IP addresses section under function configuration. By default, when agent function is contacting ESA to register node for policy download, ESA uses agent function outbound IP address. This default behavior is caused by the default ESA hubcontroller configuration ASSIGN_DATASTORE_USING_NODE_IP=false and agent default configuration PTY_ADDIPADDRESSHEADER=yes.
In some cases, when there is a proxy server between the ESA and agent function, the desirable ESA configuration is ASSIGN_DATASTORE_USING_NODE_IP=true. and PTY_ADDIPADDRESSHEADER=no which will cause the ESA to use proxy server IP address.
The table below shows how the hubcontroller and agent settings will affect node IP registration on ESA.
| Agent source IP | Agent Function Outbound IP | Proxy IP | ESA config - ASSIGN_DATASTORE_USING_NODE_IP | Agent function config - PTY_ADDIPADDRESSHEADER | Agent node registration IP |
|---|---|---|---|---|---|
| 169.254.144.81 | 20.75.43.207 | No Proxy | true | yes | 169.254.144.81 |
| true | no | 20.75.43.207 | |||
| false | yes | 20.75.43.207 | |||
| false | no | 20.75.43.207 | |||
| 169.254.144.81 | 20.75.43.207 | 34.230.42.110 | true | yes | 169.254.144.81 |
| true | no | 34.230.42.110 | |||
| false | yes | 34.230.42.110 | |||
| false | no | 34.230.42.110 |