Instance

Instance

Instances of this class are returned from Project#instances, Project#getInstance, and Project#createInstance. They should not be created using the constructor.

Members

bootOptions

Source:

The instance boot options.

flavor

Source:

The instance flavor, such as iphone6.

name

Source:

The instance name.

state

Source:

The instance state. Possible values include:

State Description
on The instance is powered on.
off The instance is powered off.
creating The instance is in the process of creating.
deleting The instance is in the process of deleting.
deleted The instance is deleted, instance will set to undefined.
paused The instance is paused.

A full list of possible values is available in the API documentation.

stateChanged

Source:

The timestamp when the state last changed.

taskState

Source:

Return the current task state.

type

Source:

The instance type, such as ios.

userTask

Source:

The pending task that is being requested by the user and is being executed by the backend. This field is null when no tasks are pending. The returned object has two fields: name and options.

Current options for name are start, stop, pause, unpause, snapshot, revert. For start and revert, options.bootOptions contains the boot options the instance is to be started with.

Methods

(async) agent() → {Agent}

Source:

Return an Agent connected to this instance. Calling this method multiple times will reuse the same agent connection.

Example
let agent = await instance.agent();
await agent.ready();
Returns:
Type
Agent

(async) clearCoreTraceFilter()

Source:

Clear CoreTrace filter

Example
await instance.clearCoreTraceFilter();

(async) clearCoreTraceLog()

Source:

Clean CoreTrace log

Example
await instance.clearCoreTraceLog();

(async) clearPanics()

Source:

Clear the recorded kernel panics of this instance.

Example
const instances = await project.instances();
const instance = instances.find(instance => instance.name == 'foo');
await instance.clearPanics();

(async) compressAndUploadImage(type, filePath, name, progressopt) → {Promise.<Image>}

Source:

compress an image and upload it to an instance

Parameters:
Name Type Attributes Description
type string

the type of image being uploaded ie. kernel, ramdisk, or devicetree

filePath string

The path on the local file system to get the file.

name string

The name of the file to identify the file on the server. Usually the basename of the path.

progress Project~progressCallback <optional>

The callback for file upload progress information.

Returns:
Type
Promise.<Image>

(async) console() → {WebSocket-Stream}

Source:

Returns a bidirectional node stream for this instance's serial console.

Example
const consoleStream = await instance.console();
consoleStream.pipe(process.stdout);
Returns:
Type
WebSocket-Stream

(async) consoleLog() → {string}

Source:

Returns a dump of this instance's serial port log.

Example
const instances = await project.instances();
const instance = instances.find(instance => instance.name == 'foo');
console.log(await instance.consoleLog());
Returns:
Type
string

(async) deleteImage(kernelImage)

Source:

Delete an image that is attached to an instance

Parameters:
Name Type Description
kernelImage Image | KernelImage | FirmwareImage

(async) deleteIotFirmware(firmwareImage)

Source:

Delete Iot Firmware that is attached to an instance

Parameters:
Name Type Description
firmwareImage FirmwareImage

(async) deleteKernel(kernelImage)

Source:

Delete kernel that is attached to an instance

Parameters:
Name Type Description
kernelImage KernelImage

(async) destroy()

Source:

Destroy this instance.

Example

delete all instances of the project

let instances = await project.instances();
instances.forEach(instance => {
    instance.destroy();
});

(async) disableExposedPort()

Source:

Disable exposing a port for connecting to VM. For iOS, this would mean ssh, for Android, adb access.

(async) downloadCoreTraceLog()

Source:

Download CoreTrace Log

Example
let trace = await instance.downloadCoreTraceLog();
console.log(trace.toString());

(async) enableExposedPort()

Source:

Enable exposing a port for connecting to VM. For iOS, this would mean ssh, for Android, adb access.

(async) executeFridaScript(filePath)

Source:

Execute FRIDA script by name

