Corellium

https://support.corellium.com/
Admin
Corellium is a platform that provides virtual iOS, Android, and IoT devices in the cloud with...
Tokens:145,556
Snippets:956
Trust Score:9.8
Update:11 months ago
Show doc for...
Tokens:
Raw
### Get Help for Corellium Private Cloud Instance Creation Script

Source: https://support.corellium.com/setup/private-cloud

This command displays the help message for the `create_private_cloud_instance.sh` script, detailing all available options and their purposes. It's useful for understanding the parameters required for instance creation.

```bash
./create_private_cloud_instance.sh --help
```

--------------------------------

### Install Corellium API Package (npm)

Source: https://support.corellium.com/sdk/apis/javascript-v1/simple-example

Installs the necessary Corellium API package using npm. This is a prerequisite for running the example script.

```bash
npm install @corellium/corellium-api
```

--------------------------------

### Fetch Projects using C and libcurl

Source: https://support.corellium.com/sdk/apis/other-languages

Demonstrates how to fetch a list of projects from the Corellium API using C and the libcurl library. It handles HTTP request setup, authentication, response writing, and error handling. Requires libcurl to be installed and linked during compilation.

```c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <curl/curl.h>

struct string {
    char *ptr;
    size_t len;
};

void init_string(struct string *s) {
    s->len = 0;
    s->ptr = malloc(s->len + 1);
    if (s->ptr == NULL) {
        fprintf(stderr, "malloc() failed\n");
        exit(EXIT_FAILURE);
    }
    s->ptr[0] = '\0';
}

size_t writefunc(void *ptr, size_t size, size_t nmemb, struct string *s) {
    size_t new_len = s->len + size * nmemb;
    s->ptr = realloc(s->ptr, new_len + 1);
    if (s->ptr == NULL) {
        fprintf(stderr, "realloc() failed\n");
        exit(EXIT_FAILURE);
    }
    memcpy(s->ptr + s->len, ptr, size * nmemb);
    s->ptr[new_len] = '\0';
    s->len = new_len;

    return size * nmemb;
}

int main(void) {
    CURL *curl;
    CURLcode res;
    struct string s;
    char *api_key = getenv("CORELLIUM_API_TOKEN");
    char *endpoint = getenv("CORELLIUM_API_ENDPOINT");
    char url[256];

    snprintf(url, sizeof(url), "%s/v1/projects", endpoint);

    init_string(&s);
    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();

    if (curl) {
        struct curl_slist *headers = NULL;
        char auth_header[256];

        snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", api_key);
        headers = curl_slist_append(headers, auth_header);
        headers = curl_slist_append(headers, "Content-Type: application/json");

        curl_easy_setopt(curl, CURLOPT_URL, url);
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writefunc);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &s);

        res = curl_easy_perform(curl);

        if (res != CURLE_OK) {
            fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(res));
        } else {
            printf("%s\n", s.ptr);
        }

        curl_easy_cleanup(curl);
        curl_slist_free_all(headers);
    }

    free(s.ptr);
    curl_global_cleanup();

    return 0;
}

```

--------------------------------

### GET /v1/projects (Swift)

Source: https://support.corellium.com/sdk/apis/other-languages

This Swift example demonstrates how to fetch a list of projects from the Corellium API using `URLSession` and `JSONSerialization`. It includes setup instructions for Xcode environment variables and permissions.

```APIDOC
## GET /v1/projects

### Description
Fetches a list of projects from the Corellium API using Swift.

### Method
GET

### Endpoint
/v1/projects

### Parameters

#### Query Parameters
None

#### Request Body
None

### Request Example
```swift
import SwiftUI

struct ContentView: View {
    @State private var output: String = "Loading..."

    var body: some View {
        Text(output)
            .padding()
            .onAppear(perform: fetchProjects)
    }

