Policy Agent Installation

The following sections will install the Policy Agent. The Policy Agent polls the ESA and deploys the policy to Protegrity Serverless as a static resource. Some of the installation steps are not required for the operation of the software but recommended for establishing a secure environment. Contact Protegrity Professional Services for further guidance on configuration alternatives in the Cloud.

ESA Server

Policy Agent Lambda requires ESA server running and accessible on TCP port 443.

Note down ESA IP address:

ESA IP Address (EsaIpAddress): ___________________

Certificates on ESA

Whether your ESA is configured with default self-signed certificate or your corporate CA certificate, Policy Agent can validate authenticity of ESA connection using CA certificate. The process for both scenarios is the same:

• Obtain CA certificate
• Convert CA certificate to a value accepted by Policy Agent
• Provide converted CA certificate value to Policy Agent

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. To convert downloaded CA certificate to a value accepted by Policy Agent, open the downloaded 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 or PTY_ESA_CA_SERVER_CERT_SECRET Lambda variable in section Policy Agent Lambda Configuration

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

Identify or Create a new VPC

Establish a VPC where the Policy Agent will be hosted. This VPC will need connectivity to the ESA. The VPC should be in the same account and region established in Pre-Configuration.

VPC name: ___________________

VPC Subnet Configuration

Identify or create a new subnet in the VPC where tha Lambda function will be connected to. It is recommended to use a private subnet.

Subnet name: ___________________

NAT Gateway For ESA Hosted Outside AWS Network

If ESA server is hosted outside of the AWS Cloud network, the VPC configured for Lambda function must ensure additional network configuration is available to allow connectivity with ESA. For instance if ESA has a public IP, the Lambda function VPC must have public subnet with a NAT server to allow routing traffic outside of the AWS network. A Routing Table and Network ACL may need to be configured for outbound access to the ESA as well.

VPC Endpoints Configuration

If an internal VPC was created, then add VPC Endpoints, which will be used by the Policy Agent to access AWS services. Policy Agent needs access to the following AWS services:

Identify or Create Security Groups

Policy Agent and cloud-based ESA appliance use AWS security groups to control traffic that is allowed to leave and reach them. Policy Agent runs on schedule and is mostly concerned with allowing traffic out of itself to ESA and AWS services it depends on. ESA runs most of the time and it must allow Policy Agent to connect to it.

Policy Agent security group must allow outbound traffic using rules described in the table below. To edit security group navigate:

From VPC > Security Groups > Policy Agent Security Group configuration.

Record Policy Agent security group ID:

Policy Agent Security Group Id: ___________________

Policy Agent will reach out to ESA on port 443. Create following inbound security group rule for cloud-based ESA appliance to allow connections from Policy Agent:

Creating ESA Credentials

Policy Agent Lambda requires ESA credentials to be provided as one of the three options.

• Option 1: Secrets Manager

• Option 2: KMS Encrypted Password

• Option 3: Custom AWS Lambda function

Option 1: Secrets Manager

Creating secrets manager secret with ESA username and password.

1. From the AWS Secrets Manager Console, select Store New Secret.

2. Select Other Type of Secrets.

3. Specify the username and password key value pair.

   

4. Select the encryption key or leave default AWS managed key.

5. Specify the Secret Name and record it.

   ESA Credentials Secret Name: __________________

Option 2: KMS Encrypted Password

ESA password is encrypted with AWS KMS symmetric key.

1. Create AWS KMS symmetric key which will be used to encrypt ESA password. See Create KMS Key for instructions on how to create KMS symmetric key using AWS console.

2. Record KMS Key ARN.

   ESA PASSWORD KMS KEY ARN: __________________

3. Run AWS CLI command to encrypt ESA password. Below you can find sample Linux aws cli command. Replace <key_arn> with KMS symmetric key ARN.

   aws kms encrypt --key-id <key_arn> --plaintext $(echo '<esa_password>' | base64 )
   

4. Sample output.

   {
     "CiphertextBlob": "esa_encrypted_password",
     "KeyId": "arn:aws:kms:region:aws_account:key/key_id ",
     "EncryptionAlgorithm": "SYMMETRIC_DEFAULT"
   }
   

5. Record ESA username and encrypted password.

   ESA USERNAME: __________________

   ESA ENCRYPTED PASSWORD: __________________

Option 3: Custom AWS Lambda function

With this option ESA username and password are returned by a custom AWS Lambda function. This method may be used to get the username and password from external vaults.