Example
await instance.executeFridaScript("/data/corellium/frida/scripts/script.js");
Parameters:
Name Type Description
filePath string

path to FRIDA script

(async) finishRestore()

Source:

Wait for the instance to finish restoring and start its first boot.

Example

Wait for VM to finish restore

instance.finishRestore();

(async) fridaConsole() → {WebSocket-Stream}

Source:

Returns a bidirectional node stream for this instance's frida console.

Example
const consoleStream = await instance.fridaConsole();
consoleStream.pipe(process.stdout);
Returns:
Type
WebSocket-Stream

(async) getCoreTraceThreadList() → {Promise.<Array.<ThreadInfo>>}

Source:

Get CoreTrace Thread List

Example
let procList = await instance.getCoreTraceThreadList();
for (let p of procList) {
    console.log(p.pid, p.kernelId, p.name);
    for (let t of p.threads) {
        console.log(t.tid, t.kernelId);
    }
}
Returns:
Type
Promise.<Array.<ThreadInfo>>

(async) getPeripherals() → {Promise.<PeripheralData>}

Source:

Get peripheral/sensor data

Example
let peripherals = await instance.getPeripherals();
Returns:
Type
Promise.<PeripheralData>

(async) message(number, message)

Source:

Send a message to an jailbroken iOS device

Example
await instance.message('123','321');
Parameters:
Name Type Description
number string

phone number to receive the message from

message string

message to receive

(async) messageRaw(data)

Source:

Send a raw message to an jailbroken iOS device

Example
await instance.messageRaw('AAAAAAAAAAAAAAAAA');
Parameters:
Name Type Description
data string

hex encoded data to send

(async) modifyBootOptions(bootOptions)

Source:

Change boot options for an instance.

Example

Changing the boot arguments for the instance.

const instances = await project.instances();
const instance = instances.find(instance => instance.name == 'foo');
await instance.modifyBootOptions(Object.assign({}, instance.bootOptions, {bootArgs: 'new-boot-args'}));
Parameters:
Name Type Description
bootOptions Object

The new boot options for the instance.

(async) modifyPeripherals(peripheralData)

Source:

Change device peripheral/sensor values.

Currently available for Android only.

Example

Changing the sensor values for the instance.

const instances = await project.instances();
const instance = instances.find(instance => instance.name == 'foo');
await instance.modifyPeripherals({
    "gpsToffs": "0.000000",
    "gpsLat": "37.414300",
    "gpsLon": "-122.077400",
    "gpsAlt": "45.000000",
    "acOnline": "1",
    "batteryPresent": "1",
    "batteryStatus": "discharging",
    "batteryHealth": "overheat",
    "batteryCapacity": "99.000000",
    "acceleration": "0.000000,9.810000,0.000000",
    "gyroscope": "0.000000,0.000000,0.000000",
    "magnetic": "0.000000,45.000000,0.000000",
    "orientation": "0.000000,0.000000,0.000000",
    "temperature": "25.000000",
    "proximity": "50.000000",
    "light": "20.000000",
    "pressure": "1013.250000",
    "humidity": "55.000000"
}));
Parameters:
Name Type Description
peripheralData PeripheralData

The new peripheral options for the instance.

(async) networkMonitor() → {NetworkMonitor}

Source:

Return an NetworkMonitor connected to this instance. Calling this method multiple times will reuse the same agent connection.

Returns:
Type
NetworkMonitor

(async) newAgent() → {Agent}

Source:

Create a new Agent connection to this instance. This is useful for agent tasks that don't finish and thus consume the connection, such as Agent#crashes.

Example
let crashListener = await instance.newAgent();
crashListener.crashes('com.corellium.demoapp', (err, crashReport) => {
    if (err) {
        console.error(err);
        return;
    }
    console.log(crashReport);
});
Returns:
Type
Agent

(async) newNetworkMonitor() → {NetworkMonitor}

Source:

Create a new NetworkMonitor connection to this instance.

Returns:
Type
NetworkMonitor

(async) panics() → {Promise.<Array.<PanicInfo>>}

Source:

Return an array of recorded kernel panics.

Example
const instances = await project.instances();
const instance = instances.find(instance => instance.name == 'foo');
console.log(await instance.panics());
Returns:
Type
Promise.<Array.<PanicInfo>>

(async) pause()

Source:

Pause this instance

Example
await instance.pause();

(async) rate() → {RateInfo}

Source:

Returns the cost, in microcents, for the instance in the on and off state. Instances are charged $0.25 / day for storage (off) and $0.25 per core per hour (on).

Example
const rateInfo = await instance.rate();
Returns:
Type
RateInfo

(async) reboot()

Source:

Reboot this instance.

Example
await instance.reboot();

(async) rename(name)

Source:

Rename an instance.

Example

Renaming the first instance named `foo` to `bar`

const instances = await project.instances();
const instance = instances.find(instance => instance.name == 'foo');
await instance.rename('bar');
Parameters:
Name Type Description
name string

The new name of the instance.

(async) sendInput(input)

Source:
See:

Send an input to this instance.

Example
await instance.sendInput(I.pressRelease('home'));
Parameters:
Name Type Description
input Input

The input to send.

(async) setCoreTraceFilter(pids, names, tids)

Source:

Add List of PIDs/Names/TIDs to CoreTrace filter

Example
await instance.setCoreTraceFilter([111, 222], ["proc_name"], [333]);
Parameters:
Name Type Description
pids Array.<integer>

array of process IDs to filter

names Array.<string>

array of process names to filter

tids Array.<integer>

array of thread IDs to filter

(async) snapshots() → {Array.<Snapshot>}

Source:

Return an array of this instance's Snapshots.

Example
const instances = await project.instances();
const instance = instances.find(instance => instance.name == 'foo');
await instance.snapshots();
Returns:

This instance's snapshots

Type
Array.<Snapshot>

(async) start()

Source:

Start this instance.

Example
await instance.start();

(async) startCoreTrace()

Source:

Start CoreTrace

Example
await instance.startCoreTrace();

(async) stop()

Source:

Stop this instance.

Example
await instance.stop();

(async) stopCoreTrace()

Source:

Stop CoreTrace

Example
await instance.stopCoreTrace();

(async) takeScreenshot(options)

Source:

Takes a screenshot of this instance's screen. Returns a Buffer containing image data.

Example
const screenshot = await instance.takeScreenshot();
fs.writeFileSync('screenshot.png', screenshot);
Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Default Description
format string <optional>
png

Either png or jpg.

scale int <optional>
1

The image scale. Specifying 2 would result in an image with half the instance's native resolution. This is useful because smaller images are quicker to capture and transmit over the network.

(async) takeSnapshot(name) → {Snapshot}

Source:

Take a new snapshot of this instance.

Example
const instances = await project.instances();
const instance = instances.find(instance => instance.name == 'foo');
await instance.takeSnapshot("TestSnapshot");
Parameters:
Name Type Description
name string

The name for the new snapshot.

Returns:

The new snapshot

Type
Snapshot

(async) unpause()

Source:

Unpause this instance

Example
await instance.unpause();

(async) uploadDeviceTree(filePath, name, progressopt) → {Promise.<DeviceTreeImage>}

Source:

Add a device tree image to an instance.

Parameters:
Name Type Attributes Description
filePath string

The path on the local file system to get the device tree file.

name string

The name of the file to identify the file on the server. Usually the basename of the path.

progress Project~progressCallback <optional>

The callback for file upload progress information.

Returns:
Type
Promise.<DeviceTreeImage>

(async) uploadImage(type, filePath, name, progressopt) → {Promise.<Image>}

Source:

Add an image to the instance. These images may be removed at any time and are meant to facilitate creating a new Instance with images.

