Tenet Labs

Deploy on Amazon ECS

Tenet PII Engine 0.5.4 runs in your own AWS account, in private subnets, with no NAT gateway or internet route. Your text and keys stay in your VPC. Callers authenticate with their own IAM role through Amazon VPC Lattice, so there are no shared tokens, and every rehydration and erasure is audited with the caller’s identity.

What the template creates

One CloudFormation stack, deployed into a VPC you already have:

  • Access: a VPC Lattice service network associated with your VPC, and a detect and a rehydrate service on HTTPS. Each service forwards only its own routes, and its IAM auth policy names the roles allowed on each route.
  • Detection: ECS on EC2 (Graviton c9g.xlarge), with at least two tasks across Availability Zones. Tasks accept traffic only from VPC Lattice. Fargate is not supported.
  • Rehydration: an optional separate service with its own role and an S3 Object Lock audit bucket.
  • Vault: Aurora PostgreSQL Serverless v2, encrypted with a customer-managed KMS key.
  • VPC endpoints for the AWS services it uses, including AWS Marketplace metering, and outside us-east-1 the endpoints that reach the image there.

Download the 0.5.4 CloudFormation template

Before you start

  1. Subscribe to the product in AWS Marketplace. The detect service refuses to start in an account that isn’t subscribed.
  2. Have a VPC with DNS hostnames enabled and one private subnet in each of at least two Availability Zones. VPC Lattice isn’t offered in every zone, for example use1-az3 in us-east-1, so choose subnets in zones it supports.
  3. Check capacity. Each detect task uses a whole c9g.xlarge, so the default deployment needs at least 8 On-Demand Standard vCPUs. Allow 12 with rehydration.
  4. Outside us-east-1, nothing to copy. AWS Marketplace serves the image only from us-east-1, in every Region. The template reaches it there through VPC endpoints that cross Regions (AWS PrivateLink), so there’s still no NAT. Admin and PowerUser roles can create them; a deploy role limited to specific actions also needs vpce:AllowMultiRegion.

Deploy

Run this as the role you pass in KeyAdminRoleArn. The template is too large to send inline, so CloudFormation needs an S3 bucket in the same Region to read it from.

Deploy the stack
prefix_list() {
aws ec2 describe-managed-prefix-lists --filters Name=prefix-list-name,Values=com.amazonaws.$AWS_REGION.$1 \
--query 'PrefixLists[0].PrefixListId' --output text
}
aws cloudformation deploy \
--stack-name tenet-pii \
--template-file tenet-pii-enterprise.yaml \
--s3-bucket <bucket-in-this-region> \
--capabilities CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND \
--parameter-overrides \
VpcId=<vpc-id> VpcCidr=<vpc-cidr> \
PrivateSubnetIds=<subnet-a>,<subnet-b> \
PrivateRouteTableIds=<rtb-a>,<rtb-b> \
S3PrefixListId=$(prefix_list s3) \
LatticePrefixListId=$(prefix_list vpc-lattice) \
KeyAdminRoleArn=<admin-role-arn> \
ImageUri=709825985650.dkr.ecr.us-east-1.amazonaws.com/tenet-labs/tenet-pii-engine:0.5.4 \
DeploymentId=<stable-name> \
DetectInvokerRoleArns=<role-of-the-app-that-calls-detect> \
RehydrateInvokerRoleArns=<role-allowed-to-rehydrate> \
ErasureInvokerRoleArns=<role-allowed-to-erase-sessions> \
AuditObjectLockMode=COMPLIANCE
ParameterWhat to know
DeploymentIdBound into the KMS encryption context. Pick a stable name; it can’t change on an existing vault.
DetectInvokerRoleArnsRoles that may call /detect, /redact and /deidentify. Required.
RehydrateInvokerRoleArnsRoles that may call /reidentify. Required with rehydration.
ErasureInvokerRoleArnsRoles that may erase a session. Leave it empty and nobody can; sessions then just expire.
EnableRehydrationSet to false for detection only. No rehydrate service or role is created. The audit bucket still is, for erasure records.
ExistingServiceNetworkArnA VPC can join only one VPC Lattice service network. If yours already has one, pass its ARN and the stack uses it.
CreateVpcEndpointsSet to false if your VPC already has private-DNS endpoints for these services, including metering-marketplace. Outside us-east-1 that includes ecr.api, ecr.dkr and s3 interface endpoints whose service Region is us-east-1, for the image.
AuditObjectLockModeUse COMPLIANCE in production. Nobody can delete audit objects before retention ends, including the root user.

For a trial you plan to delete, add AuroraDeletionProtection=false VaultDeletionPolicy=Delete AuditObjectLockMode=GOVERNANCE.

Deploy with Terraform instead

The Terraform module creates the same stack and needs Terraform 1.11 or later. Extract it next to your configuration and point source at that folder, not at the repository shown in its README. The README lists the other inputs, and the destroy steps for a trial.

Download the 0.5.4 Terraform module

main.tf
module "tenet_pii" {
source = "./tenet-pii-enterprise-terraform-0.5.4/deploy/terraform"
vpc_id = "<vpc-id>"
vpc_cidr = "<vpc-cidr>"
private_subnet_ids = ["<subnet-a>", "<subnet-b>"]
private_route_table_ids = ["<rtb-a>", "<rtb-b>"]
key_admin_role_arn = "<admin-role-arn>"
image_uri = "709825985650.dkr.ecr.us-east-1.amazonaws.com/tenet-labs/tenet-pii-engine:0.5.4"
deployment_id = "<stable-name>"
detect_invoker_role_arns = ["<role-of-the-app-that-calls-detect>"]
rehydrate_invoker_role_arns = ["<role-allowed-to-rehydrate>"]
erasure_invoker_role_arns = ["<role-allowed-to-erase-sessions>"]
}

