Instance

Members

bootOptions

Description:

• The instance boot options.

Source:

• instance.js, line 205

consoleTypes

Description:

• Returns an array of all supported console types for this instance.

Source:

• instance.js, line 874

Example

// types might be ['uart0-cons', 'uart1-cons', ...]
const types = instance.consoleTypes();

flavor

Description:

• The instance flavor, such as iphone6.

Source:

• instance.js, line 150

name

Description:

• The instance name.

Source:

• instance.js, line 118

orientation

Description:

• The instance orientation

Source:

• instance.js, line 164

state

Description:

• 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.

Source:

• instance.js, line 136

stateChanged

Description:

• The timestamp when the state last changed.

Source:

• instance.js, line 143

taskState

Description:

• Return the current task state.

Source:

• instance.js, line 183

type

Description:

• The instance type, such as ios.

Source:

• instance.js, line 157

userTask

Description:

• 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.

Source:

• instance.js, line 176

Methods

(async) _waitFor(reporterFn)

Description:

• Wait for ...

Source:

• instance.js, line 983

Parameters:

(async) agent() → {Agent}

Description:

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

Source:

• instance.js, line 362

Example

let agent = await instance.agent();
await agent.ready();

Returns:

Type

Agent

(async) clearCoreTraceFilter()

Description:

• Clear CoreTrace filter

Source:

• instance.js, line 796

Example

await instance.clearCoreTraceFilter();

(async) clearCoreTraceLog()

Description:

• Clean CoreTrace log

Source:

• instance.js, line 843

Example

await instance.clearCoreTraceLog();

(async) clearPanics()

Description:

• Clear the recorded kernel panics of this instance.

Source:

• instance.js, line 350

Example

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

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

Description:

• compress an image and upload it to an instance

Source:

• instance.js, line 1140

Parameters:

Returns:

Type

Promise.<{id: string, name: string}>

(async) console(nameopt) → {Promise.<WebSocket>}

Description:

• Creates and returns a bidirectional WebSocket stream for accessing console output. If no console name is specified, returns the default console stream.

Source:

• instance.js, line 572

Examples

// Connect to default console
const consoleStream = await instance.console();
consoleStream.pipe(process.stdout);

// Connect to a specific named console
const uartConsole = await instance.console('uart-0');
uartConsole.pipe(process.stdout);

Parameters:

Throws:

If the console connection cannot be established

Type

Error

Returns:

Type

Promise.<WebSocket>

(async) consoleLog() → {string}

Description:

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

Source:

• instance.js, line 326

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)

Description:

• Delete an image that is attached to an instance

Source:

• instance.js, line 1086

Parameters:

(async) deleteIotFirmware(firmwareImage)

Description:

• Delete Iot Firmware that is attached to an instance

Source:

• instance.js, line 1070

Parameters:

(async) deleteKernel(kernelImage)

Description:

• Delete kernel that is attached to an instance

Source:

• instance.js, line 1078

Parameters:

(async) destroy()

Description:

• Destroy this instance.

Source:

• instance.js, line 711

Example

delete all instances of the project

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

(async) disableExposedPort()

Description:

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

Source:

• instance.js, line 931

(async) downloadCoreTraceLog()

Description:

• Download CoreTrace Log

Source:

• instance.js, line 830

Example

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

(async) downloadPcap(pcapFile, asStreamopt) → {Promise.<(Buffer|NodeJS.ReadableStream)>}

Description:

• Download specified pcap file. If pcapFile is not given or is invalid, default to netdump.pcap

Source:

• instance.js, line 499

Example

const pcap = await instance.downloadPcap();
console.log(pcap.toString());

Parameters:

Returns:

Type

Promise.<(Buffer|NodeJS.ReadableStream)>

(async) enableExposedPort()

Description:

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

Source:

• instance.js, line 923

(async) executeFridaScript(filePath)

Description:

• Execute FRIDA script by name

Source:

• instance.js, line 884

Example

await instance.executeFridaScript("/data/corellium/frida/scripts/script.js");

Parameters:

(async) finishRestore(reporterFn)

Description:

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

Source:

• instance.js, line 1023

Example

Wait for VM to finish restore

instance.finishRestore();

Parameters:

(async) finishUpgrade(reporterFn)

Description:

• Wait for the instance to finish upgrading.

Source:

• instance.js, line 1013

Example

Wait for VM to finish OS upgrade

instance.finishUpgrade();

Parameters:

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

Description:

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

Source:

• instance.js, line 854

Example

const consoleStream = await instance.fridaConsole();
consoleStream.pipe(process.stdout);

Returns:

Type

WebSocket-Stream

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

Description:

• Get CoreTrace Thread List

Source:

• instance.js, line 753

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) getImages(type)

Description:

• Get all images attached to this instance with optional type

Source:

• instance.js, line 1096

Parameters:

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

Description:

• Get peripheral/sensor data

Source:

• instance.js, line 281

Example

let peripherals = await instance.getPeripherals();

Returns:

Type

Promise.<PeripheralData>

(async) message(number, message)

Description:

• Send a message to an jailbroken iOS device

Source:

• instance.js, line 723

Example

await instance.message('123','321');

Parameters:

(async) messageRaw(data)

Description:

• Send a raw message to an jailbroken iOS device

Source:

• instance.js, line 737

Example

await instance.messageRaw('AAAAAAAAAAAAAAAAA');

Parameters:

(async) modifyBootOptions(bootOptions)

Description:

• Change boot options for an instance.

Source:

• instance.js, line 217

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:

(async) modifyPeripherals(peripheralData)

Description:

• Change device peripheral/sensor values.

  Currently available for Android only.

Source:

• instance.js, line 253

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:

(async) netdump() → {Netdump}

Description:

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

Source:

• instance.js, line 457

Returns:

Type

Netdump

(async) networkMonitor() → {Promise.<NetworkMonitor>}

Description:

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

Source:

• instance.js, line 521

Returns:

Type

Promise.<NetworkMonitor>

(async) newAgent() → {Agent}

Description:

• 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.

Source:

• instance.js, line 448

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) newNetdump() → {Netdump}

Description:

• Create a new Netdump connection to this instance.

Source:

• instance.js, line 486

Returns:

Type

Netdump

(async) newNetworkMonitor() → {NetworkMonitor}

Description:

• Create a new NetworkMonitor connection to this instance.

Source:

• instance.js, line 550

Returns:

Type

NetworkMonitor

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

Description:

• Return an array of recorded kernel panics.

Source:

• instance.js, line 339

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()

Description:

• Pause this instance

Source:

• instance.js, line 642

Example

await instance.pause();

(async) reboot()

Description:

• Reboot this instance.

Source:

• instance.js, line 660

Example

await instance.reboot();

(async) rename(name)

Description:

• Rename an instance.

Source:

• instance.js, line 195

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:

(async) restoreBackup(passwordopt)

Description:

• Restore instance from backup

Source:

• instance.js, line 672

Example

await instance.restoreBackup();

Parameters:

(async) rotate(rotation)

Description:

• Change device orientation.

Source:

• instance.js, line 265

Example

await instance.rotate(1);

Parameters:

(async) sendInput(input)

Description:

• Send an input to this instance.

Source:

• instance.js, line 605

See:

• Input

Examples

await instance.sendInput(I.pressRelease('home'));

await instance.sendInput([{ "text": "Hello, world" }]);

Parameters:

(async) setCoreTraceFilter(pids, names, tids)

Description:

• Add List of PIDs/Names/TIDs to CoreTrace filter

Source:

• instance.js, line 765

Example

await instance.setCoreTraceFilter([111, 222], ["proc_name"], [333]);

Parameters:

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

Description:

• Return an array of this instance's Snapshots.

Source:

• instance.js, line 293

Example

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

Returns:

Type

Array.<Snapshot>

(async) start(options)

Description:

• Start this instance.

Source:

• instance.js, line 624

Example

await instance.start({
 sockcap: true,
 paused: true
});

Parameters:

(async) startCoreTrace()

Description:

• Start CoreTrace

Source:

• instance.js, line 805

Example

await instance.startCoreTrace();

(async) stop()

Description:

• Stop this instance.

Source:

• instance.js, line 633

Example

await instance.stop();

(async) stopCoreTrace()

Description:

• Stop CoreTrace

Source:

• instance.js, line 817

Example

await instance.stopCoreTrace();

(async) takeScreenshot(options)

Description:

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

Source:

• instance.js, line 909

Example

const screenshot = await instance.takeScreenshot();
fs.writeFileSync('screenshot.png', screenshot);

Parameters:

(async) takeSnapshot(name) → {Snapshot}

Description:

• Take a new snapshot of this instance.

Source:

• instance.js, line 307

Example

const instances = await project.instances();
const instance = instances.find(instance => instance.name == 'foo');
await instance.takeSnapshot("TestSnapshot");

Parameters:

Returns:

Type

Snapshot

(async) unpause()

Description:

• Unpause this instance

Source:

• instance.js, line 651

Example

await instance.unpause();

(async) upgrade(options)

Description:

• Upgrade the iOS version of this instance.

Source:

• instance.js, line 695

Example

await instance.upgrade({
    os: '16.1',
    osbuild: '20B79'
});

Parameters:

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

Description:

• Add a device tree image to an instance.

Source:

• instance.js, line 1190

Parameters:

Returns:

Type

Promise.<DeviceTreeImage>

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

Description:

• 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.

Source:

• instance.js, line 1204

Parameters:

Returns:

Type

Promise.<{id: string, name: string}>

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

Description:

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

Source:

• instance.js, line 1126

Parameters:

Returns:

Type

Promise.<FirmwareImage>

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

Description:

• Add a kernel image to an instance

Source:

• instance.js, line 1164

Parameters:

Returns:

Type

Promise.<KernelImage>

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

Description:

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

Source:

• instance.js, line 1113

Parameters:

Returns:

Type

Promise.<PartitionImage>

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

Description:

• Add a ram disk image to an instance

Source:

• instance.js, line 1177

Parameters:

Returns:

Type

Promise.<RamDiskImage>

(async) waitForLineOnConsole()

Description:

• Waits for a specified line on console.

Source:

• instance.js, line 582

Example

await instance.waitForLineOnConsole(line)

(async) waitForState(state, reporterFn)

Description:

• Wait for the instance to enter the given state.

Source:

• instance.js, line 1034

Example

Wait for VM to be ON

instance.waitForState('on');

Parameters:

(async) waitForTaskState(reporterFn, taskName)

Description:

• Wait for the instance task to enter the given state.

Source:

• instance.js, line 1043

Parameters:

(async) waitForUserTask(reporterFn, userTaskName)

Description:

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

Source:

• instance.js, line 1052

Parameters:

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

Description:

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

Source:

• instance.js, line 1234

Example

let webplayer = instance.webplayer(features, permissions);

Parameters:

Returns:

Type

Promise.<(WebPlayer|null)>

Events

change

Description:

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

Source:

• instance.js, line 944

Example

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

panic

Description:

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

Source:

• instance.js, line 954

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