Bulk Student Setup With The API

Educators and lecturers who use Corellium to teach will often create a new project dedicated to each student and then pre-configure devices for the students.

We built this example API script that automates this process and saves time for the instructor. The script will create new user accounts, new projects, and new cloned devices for each student based on a pre-configured device snapshot from a list of email addresses.

Please note that this script has very few features and does not include error handling. If you experience errors, please verify that you satisfy the prerequisites and appropriately configure the variables.

Code Example

<<comment

WHAT DOES THIS SCRIPT DO?

This shell script can be run in Shell or a BASH terminal.

When this script is run it will;
1. create new users from a list
2. For each of the new users and optionally for an existing user on the list
2.1 Create a project for the user
2.2 Assign the user as a member
2.3 Create a device from a snapshot for the user. Once created and booted up the device will be on.

This script does not throw errors if a request fails.

PREREQUISITE

- JQ (https://stedolan.github.io/jq/) is the only dependency for this script.
- You have a Corellium account with the appropriate resources including CPU cores and device slots for the number of devices being created.
- You have created a snapshot to use as the original device to clone.

REQUIRED VARIABLES

1. Corellium Auth Token
2. List of emails of the users
3. The domain of your enterprise Corellium account
4. Corellium device ID where the snapshot is stored. This uid can be found in the URL when you are in the device on the Corellium APP.
5. Exact name of the snapshot. (Case sensitive)
6. Option to toggle creation for existing users


comment

# -------------------------------------------------------------
#   ------------------- VARIABLES ---------------------------
# -------------------------------------------------------------

# Set up your variables

# 1. Add your Corellium auth token. See https://support.corellium.com/administration/api-token for more information.
auth_token=<your_api_key>

# 2. Add each of your users into the array (remember to remove the examples)
users=(
"[email protected]"
"[email protected]"
"[email protected]"
)

# 3. Set the API of the domain.
# domain=https://your_domain.enterprise.corellium.com
domain=<your_domain>

# 4. Set the UID of the device to clone the snapshot from.
original_device_id=<your_device_instance_id>

# 5. Select the correct snapshot. If there's a space in your snapshot, put it in "double quotes."
snapshot_name=<device_snapshot_name>

# 6. Do you want to create devices if there is an existing user with the same username? The email is used for the users name, username and email.
new_users_only=false

# ------------------------------------------------------------------
#   ---- NOTHING BELOW THIS SECTION IS REQUIRED TO BE CHANGED ----
# ------------------------------------------------------------------

api_version=v1

# Setup of the request urls
create_user="${domain}/api/${api_version}/users"
create_project="${domain}/api/${api_version}/projects"
create_device="${domain}/api/${api_version}/instances"
get_original_device="${domain}/api/${api_version}/instances/${original_device_id}"
get_device_snapshots="${domain}/api/${api_version}/instances/${original_device_id}/snapshots"
get_users="${domain}/api/${api_version}/teams"

#Get original device data required
device_config=$(
curl -sS -X GET $get_original_device \
-H "Accept: application/json" \
-H "Authorization: Bearer $auth_token" \
-H "Content-Type: application/json" \
)
os=$(jq -r '.os' <<< ${device_config})
flavor=$(jq -r '.flavor' <<< ${device_config})

#Get the snapshot details
snapshot_info=$(
curl -sS -X GET $get_device_snapshots \
-H "Accept: application/json" \
-H "Authorization: Bearer $auth_token" \
-H "Content-Type: application/json" \
)
#get info snapshot by the name
target_snapshot_id=$(jq -r --arg snapshot_name "${snapshot_name}" '.[] | select(.name==$snapshot_name) | {id}' <<< ${snapshot_info})
target_snapshot_id_str=$(jq -r '.id' <<< ${target_snapshot_id})


device_setup () {
# Create the project
project_id=$(
curl -sS -X POST $create_project \
-H "Accept: application/json" \
-H "Authorization: Bearer $auth_token" \
-H "Content-Type: application/json" \
-d '{"name": "'"$user"'","settings":{"version":1,"internet-access":true},"quotas": {"cores":2,"instances": 1}}'
)
project_id_str=$(jq -r '.id' <<< ${project_id})
printf "\nProject created, id $project_id_str"

# Assign the user to the project
assign_role="${domain}/api/${api_version}/roles/projects/${project_id_str}/users/${user_id_str}/roles/_member_"
role_id=$(
curl -sS -X PUT $assign_role \
-H "Accept: application/json" \
-H "Authorization: Bearer $auth_token" \
-H "Content-Type: application/json" \
)
printf "\nUser assigned into the project"


# Create the device from the snapshot id
cloned_device=$(
curl -sS -X POST $create_device \
-H "Accept: application/json" \
-H "Authorization: Bearer $auth_token" \
-H "Content-Type: application/json" \
-d '{"project": "'"$project_id_str"'","name": "'"$snapshot_name"'","os": "'"$os"'","flavor": "'"$flavor"'","snapshot": "'"$target_snapshot_id_str"'"}'
)
cloned_device_id_str=$(jq -r '.id' <<< ${cloned_device})
printf "\nDevice cloned into the project, id $cloned_device_id_str"
}


# loop through each of the users
for user in ${users[@]};

do
printf "\n ---- Creation process for ${user} ---- \n"
# Create the user

user_id=$(
curl -sS -X POST $create_user \
-H "Accept: application/json" \
-H "Authorization: Bearer $auth_token" \
-H "Content-Type: application/json" \
-d '{"label": "'"$user"'", "name": "'"$user"'", "email": "'"$user"'" }'
)
user_id_str=$(jq -r '.id' <<< ${user_id})

if [ $user_id_str = "null" ]
then
if [ "$new_users_only" = true ]
then
printf "User exists no action taken (set 'new_users_only' to false to create projects for existing users)"
else
users_list=$(
curl -sS -X GET $get_users \
-H "Accept: application/json" \
-H "Authorization: Bearer $auth_token" \
-H "Content-Type: application/json" \
)
users_array=$(jq '.[0].users' <<< "$users_list")
user_id=$(jq -r --arg user "${user}" '.[] | select(.email==$user) | {id}' <<< ${users_array})
user_id_str=$(jq -r '.id' <<< ${user_id})
printf "User exists, id $user_id_str"
device_setup
fi
else
printf "User account created, $user_id_str"
device_setup
fi
printf "\n -------- End -------- \n"

done

How to Execute the Code

1. Review the prerequisites in the comment section and ensure you have installed the dependency jq.
2. Save the example code above to a file called bulk_student_setup.sh.
3. Add your API key under Variable on line 42. You can generate a new API key from your user profile page.
4. Add the list of user email addresses, one per line, starting on line 46.
5. Set the URL for your domain, such as https://your_domain.enterprise.corellium.com/, on line 53.
6. Set your original device's unique identifier on line 56. You can find the ID in the URL. For example, if your device's URL is https://davidtestent.enterprise.corellium.com/devices/681b4623-3719-438f-a6c4-eb6d3850b6f2/connect, the unique identifier is 681b4623-3719-438f-a6c4-eb6d3850b6f2.
7. Set the snapshot name you want to use as a template on line 59.
8. Set the new_users_only boolean as appropriate on line 62.
9. Save the script and run in Terminal using: bash ~/bulk_student_setup.sh. You should see a response similar to below.

user1@comp1 ~ % bash ~/bulk_student_setup_v2.sh

 ---- Creation process for [email protected] ----
User account created, 1042bfbf-a619-4a7c-bb94-08f704fce623
Project created, id 102df40a-a60d-491d-8948-b4018d5b61ce
User assigned into the project
Device cloned into the project, id bdd73bfb-5991-4de7-b80b-212c1147c9c5
 -------- End --------

 ---- Creation process for [email protected] ----
User account created, fe1bb34f-b502-4eca-b41b-4e21459f4d33
Project created, id 3acb8341-fc3c-4521-8632-54d0675c5f49
User assigned into the project
Device cloned into the project, id ac0b9baa-c6f4-41af-95b1-aaccef72900c
 -------- End --------

 ---- Creation process for [email protected] ----
User account created, 5469d8ae-1c6e-496d-a2ca-e3b935dd89ba
Project created, id 591000cd-a117-425d-9aed-ee54691fc45e
User assigned into the project
Device cloned into the project, id e44fcb9c-e6d0-4c22-8ac3-56a425360354
 -------- End --------

The new users, projects, and devices have been created. You can validate this by logging into your account.