1 - Prerequisites

Requirements before installing the protector.

    Google Cloud Services

    The following table describes the Google Cloud services that may a part of your Protegrity installation.

    ServiceDescription
    Cloud Run FunctionsProvides serverless compute for Protegrity protection operations and the ESA integration to fetch policy updates.
    API GatewayProvides the end-point and access control (Required for Snowflake only).
    Key Management ServiceProvides cryptographic keys for envelope encryption/decryption of the policy.
    Secret Manager ServiceStores secrets required during deployment, e.g., ESA credentials.
    Cloud Storage ServiceStorage location for the encrypted ESA policy package.
    Identity and Access ManagementEnforces access policies for deployed resources.
    Cloud Logging ServiceApplication and audit logs, performance monitoring, and alerts.
    Cloud VPCRequired for securing network access to On-Prem or cloud-based ESA.
    Pub/SubProvides a messaging service when forwarding audit logs to ESA is enabled.

    ESA Version Requirements

    The Protector and Log Forwarder functions require a security policy from a compatible ESA version.

    The table below shows compatibility between different Protector and ESA versions.

    Protector VersionESA Version
    8.x9.09.1 & 9.210.0
    2.xNoYes*No
    3.0.x & 3.1.xNoNoYesNo
    3.2.xNoNoYes*
    4.0.xNoNoNoYes

    Legend

    Yes

    Protector was designed to work with this ESA version

    No

    Protector will not work with this ESA version

    *

    Backward compatible policy download supported:

    • Data elements and features which are common between this and previous ESA versions will be downloaded
    • Data elements and features which are new to this ESA version and do not exist in previous ESA version will not be downloaded

    Prerequisites

    The following requirements must be completed for the Snowflake implementation.

    RequirementsDescription
    Protegrity distribution and installation scriptsThese artifacts are provided by Protegrity
    Protegrity ESA 10.0+The Cloud VPC must be able to obtain network access to the ESA
    Google Cloud AccountRecommend creating a new project for Protegrity Serverless
    Snowflake cluster (Enterprise Edition recommended)
    Terraform CLI v0.14 or higherTerraform is used to deploy resources to Google Cloud Account

    Required Skills and Abilities

    RequirementsDescription
    Google Cloud Account AdministratorRun Terraform (or perform steps manually), create/configure a VPC and IAM permissions.
    Protegrity AdministratorThe ESA credentials required to extract the policy for the Policy Agent
    Snowflake AdministratorAccount Admin access required to setup access
    Network AdministratorOpen firewall to access ESA and evaluate Google Cloud network setup

    2 - Pre-Configuration

    Configuration steps prior product installation.

      Google Cloud Project

      Identify or create a new Google Cloud Project where the Protegrity solution will be installed. It is recommended to create a new project. This provides greater security controls and avoids conflicts with other applications that might impact regional account limits. An individual with the Owner role will be required for some of the subsequent installations.

      Google Project ID: ___________________

      Google Project Number: ___________________

      Google Cloud Region: ___________________

      Region

      Query the Google Cloud region where the Snowflake cluster is running. This is the region in which Protegrity Serverless must be installed.

      To determine the Google Cloud region:

      1. Login to Snowflake

      2. In the SQL console, run the following query.

        select current_region();
        
      3. Record the Google Cloud region. For example, GCP_US_CERNTAL1.

        Snowflake Google Cloud Region: ___________________

      Key Management Service

      The Google Cloud Key Management Service (KMS) provides Protegrity Serverless solution the ability to encrypt and decrypt the Protegrity Security Policy.

      To create KMS Key Ring and Asymmetric Encryption Master Key:

      1. Log in to Google Account and select project where Protegrity service will be installed.

      2. Navigate to Security > Key Management.

      3. Select Create key ring.

      4. Specify key ring name. For example, protegrity-policy-keyring.

      5. select Key ring location which corresponds to the region where Protegrity solution will be installed.

      6. Select Create.

      7. Select CREATE KEY to create encryption key.

      8. Specify key name. For example, protegrity-policy-key.

      9. under Purpose selection, select Asymmetric Decrypt .

      10. Select Key Algorithm. For example, 3072-bit RSA with OAEP Padding and SHA256 digest.

      11. Select Create.

      12. Once the key is created, a screen opens on the key. If the screen does not appear, click on the key name.

      13. Then click on the elipses under Actions that is next to the key version.

      14. Select Copy Resource Name and record the value below, e.g., projects/{project-id}/locations/region/keyRings/{key-ring}/cryptoKeys/{key-name}/cryptoKeyVersions/1

        Policy Encryption Key Version Resource Name: ___________________

      Google Cloud Storage

      Cloud Storage buckets are required for the Gen 2 Cloud Function sources, the Terraform backend, and the deployment of the Protegrity installation artifacts. It is recommended that you create 3 separate buckets to separate files used for different purposes. If you cannot create 3 separate buckets, you may reuse a bucket for multiple purposes.

      Create the buckets:

      1. Run the cloud command below to enable the Google Storage Transfer API.

        gcloud services enable storagetransfer.googleapis.com
        
      2. Create the Gen 2 Cloud Function sources bucket. This bucket is not required if you will be deploying to Gen 1 Cloud Functions. The bucket name much match the example below. Replace the <gcp-project-number> and <region> placeholders.

        gcf-v2-sources-<gcp-project-number>-<region>
        

        Use the following gcloud command to obtain project number

        gcloud projects describe <gcp-project-id> --format='value(projectNumber)'
        
      3. Create the deployment bucket or reuse an existing bucket. This bucket is used during the installation process to store the Protegrity installation artifacts.

        Deployment Bucket Name:___________________

      4. Create the Terraform backend bucket or reuse an existing bucket. This bucket is used by Terraform to store information about your Cloud Protect installation, and will be used if you upgrade to a later version of Cloud Protect in the future.

        Terraform Backend Bucket Name:___________________

      Cloud Functions Service Accounts

      Cloud Functions use the service accounts created in this deployment. You can create Service accounts manually or use the Protegrity Terraform installation script to create one. Each service account requires specific permissions, which must be granted through IAM roles. Run the following steps to create service accounts and configure the required IAM access. If you use Terraform scripts, skip these steps.

      Agent Function IAM Role

      To create Agent Function IAM Role:

      1. Log in to Google Account and select project where Protegrity service will be installed.

      2. Navigate to IAM & Admin > Roles, Select CREATE ROLE.

      3. Specify role name and description.

      4. Select ADD PERMISSIONS.

      5. Select the following permissions:

        • cloudkms.cryptoKeyVersions.useToEncrypt
        • cloudkms.cryptoKeyVersions.viewPublicKey
        • secretmanager.versions.access
        • storage.objects.get
        • storage.objects.create
        • storage.objects.delete
        • storage.objects.list
        • storage.objects.update
        • storage.buckets.get
        • cloudfunctions.functions.get
        • cloudfunctions.functions.update
        • cloudfunctions.functions.sourceCodeGet
        • cloudfunctions.functions.sourceCodeSet
        • iam.serviceAccounts.actAs
      6. Click Add and then Create.

      Alternatively, you can run the following command from the Cloud Shell Terminal.

            gcloud iam roles create role-id \
            --project=project-id \
            --title=role-title \
            --description=role-description \
            --permissions=cloudkms.cryptoKeyVersions.useToEncrypt,\
            cloudkms.cryptoKeyVersions.viewPublicKey,\
            secretmanager.versions.access,\
            storage.objects.get,\
            storage.objects.create,\
            storage.objects.delete,\
            storage.objects.list,\
            storage.objects.update,\
            storage.buckets.get,\
            cloudfunctions.functions.get,\
            cloudfunctions.functions.update,\
            cloudfunctions.functions.sourceCodeGet,\
            cloudfunctions.functions.sourceCodeSet,\
            iam.serviceAccounts.actAs \
            --stage=GA 
            
      
      • role-id

        is the name of the role, such as ptyProtectRole.

      • project-id

        is the name of the project, such as my-project-id.

      • role-description

        is a short description of the role, such as “My custom role description”.

      Sample output:

      
            Created role [role-id]. 
            description: role-description 
            etag: *****************
            includedPermissions: 
            - cloudfunctions.functions.get 
            - cloudfunctions.functions.sourceCodeGet 
            - cloudfunctions.functions.sourceCodeSet 
            - cloudfunctions.functions.update 
            - cloudkms.cryptoKeyVersions.useToEncrypt 
            - cloudkms.cryptoKeyVersions.viewPublicKey 
            - iam.serviceAccounts.actAs 
            - secretmanager.versions.access 
            - storage.buckets.get 
            - storage.objects.create 
            - storage.objects.delete 
            - storage.objects.get 
            - storage.objects.list 
            - storage.objects.update 
            name: projects/{project-id}/roles/{role-id} 
            stage: GA 
            title: role-title
            
      

      Agent Service Account

      To create Agent Service Account:

      1. Log in to Google Account and select project where Protegrity service will be installed.

      2. Navigate to IAM & Admin > Service Accounts.

      3. Select CREATE SERVICE ACCOUNT.

      4. Specify service account name and description.

      5. Select Create and Continue.

      6. In the next step, click Select Role.

      7. Select Custom and select the role created above .

      8. Click Done.

      9. Once the service account is created, the screen should open on the service account. If the screen does not appear, refresh the page with the service account list and select the service account created.

      10. Record the full email. For example, service-account-name@project-id.iam.gserviceaccount.com

        Agent Function Service Account Email: ___________________

      Protect Function IAM role

      To create Protect Function IAM role:

      1. Log in to Google Account and select project where Protegrity service will be installed.

      2. Navigate to IAM & Admin > Roles, Select CREATE ROLE.

      3. Specify role name and description.

      4. Select ADD PERMISSIONS.

      5. Select the cloudkms.cryptoKeyVersions.useToDecrypt permission.

      6. Click Add and then Create.

      Protect Service Account

      To create Protect Service Account:

      1. Log in to Google Account and select the project where Protegrity service will be installed.

      2. Navigate to IAM & Admin > Service Accounts.

      3. Select CREATE SERVICE ACCOUNT.

      4. Specify service account name and description.

      5. Select Create and Continue.

      6. In the next step, click Select Role. Then select Custom and select the role created above .

      7. Click Done.

      8. Once the service account is created, the screen should open on the service account. If the screen does not appear, refresh the page with the service account list and select the service account created.

      9. Record the full email. For example, service-account-name@project-id.iam.gserviceaccount.com.

        Protect Function Service Account Email: ___________________

      3 - Protect Service Installation

      Product Installation Guide.

        Preparation

        1. Ensure that all the steps in Pre-Configuration are performed.

        2. Log in to the Google Cloud account where Protegrity will be installed.

        3. Select the project.

        4. Ensure that you have access to shell command on your computer or Cloud Shell with Terraform CLI v0.14 or higher installed.

        5. Ensure that the Terraform scripts provided by Protegrity are available on your local computer.

        Install Protect Function via Terraform Scripts

        Resources created with Terraform scripts include Protect Cloud Functions Service and other required resources depending on Terraform parameters. If you don’t specify the deployment bucket Terraform parameter, a new storage bucket will also be created. You can optionally choose to create a new service account with custom IAM role.

        To install using Terraform:

        1. From the command shell move to directory where you downloaded Protegrity installation bundle.

        2. Unzip the main bundle. Then unzip protegrity-cloud-protect-gcp-{version}.zip. Verify that the following files are available:

          • pty-protect-gcp/
          • main.tf
          • outputs.tf
          • protegrity-cloud-protect-gcp-{version}.zip
          • README.md
        3. Unzip the protegrity-cloud-protect-gcp-{version}.zip file. Verify that the following files are available:

          • pty-protect-gcp/
          • main.tf
          • outputs.tf
          • protegrity-cloud-protect-gcp-{version}.zip
          • README.md
        4. Open the main.tf file and update Terraform backend information at the top of the file:

          terraform {
            backend "gcs" {
              bucket  = ""
              prefix  = "protegrity/terraform/pty-protect-gcp/state"
            }
          }
          
        5. In the same main.tf file, specify the following Terraform variables: All the values were recorded in Google Cloud Project.

        Parameter

        Description

        project_id

        The project id recorded in the pre-configuration step

        region

        The Region recorded in the pre-configuration step.

        deployment_id

        Specify short name to identify deployment. This id will be added to all resources deployed with Terraform.

        deployment_bucket

        Use Deployment Bucket Name recorded in pre-configuration or leave empty to create new bucket.

        create_service_account

        Leave this as false if you created service account in pre-configuration. Otherwise set to true.

        protect_function_service_account_email

        Use Protect Function Service account recorded in pre-configuration or leave empty.

        api_gateway_gcp_service_account_issuer

        Allows setting issuer of JSON Web Token credential used to authenticate calls to API Gateway. Set this to API_GCP_SERVICE_ACCOUNT obtained in section Describe the API Integration Object

        username_regex

        If username_regex is set, the effective policy user will be extracted from the user in the request.

        max_instance_count

        GCP Cloud Functions advanced configuration

        available_memory_mb

        GCP Cloud Functions advanced configuration

        timeout_seconds

        GCP Cloud Functions advanced configuration

        gen2_available_cpu

        2nd Gen Cloud Function advanced configuration

        gen2_container_concurrency

        2nd Gen Cloud Function advanced configuration

        upgrade_step

        Set this variable when upgrading to the latest version.

        labels

        You can set this map to include labels for deployed resources. Pay attention to GCP label requirements. For more information, refer to the following link https://cloud.google.com/compute/docs/labeling-resources. For example, only use lowercase and maximum length of 63 characters.

        min_log_level

        Minimum log level for log forwarder function. One of off|severe|warning|info|config|all. Defaults to ‘severe’

        pty_log_output

        Audit log output. Accepted values: “”(empty string), “pub_sub”.

        pty_pub_sub_topic

        Pub/Sub topic where audit logs will be sent.

        1. Run the following command.

          terraform init
          
        2. Terraform will download necessary providers.

        3. Run the following command to verify configuration and print out deployment plan.

          terraform plan
          
        4. Run the following command to deploy resources to your account.

          terraform apply
          
        5. Once deployment is complete Terraform will print output variables.

        6. Record the following values:

          • protect_function_name: ________________________________
          • protect_function_url: __________________________
          • api_gateway_managed_service: _____________________________
          • api_gateway_protect_service_url: ____________________
          • protect_function_resource_name: _______________________

        Test Protect Function Installation

        Before continuing with next steps, you can verify whether Cloud Functions are installed correctly. This step is optional and can be skipped.

        1. Below you can find example CURL command to test your function.

        2. Before you can execute it, you need to obtain temporary authentication token. Run the gcloud auth login and then gcloud auth print-identity-token commands. The logged in gcloud user must have the roles/run.invoker role. Record the output of print identity token command.

          gcloud_auth_token: _________________

        3. Replace {protect_function_url}; with value recorded in previous step.

        4. Replace {gcloud_auth_token} with value recorded in above step.

        5. Run the following CURL command to test Function deployment.

          curl -X POST "{protect_function_url}" \
                  -H 'Authorization:Bearer {gcloud_auth_token}' \
          -H 'sf-custom-X-Protegrity-HCoP-Rules: {"jsonpaths":[{"op_type":"unprotect","data_element":"alpha"}]}' \
          -H 'sf-context-current-user: test' \
          -H 'sf-external-function-current-query-id: test-id' \
          -H 'Content-Type: application/json' \
          -d '{ 
            "data": [ 
              ["0", "UtfVk UHgcD!"] 
            ] 
          } 
          ' 
          
        6. Verify the following output:

          {"data":[[0,"hello world!"]]}
          

        4 - Snowflake Configuration

        Configure Snowflake to access the API Gateway.

          The following sections will configure Snowflake to access the API Gateway. The Terraform installation deployed a sample policy that can be used to smoke test the installation.

          Login to Snowflake as ACCOUNTADMIN

          Ensure that the current user can assume the Account Administrator role. This role is required to create the Snowflake API Integration object.

          Create the Snowflake API Integration Object

          1. From the Snowflake console worksheet, select the role ACCOUNTADMIN.

          2. Paste the following text and replace the two parameters <api_gateway_managed_service> and <api_gateway_protect_service_url> with values recorded in the last installation step of Install Protect Function via Terraform Scripts, then run the following Data Definition Language (DDL) in the console to create API integration object:

            create or replace api integration protegrity_api 
            api_provider = google_api_gateway
            google_audience = '<api_gateway_managed_service>' 
            enabled = true
            api_allowed_prefixes = ('<api_gateway_protect_service_url>/pty/snowflake');
            

          Describe the API Integration Object

          We require values generated by the Snowflake integration object to configure the API Gateway Authorization.

          To describe API integration objects:

          1. Run the following query in the console.

            DESCRIBE API INTEGRATION protegrity_api;
            
          2. Record the API_GCP_SERVICE_ACCOUNT value from the resulting query:

            • API GCP Service Account: ___________________

          Update API Gateway Authorization Configuration

          This step allows the Snowflake service account to invoke Protect API Gateway endpoint.

          Update Protect API Gateway Endpoint:

          1. Return to Terraform script used to install Protegrity Protect service.

          2. Open main.tf and update api_client_service_account_email with the API GCP Service Account recorded in previous step.

          3. Run terraform apply.

          4. Wait till the process is completed.

          Test Connectivity

          Perform the following steps to verify whether Snowflake is working correctly with the Protegrity product.

          1. Access the Snowflake SQL console.

          2. Copy and paste the following snippet into a worksheet.

            CREATE OR REPLACE SECURE EXTERNAL FUNCTION PTY_UNPROTECT_SAMPLE_POLICY(VAL VARCHAR)
                RETURNS VARCHAR(16777216)
                IMMUTABLE
                API_INTEGRATION = PROTEGRITY_API
                HEADERS =(  
                'X-Protegrity-HCoP-Rules'=
                '{"jsonpaths":[{"op_type":"UNPROTECT","data_element":"alpha"}]}'
                ) 
                CONTEXT_HEADERS = (CURRENT_USER,CURRENT_TIMESTAMP,CURRENT_ACCOUNT)
                COMMENT='Unprotects text using an alpha token type.'
                AS '<api_gateway_protect_service_url>/pty/snowflake';
            
          3. Replace the placeholder value indicated substituting your API Gateway URL captured in the Terraform outputs (api_gateway_protect_service_url).

          4. Run the following protect in the console:

            select pty_unprotect_sample_policy('UtfVk UHgcD!');
            
          5. Verify that the string hello world! is returned.

          Troubleshooting

          Use Cloud Logging to troubleshoot errors.

          From your Google Console, navigate to Logging > Logs Explorer

          Use the Log Fields panel to filter results by resource type, name, severity, and other criteria. For instance to see the last Cloud Protect Function logs, make the following selections:

          RESOURCE TYPE = Cloud Function 
              FUNCTION NAME = pty-protect-{deployment-id}
          

          You can also use the Log Filter Query and run the following query:

          resource.type="cloud_function" 
              resource.labels.function_name="pty-protect-"
          

          You can change the time range in the top right corner. If Protegrity policy is configured to generate audit logs, you can use the following query to only view the audit logs:

          resource.type="cloud_function" 
            resource.labels.function_name="pty-protect-" 
            jsonPayload.message=~"\"type\":\"audit\""
          

          5 - Policy Agent Installation

          Install the policy agent.

            Policy Agent Function installation is done via Terraform scripts provided by Protegrity. Before running the template, some resources must be created manually.

            ESA Server

            Policy Agent function requires ESA server running and accessible from Agent Cloud Function on TCP port 8443. Make sure inbound connections on TCP:8443 are allowed for the network where ESA is hosted.

            Note down ESA IP address:

            ESA IP Address (EsaIpAddress): ___________________

            Certificates on ESA

            By default, ESA is configured with self-signed certificates, which can only be validated using self-signed CA certificate supplied in Cloud Function Environment variables configuration.

            In case ESA is configured with publicly signed certificates, this section can be skipped since the Cloud Function will use public CA to validate ESA certificates.

            To obtain self-signed CA certificate from ESA:

            1. Log in to ESA Web UI.

            2. Select Settings > Network > Manage Certificates.

            3. Hover over Server Certificate and click on download icon to download the CA certificate.

            4. After certificate is downloaded, open the PEM file in text editor and replace all new lines with escaped new line: \n.

              To escape new lines from command line, use one of the following commands depending on your operating system:

              Linux Bash:

              awk 'NF {printf "%s\\n",$0;}' ProtegrityCA.pem > output.txt
              

              Windows PowerShell:

              (Get-Content '.\ProtegrityCA.pem') -join '\n' | Set-Content 'output.txt'
              
            5. Record the certificate content with new lines escaped.

              ESA CA Server Certificate (EsaCaCert): ___________________

              This value will be used to set pty_esa_ca_server_cert Terraform variable in installation section.

            For more information about ESA certificate management refer to Certificate Management Guide in ESA documentation.

            Identify or Create a new VPC

            Google Cloud VPC is used to route traffic from Policy Agent Cloud Function to ESA. If your ESA is in a Google Cloud VPC, it is recommended to create a serverless VPC access and record its name:

            google_vpc_access_connector_name: ___________________

            If ESA is not on Google Cloud VPC, you can either create one or choose to let Terraform script to create one. The Terraform script will create the following elements:

            • NAT gateway

              To connect to ESA outside the Google Cloud Network

            • External IP address

              Can add it to the allowlist by the firewall in the network environment where ESA is hosted.

            • Serverless VPC access

              Allows connectivity from the Cloud function to the VPC.

            Creating ESA Credentials

            Policy Agent Function requires ESA credentials to be provided as one of the two options:

            Secret Manager

            Secret Manager is the recommended option for storing ESA credentials.

            Create ESA credentials secrets:

            1. Log in to Google Account and select project where Protegrity service will be installed.

            2. Go to Security > Secret Manager.

            3. Select CREATE SECRET.

            4. Specify the Secret Value:

              {
                "username": "{esa_username}", 
                "password": "{esa_password}"
              }
              
            5. Select Create Secret.

            6. Once the secret is created, you should see the secret screen opened. If not click on the secret name to see a screen with secret versions.

            7. Click on Actions, next to the secret version you just created.

            8. Select Copy Resource ID and record the full secret version path, For example, projects/{project-id}/secrets/{secret name}/versions/2.

              Secret resource id: ___________________

            Custom Cloud Function

            If you have the skills to write code, you may provide a custom Cloud Function that returns the ESA credentials to the Policy Agent. One use case is when reading the ESA credentials from a third-party password vault.

            Create the Cloud Function:

            1. Create a new 2nd gen Cloud Function using any runtime.

              1. The Policy Agent does not provide an input payload.

              2. The Cloud Function must return a response according to the following schema:

                response: 
                  type: object 
                    properties: 
                      username: string 
                      password: string
                

                For example,

                example output: {"username": "admin", "password": "Password1234"} 
                
              3. Sample GCP Function in Python:

                def handler(request): 
                    return {"username": "admin", "password": "password1234"} 
                
            2. Grant the Cloud Run Invoker role to the Policy Agent function service account.

            3. Grant the cloudfunctions.functions.get permission to the Policy Agent function service account role.

            4. Record the Function name:

              ESA CREDENTIALS FUNCTION NAME: _______________

            Install Policy Agent Function through Terraform Scripts

            Agent Terraform scripts provided by Protegrity create a Cloud Function in your Google account. If you don’t specify the deployment bucket Terraform parameter, a new storage bucket will also be created. You can also create the following optional resources by specifying the corresponding parameters:

            • Service account with IAM role
            • VPC with NAT external IP
            • VPC access connector

            To install Policy Agent Function through Terraform:

            1. From command shell, move to the directory where you downloaded Protegrity installation bundle.

            2. Unzip the bundle, then unzip the protegrity-agent-gcp-{version}.zip. Verify that the following files are available:

              • pty-agent-gcp/
              • main.tf
              • outputs.tf
              • README.md
            3. Open the main.tf file and update Terraform backend information at the top of the file:

              
              terraform {
                backend "gcs" {
                  bucket  = ""
                  prefix  = "protegrity/terraform/pty-protect-gcp/state"
                }
              }
              
            4. Set the bucket property to Terraform Backend Bucket Name recorded in Google Cloud Storage

            5. Set the prefix property with value unique to your deployment.

            6. In the same main.tf file, specify the following Terraform variables.

              ParameterDescription
              project_idThe Project ID recorded in the pre-configuration step
              regionThe Region recorded in the pre-configuration step, for example, us-central1.
              deployment_idSpecify short name to identify deployment. This id will be added to all resources deployed with Terraform.
              deployment_bucketUse Deployment Bucket Name recorded in pre-configuration or leave empty to create new bucket.
              deployment_bucket_locationGeographical location of deployment bucket, e.g., US, EU, ASIA.
              deployment_file_directory_pathPath to directory where deployment zip file is located. By default the deployment file should be in the same directory as this main.tf file.
              policy_download_cron_expressionCron expression determining how often policy agent function will run to synchronize security policy from ESA.
              create_service_accountLeave this as false if you created service account in pre-configuration. Otherwise set to true.
              agent_function_service_account_emailUse Agent Function Service account recorded in pre-configuration or leave empty.
              create_vpcSet this to true, if you would like to create VPC with NAT, external IP and vpc access connector, otherwise leave empty. This will be ignored if google_vpc_access_connector_name is specified.
              google_vpc_access_connector_nameSpecify the existing VPC access connector name you identified in earlier step, otherwise leave empty. This setting will disable create_vpc = true.
              google_vpc_access_connector_full_resource_nameAlternative configuration for VPC access connector. If this parameter is set the google_vpc_access_connector_name will be ignored. Use this parameter, if vpc connector is in different region/project that the one specified for the deployment.
              labelsYou can set this map to include labels for deployed resources. Pay attention to gcp label requirements. More information in: https://cloud.google.com/compute/docs/labeling-resources. For example, only use lowercase and maximum length of 63 characters.

              All the values were recorded in Pre-Configuration and this section’s previous steps.

            7. Provide Policy update Terraform variables. In the same main.tf file, you can specify configuration related to policy update. Any of these variables can be updated at any given time by running the terraform again or directly in the GCP Console. Most of the values were recorded in previous installation steps.

              Parameter

              Description

              Notes

              pty_esa_ip

              ESA IP address or hostname

              ESA Server

              pty_esa_ca_server_cert

              ESA self-signed CA certificate used by policy Agent Function to ensure ESA is the trusted server.

              Recorded in step Certificates on ESA

              In case ESA is configured with publicly signed certificates, the pty_esa_ca_server_cert configuration will be ignored.

              gcp_esa_credentials_secret_resource_id

              ESA username and password (encrypted value by Google Cloud Secrets Manager). For example, projects/{project-id}/secrets/{secret name}/versions/{version}

              Creating ESA Credentials

              pty_esa_credentials_function

              ESA credentials GCP function resource name. For example, projects/{project-name}/locations/{region}/functions/{esa-credentials-function-name}.

              Recorded in step Option 2: Custom Cloud Function ESA CREDENTIALS FUNCTION NAME. Presence of gcp_esa_credentials_secret_resource_id will cause this value to be ignored. The Policy Agent Function must have network access and IAM permissions to call the ESA Credentials function you have created in Option 2: Custom Cloud Function.

              gcp_kms_key_resource_name

              The Key full resource name. For Example, projects/{project-id}/locations/region/keyRings/ {key-ring}/cryptoKeys/{key-name}/cryptoKeyVersions/1

              Key Management Service

              gcp_protect_function_resource_name

              List of comma separated Protect function resource names. For Example, projects/{project-id}/ locations/{region}/functions/{function-name1},projects/{project-id}/ locations/{region}/functions/{function-name2}

              Use protect_function_resource_name recorded in Protect Service Installation section.

              gcp_policy_retention_storage_bucket

              Deployment Bucket Name where the encrypted policy will be written.

              You can use deployment bucket recorded in Google Cloud Storage section, or you can specify other existing bucket.

              gcp_policy_version_object_key

              Filename of the encrypted policy stored in the Deployment Bucket Name

              Default: policy.zip

              retain_policy_versions

              Number of policy versions to retain as backup. (e.g. 2 will retain the latest 2 policies and remove older ones). -1 retains all.

              Default: 10

              disable_deploy

              This flag can be either 1 or 0. If set to 1, then the agent will not update protector function with the newest policy. Else, the policy will be saved in the cloud storage bucket and deployed to the protector function.

              Default: 0

              log_level

              Application and audit logs verbiage level

              Default: INFO. Allowed values: DEBUG – the most verbose INFO, WARNING, ERROR – the least verbose

              policy_pull_timeout

              Time in seconds to wait for the ESA to send the full policy

              Default: 20

              pty_core_casesensitive

              Specifies whether policy usernames should be case sensitive

              Default: no. Allowed values: yes, no

              pty_core_emptystring

              Override default behavior. Empty string response values are returned as null values. For instance, (un)protect(’’) -> null (un)protect(’’) -> ''

              Default: empty. Allowed values: null, empty

              esa_connection_timeout

              Time in seconds to wait for the ESA response

              Default: 5s

              pty_addipaddressheader

              When enabled, agent will send its source IP address in the request header. This configuration works in conjunction with ESA hubcontroller configuration ASSIGN_DATASTORE_USING_NODE_IP (default=false). See Associating ESA Data Store With Cloud Protect Agent for more information.

              Default: yes. Allowed values: yes, no

              pty_datastore_key

              ESA policy datastore public key fingerprint (64 char long) e.g. 123bff642f621123d845f006c6bfff27737b21299e8a2ef6380aa642e76e89e5.

              The export key is the public part of an asymmetric key pair created in a Create KMS Key. A user with Security Officer permissions adds the public key to the data store in ESA via Policy Management > Data Stores > Export Keys. The fingerprint can then be copied using the Copy Fingerprint icon next to the key. Refer to Exporting Keys to Datastore for details.

              pty_sync_datastore

              Optional name of the policy datastore to sync with ESA. Refer to ESA documentation for more information on policy datastore sync.

              Default: ""
            8. From local command line or Cloud Shell, change directory to location of the main.tf, for example:

              protegrity-agent-gcp-{version}/pty-agent-gcp/
              
            9. Run terraform init.

              Terraform will download necessary providers.

            10. Run terraform plan to verify configuration and print out deployment plan.

            11. Run terraform apply to deploy resources to your account. Once deployment is complete, Terraform will print output variables.

            12. Below is the sample output from successful deployment.

              
                      Apply complete! Resources: 1 added, 0 changed, 0 destroyed. 
                      Outputs: 
                      agent_function_service_account_email = "pty-agent-test@test.iam.gserviceaccount.com" 
                      deployment_bucket_name = "test-bucket" 
                      nat_ip = 0 
                      policy_agent_function_deployment_object = "pty-agent-test-1.0.1.zip" 
                      policy_agent_function_name = "pty-agent-test" 
              

            Test Agent Function Installation

            After configuration is complete, you can test the function.

            To test and run the Policy Agent Function:

            1. From the Google Cloud console, go to Cloud Run Functions or Cloud Run.

            2. Click on the function you just deployed: pty_agent_{deployment_id}.

            3. Click Test button at the top right section of the screen.

            4. Scroll down to CLI test command.

            5. Copy and run the curl command to trigger the agent. Alternatively, use the option Test in Cloud Shell.

            6. Wait for the function to complete.

            7. Navigate to the LOGS tab to view agent execution logs.

            8. Alternatively, you may review the logs by navigating to Logging from your Google Console. In the Log Explorer select the All resources dropdown, then Cloud Run Revision > pty-agent-{deployment-id} and apply.

              
              Function execution took 23892 ms, finished with status: 'ok'
              iap.policy_deployer:INFO:Deleting object [policy_v07-26-2021_21-00-00.zip]
              iap.policy_deployer:INFO:Deleting object [policy_v07-26-2021_19-03-23.zip]
              iap.policy_deployer:INFO:Removing old function versions in [test-artifacts]. Will retain [1] versions.
              iap.policy_deployer:INFO:Updating function [projects/cloud-engineering-315519/locations/us-central1/functions/pty-protect-test] with new deployment artifact [test-artifacts/policy_v07-26-2021_21-00-01.zip] ...
              iap.imp_creator:INFO:Uploading encrypted policy data to: [test-artifacts/policy_v07-26-2021_19-03-23.zip]
              iap.imp_creator:INFO:Preparing deployment package ...
              iap_agent_gcp.cloud_functions_util:INFO:Downloading function deployment package ...
              iap.imp_creator:INFO:Encrypting policy package ...
              iap.policy_agent:INFO:Preparing new policy deployment ...
              iap.policy_agent:WARNING:Current policy deployment has no checksum_mapping metadata:
              iap.imp_creator:INFO:Checking current policy version ...
              iap.policy_agent:INFO:Current deployment package version: [policy_v07-26-2021_18-51-43.zip].
              iap.policy_agent:INFO:Getting current policy metadata ...
              iap.imp_creator:INFO:Policy downloaded successfully ...
              iap.imp_creator:INFO:PepServer started ...
              iap.imp_creator:INFO:Starting PepServer ...
              iap.imp_creator:INFO:PepServer configured successfully
              iap.imp_creator:INFO:Downloading certificates from ESA ...
              iap.imp_creator:INFO:Configuring PepServer ...
              iap.policy_agent:INFO:Starting policy agent ...
              iap.policy_agent:INFO:Using Secret Manager [GCP_ESA_CREDENTIALS_SECRET_RESOURCE_ID] to retreive ESA credentials.
              iap.policy_agent:INFO:PTY_CORE_CASESENSITIVE [no]
              iap.policy_agent:INFO:PTY_CORE_EMPTYSTRING [empty]
              iap.policy_agent:INFO:RETAIN_POLICY_VERSIONS [1]
              iap.policy_agent:INFO:GCP_PROTECT_FUNCTION_RESOURCE_NAME [projects/test/locations/us-central1/functions/pty-protect-test]
              iap.policy_agent:INFO:GCP_POLICY_VERSION_OBJECT_KEY [policy.zip]
              iap.policy_agent:INFO:GCP_POLICY_RETENTION_STORAGE_BUCKET [test-artifacts]
              iap.policy_agent:INFO:GCP_KMS_KEY_RESOURCE_NAME [projects/test/locations/us-central1/keyRings/test-key-ring/cryptoKeys/test-protect-asymmetric/cryptoKeyVersions/1]
              iap.policy_agent:INFO:GCP_ESA_CREDENTIALS_SECRET_RESOURCE_ID [projects/1234/secrets/ESA_ADMIN_CREDENTIALS/versions/2]
              iap.policy_agent:INFO:PTY_ESA_IP [54.236.107.39]
              iap.policy_agent:INFO:POLICY_PULL_TIMEOUT [20]
              iap.policy_agent:INFO:DISABLE_DEPLOY [0]
              Function execution started
              

            Troubleshooting

            Configure additional logging:

            1. Set log_level Terraform variable on the Agent function to DEBUG.

            2. In the GCP Logs Explorer, you can run the query below, replacing placeholders with your deployment id and project name.

              resource.type="cloud_run_revision"
              resource.labels.service_name=~"pty-agent-<deploymentd-id>"
              severity=ERROR OR textPayload=~"\[error\]"
              -logName="projects/<gcp-project-id>/logs/run.googleapis.com%2Frequests"
              
            3. Expand each log entry for more details. Check for jsonPayload > exception to see more detailed error.

            Error message

            Details

            iap_agent_gcp.cloud_functions_util.CloudFunctionsApiException: Resource 'projects/<account>/locations/<region>/functions/protegrity-protect-<deployment-id>' was not found
            
            This error may indicate the following configuration issues:
            1. The function name indicated in setting gcp_protect_function_resource_name has been provided incorrectly, and thus cannot be found.
            2. disable_deploy has been set, and a dummy function has been entered to work around the gcp_protect_function_resource_name requirement. The Agent deployment requires a deployed Protect or Log Forwarder Cloud Run function to operate.
            [ERROR] policy_agent:Invalid GCP_PROTECT_FUNCTION_RESOURCE_NAME parameter value. Must be a comma separated list of Lambda Function names or ARNs.
            
            This error may indicate the following configuration issues:
            1. The setting gcp_protect_function_resource_name is empty. The Agent deployment requires a deployed Protect or Log Forwarder Cloud Run function to operate, this setting may not be left empty.
            2. The list of function names provided to gcp_protect_function_resource_name contains invalid function name or is not valid csv format.
            [ERROR] iap_agent_gcp.cloud_functions_util:<HttpError 403 when requesting https://cloudfunctions.googleapis.com/v2/projects/<account>/locations/<region>/functions/pty-protect-<deployment-id>:generateDo
            wnloadUrl?alt=json returned "Permission 'cloudfunctions.functions.sourceCodeGet' denied on 'projects/<account>/locations/<region>/functions/<deployment-id>'". Details: "Permission 'cloudfunctions.functions.sourceCodeGet' denied on 'projects/<account>/locations/<region>/functions/pty-protect-<deployment-id>'">
            [ERROR] policy_agent:Permission 'cloudfunctions.functions.sourceCodeGet' denied on 'projects/<account>/locations/<region>/functions/pty-protect-<deployment-id>'
            ...
            iap_agent_gcp.cloud_functions_util.CloudFunctionsApiException: Permission 'cloudfunctions.functions.sourceCodeGet' denied on 'projects/<account>/locations/<region>/functions/pty-protect-<deployment-id>' 
            

            Indicates the Agent Cloud Run function’s identity does not have permissions to sourceCodeGet for Protect/Log Forwarder function(s) provided to the gcp_protect_function_resource_name configuration.

            6 - Audit Log Forwarder Installation

            Install the audit log forwarder.

                Audit Log Forwarder installation is done via Terraform scripts provided by Protegrity in the installation bundle.

                ESA Audit Store Configuration

                ESA server is required as the recipient of audit logs. Verify the information below to ensure ESA is accessible and configured properly.

                1. ESA server running and accessible on TCP port 9200.

                2. Audit Store service is configured and running on ESA. For information related to ESA Audit Store configuration, refer to Audit Store Guide.

                Certificates on ESA

                By default, ESA is configured with self-signed certificates, which can only be validated using self-signed CA certificate supplied in Log Forwarder configuration.

                In case ESA is configured with publicly signed certificates, this section can be skipped since the Log Forwarder will use public CA to validate ESA certificates.

                To obtain self-signed CA certificate from ESA:

                1. Download ESA CA certificate from the /etc/ksa/certificates/plug directory of the ESA

                2. After certificate is downloaded, open the PEM file in text editor and replace all new lines with escaped new line: \n.

                  To escape new lines from command line, use one of the following commands depending on your operating system:

                  Linux Bash:

                  awk 'NF {printf "%s\\n",$0;}' CA.pem > output.txt
                  

                  Windows PowerShell:

                  (Get-Content '.\CA.pem') -join '\n' | Set-Content 'output.txt'
                  
                3. Record the certificate content with new lines escaped.

                  ESA CA Server Certificate (EsaCaCert): ___________________

                  This value will be used to set pty_esa_ca_server_cert Terraform variable in installation section. Install Log Forwarder via Terraform

                For more information about ESA certificate management refer to Certificate Management Guide in ESA documentation.

                VPC configuration

                Similar to Policy Agent Function, log forwarder function requires Google Cloud VPC to route traffic from the function to ESA. Review the VPC configuration steps for agent in section Identify or Create a new VPC. Same VPC connector as the policy agent can be used. Note down VPC connector name:

                google_vpc_access_connector_name: ___________________

                ESA Authentication

                Audit Log Forwarder must authenticate with ESA using certificate-based authentication with client certificate and certificate key. Download the following certificates from the /etc/ksa/certificates/plug directory of the ESA:

                File NameDescription
                client.keyClient certificate key
                client.pemClient certificate (PEM)

                Both certificate and certificate key must be converted to single-line values using code similar to the following examples.

                Client certificate (client.pem):

                $folder = 'C:\Temp'
                cd $folder
                (Get-Content "$folder\client.pem") -join '\n' | Set-Content "$folder\one-liner-client.pem"
                cat "$folder\one-liner-client.pem"
                
                folder="/tmp"
                cd "$folder"
                awk 'NF {printf "%s\\n",$0}' "client.pem" > "one-liner-client.pem"
                cat "one-liner-client.pem"
                

                Client certificate key (client.key):

                $folder = 'C:\Temp'
                cd $folder
                (Get-Content "$folder\client.key") -join '\n' | Set-Content "$folder\one-liner-client.key"
                cat "$folder\one-liner-client.key"
                
                folder="/tmp"
                cd "$folder"
                awk 'NF {printf "%s\\n",$0}' "client.key" > "one-liner-client.key"
                cat "one-liner-client.key"
                

                While installing using Terraform template:

                1. Provide single-line client certificate for pty_esa_client_cert
                2. Provide ID of the GCP secret containing the single-line certificate key for pty_esa_client_cert_key_secret_id Secret is created in a later step

                Configure ESA Secrets In GCP Secret Manager

                Audit Log Forwarder Function uses GCP Secret Manager to store ESA Audit Store credentials used during authentication.

                For information on how to configure basic and certificate authentication for Audit Store on ESA refer to Audit Store Guide.

                1. Log in to Google Account and select project where Protegrity service will be installed.

                2. Go to Security > Secret Manager.

                3. Select CREATE SECRET.

                4. Specify the Secret Value:

                  {
                    "username": "admin", 
                    "password": "{esa_password}"
                  }
                  
                5. Select Create Secret.

                6. Once the secret is created, you should see the secret screen opened. If not click on the secret name to see a screen with secret versions.

                7. Click on Actions, next to the secret version you just created.

                8. Select Copy Resource ID and record the full secret version path, for example, projects/{project-id}/secrets/{secret name}/versions/2.

                  ESA Log Forwarder Credentials Secret Name: _________________

                9. Create another secret with single-line contents of ESA client certificate key file

                  See Certificate Authentication for details on client certificate key

                10. Record the full secret version path, for example, projects/{project-id}/secrets/{secret name}/versions/1.

                  ESA Log Forwarder Client Certificate Key Secret Name: _________________

                Create Log Forwarder Service Account

                To create Log Forwarder Service Account:

                1. Log in to Google Account and select the project where Protegrity service will be installed.

                2. Navigate to IAM & Admin > Service Accounts.

                3. Select CREATE SERVICE ACCOUNT.

                4. Specify service account name and description.

                5. Select Create and Continue.

                6. In the next step, click Select Role. Then select the following roles:

                  • Cloud KMS CryptoKey Decrypter
                  • Pub/Sub Publisher
                  • Secret Manager Secret Accessor
                7. Click Done.

                8. Once the service account is created, the screen should open on the service account. If the screen does not appear, refresh the page with the service account list and select the service account created.

                9. Record the full email. For example, service-account-name@project-id.iam.gserviceaccount.com.

                  Log Forwarder Function Service Account Email: ___________________

                Create Service Account For Forwarder Pub/Sub

                Pub/Sub service requires Cloud Run Invoker permissions in order to be able to send messages to the Forwarder function.

                1. Log in to Google Account and select the project where Protegrity forwarder will be installed.

                2. Navigate to IAM & Admin > Service Accounts.

                3. Select CREATE SERVICE ACCOUNT.

                4. Specify service account name and description.

                5. Select Create and Continue.

                6. In the next step, click Select Role. Then select Cloud Run Invoker.

                7. Click Done.

                8. Once the service account is created, the screen should open on the service account. If the screen does not appear, refresh the page with the service account list and select the service account created.

                9. Record the full email. For example, service-account-name@project-id.iam.gserviceaccount.com.

                  Pub/Sub Log Forwarder Service Account Email: ___________________

                Preparation

                1. Ensure that all the steps in Google Cloud Project are performed.

                2. Log in to the Google Cloud account where Protegrity will be installed.

                3. Select the project.

                4. Ensure that you have access to shell command on your computer or Cloud Shell with Terraform CLI v0.14 or higher installed.

                5. Ensure that the Terraform scripts provided by Protegrity are available on your local computer.

                Install Log Forwarder Function via Terraform Scripts

                Resources created with Terraform scripts include Audit Log Forwarder Cloud Functions Service and Pub/Sub topic. If you don’t specify the deployment bucket Terraform parameter, a new storage bucket will also be created. You can optionally choose to create a new service account with custom IAM role.

                To install using Terraform:

                1. From the command shell move to directory where you downloaded Protegrity installation bundle.

                2. Unzip the bundle, then unzip the protegrity-gcp-bigquery-{version}.zip. Navigate to pty-log-forwarder-gcp/. Verify that the following files are available:

                  • pty-log-forwarder-gcp/
                  • main.tf
                  • outputs.tf
                  • protegrity-cloud-api-gcp-{version}.zip
                  • README.md
                3. Open the main.tf file and update Terraform backend information at the top of the file:

                  terraform {
                    backend "gcs" {
                      bucket  = ""
                      # The bucket/prefix combination must be unique for different deployments 
                      # to avoid conflicting Terraform states and accidental resources destruction.
                      # prefix = "protegrity-gcp-bigquery/forwarder/<deployment_id>/tf-state"
                    }
                  }
                  
                4. Set the bucket property to Terraform Backend Bucket Name recorded in Google Cloud Storage

                5. Set the prefix property with value unique to your deployment.

                6. In the same main.tf file, specify the following Terraform variables: All the values were recorded in Google Cloud Project.

                  ParameterDescription
                  project_idThe project id recorded in the pre-configuration step
                  regionThe Region recorded in the pre-configuration step.
                  deployment_idSpecify short name to identify deployment. This id will be added to all resources deployed with Terraform.
                  deployment_bucketUse Deployment Bucket Name recorded in pre-configuration or leave empty to create new bucket.
                  create_service_accountLeave this as false if you created service account in pre-configuration. Otherwise set to true.
                  forwarder_function_service_account_emailUse Forwarder Function Service account recorded in pre-configuration or leave empty.
                  pub_sub_log_forwarder_service_account_emailService account of the audit log Pub/Sub trigger. The service account must be assigned Cloud Run Invoker (roles/run.invoker) role.
                  create_vpcIf create_vpc flag is set, new vpc will be created together with vpc connector, NAT and external IP Use this flag if you have VPC admin permissions in your Google Account. If you set it to false, you can specify the existing VPC in the google_vpc_access_connector_name parameter.
                  google_vpc_access_connector_nameUse existing VPC connector to associate with Log Forwarder Function. You can specify either the VPC connector name or the full resource name if vpc connector is in different region/project that the one specified for the deployment. You can alternatively set the use google_vpc_access_connector_full_resource_name. Both parameters are optional. Full resource name takes precedence over connector name.
                  log_destination_esa_ipIp address of the ESA where Protector logs will be sent to.
                  pty_esa_ca_server_certESA self-signed CA certificate used by log forwarder function to ensure ESA is the trusted server. See documentation for more details.
                  esa_credentials_secret_resource_idGCP Secret Manager secret id where ESA Fluent Bit logger credentials are stored.
                  pty_esa_client_certSingle-line ESA client certificate content. See Certificate Authentication for details on client certificate
                  pty_esa_client_cert_key_secret_idGCP Secret Manager secret id where single-line ESA client certificate key content is stored. See Configure ESA Secrets In GCP Secret Manager for details on client certificate key secret
                  min_log_levelMinimum log level for log forwarder function. Must be one of the following: [off,severe,warning,info,config,all].
                  esa_tls_disable_cert_verifyDisable certificate verification when connecting to ESA. This is only for dev purposes, should not be used in production environment.
                  esa_connect_timeoutEsa connection timeout in seconds.
                  esa_virtual_hostESA Virtual Host.
                  audit_log_flush_intervalTime interval in seconds used to accumulate audit logs before sending to ESA. Default value: 10
                  Min value: 1
                  Max value: 900
                  dlq_topic_message_retention_durationIndicates the minimum duration to retain a message in dead letter queue topic in case log destination server is not available. Value must be decimal number, followed by the letter s (seconds). Cannot be more than 31 days or less than 10 minutes. Default value is 1 day
                  audit_log_dead_letter_topicThis parameter is expected to be used in a separate deployment to replay dead letter queue messages.
                  max_instance_countGCP Cloud Functions advanced configuration
                  available_memory_mbGCP Cloud Functions advanced configuration
                  timeout_secondsGCP Cloud Functions advanced configuration
                  gen2_available_cpu2nd Gen Cloud Function advanced configuration
                  gen2_container_concurrency2nd Gen Cloud Function advanced configuration
                  upgrade_stepSet this variable when upgrading to the latest version.
                  labelsYou can set this map to include labels for deployed resources. Pay attention to GCP label requirements. For more information, refer to the following link https://cloud.google.com/compute/docs/labeling-resources. For example, only use lowercase and maximum length of 63 characters.
                7. From local command line or Cloud Shell, change directory to location of the main.tf, for example:

                  pty-log-forwarder-gcp-{version}/pty-log-forwarder-gcp/
                  
                8. Run the following command.

                  terraform init
                  
                9. Terraform will download necessary providers.

                10. Run the following command to verify configuration and print out deployment plan.

                  terraform plan
                  
                11. Run the following command to deploy resources to your account.

                  terraform apply
                  
                12. Once deployment is complete Terraform will print output variables.

                13. Record the following values:

                  • forwarder_function_name: ____________________________
                  • forwarder_function_url: ____________________________
                  • forwarder_function_resource_name: __________________

                Turn on Instance-based billing.

                Both Protect and Log Forwarder functions must run for a short period of time after all requests are handled. In order for the GCP Cloud Run service to allow that, the Instance-based billing feature must be enabled for both function deployments.

                To enable Instance-based billing:

                1. Log in to Google Account and select the project where Protegrity Cloud Run Function was installed.

                2. Navigate to Cloud Run.

                3. Click on the Cloud Function name.

                4. In Cloud Run revision view, select Edit & deploy new revision.

                5. Scroll down to Billing.

                6. Select Instance-based.

                7. Click DEPLOY.

                8. Repeat the steps for Log Forwarder function.

                Test Log Forwarder Function Installation

                Before continuing with next steps, you can verify whether Log Forwarder Function is installed correctly. This step is optional and can be skipped.

                1. Below you can find example CURL command to test your function.

                2. Before you can execute it, test if you can obtain temporary authentication token. Run the gcloud auth login and then gcloud auth print-identity-token commands. The logged in gcloud user must have the Cloud Run Invoker permissions. Continue to the next step if the command succeeds and prints the token.

                3. Replace {forwarder_function_url}; with value recorded in previous step.

                4. Run the following CURL command to test Function deployment.

                  curl {forwarder_function_url} \
                  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
                  -H "Content-Type: application/json" \
                  -H "ce-id: 123451234512345" \
                  -H "ce-specversion: 1.0" \
                  -H "ce-time: 2020-01-02T12:34:56.789Z" \
                  -H "ce-type: google.cloud.pubsub.topic.v1.messagePublished" \
                  -H "ce-source: //pubsub.googleapis.com/projects/MY-PROJECT/topics/MY-TOPIC" \
                  -d '{
                      "message": { 
                          "data": "'"$(echo '{"additional_info":{"description":"Data unprotect operation was successful.","query_id":"sf-query-id:k6-test-df51a612-4739-4cfb-9fe4-6ec548b70d23"},"client":{},"cnt":4000,"correlationid":"sf-query-id:k6-test-df51a612-4739-4cfb-9fe4-6ec548b70d23","level":"SUCCESS","logtype":"Protection","origin":{"hostname":"localhost","time_utc":1725558586},"process":{"id":1},"protection":{"audit_code":8,"dataelement":"alpha","datastore":"SAMPLE_POLICY","mask_setting":"","operation":"Unprotect","policy_user":"master_user"},"protector":{"core_version":"1.2.2+42.g01eb3.HEAD","family":"cp","pcc_version":"3.4.0.20","vendor":"gcp.snowflake","version":"3.1.0.158"},"signature":{"checksum":"7CE5FFCE9DBE570AAA72D1BB20CD083532EF8FAD3E96E38629EB92E837272D8E","key_id":"676c5178-756d-4363-9"}}' | base64 -w 0)"'",
                          "attributes": {},  
                          "messageId": "",  
                          "publishTime": "2014-10-02T15:01:23Z",
                          "orderingKey": ""
                     }
                  }'
                  
                5. In GCP Logs Explorer console verify that the following output appears in the logs:

                  Request finished HTTP/1.1 POST http://pty-forwarder-31-smoke-jf-pfadh7riaq-uc.a.run.app/ - 200 0 - 75.6570ms
                  
                6. .

                Grant Pub/Sub Publisher Permission to the Protect Function Service Account

                Protect function requires permissions to publish audit log messages to Pub/Sub.

                1. Log in to Google Account and select the project where Protegrity service will be installed.

                2. Navigate to IAM & Admin.

                3. Search for protector function service account email recorded in protect service installation step.

                4. Select Edit principal pencil icon.

                5. Select ADD ANOTHER ROLE.

                6. Select Pub/Sub Publisher.

                7. Click Save.

                Protect Function Pub/Sub Log Output

                Protect function must be configured to output audit logs to Pub/Sub topic.

                To configure Protect function audit log output:

                1. Go to Protect function Terraform deployment.

                2. Navigate to pty-protect-gcp/main.tf.

                3. Set Terraform variable pty_log_output=“pub_sub”.

                4. Set Terraform variable pty_pub_sub_topic to log forwarder Pub/Sub topic.

                5. Run terraform apply.

                Troubleshooting

                Configure additional logging:

                1. Set min_log_level Terraform variable on both Protect function and Log Forwarder function to config.

                2. In the GCP Logs Explorer, you can run the query below, replacing placeholders with your deployment id and project name.

                  resource.type="cloud_run_revision"
                  resource.labels.service_name=~"pty-(protect|forwarder)-<deploymentd-id>"
                  severity=ERROR OR textPayload=~"\[error\]"
                  -logName="projects/<gcp-project-id>/logs/run.googleapis.com%2Frequests"
                  
                3. Expand each log entry for more details. Check for jsonPayload > exception to see more detailed error.

                Error message

                Details

                Pub/Sub configuration error.
                
                1. Indicates problems with Pub/Sub service configuration/availability.

                2. Expand error log entry and check exception details. For instance:

                  exception: "Grpc.Core.RpcException: Status(StatusCode="InvalidArgument", Detail="Invalid resource name given (name=projects/<todo>/topics/pty-forwarder-<todo>). 
                  
                3. Verify that pty_pub_sub_topic Terraform variable is set to correct pub/sub resource name.

                4. Verify that Pub/Sub topic exists.

                Failed to send x/y audit logs to GCP Pub/Sub.   
                
                1. This error may be shown as a consequence of Pub/Sub configuration/availability errors.
                2. Check for pub/sub configuration errors.
                3. If pub/sub configuration looks correct, this may indicate that cloud function can’t process audit logs fast enough.
                4. From Protector Function Terraform configuration, try increasing CPU and concurrency.
                Audit log sink error: Unable to deliver all logs. 
                
                opensearch.0: Dropped records: 1/1
                
                [error] [output:opensearch:opensearch.0] HTTP status=401 URI=/_bulk
                
                1. Indicates problems with ESA Audit Store availability/configuration.
                2. Those errors will usually be displayed together. The third error will have details on what is the status or response from ESA.
                3. In this example, the HTTP status 401 indicates authentication issue.

                7 -

                Prerequisites

                The following requirements must be completed for the Snowflake implementation.

                RequirementsDescription
                Protegrity distribution and installation scriptsThese artifacts are provided by Protegrity
                Protegrity ESA 10.0+The Cloud VPC must be able to obtain network access to the ESA
                Google Cloud AccountRecommend creating a new project for Protegrity Serverless
                Snowflake cluster (Enterprise Edition recommended)
                Terraform CLI v0.14 or higherTerraform is used to deploy resources to Google Cloud Account

                8 -

                Required Skills and Abilities

                RequirementsDescription
                Google Cloud Account AdministratorRun Terraform (or perform steps manually), create/configure a VPC and IAM permissions.
                Protegrity AdministratorThe ESA credentials required to extract the policy for the Policy Agent
                Snowflake AdministratorAccount Admin access required to setup access
                Network AdministratorOpen firewall to access ESA and evaluate Google Cloud network setup