    func fetchProjects() {
        guard let apiKey = ProcessInfo.processInfo.environment["CORELLIUM_API_TOKEN"],
              let endpoint = ProcessInfo.processInfo.environment["CORELLIUM_API_ENDPOINT"],
              let url = URL(string: "\(endpoint)/v1/projects") else {
            output = "Missing environment variables"
            return
        }

        var request = URLRequest(url: url)
        request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")

        URLSession.shared.dataTask(with: request) { data, response, error in
            DispatchQueue.main.async {
                if let error = error {
                    self.output = "Error: \(error.localizedDescription)"
                } else if let data = data,
                          let json = try? JSONSerialization.jsonObject(with: data, options: []) {
                    self.output = "\(json)"
                } else {
                    self.output = "Failed to fetch projects"
                }
            }
        }.resume()
    }
}

struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
    }
}
```

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects.

#### Response Example
```json
[
  {
    "id": "12345abcde",
    "name": "My Project",
    "owner": "user@example.com",
    "created": "2023-10-27T10:00:00Z"
  }
]
```
```

--------------------------------

### Install Node.js and Corellium Client API

Source: https://support.corellium.com/sdk/apis/javascript-v2/simple-example

These commands show how to install Node.js using Homebrew and then install the '@corellium/client-api' package as a project dependency. The `npm run build` command is typically used to prepare the project for execution.

```bash
brew install node
npm install @corellium/client-api --save
npm run build
```

--------------------------------

### Corellium Private Cloud Instance Creation Output (JSON)

Source: https://support.corellium.com/setup/private-cloud/deployment

Example output demonstrating the successful creation and configuration of a Corellium Private Cloud instance. It includes details on AMI search, key pair creation, instance status, volume attachment, and final confirmation.

```json
{
    "AttachTime": "2023-06-01T16:38:19.152000+00:00",
    "Device": "/dev/sdf",
    "InstanceId": "i-*****************",
    "State": "attaching",
    "VolumeId": "vol-*****************"
}
```

--------------------------------

### Install Android Platform Tools (Ubuntu)

Source: https://support.corellium.com/features/connect/quick-connect

Installs the `android-sdk-platform-tools` package, which includes the `adb` command, on Ubuntu systems using the APT package manager. This is required if the `adb` command is not recognized.

```bash
sudo apt install android-sdk-platform-tools

```

--------------------------------

### GET /v1/projects (Rust)

Source: https://support.corellium.com/sdk/apis/other-languages

This Rust example demonstrates how to fetch a list of projects from the Corellium API using the `reqwest` and `serde_json` crates. Ensure you have added `reqwest`, `serde`, and `serde_json` to your `Cargo.toml`.

```APIDOC
## GET /v1/projects

### Description
Fetches a list of projects from the Corellium API.

### Method
GET

### Endpoint
/v1/projects

### Parameters

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use reqwest::blocking::Client;
use std::env;
use serde_json::Value;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let api_key = env::var("CORELLIUM_API_TOKEN")?;
    let url = format!("{}/v1/projects", env::var("CORELLIUM_API_ENDPOINT")?);

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Authorization", format!("Bearer {}", api_key).parse()?);

    let response = client.get(&url)
        .headers(headers)
        .send()? 
        .json::<Value>()?;

    println!("{:#?}", response);
    Ok(())
}
```

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects.

#### Response Example
```json
[
  {
    "id": "12345abcde",
    "name": "My Project",
    "owner": "user@example.com",
    "created": "2023-10-27T10:00:00Z"
  }
]
```
```

--------------------------------

### Create Corellium Private Cloud Instance

Source: https://support.corellium.com/setup/private-cloud

This command creates a Corellium Private Cloud instance using the `create_private_cloud_instance.sh` script. It requires various parameters such as hostname, region, AMI ID, key name, subnet ID, device CIDR, S3 bucket name, and the installer package name. Ensure all prerequisites are met before execution.

```bash
./create_private_cloud_instance.sh --hostname my-host --region us-west-2 --ami-id ami-***************** --key-name my-key --subnet-id subnet-***************** --device-cidr 10.20.0.0/16 --bucket-name private-cloud-debs --installer-pkg aws-private-cloud-4.6.0.tar.xz
```

--------------------------------

### GET /v1/projects (Ruby)

Source: https://support.corellium.com/sdk/apis/other-languages

This Ruby example demonstrates how to fetch a list of projects from the Corellium API using the `net/http`, `json`, and `uri` libraries.

```APIDOC
## GET /v1/projects

