Amazon Web Services (Asset Mode)

This page covers running the XplicitTrust agent as an asset on AWS with the official container image. Everything in Docker / Podman (Asset Mode) applies; this page adds what is specific to AWS: where the container can run, how its configuration survives a recreated task, and how to protect that configuration.

Where the agent can run

The agent needs the NET_ADMIN and NET_RAW capabilities and the host's /dev/net/tun device (see Prerequisites).

Service	Supported
EC2 (container or Linux package)	Yes
ECS on EC2 (EC2 launch type or EC2 capacity provider)	Yes
EKS with EC2 nodes	Yes
AWS Fargate (ECS or EKS)	No: Fargate grants neither NET_ADMIN nor /dev/net/tun

Persistent configuration

The agent keeps its state in /etc/XplicitTrust inside the container. If that directory is not on a persistent volume, every new container or task starts without configuration, registers again with the token and appears as an additional asset. On ECS this happens on every deployment, task replacement or instance change.

Mount a persistent volume at /etc/XplicitTrust with one of the options below. Registration flags (-token, -domain, -name) are only used when the directory holds no configuration, so passing them again on a later start is harmless.

The configuration directory contains credentials

/etc/XplicitTrust holds the asset's authentication secret and refresh token, its machine ID and the agent logs. Anyone who obtains a copy can authenticate as this asset. Treat it like a private key:

• Encrypt it at rest: an encrypted EBS volume or EFS file system, preferably with a customer-managed KMS key.
• Restrict access to root, with directory mode 0700. The agent writes its files with mode 0600.
• Use one directory per asset. Never share it between two running agents, and never include it in an AMI, container image, launch template or shared snapshot: each copy carries the same identity.
• Protect backups the same way, or exclude the directory from them.
• If a copy may have leaked, delete the asset in the Admin Console and register it again. This invalidates the stored credentials.

ECS on EC2 with a host directory

The simplest option when the task always runs on the same instance. Use an encrypted EBS root volume and a placement constraint that pins the task to that instance. Create the directory once on the instance:

sudo install -d -m 0700 -o root -g root /opt/xtna/aws-gw

Task definition (excerpt):

{
  "requiresCompatibilities": ["EC2"],
  "volumes": [
    { "name": "xtna-config", "host": { "sourcePath": "/opt/xtna/aws-gw" } }
  ],
  "containerDefinitions": [
    {
      "name": "xtna-agent",
      "image": "cr-public.xplicittrust.com/xtna-agent:latest",
      "essential": true,
      "mountPoints": [
        { "sourceVolume": "xtna-config", "containerPath": "/etc/XplicitTrust" }
      ],
      "linuxParameters": {
        "capabilities": { "add": ["NET_ADMIN", "NET_RAW"] },
        "devices": [
          { "hostPath": "/dev/net/tun", "containerPath": "/dev/net/tun" }
        ]
      },
      "command": [
        "-token", "<token>", "-domain", "<tenant-domain>",
        "-name", "aws-gw", "-ignore-hostname"
      ]
    }
  ]
}

ECS on EC2 with Amazon EFS

Use EFS when the task can be rescheduled onto a different instance:

"volumes": [
  {
    "name": "xtna-config",
    "efsVolumeConfiguration": {
      "fileSystemId": "fs-xxxxxxxx",
      "transitEncryption": "ENABLED",
      "authorizationConfig": { "accessPointId": "fsap-xxxxxxxx", "iam": "ENABLED" }
    }
  }
]

• Create the file system with encryption at rest enabled.
• Create a dedicated access point per asset, with its own root directory (e.g. /xtna/aws-gw, permissions 0700) and POSIX user 0:0, since the agent runs as root.
• Restrict mounting with an EFS file system policy to the agent's task role, and allow NFS in the mount target's security group only from the agent's instances.
• Run one task per asset (desired count 1) and configure the service to stop the old task before starting a new one (maximumPercent: 100, minimumHealthyPercent: 0). Two agents must never use the same directory at the same time.

EKS

Use a PersistentVolumeClaim from the EBS CSI driver with an encrypted StorageClass and ReadWriteOnce access, mounted at /etc/XplicitTrust. Run a single replica with strategy: type: Recreate so that two pods never hold the volume at once. See the Kubernetes example.

The Asset Creation Token

The token is passed only as a command-line flag. ECS does not expand variables or secrets into command, so the token is stored in plain text in the task definition. Treat it as a secret as well:

• Restrict who can read the task definition.
• Once the asset is registered, remove the token from the task definition, or revoke it in the Admin Console. It is not needed again as long as the configuration directory persists.

Gateway asset for a VPC subnet

To make hosts in the VPC reachable over XplicitTrust Network Access, configure the VPC range (or a part of it) as a Subnet with the agent as its gateway asset. No macvlan network is needed: with the default NAT, the agent forwards traffic to the hosts from its own VPC address, so the replies come back to it like any other traffic.

• Allow the traffic in the security groups of the target hosts, with the agent's security group (or VPC address) as source.
• With No NAT enabled, the hosts see the clients' tunnel addresses and send their replies to those. Run the task with "networkMode": "host" so that the agent uses the instance's network interface, disable the source/destination check on that interface, and add a route for the tunnel network to it in the subnet's route table.