Instance - Documentation

Members

bootOptions

Source:

instance.js, line 185

The instance boot options.

flavor

Source:

instance.js, line 137

The instance flavor, such as iphone6.

name

Source:

instance.js, line 105

The instance name.

state

Source:

instance.js, line 123

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:

instance.js, line 130

The timestamp when the state last changed.

taskState

Source:

instance.js, line 163

Return the current task state.

type

Source:

instance.js, line 144

The instance type, such as ios.

userTask

Source:

instance.js, line 156

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:

instance.js, line 327

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:

instance.js, line 645

Clear CoreTrace filter

Example

await instance.clearCoreTraceFilter();

(async) clearCoreTraceLog()

Source:

instance.js, line 692

Clean CoreTrace log

Example

await instance.clearCoreTraceLog();

(async) clearPanics()

Source:

instance.js, line 315

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:

instance.js, line 944

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:

instance.js, line 462

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:

instance.js, line 291

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:

instance.js, line 902

Delete an image that is attached to an instance

Parameters:

Name	Type	Description
`kernelImage`	Image \| KernelImage \| FirmwareImage

(async) deleteIotFirmware(firmwareImage)

Source:

instance.js, line 886

Delete Iot Firmware that is attached to an instance

Parameters:

Name	Type	Description
`firmwareImage`	FirmwareImage

(async) deleteKernel(kernelImage)

Source:

instance.js, line 894

Delete kernel that is attached to an instance

Parameters:

Name	Type	Description
`kernelImage`	KernelImage

(async) destroy()

Source:

instance.js, line 563

Destroy this instance.

Example

delete all instances of the project

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

(async) disableExposedPort()

Source:

instance.js, line 769

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

(async) downloadCoreTraceLog()

Source:

instance.js, line 679

Download CoreTrace Log

Example

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

(async) enableExposedPort()

Source:

instance.js, line 761

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

(async) executeFridaScript(filePath)

Source:

instance.js, line 722

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:

instance.js, line 842

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:

instance.js, line 703

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:

instance.js, line 605

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:

instance.js, line 246

Get peripheral/sensor data

Example

let peripherals = await instance.getPeripherals();

Returns:

Type: Promise.<PeripheralData>

(async) message(number, message)

Source:

instance.js, line 575

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:

instance.js, line 589

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:

instance.js, line 197

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:

instance.js, line 233

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:

instance.js, line 422

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:

instance.js, line 413

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:

instance.js, line 451

Create a new NetworkMonitor connection to this instance.

Returns:

Type: NetworkMonitor

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

Source:

instance.js, line 304

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:

instance.js, line 531

Pause this instance

Example

await instance.pause();

(async) rate() → {RateInfo}

Source:

instance.js, line 493

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:

instance.js, line 549

Reboot this instance.

Example

await instance.reboot();

(async) rename(name)

Source:

instance.js, line 175

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:

instance.js, line 504

See:

Input

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:

instance.js, line 617

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:

instance.js, line 258

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:

instance.js, line 513

Start this instance.

Example

await instance.start();

(async) startCoreTrace()

Source:

instance.js, line 654

Start CoreTrace

Example

await instance.startCoreTrace();

(async) stop()

Source:

instance.js, line 522

Stop this instance.

Example

await instance.stop();

(async) stopCoreTrace()

Source:

instance.js, line 666

Stop CoreTrace

Example

await instance.stopCoreTrace();

(async) takeScreenshot(options)

Source:

instance.js, line 747

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:

instance.js, line 272

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:

instance.js, line 540

Unpause this instance

Example

await instance.unpause();

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

Source:

instance.js, line 994

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:

instance.js, line 1008

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:

instance.js, line 930

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:

instance.js, line 968

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:

instance.js, line 917

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:

instance.js, line 981

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:

instance.js, line 472

Waits for a specified line on console.

Example

await instance.waitForLineOnConsole(line)

(async) waitForState(state)

Source:

instance.js, line 852

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:

instance.js, line 860

Wait for the instance task to enter the given state.

Parameters:

Name	Type	Description
`taskName`	string

(async) waitForUserTask(userTaskName)

Source:

instance.js, line 868

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:

instance.js, line 1036

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:

instance.js, line 782

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:

instance.js, line 792

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
    }
});