### Description
Fetches a list of projects from the Corellium API.

### Method
GET

### Endpoint
/v1/projects

### Parameters

#### Query Parameters
None

#### Request Body
None

### Request Example
```ruby
require 'net/http'
require 'json'
require 'uri'

api_key = ENV['CORELLIUM_API_TOKEN']
endpoint = ENV['CORELLIUM_API_ENDPOINT']
url = URI("#{endpoint}/v1/projects")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request['Authorization'] = "Bearer #{api_key}"
request['Content-Type'] = 'application/json'

response = http.request(request)
result = JSON.parse(response.body)

puts JSON.pretty_generate(result)
```

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects.

#### Response Example
```json
[
  {
    "id": "12345abcde",
    "name": "My Project",
    "owner": "user@example.com",
    "created": "2023-10-27T10:00:00Z"
  }
]
```
```

--------------------------------

### Turn Instance On or Create New Instance

Source: https://support.corellium.com/sdk/apis/python/example-script

Checks if a default instance exists and is powered on. If the instance is off, it starts it. If the instance does not exist, it attempts to create a new one with specified hardware and firmware. Handles 'insufficient resource' errors during creation.

```python
async def turn_instance_on_or_create_new_instance(api_instance):
    # Assuming DEFAULT_INSTANCE_ID, DEFAULT_INSTANCE_HARDWARE, DEFAULT_INSTANCE_FIRMWARE, DEFAULT_PROJECT_ID, DEFAULT_INSTANCE_NAME are defined elsewhere
    try:
        api_response_get_default_instance = await api_instance.v1_get_instance(DEFAULT_INSTANCE_ID)
        print(f'Instance {DEFAULT_INSTANCE_ID} was found.')
        # check if the instance is off
        if api_response_get_default_instance.state == INSTANCE_STATE_OFF:
            print(f'Instance {DEFAULT_INSTANCE_ID} is off.')
            # start the instance
            await api_instance.v1_start_instance(DEFAULT_INSTANCE_ID)
            print(f'Instance {DEFAULT_INSTANCE_ID} is powering on.')
        return DEFAULT_INSTANCE_ID
    except ApiException as e:
        if e.status == 404:
            print(f'Instance {DEFAULT_INSTANCE_ID} was not found.')
            print(f'Creating a new instance of {DEFAULT_INSTANCE_HARDWARE} hardware with {DEFAULT_INSTANCE_FIRMWARE} firmware.')
            try:
                api_response_create_instance = await api_instance.v1_create_instance({
                    "project": DEFAULT_PROJECT_ID,
                    "name": DEFAULT_INSTANCE_NAME,
                    "flavor": DEFAULT_INSTANCE_HARDWARE,
                    "os": DEFAULT_INSTANCE_FIRMWARE
                })
                print(f'Instance {api_response_create_instance.id} is creating.')
                return api_response_create_instance.id
            except ApiException as e:
                if e.status == 400 and 'insufficient resource: cores' in e.body:
                    raise RuntimeError(f'Insufficient resources to create a new instance: {e.body}')
                else:
                    raise RuntimeError(f'Exception when calling CorelliumApi->v1_create_instance: {e}\n')
            except Exception as e:
                raise RuntimeError(f'Exception in turn_instance_on_or_create_new_instance: {e}\n')
        else:
            raise RuntimeError(f'Exception when calling CorelliumApi->v1_get_instance: {e}\n')
    except Exception as e:
        raise RuntimeError(f'Exception in turn_instance_on_or_create_new_instance: {e}\n')

