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.

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

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