Corellium Atlas AMI for AWS Virtual Engineering Workbench

Deploys a Corellium connector as a Virtual Target in AWS Virtual Engineering Workbench (VEW). Once deployed, developers launch an EC2 instance from the VEW console that automatically provisions or attaches to a Corellium virtual device and exposes its services over an OpenVPN tunnel.

---

Getting started

VEW does not read from this repository. The VEW console accepts YAML pasted into a form, so you clone this repo locally and copy file contents into the console during the steps below.

git clone https://git.corellium.co/infrastructure/amazon-view-ami.git
cd amazon-view-ami

File	Used in	Purpose
src/component.yaml	Step 1	EC2 Image Builder component. Installs the toolchain and the crlmanager helper into the AMI.
src/product.yaml	Step 4	CloudFormation template published as a VEW Virtual Target product.
src/validate.py	Optional	Linter for the two YAML files. Run before pasting.

Deployment order is Component → Recipe → Pipeline → Product → Launch. Steps 1–4 are performed once by a VEW product contributor. Step 5 is performed by any developer each time they need a device.

---

Prerequisites

1. A deployed VEW platform, with product contributor permissions.
2. An onboarded spoke account.
3. VPC endpoints for SSM in the spoke VPC: com.amazonaws.<region>.ssm, .ssmmessages, .ec2messages.
4. NACL rules on the spoke subnets allowing ports 22, 80, 443, 2000, 4000, and 5001 inbound and outbound. The product's security group covers SG-level rules; NACLs are configured separately.
5. A public subnet with an Internet Gateway route, tagged so VEW's subnet selector will pick it. Outbound internet access is required for the OpenVPN tunnel to Corellium.
6. More than one subnet tagged for VEW provisioning, in different Availability Zones. This prevents launches from being pinned to a single AZ.
7. Corellium credentials. An API token is preferred over username/password.
8. A Corellium project UUID.

No S3 bucket is required. The crlmanager helper is written into the AMI by the component.

---

Step 1: Create the component

1. Components → Create component.

   Field	Value
   Name	Corellium
   Description	Installs AWS CLI, OpenVPN, Node.js, Corellium CLI, and crlmanager.
   Platform	Linux
   Supported architectures	arm64
   Supported OS version	Ubuntu 2024

2. Create version:

   Field	Value
   Description	Installs AWS CLI, OpenVPN, Node.js, Corellium CLI, and crlmanager.
   Software vendor	Corellium
   Software version	1.0.0
   Release type	Major

3. Paste the full contents of src/component.yaml into the YAML Definition field.

4. Skip dependencies → Next.

5. Wait for the status to reach Released.

Architecture. These templates target arm64. To build for x86_64 instead, set the recipe architecture accordingly and replace InstanceType.AllowedValues and Default in src/product.yaml with x86 instance types (for example t3.large, m8i.xlarge). The architecture of the instance types must match the architecture of the AMI.

Step 2: Create the recipe

1. Recipes → Create recipe.

   Field	Value
   Name	Corellium virtual target connector
   Description	Corellium virtual target connector
   Platform	Linux
   Supported architectures	arm64
   Supported OS version	Ubuntu 2024

2. View the newly created recipe → View

3. Open the recipe → Create version.

   Field	Value
   Description	Corellium virtual target connector
   Volume size	100
   Release type	Major

4. Add the component:

   Field	Value
   Component	Corellium
   Version	1.0.0
   Type	Main

5. Create version → wait for Validated.

6. Select 1.0.0-rc.1 → Actions → Release.

Step 3: Build the image

1. Pipelines → Create pipeline.

   Field	Value
   Name	Corellium image build pipeline
   Description	Corellium procy image build pipeline
   Schedule	0 13 1 * ? *
   Recipe	Corellium virtual target connector
   Recipe version	1.0.0
   Build instance type	any arm64 type, for example m7g.2xlarge
   Product	leave empty

2. Create Pipeline →

3. Select the pipeline then → Create image.

4. Wait for the image status to reach Created.

Step 4: Publish the product

1. Products → Create product.

   Field	Value
   Name	Corellium
   Description	Corellium proxy target
   Type	Virtual target

2. Open the product → Create version.

3. In the AMI ID field, search corellium and select the AMI built in Step 3.

4. Next → select all existing content in the template field, delete it, then paste the full contents of src/product.yaml.

5. Next → wait for the status to reach Created.

Product versions are immutable. To apply a change to either YAML file, create a new product version; editing an existing one is not possible.

Step 5: Launch a virtual target

All virtual targets → Corellium → Create → select the newest version.