```

--------------------------------

### Create Project and Device with Corellium API (JavaScript)

Source: https://support.corellium.com/sdk/webplayer/installation

Demonstrates how to create a new project and an instance (device) within that project using the Corellium API. It requires API credentials and specifies device flavor, OS, and boot snapshot. Outputs project and instance IDs.

```javascript
const { Corellium } = require('@corellium/corellium-api');  
  
const flavor = 'iphone6';  
const os = '12.5.6';  
const apiToken = 'my_api_token';  
const endpoint = 'my_endpoint.enterprise.corellium.com';  
const snapshot = 'my_snapshot_id';  
  
const corellium = new Corellium({
  endpoint,  
  apiToken,  
});  
  
const createProjectAndInstance = async () => {
  try {
    const project = await corellium.createProject('Webplayer Project');  

    await project.setQuotas({ cores: 6 });  
      
    const instance = await project.createInstance({
      name: 'Webplayer Device',  
      flavor,
      os,
      bootOptions: {
        snapshot,
      },
    });
  
    console.log('project id :>>', project.id);
    console.log('instance id :>> ', instance.id); // also device id  
  } catch (error) {
    console.error(error);
  }
};
  
createProjectAndInstance();  

```

--------------------------------

### Upload Corellium Private Cloud Installer Package to S3

Source: https://support.corellium.com/setup/private-cloud

This script, `s3_upload.sh`, is used to create an AWS S3 bucket if it doesn't exist and upload the Corellium Private Cloud installer package to it. This is a prerequisite for launching the CPC instance.

```bash
s3_upload.sh
```

--------------------------------

### Install AWS CLI on macOS

Source: https://support.corellium.com/setup/private-cloud/overview

Installs the AWS CLI version 2 on macOS. It downloads the macOS package installer and then uses the `installer` command with root privileges to install it system-wide.

```bash
curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"  
sudo installer -pkg AWSCLIV2.pkg -target /  
```

--------------------------------

### Automate Corellium Student Setup with Shell Script

Source: https://support.corellium.com/sdk/apis/rest/bulk-student-setup-with-the-api

This shell script automates the bulk creation of users, projects, and devices in Corellium. It takes a list of user emails and a device snapshot to set up individual student environments. Dependencies include JQ for JSON parsing. The script requires configuration of authentication tokens, domain, and device snapshot details.

```shell
<<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=(  
"newuser01@corellium.com"  
"newuser02@corellium.com"  
"newuser03@corellium.com"  
)  
  
# 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"

```

--------------------------------

### Example MainActivity for System App

Source: https://support.corellium.com/features/apps/install-custom-android-system-app

Provides a basic `MainActivity` implementation for an Android system app. This code sets up a simple TextView displaying "Hello world!". Ensure the package name matches the one defined in `build.gradle` and `AndroidManifest.xml`.

```java
package com.corellium.mysystemapp;

import android.app.Activity;
import android.os.Bundle;
import android.widget.TextView;

public class MainActivity extends Activity
{
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        TextView label = new TextView(this);
        label.setText("Hello world!");