1. Create AWS Lambda in any AWS supported runtime.

   1. There is no input needed.

   2. The Lambda function must return the following response schema.

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

      For example,

      example output: {"username": "admin", "password": "Password1234"}
      

   3. Sample AWS Lambda function in Python:

      import json
      
      def lambda_handler(event, context):
      
          return {"username": "admin", "password": "password1234"}
      

      Warning

      Protegrity does not recommend hardcoding ESA username and password in the clear.

2. Record the Lambda name:

   Custom AWS lambda for ESA credentials: _______________

Create Agent Lambda IAM Policy

Follow the steps below to create Lambda execution policies.

Create Agent Lambda IAM policy

1. From AWS IAM console, select Policies > Create Policy.

2. Select JSON tab and copy the following snippet.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "EC2ModifyNetworkInterfaces",
         "Effect": "Allow",
         "Action": [
           "ec2:CreateNetworkInterface",
           "ec2:DescribeNetworkInterfaces",
           "ec2:DeleteNetworkInterface"
         ],
         "Resource": "*"
       },
       {
         "Sid": "CloudWatchWriteLogs",
         "Effect": "Allow",
         "Action": [
           "logs:CreateLogGroup",
           "logs:CreateLogStream",
           "logs:PutLogEvents"
         ],
         "Resource": "*"
       },
       {
         "Sid": "LambdaUpdateFunction",
         "Effect": "Allow",
         "Action": [
           "lambda:UpdateFunctionConfiguration"
         ],
         "Resource": [
           "arn:aws:lambda:*:*:function:*"
         ]
       },
       {
         "Sid": "LambdaReadLayerVersion",
         "Effect": "Allow",
         "Action": [
           "lambda:GetLayerVersion",
           "lambda:ListLayerVersions"
         ],
         "Resource": "*"
       },
       {
         "Sid": "LambdaDeleteLayerVersion",
         "Effect": "Allow",
         "Action": "lambda:DeleteLayerVersion",
         "Resource": "arn:aws:lambda:*:*:layer:*:*"
       },
       {
         "Sid": "LambdaPublishLayerVersion",
         "Effect": "Allow",
         "Action": "lambda:PublishLayerVersion",
         "Resource": "arn:aws:lambda:*:*:layer:*"
       },
       {
         "Sid": "S3GetObject",
         "Effect": "Allow",
         "Action": [
           "s3:GetObject"
         ],
         "Resource": "arn:aws:s3:::*/*"
       },
       {
         "Sid": "S3PutObject",
         "Effect": "Allow",
         "Action": [
           "s3:PutObject"
         ],
         "Resource": "arn:aws:s3:::*/*"
       },
       {
         "Sid": "KmsEncrypt",
         "Effect": "Allow",
         "Action": [
           "kms:GetPublicKey"
         ],
         "Resource": [
           "arn:aws:kms:*:*:key/*"
         ]
       },
       {
         "Sid": "SecretsManagerGetSecret",
         "Effect": "Allow",
         "Action": [
           "secretsmanager:GetSecretValue"
         ],
         "Resource": [
           "arn:aws:secretsmanager:*:*:secret:*"
         ]
       },
       {
         "Sid": "LambdaGetConfiguration",
         "Effect": "Allow",
         "Action": [
             "lambda:GetFunctionConfiguration"
         ],
         "Resource": [
             "arn:aws:lambda:*:*:function:*"
         ]
       }
     ]
   }
   

3. Replace wildcard * with the region, account, and resource name information where required.

4. This step is required if KMS is used to encrypt ESA password.

   Add policy entry below. Replace ESA PASSWORD KMS KEY ARN with the value recorded in Option 2: KMS Encrypted Password.

   
     {
       "Sid": "KmsDecryptEsaPassword",
       "Effect": "Allow",
       "Action": [
         "kms:Decrypt"
       ],
       "Resource": [
         "**ESA PASSWORD KMS KEY ARN**"
       ]
     }
   

5. Select Next type in the policy name and Create Policy. Record policy name:

   Policy Name: ___________________

Create Agent Lambda IAM Role

Perform the following steps to create Agent Lambda execution IAM role.

To create agent Lambda IAM role:

1. From AWS IAM console, select Roles > Create Role.

2. Select AWS Service > Lambda > Next.

3. Select the policy created in Create Agent Lambda IAM policy.

4. Proceed to Name, Review and Create.

5. Type the role name, for example, ProtegrityAgentRole and click Confirm.

6. Select Create role.

7. Record the role ARN.

   Agent Lambda IAM Execution Role Name: ___________________

Corporate Firewall Configuration