Parameters:
Name Type Attributes Description
type string

E.g. fw for the main firmware image.

filePath string

The path on the local file system to get the file.

name string

The name of the file to identify the file on the server. Usually the basename of the path.

progress Project~progressCallback <optional>

The callback for file upload progress information.

Returns:
Type
Promise.<Image>

(async) uploadIotFirmware(filePath, name, progressopt) → {Promise.<FirmwareImage>}

Source:

Add a custom IoT firmware image to a project for use in creating new instances.

Parameters:
Name Type Attributes Description
filePath string

The path on the local file system to get the firmware file.

name string

The name of the file to identify the file on the server. Usually the basename of the path.

progress Project~progressCallback <optional>

The callback for file upload progress information.

Returns:
Type
Promise.<FirmwareImage>

(async) uploadKernel(filePath, name, progressopt) → {Promise.<KernelImage>}

Source:

Add a kernel image to an instance

Parameters:
Name Type Attributes Description
filePath string

The path on the local file system to get the kernel file.

name string

The name of the file to identify the file on the server. Usually the basename of the path.

progress Project~progressCallback <optional>

The callback for file upload progress information.

Returns:
Type
Promise.<KernelImage>

(async) uploadPartition(filePath, name, progressopt) → {Promise.<PartitionImage>}

Source:

Upload a partition (e.g. flash) to an instance.

Parameters:
Name Type Attributes Description
filePath string

The path on the local file system to get the firmware file.

name string

The name of the partition to load this file to.

progress Project~progressCallback <optional>

The callback for file upload progress information.

Returns:
Type
Promise.<PartitionImage>

(async) uploadRamDisk(filePath, name, progressopt) → {Promise.<RamDiskImage>}

Source:

Add a ram disk image to an instance

Parameters:
Name Type Attributes Description
filePath string

The path on the local file system to get the ram disk file.

name string

The name of the file to identify the file on the server. Usually the basename of the path.

progress Project~progressCallback <optional>

The callback for file upload progress information.

Returns:
Type
Promise.<RamDiskImage>

(async) waitForLineOnConsole()

Source:

Waits for a specified line on console.

Example
await instance.waitForLineOnConsole(line)

(async) waitForState(state)

Source:

Wait for the instance to enter the given state.

Example

Wait for VM to be ON

instance.waitForState('on');
Parameters:
Name Type Description
state string

state to wait

(async) waitForTaskState(taskName)

Source:

Wait for the instance task to enter the given state.

Parameters:
Name Type Description
taskName string

(async) waitForUserTask(userTaskName)

Source:

Wait for the instance user task name to be a given state.

Parameters:
Name Type Description
userTaskName string

(async) webplayer(features, permissions, expiresInnullable) → {Promise.<(WebPlayer|null)>}

Source:

Return a WebPlayer session tied to this instance. Calling this method multiple times will reuse the same webplayer.

Example
let webplayer = instance.webplayer(features, permissions);
Parameters:
Name Type Attributes Description
features object

The enabled frontend feature set for this session

permissions object

The endpoint permissions for this session

expiresIn number <nullable>

Number of seconds until the token expires (default: 15 minutes)

Returns:
Type
Promise.<(WebPlayer|null)>

Events

change

Source:

Fired when a property of an instance changes, such as its name or its state.

Example
instance.on('change', () => {
    console.log(instance.id, instance.name, instance.state);
});

panic

Source:

Fired when an instance panics. The panic information can be retrieved with Instance#panics.

Example
instance.on('panic', async () => {
    try {
        console.log('Panic detected!');
        // get the panic log(s)
        console.log(await instance.panics());
        // Download the console log.
        console.log(await instance.consoleLog());
        // Clear the panic log.
        await instance.clearPanics();
        // Reboot the instance.
        await instance.reboot();
    } catch (e) {
        // handle the error somehow to avoid an unhandled promise rejection
    }
});