Parameter	Required	crlmanager flag	Notes
EndpointHost	Yes	--endpoint-host	Hostname only, no https://
ProjectId	Yes	--project	Corellium project UUID
CorelliumToken	Yes, or user/pass	--api-token	Preferred. Leave username and password blank when set.
CorelliumUsername	Only without token	--username
CorelliumPassword	Only without token	--password
DeviceId	No	--device-id	Set to attach to an existing device. Leave blank to create a new one.
DeviceFlavor	When creating	--device-flavor	For example rpi4b
DeviceOs	When creating	--device-os	For example 22.04.1
DeviceName	No	--device-name
SnsTopicArn	No	--sns-topic-arn	Receives a device-ready event
InstanceType	No	—	Defaults to t4g.large

Example: create a new Raspberry Pi device

EndpointHost      = app.corellium.com
ProjectId         = b9240518-ad8f-462b-b39d-21ad8a47c86b
CorelliumToken    = <api-token>
DeviceFlavor      = rpi4b
DeviceOs          = 22.04.1
DeviceName        = rpi-vew-tester
DeviceId          = (blank)

Example: attach to an existing device

EndpointHost      = app.corellium.com
ProjectId         = b9240518-ad8f-462b-b39d-21ad8a47c86b
CorelliumToken    = <api-token>
DeviceId          = f90ac048-e788-463c-bc20-e35d18620985

Step 6: Connect

1. My virtual targets → select the instance → Log in. This downloads connect_vew-pp-<UUID>.key.

2. Connect over SSH:

chmod 0600 connect_vew-pp-<UUID>.key
ssh -i connect_vew-pp-<UUID>.key ubuntu@<public-ip>

Device services are reachable through the instance's public IP on port 2000 (console), 4000 (agent), and 5001 (streaming).

Verifying the deployment

crlmanager runs automatically from user-data at boot. It does not need to be invoked manually.

sudo cat /var/log/corellium-userdata.log   # crlmanager output
sudo cat /var/log/cloud-init-output.log    # full boot output
systemctl status openvpn                   # VPN tunnel
sudo iptables -t nat -L -n                 # NAT rules
sudo cat /etc/crlmanager/state.env         # recorded device ID

A successful run ends with:

crlmanager: ready. device=<uuid> ec2=<instance-id>

---

Troubleshooting

"Provisioning error" in the VEW console

This message is generic. The specific cause is recorded by CloudFormation:

CloudFormation → Stacks → SC-<account>-pp-<id> → Events → the first CREATE_FAILED row → Status reason.

The same information is available under Service Catalog → Provisioned products → the failed product → Events.

Insufficient capacity in the requested Availability Zone

EC2 capacity for a given instance type varies by AZ and over time. Select a different InstanceType at launch, or retry later. Tagging subnets in multiple AZs for VEW provisioning (Prerequisite 6) reduces how often this occurs.

Changes to a YAML file have no effect

Component, recipe, and product versions are immutable. Create a new version and select it at launch. When creating a product version, clear the template field before pasting, as it pre-populates with the previous version's contents.

Security group creation fails on rule descriptions

EC2 restricts rule descriptions to a-zA-Z0-9 and the characters . _-:/()#,@[]+=&;{}!$*. Apostrophes and other characters outside this set are rejected. src/validate.py checks this.

Root volume smaller than snapshot

See the note in Step 3. Set VolumeSize in src/product.yaml to at least the AMI snapshot size.

---

Validating changes

src/validate.py checks both YAML files before they are pasted into VEW. It returns exit code 0 when all checks pass and 1 otherwise, so it can be used in CI.

pip install pyyaml
python3 src/validate.py

Checks performed:

• both files parse, including CloudFormation short-form intrinsics
• every ${Param} in UserData resolves to a declared parameter
• ${!Var} escapes are preserved for bash
• no orphaned parameters
• every security group description matches EC2's allowed character set
• the root volume size is at least the AMI snapshot size
• all instance types match the AMI architecture
• the embedded crlmanager scripts are syntactically valid bash

---

Configuration reference

Ports. The product's security group permits 22, 80, 443, 2000, 4000, and 5001, with ingress restricted to the launching user's security group.

IAM. The instance role grants sns:Publish (scoped to SnsTopicArn when supplied), ec2:CreateTags and ec2:DescribeTags (constrained by region), CloudWatch Logs write access, and AmazonSSMManagedInstanceCore.

VPN addressing. crlmanager installs NAT rules forwarding port 2000 to 10.11.1.1:2000 and masquerading return traffic to 10.11.1.2. To use a different range, edit the iptables lines in the crlmanager heredoc in src/component.yaml.

Replacing crlmanager. The helper is written into the AMI by the InstallCrlManager step in src/component.yaml. To substitute a different implementation, replace the heredoc body in that step and rebuild the image.