Cequence Network Sensor — ECS on EC2 Installation Guide – Cequence Security

Every new EC2 launched in your ECS cluster — including spot replacements — installs the sensor on first boot and begins forwarding traffic to UAP automatically. No manual install per host, and no image rebuild when credentials rotate.

The sensor and bridge run as a single container. You do not deploy the bridge separately — it is bundled with the sensor, authenticates to UAP automatically, and forwards captured HTTP metadata.

Choose Your Path

Path	How the sensor image is delivered	When to use
Path A — Registry	You push the image to ECR or a private registry (JFrog, Harbor, etc.). Each EC2 pulls it from your registry on first boot.	Your policy requires container images to be sourced from an approved internal registry
Path B — Bundle-baked	The image is baked into the AMI from the offline bundle. No registry access needed.	Air-gapped environments or no registry requirement

Note on the bundle: Both paths require ami-bake.tar.gz — it contains the sensor scripts, binaries, and systemd service used at AMI build time. For Path A, the image tar inside the bundle is discarded during the build; the image comes from your registry instead. For Path B, the image tar is baked directly into the AMI.

Path A — Registry (ECR or Private Registry)

Before You Start (Path A)

What you need	Where to find it
UAP subdomain	e.g. `your-tenant.cequence.ai` — from your Cequence account team
`client_id` and `client_secret`	UAP portal → Settings → Clients
`ami-bake.tar.gz`	Provided by Cequence
AWS region and account ID	Region your ECS cluster runs in; account ID from the console top-right menu
S3 bucket	Any existing bucket to stage build files
Base AMI ID	Your current ECS-optimized AMI — Launch Template → Details → AMI ID
Registry details (ECR)	Your AWS account ID and region — no separate credentials needed
Registry details (JFrog / private)	Registry domain (e.g. `yourco.jfrog.io`), username, and password/API key with read access

A-1 — Push the Sensor Image to Your Registry

Pull the image from Cequence and push it to your registry. This is what each EC2 will pull at first boot.

ECR:

# Create the repo (skip if it already exists)
aws ecr create-repository --repository-name cequence/sensor --region YOUR-REGION

# Authenticate, pull, retag, push
aws ecr get-login-password --region YOUR-REGION \
  | docker login --username AWS --password-stdin \
    YOUR-ACCOUNT-ID.dkr.ecr.YOUR-REGION.amazonaws.com

docker pull registry.gitlab.com/cequence/releases/dataplane/sensor:5.1.1
docker tag  registry.gitlab.com/cequence/releases/dataplane/sensor:5.1.1 \
  YOUR-ACCOUNT-ID.dkr.ecr.YOUR-REGION.amazonaws.com/cequence/sensor:5.1.1
docker push YOUR-ACCOUNT-ID.dkr.ecr.YOUR-REGION.amazonaws.com/cequence/sensor:5.1.1

Private registry (JFrog, Harbor, Nexus, GitLab, etc.):

docker login YOUR-REGISTRY-DOMAIN -u YOUR-USER -p YOUR-PASSWORD-OR-TOKEN

docker pull registry.gitlab.com/cequence/releases/dataplane/sensor:5.1.1
docker tag  registry.gitlab.com/cequence/releases/dataplane/sensor:5.1.1 \
  YOUR-REGISTRY-DOMAIN/cequence/sensor:5.1.1
docker push YOUR-REGISTRY-DOMAIN/cequence/sensor:5.1.1

A-2 — One-Time AWS Account Setup

Store UAP credentials in Parameter Store:

aws ssm put-parameter --name /cequence/uap-subdomain --type String \
  --value 'your-tenant.cequence.ai'
aws ssm put-parameter --name /cequence/client-id --type String \
  --value 'paste-client-id'
aws ssm put-parameter --name /cequence/client-secret --type SecureString \
  --value 'paste-client-secret'

For private registry only — also store registry login credentials:

aws ssm put-parameter --name /cequence/registry-user --type String \
  --value 'YOUR-USER'
aws ssm put-parameter --name /cequence/registry-pass --type SecureString \
  --value 'YOUR-PASSWORD-OR-TOKEN'

Attach IAM policy to your ECS EC2 instance role:

AWS Console: IAM → Roles → your ECS instance role → Add permissions → Create inline policy → JSON

{
  "Version": "2012-10-17",
  "Statement": [
    { "Sid": "ReadCequenceParams", "Effect": "Allow",
      "Action": ["ssm:GetParameter", "ssm:GetParameters"],
      "Resource": "arn:aws:ssm:*:*:parameter/cequence/*" },
    { "Sid": "DecryptCequenceSecret", "Effect": "Allow",
      "Action": "kms:Decrypt", "Resource": "*",
      "Condition": {"StringEquals": {"kms:ViaService": "ssm.YOUR-REGION.amazonaws.com"}} }
  ]
}

Also attach the AWS managed policy AmazonSSMManagedInstanceCore to the same role (allows SSM Session Manager for troubleshooting).

ECR only — add ECR pull permission to the same role:

{ "Sid": "EcrAuth", "Effect": "Allow",
  "Action": "ecr:GetAuthorizationToken", "Resource": "*" },
{ "Sid": "EcrPull", "Effect": "Allow",
  "Action": ["ecr:BatchGetImage","ecr:GetDownloadUrlForLayer","ecr:BatchCheckLayerAvailability"],
  "Resource": "arn:aws:ecr:YOUR-REGION:YOUR-ACCOUNT-ID:repository/cequence/sensor" }

If your ECS tasks already pull from ECR, this permission is likely already present.

A-3 — Build the AMI

Upload build files to S3:

Why does Path A still need the bundle? The bundle contains the sensor binary, startup scripts, and config templates that need to be present on every EC2. The Image Builder component downloads the bundle, extracts these scripts, then deletes the image tar — the sensor container image comes from your registry instead. Think of it as: bundle provides the scripts, registry provides the image.

tar -xzf ami-bake.tar.gz

# Bundle — provides sensor scripts and binaries (image tar inside will be discarded by the build step)
aws s3 cp ami-bake/cequence-sensor-bundle-rhel-5.1.1.tar.gz \
  s3://YOUR-BUCKET/cequence-sensor/cequence-sensor-bundle-rhel-5.1.1.tar.gz

# Registry-specific firstboot scripts
aws s3 cp ami-bake/imagebuilder-registry/registry-firstboot.sh \
  s3://YOUR-BUCKET/cequence-sensor/registry/registry-firstboot.sh
aws s3 cp ami-bake/imagebuilder-registry/setup-registry.sh \
  s3://YOUR-BUCKET/cequence-sensor/registry/setup-registry.sh
aws s3 cp ami-bake/imagebuilder-registry/cequence-firstboot.service \
  s3://YOUR-BUCKET/cequence-sensor/registry/cequence-firstboot.service

Open the component YAML (ami-bake/imagebuilder-registry/cequence-sensor-registry-component.yaml), replace {{S3_BUCKET}} with your bucket name, then register it:

aws imagebuilder create-component \
  --name CequenceSensorRegistry --semantic-version 1.0.0 --platform Linux \
  --data file://ami-bake/imagebuilder-registry/cequence-sensor-registry-component.yaml \
  --region YOUR-REGION

Add to your existing Image Builder pipeline (recommended):

EC2 Image Builder → Image recipes → your ECS recipe → Create new version
Build components → Add → select CequenceSensorRegistry → keep existing components → Create recipe version
EC2 Image Builder → Image pipelines → your pipeline → Actions → Run pipeline
When done (~10–15 min), note the new AMI ID from Output resources

No existing pipeline? Use the helper script instead:

export AWS_REGION=YOUR-REGION
export AWS_ACCOUNT_ID=YOUR-ACCOUNT-ID
export S3_BUCKET=YOUR-BUCKET
export BASE_AMI_ID=ami-xxxxxxxx   # your current ECS Launch Template AMI

bash ami-bake/imagebuilder-registry/setup.sh

A-4 — Launch a Test EC2 and Verify

Before updating the whole fleet, launch a single EC2 from the new AMI to confirm the sensor installs and connects correctly.

Launch from AWS Console: EC2 → Launch instances → AMI = new AMI ID from Step A-3 → same instance type and security groups as your ECS cluster → paste this user-data:

For ECR:

#!/bin/bash
echo "ECS_CLUSTER=YOUR_CLUSTER_NAME" >> /etc/ecs/ecs.config
cat > /etc/default/cequence-firstboot <<'EOF'
REGISTRY_TYPE=ecr
REGISTRY_IMAGE=YOUR-ACCOUNT-ID.dkr.ecr.YOUR-REGION.amazonaws.com/cequence/sensor:5.1.1
EOF

For private registry:

#!/bin/bash
echo "ECS_CLUSTER=YOUR_CLUSTER_NAME" >> /etc/ecs/ecs.config
cat > /etc/default/cequence-firstboot <<'EOF'
REGISTRY_TYPE=private
REGISTRY_IMAGE=YOUR-REGISTRY-DOMAIN/cequence/sensor:5.1.1
REGISTRY_DOMAIN=YOUR-REGISTRY-DOMAIN
REGISTRY_USER_PARAM=/cequence/registry-user
REGISTRY_PASS_PARAM=/cequence/registry-pass
EOF

Required: REGISTRY_IMAGE must be set. If missing, first boot stops with an error and the sensor will not install.

Wait ~3 minutes for first boot to complete, then connect via SSM Session Manager (AWS Console → Systems Manager → Session Manager → Start session → select your instance) and run:

# 1. Firstboot completed
sudo systemctl status cequence-firstboot.service
# Expected: active (exited)

# 2. Sensor running
sudo docker ps | grep sensor
# Expected: "sensor" container Up

# 3. Forwarding to UAP
sudo docker exec sensor tail /opt/cequence/sensor/log/connector.log
# Look for: connected: true   written: N   errors: 0

Once all 3 checks pass, proceed to update the fleet.

A-5 — Update the Fleet (Launch Template + Instance Refresh)

EC2 → Launch Templates → your ECS template → Actions → Modify template (Create new version) → set Image ID to the new AMI → Create template version
Set as default: Actions → Set default version

Confirm your ASG uses $Default — check under Auto Scaling Groups → Details → Launch template. If it shows a pinned version number, update it:

aws autoscaling update-auto-scaling-group \
  --auto-scaling-group-name YOUR-ASG-NAME \
  --launch-template "LaunchTemplateId=YOUR-LT-ID,Version=\$Default"

Auto Scaling Groups → Instance refresh → Start instance refresh

Path B — Bundle-baked (Offline)

Before You Start (Path B)

What you need	Where to find it
UAP subdomain	e.g. `your-tenant.cequence.ai` — from your Cequence account team
`client_id` and `client_secret`	UAP portal → Settings → Clients
`ami-bake.tar.gz`	Provided by Cequence — sensor image + scripts bundled together
AWS region and account ID	Region your ECS cluster runs in; account ID from the console top-right menu
S3 bucket	Any existing bucket to stage build files
Base AMI ID	Your current ECS-optimized AMI — Launch Template → Details → AMI ID

B-1 — One-Time AWS Account Setup