If an on-premise firewall is used, then the firewall must allow access from the NAT Gateway to an ESA. The firewall must allow access from the NAT Gateway IP to ESA via port 443 and 443.

CloudFormation Installation

Create the Policy Agent in the VPC using the CloudFormation script provided by Protegrity.

1. Access the CloudFormation service.

2. Select the target installation region.

3. Create a stack with new resources.

4. Upload the Policy Agent CloudFormation template (file name: pty_agent_cf.json).

5. Specify the following parameters for Cloud Formation:

   Parameter	Description	Note
   VPC	VPC where the Policy Agent will be hosted	Identify or Create a new VPC
   Subnet	Subnet where the Policy Agent will be hosted	VPC Subnet Configuration
   PolicyAgentSecurityGroupId	Security Group Id, which allows communication between the Policy Agent and the ESA	Identify or Create Security Groups
   LambdaExecutionRoleArn	Agent Lambda IAM execution role ARN allowing access to the S3 bucket, KMS encryption Key, Lambda and Lambda Layer	Create Agent Lambda IAM Role
   ArtifactS3Bucket	S3 bucket name with deployment package for the Policy Agent	Use S3 Bucket name recorded in Create S3 bucket for Installing Artifacts
   CreateCRONJob	Set to True to create a CloudWatch schedule for the agent to run.	Default: False

Policy Agent Lambda Configuration

After the CloudFormation stack is deployed, the Policy Agent Lambda must be configured with parameters recorded in earlier steps. From your AWS Console, navigate to lambda and select the following Lambda.

Protegrity_Agent<STACK_NAME>_

Select Configuration tab and scroll down to the Environment variables section. Select Editand replace all entries with the actual values.

{
  "PTY_ESA_CA_SERVER_CERT":"-----BEGIN CERTIFICATE----- MIIF..."
}

Test Installation

Open the Lambda and configure Test to execute the lambda and specify the default test event. Wait for around 20 seconds for the Lambda to complete. If policy is downloaded successfully, then a success message appears.

Navigate to the AWS_POLICY_S3_BUCKET bucket and verify that the AWS_POLICY_S3_FILENAME file was created.

Troubleshooting

2020-10-06T23:40:54.121Z 2dc84942-b5cc-4be9-aa4c-965f322307e4 Task timed out after 90.09 seconds

{
  "errorMessage": "Timeout! Unable to download policy in 20 seconds.",
  "errorType": "Exception",
  "stackTrace": [...]
}

{
  "errorMessage": "ESA connection error. Failed to download certificates. HTTP response code: 401.",
  "errorType": "ConnectionError",
  "stackTrace": [...]
}

xyz Access Denied: Exception
Traceback (most recent call last):
  … Exception: xyz Access Denied

Secrets Manager Access Denied: Exception
Traceback (most recent call last):
  … Exception: Secrets Manager Access Denied

[ERROR] PolicyAgentException: An error occurred (AccessDenied) when calling the PutObject operation: Access Denied

kms:Decrypt
kms:GenerateDatakey

An error occurred (AccessDeniedException) when calling the PublishLayerVersion operation: Your access has been denied by S3,
please make sure your request credentials have permission to GetObject for BUCKET_NAME/FILENAME. S3 Error Code: AccessDenied. S3 Error Message: Access Denied

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VpcRestrictions",
      "Effect": "Deny",
      "Principal": {
        "AWS": "*"
      },
      "Action": "s3:*Object",
      "Resource": [
        "arn:aws:s3:::<s3_bucket_name>/*",
        "arn:aws:s3:::<s3_bucket_name>"
      ],
      "Condition": {
        "Bool": {
          "aws:ViaAWSService": "false"
        },
        "StringNotEquals": {
          "aws:sourceVpc": "<vpc_id>"
        }
      }
    }
  ]
}

Additional Configuration

Strengthen the KMS IAM policy by granting access only to the required Lambda function(s).

Finalize the IAM policy for the Lambda Execution Role. Ensure to replace wildcard * with the region, account, and resource name information where required.

For example,

"arn:aws:lambda:*:*:function:*" -> "arn:aws:lambda:us-east-1:account:function:function_name"

Policy Agent Schedule

If specified in CloudFormation Installation, the agent installation created a CloudWatch event rule, which checks for policy update on an hourly schedule. This schedule can be altered to the required frequency.

Under CloudWatch > Events > Rules, find Protegrity_Agent_{stack_name}. Click Action > Edit Set the cron expression. A cron expression can easily be defined using CronMaker, a free online tool. Refer to http://www.cronmaker.com.