Granica Screen can be provided as a container to be hosted by the user, allowing users full control to deploy the solution within their infrastructure according to their needs.

This guide provides instructions for gaining access to the container image, and simple directions to start the container and try out the Screen API.

Get Access to the Container Image

Getting access to the container image is as simple as providing an AWS role to be granted access by the Granica team. This section walks through the steps of creating a role with the minimal necessary permissions. If you already have an EC2 role you wish to use with sufficient permissions, skip straight to requesting access.

Note that this setup requires sufficient IAM permissions to create service roles and policies. See the AWS docs for more details.

Create an IAM Policy

Create a new IAM policy with the following json content. We will refer to this policy as granica-screen-docker-policy for subsequent steps.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ECRToken",
            "Effect": "Allow",
            "Action": "ecr:GetAuthorizationToken",
            "Resource": "*"
        },
        {
            "Sid": "ImageAccess",
            "Effect": "Allow",
            "Action": [
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage",
                "ecr:BatchCheckLayerAvailability"
            ],
            "Resource": "arn:aws:ecr:us-east-2:809541265033:repository/screen"
        }
    ]
}

Create an IAM Role

Create a new EC2 role and attach the newly created granica-screen-docker-policy IAM policy to it. We will refer to this role as granica-screen-docker-role for subsequent steps.

Request Access

Contact us to give us the ARN of the IAM role created in the previous step. Our team will grant this role access to pull the docker image from our ECR repository.

If you intend to deploy the container using a different method, simply provide another role which would be the preferred method of access.

Setup EC2 Instance with the Docker Container

System Requirements

Minimum system for the screen container development are as follows:

Any 64-bit x86 processor with 28GB RAM
NVIDIA GPU with at least 16GB VRAM
128GB disk volume

On AWS, we recommend the g5.xlarge instance, which is a low cost GPU-based instance with the following specs:

2 core 4 vCPU instance with 16 GB RAM
NVIDIA A10G Tensor Core GPU with 24GB VRAM
128GB disk volume

Provision the EC2 Instance

Choose Deep Learning Base OSS Nvidia Driver GPU AMI (Ubuntu 20.04) 20240308 as the AMI.
Select g5.xlarge as the instance type.
Make sure to select an EC2 keypair you have access to, or create a new one. You'll need it to access the EC2 instance.
Configure a default security group. Allow HTTP traffic to be able to access the screen endpoint from outside the container.
Allocate 128 GiB to the EBS gp2 root volume.
Within the Advanced Details section, attach the granica-screen-docker-role IAM role.

SSH into the EC2 Instance

SSH into the server using the following command. Replace <KEY_PAIR.pem> and <EC2_ADDRESS> with the location of your SSH keypair file and EC2 Public DNS (domain name), respectively.

ssh -i "<KEY_PAIR.pem>" ubuntu@<EC2_ADDRESS>

Login to Granica's ECR repository

Run the following command on the EC2 instance to login to Granica's ECR repository on the instance:

aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin 809541265033.dkr.ecr.us-east-2.amazonaws.com

Get Your License

Contact Granica for a license for your organization. Copy this license to the machine that will run the docker image. In this tutorial we will assume the license is saved at ~/screen.lic. Change this in the docker run command below to your license path.

Pull and Start the Docker Container

Run the following command to pull and start the Granica Screen API container inside your EC2 instance.

This command will first pull the image from ECR, which may take several minutes due to the size of the image. Afterwards, the command starts a docker container, and makes the Screen API available at port 80 on the host EC2 instance.

docker run -p 80:8080 -d --gpus all --volume ~/screen.lic:/etc/screen/screen.lic 809541265033.dkr.ecr.us-east-2.amazonaws.com/screen:latest

Using the container

Make Your First Screen Request

A simple example CURL request can be made from the host EC2 instance:

curl --location --request POST 'http://localhost:80/screen' \
     --header 'Content-Type: application/json' \
     --data-raw '{
"data": "Hello, my email is joe@gmail.com and my name is John Smith. My phone is (650) 123-4566."
}'

A CURL request with privacy information parameters can be made as follows:

curl --location --request POST 'http://localhost:80/screen' \
     --header 'Content-Type: application/json' \
     --data-raw '{
    "data": "Hello, my email is joe@gmail.com and my name is John Smith. My phone is (650) 123-4566.",
    "classificationTypes": [
      {
        "classificationType": "EMAIL",
        "likelihoodType": "LIKELIHOOD_TYPE_MEDIUM"
      },
      {
        "classificationType": "PHONE_NUMBER",
        "likelihoodType": "LIKELIHOOD_TYPE_MEDIUM"
      }
    ],
    "transformationParams": {
      "transformationType": "TRANSFORMATION_TYPE_SYNTHETIC"
    }
}'

This request sends the string passed in the request to Screen for scanning and redacting, using the default settings. You should get a response with the redacted data and metadata about the scan results and transformation process.

A CURL request with bias and toxicity parameters can be made as follows:

curl --location --request POST 'http://localhost:80/screen' \
     --header 'Content-Type: application/json' \
     --data-raw '{
    "data": "No matter how much money or power you have, if you are not white, you will never be considered a true american.",
    "biasTypes": [
      "RACE_ETHNICITY",
      "NATIONALITY_LOCATION"
    ],
    "toxicityTypes": [
      "HATE",
      "PHYSICAL_SAFETY"
    ]
}'

This request sends the string passed in the request to Screen for bias and toxicity scanning. You should get a response specifying bias and toxicity levels for each bias and toxicity type provided respectively.

A CURL request with privacy information, bias and toxicity parameters can be made as follows:

curl --location --request POST 'http://localhost:80/screen' \
     --header 'Content-Type: application/json' \
     --data-raw '{
    "data": "John Smith is old and ugly, he wont be a fit for the job.",
    "classificationTypes": [
      {
        "classificationType": "PERSON_NAME",
        "likelihoodType": "LIKELIHOOD_TYPE_MEDIUM"
      },
      {
        "classificationType": "PHONE_NUMBER",
        "likelihoodType": "LIKELIHOOD_TYPE_MEDIUM"
      }
    ],
    "transformationParams": {
      "transformationType": "TRANSFORMATION_TYPE_SYNTHETIC"
    },
    "biasTypes": [
      "APPEARANCE",
      "NATIONALITY_LOCATION"
    ],
    "toxicityTypes": [
      "HATE",
      "PHYSICAL_SAFETY"
    ]
}'

This request sends the string passed in the request to Screen for privacy information, bias and toxicity scanning and redacting. You should get a response with the redacted data and metadata about the scan results and transformation process; bias and toxicity levels for each bias and toxicity type provided respectively.

Reveal Redacted Data Using the Reveal Request

The Reveal endpoint allows you to unredact the data that was redacted by the Screen API. This is useful for revealing redacted PII when necessary, such as when a user requests access to their own data.

curl --location --request POST 'http://localhost:80/reveal' \
     --header 'Content-Type: application/json' \
     --data-raw '{
    "redactedData": "Hello, my email is [EMAIL_1] and my name is [PERSON_NAME_1] [PERSON_NAME_2]. My phone is [PHONE_NUMBER_1].",
    "redactionMaps": [
      {
        "redactionString": "[EMAIL_1]",
        "originalData": "joe@gmail.com"
      },
      {
        "redactionString": "[PERSON_NAME_1]",
        "originalData": "John"
      },
      {
        "redactionString": "[PERSON_NAME_2]",
        "originalData": "Smith"
      },
      {
        "redactionString": "[PHONE_NUMBER_1]",
        "originalData": "(650) 123-4566"
      }
    ],
    "transformationType": "TRANSFORMATION_TYPE_NUMBERED"
}'

Note: If transformationType is an encrypted transformation type, you can provide the encryption key in the request JSON encryptionKey field instead of providing the redactionMaps field. Decryption will be performed using the provided encryption key.

The request above will result in this JSON response:

{
    "originalData": "Hello, my email is joe@gmail.com and my name is John Smith. My phone is (650) 123-4566."
}

API Docs

The Screen API provides many configuration options, as well as additional endpoints. Detailed API documentation can be found here. To find out about logging, health check and versioning, refer here.

Next steps

At this point, you have a single container running Granica Screen! This may be sufficient for simple tasks or small deployments. Larger and more complex workflows will likely want to integrate with a container orchestration system such as Kubernetes. Granica Screen can also be deployed as a fully managed cluster through the Granica Platform.

Start Screening with the Container

Get Access to the Container Image

Create an IAM Policy

Create an IAM Role

Request Access

Setup EC2 Instance with the Docker Container

System Requirements

Provision the EC2 Instance

SSH into the EC2 Instance

Login to Granica's ECR repository

Get Your License

Pull and Start the Docker Container

Using the container

Make Your First Screen Request

Reveal Redacted Data Using the Reveal Request

API Docs

Next steps

Was this page helpful?

Start Screening with the Container

Get Access to the Container Image#

Create an IAM Policy#

Create an IAM Role#

Request Access#

Setup EC2 Instance with the Docker Container#

System Requirements#

Provision the EC2 Instance#

SSH into the EC2 Instance#

Login to Granica's ECR repository#

Get Your License#

Pull and Start the Docker Container#

Using the container#

Make Your First Screen Request#

Reveal Redacted Data Using the Reveal Request#

API Docs#

Next steps#

Was this page helpful?

Get Access to the Container Image

Create an IAM Policy

Create an IAM Role

Request Access

Setup EC2 Instance with the Docker Container

System Requirements

Provision the EC2 Instance

SSH into the EC2 Instance

Login to Granica's ECR repository

Get Your License

Pull and Start the Docker Container

Using the container

Make Your First Screen Request

Reveal Redacted Data Using the Reveal Request

API Docs

Next steps