        setContentView(label);
    }
}
```

--------------------------------

### Bulk User and Device Setup Script (Bash)

Source: https://support.corellium.com/sdk/apis/rest/bulk-student-setup-with-the-api

A comprehensive bash script for bulk user and device setup on Corellium. It iterates through a list of users, creating them if they don't exist, and then proceeds to set up their projects and devices. This script orchestrates multiple API calls for user creation, project assignment, and device cloning.

```bash
# 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
```

--------------------------------

### Install AWS CLI on Windows

Source: https://support.corellium.com/setup/private-cloud/overview

Installs the AWS CLI version 2 on Windows using the Microsoft Installer (MSI). This command downloads and executes the MSI package, performing a standard Windows installation.

```powershell
msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi  
```

--------------------------------

### Install AWS CLI on Linux (x86)

Source: https://support.corellium.com/setup/private-cloud/overview

Installs the AWS CLI version 2 on x86_64 Linux systems. It downloads the zip archive, extracts it, and runs the installation script. Requires root privileges for installation.

```bash
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"  
unzip awscliv2.zip  
sudo ./aws/install  
```

--------------------------------

### Create Device from Snapshot via API (Bash)

Source: https://support.corellium.com/sdk/apis/rest/bulk-student-setup-with-the-api

Creates a new virtual device by cloning it from a specified snapshot using a POST request to the Corellium API. It requires project details, name, OS, flavor, and snapshot ID. The response containing the new device's ID is captured and parsed using jq.

```bash
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"
```

--------------------------------

### Install AWS CLI on Linux (ARM)

Source: https://support.corellium.com/setup/private-cloud/overview

Installs the AWS CLI version 2 on ARM-based Linux systems. This process involves downloading the appropriate zip archive, extracting its contents, and executing the install script with root privileges.

```bash
curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o "awscliv2.zip"  
unzip awscliv2.zip  
sudo ./aws/install  
```

--------------------------------

### Start Monitoring

Source: https://support.corellium.com/features/matrix/sdk

Starts monitoring a virtual device for a specific MATRIX assessment.

```APIDOC
## POST /matrix/{instanceId}/assessments/{assessmentId}/start

### Description
Starts monitoring a virtual device for a specific MATRIX assessment.

### Method
POST

### Endpoint
/matrix/{instanceId}/assessments/{assessmentId}/start

### Parameters
#### Path Parameters
- **instanceId** (string) - Required - The ID of the virtual device.
- **assessmentId** (string) - Required - The ID of the assessment to start monitoring.

#### Query Parameters
- **verbose** (boolean) - Optional - Enables verbose output for the monitoring start.

### Request Example
```bash
corellium matrix start-monitor \
--assessment {assessmentId} \
--instance {instanceId} \
--verbose true
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message that monitoring has started.

#### Response Example
```json
{
  "message": "Monitoring started successfully."
}
```
```

--------------------------------

### Run Corellium API Example (bash)

Source: https://support.corellium.com/sdk/apis/javascript-v1/simple-example

Executes the main JavaScript example file using Node.js. This command initiates the sequence of API operations.

```bash
node main.js.
```

--------------------------------

### Install Application on Corellium Device

Source: https://support.corellium.com/features/matrix/ci

Installs the specified application (IPA file) onto the created Corellium virtual device using the instance ID. This prepares the device for testing.

```bash
      - name: Install application
        run: corellium apps install [app.ipa] --instance ${{ env.instanceId  }} --project ${{ secrets.CORELLIUM_PROJECT_ID }} --verbose true
```

--------------------------------

### Clone Minimal Android Project

Source: https://support.corellium.com/features/apps/install-custom-android-system-app

Clones the `minimal-android-project` repository from GitHub, which serves as a starting point for building custom Android system apps. This step is crucial for setting up the project locally.

```bash
git clone https://github.com/czak/minimal-android-project.git
```

--------------------------------

### Install Node.js and Corellium API Package (Shell)

Source: https://support.corellium.com/sdk/apis/javascript-v1/hold-down-two-virtual-hardware-buttons

These shell commands are used to install Node.js via Homebrew and then install the Corellium API package using npm. This setup is required before executing the JavaScript code for interacting with Corellium devices.

```shell
brew install node
npm install @corellium/corellium-api

```

--------------------------------

### Corellium API: Manage Devices with Python

Source: https://support.corellium.com/sdk/apis/python/example-script

This script utilizes the Corellium Python API to find an existing device by instance ID. If found, it ensures the device is powered on. If not found, it creates a new device with specified hardware and firmware, waits for it to be ready, boots it, checks app subsystem readiness, and lists running applications. Requires 'corellium_api' package and API token/endpoint environment variables.