Its outputs carry the same names in snake case, such as detect_endpoint and detect_caller_policy.

Set up a caller

Each application that calls Tenet, such as a Lambda function or an ECS task, needs four things:

WhatHow
Its role in an invoker listDetectInvokerRoleArns, RehydrateInvokerRoleArns or ErasureInvokerRoleArns. Each service’s auth policy names these roles per route and method.
An identity policy on that roleAttach the DetectCallerPolicy or RehydrateCallerPolicy output. A caller in the same account needs both this and the auth policy; either alone is refused.
A network pathAttach the LatticeClientSecurityGroupId output, or allow egress on 443 to the VPC Lattice prefix list.
Signed requestsSigV4 for the service vpc-lattice-svcs in the stack’s Region, with the header x-amz-content-sha256: UNSIGNED-PAYLOAD, sent to DetectEndpoint or RehydrateEndpoint.

Callers in another VPC need that VPC associated with the ServiceNetworkArn service network and listed in AllowedSourceVpcIds. For callers in another account, share the service network with AWS RAM and list their roles by ARN.

Send your first document

The tenet-pii-lattice package signs requests with your AWS credentials and keeps one connection open, which matters: on VPC Lattice a new connection costs about 25 ms. It needs Python 3.11 or later and boto3.

Install the client
pip install https://platform.tenetlabs.com/enterprise/clients/tenet_pii_lattice-0.1.0.tar.gz

Run this from an application in the VPC, as a role listed in DetectInvokerRoleArns, with DetectEndpoint from the stack outputs in DETECT_ENDPOINT:

De-identify a note
echo "Follow up with Jane Smith (MRN 4482913) about her visit." | \
python -m tenet_pii_lattice "$DETECT_ENDPOINT" deidentify

It returns the de-identified text, such as “Follow up with [FIRST_NAME_1] ([MRN_1]) about her visit.”, plus a session_id. Placeholders stay consistent within a session. From Python:

Python
from tenet_pii_lattice import LatticeClient
with LatticeClient(detect_endpoint) as detect: # the DetectEndpoint output
out = detect.deidentify("Follow up with Jane Smith (MRN 4482913) about her visit.")
session_id, text = out["session_id"], out["text"]
with LatticeClient(rehydrate_endpoint) as rehydrate: # the RehydrateEndpoint output
restored = rehydrate.reidentify(model_answer, session_id)["text"]

Any SigV4 signer works in other languages, as long as it signs for vpc-lattice-svcs, sends x-amz-content-sha256: UNSIGNED-PAYLOAD and reuses connections. Routes are exact and case-sensitive. A request the policy doesn’t allow, or for any other path, gets a 403 or 404 from VPC Lattice and never reaches a task.

Rehydrate a response

Call RehydrateEndpoint as a role listed in RehydrateInvokerRoleArns, with RehydrateCallerPolicy attached. Detect callers are refused. Send text containing placeholders, such as your model’s answer, with the session ID from /deidentify.

Rehydrate
echo "<text containing placeholders>" | \
python -m tenet_pii_lattice "$REHYDRATE_ENDPOINT" reidentify <session_id>

The response holds the restored text, plus restored and unresolved for placeholders it did or didn’t find. Every call writes an audit record to your bucket naming the caller’s role session ARN, its account, the source VPC and the VPC Lattice request ID. If that write fails, nothing is restored. A session lasts one hour after its last /deidentify call, then returns 404.

To require approval for each use, set RequireRehydrateApprovalTag=true. Every rehydration must then come from a role session carrying the tenet-approval-id session tag, which your approval workflow sets when it assumes the role, and VPC Lattice checks it on every call. Also put the approval ID in the role session name: the audit record names the session, so the approval appears in your audit trail.

Erase a session

To delete a session’s stored values before it expires, call DELETE /sessions/<session_id> on the detect service as a role listed in ErasureInvokerRoleArns. It returns 204, including for an ID that doesn’t exist. Afterwards, rehydrating or de-identifying with that ID returns 404. Each erasure is audited before it runs, and an erasure that can’t be recorded isn’t performed.

Erase a session
python -m tenet_pii_lattice "$DETECT_ENDPOINT" erase <session_id>

Billing

AWS bills usage through your AWS account, at the prices on your Marketplace offer. Each detect task reports its hourly quantities to AWS Marketplace metering over the VPC endpoint. Rehydration is not billed. VPC Lattice itself is billed by AWS, as usual for your account.

DimensionCounts
DocumentsXSDocuments up to 256 characters
DocumentsSDocuments of 257 to 2,048 characters
DocumentsMDocuments of 2,049 to 8,192 characters
DocumentsLDocuments over 8,192 characters
TailIncrementsEach started 4,096 characters above 32,768, added to the document

What leaves your account

By default, only metering records: the product code, a dimension, a quantity and a timestamp, sent to AWS over PrivateLink. Tenet receives nothing and has no access to your account.

Sending hourly usage counts to Tenet is off by default. If you turn it on with EnableUsageTelemetryEgress, the template adds a NAT gateway. Those records hold counts only, never text or values.

If tasks stop at startup

  • “refused this deployment” (detect): this account isn’t subscribed, or the detect task role doesn’t allow aws-marketplace:MeterUsage.
  • “metering is unreachable”: the metering-marketplace VPC endpoint is missing, or the task can’t reach it.

Remove the stack

Set AuroraDeletionProtection=false and update the stack, then delete it. Stack deletion keeps the KMS key and the audit bucket.

Verify the image

Check that your image is the one Tenet signed.

Questions: team@tenetlabs.com