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
- Subscribe to the product in AWS Marketplace. The detect service refuses to start in an account that isn’t subscribed.
- 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.
- 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.
- 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.
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
| Parameter | What to know |
|---|---|
| DeploymentId | Bound into the KMS encryption context. Pick a stable name; it can’t change on an existing vault. |
| DetectInvokerRoleArns | Roles that may call /detect, /redact and /deidentify. Required. |
| RehydrateInvokerRoleArns | Roles that may call /reidentify. Required with rehydration. |
| ErasureInvokerRoleArns | Roles that may erase a session. Leave it empty and nobody can; sessions then just expire. |
| EnableRehydration | Set to false for detection only. No rehydrate service or role is created. The audit bucket still is, for erasure records. |
| ExistingServiceNetworkArn | A VPC can join only one VPC Lattice service network. If yours already has one, pass its ARN and the stack uses it. |
| CreateVpcEndpoints | Set 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. |
| AuditObjectLockMode | Use 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
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:
| What | How |
|---|---|
| Its role in an invoker list | DetectInvokerRoleArns, RehydrateInvokerRoleArns or ErasureInvokerRoleArns. Each service’s auth policy names these roles per route and method. |
| An identity policy on that role | Attach the DetectCallerPolicy or RehydrateCallerPolicy output. A caller in the same account needs both this and the auth policy; either alone is refused. |
| A network path | Attach the LatticeClientSecurityGroupId output, or allow egress on 443 to the VPC Lattice prefix list. |
| Signed requests | SigV4 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.
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:
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:
from tenet_pii_lattice import LatticeClientwith LatticeClient(detect_endpoint) as detect: # the DetectEndpoint outputout = 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 outputrestored = 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.
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.
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.
| Dimension | Counts |
|---|---|
| DocumentsXS | Documents up to 256 characters |
| DocumentsS | Documents of 257 to 2,048 characters |
| DocumentsM | Documents of 2,049 to 8,192 characters |
| DocumentsL | Documents over 8,192 characters |
| TailIncrements | Each 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.