```python
import os
import sys
import time
import asyncio
from asyncio import TimeoutError
import corellium_api
from corellium_api.rest import ApiException

# Define the default values for the instance
DEFAULT_INSTANCE_ID = 'YOUR_INSTANCE_IDENTIFIER'
DEFAULT_INSTANCE_FIRMWARE = '18.0'
DEFAULT_INSTANCE_HARDWARE = 'iphone16pm'
DEFAULT_INSTANCE_NAME = 'Python_API_demo_device'
DEFAULT_PROJECT_ID = 'YOUR_PROJECT_IDENTIFIER'

# Define time and retry constants
SLEEP_TIME_SECONDS = 60
MAX_RETRIES = 10
WAIT_TIMEOUT_SECONDS = 300

```

--------------------------------

### C++ libcurl: Interact with Corellium API

Source: https://support.corellium.com/sdk/apis/other-languages

This C++ example uses the libcurl library to make a GET request to the Corellium API. It requires linking against libcurl and setting CORELLIUM_API_TOKEN and CORELLIUM_API_ENDPOINT environment variables.

```cpp
#include <iostream>
#include <cstdlib>
#include <cstring>
#include <curl/curl.h>

struct string {
    char *ptr;
    size_t len;
};

void init_string(struct string *s) {
    s->len = 0;
    s->ptr = (char *)malloc(s->len + 1);
    if (s->ptr == NULL) {
        std::cerr << "malloc() failed" << std::endl;
        exit(EXIT_FAILURE);
    }
    s->ptr[0] = '\0';
}

size_t writefunc(void *ptr, size_t size, size_t nmemb, struct string *s) {
    size_t new_len = s->len + size * nmemb;
    s->ptr = (char *)realloc(s->ptr, new_len + 1);
    if (s->ptr == NULL) {
        std::cerr << "realloc() failed" << std::endl;
        exit(EXIT_FAILURE);
    }
    memcpy(s->ptr + s->len, ptr, size * nmemb);
    s->ptr[new_len] = '\0';
    s->len = new_len;

    return size * nmemb;
}

int main() {
    CURL *curl;
    CURLcode res;
    struct string s;
    char *api_key = getenv("CORELLIUM_API_TOKEN");
    char *endpoint = getenv("CORELLIUM_API_ENDPOINT");
    char url[256];

    snprintf(url, sizeof(url), "%s/v1/projects", endpoint);

    init_string(&s);
    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();

    if (curl) {
        struct curl_slist *headers = NULL;
        char auth_header[256];

        snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", api_key);
        headers = curl_slist_append(headers, auth_header);
        headers = curl_slist_append(headers, "Content-Type: application/json");

        curl_easy_setopt(curl, CURLOPT_URL, url);
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writefunc);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &s);

        res = curl_easy_perform(curl);

        if (res != CURLE_OK) {
            std::cerr << "curl_easy_perform() failed: " << curl_easy_strerror(res) << std::endl;
        } else {
            std::cout << s.ptr << std::endl;
        }

        curl_easy_cleanup(curl);
        curl_slist_free_all(headers);
    }

    free(s.ptr);
    curl_global_cleanup();

    return 0;
}

```

--------------------------------

### Corellium Instance Management and Monitoring Functions

Source: https://support.corellium.com/sdk/apis/rest/example-script

This part of the script handles the Corellium instance lifecycle. It checks for the existence of the 'date' command to log the script start time, then calls functions to turn on or create a new instance, waits for the instance to become ready, and finally lists the running applications on the instance.

```shell
command -v date > /dev/null && printf 'Starting the script at %s.\n' "$(date)"

new_instance_id=''
turn_instance_on_or_create_new_instance
instance_id="${new_instance_id:-${DEFAULT_INSTANCE_ID}}"

wait_for_instance_to_turn_on "${instance_id}"
wait_for_instance_agent_to_be_ready "${instance_id}"
print_list_of_running_apps "${instance_id}"
```
Tokens:
Raw