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

Description:

  • The instance boot options.

Source:

The instance boot options.

flavor

Description:

  • The instance flavor, such as iphone6.

Source:

The instance flavor, such as iphone6.

name

Description:

  • The instance name.

Source:

The instance name.

orientation

Description:

  • The instance orientation

Source:

The instance orientation

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:

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

Description:

  • The timestamp when the state last changed.

Source:

The timestamp when the state last changed.

taskState

Description:

  • Return the current task state.

Source:

Return the current task state.

type

Description:

  • The instance type, such as ios.

Source:

The instance type, such as ios.

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:

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

Description:

  • Wait for ...

Source:
Parameters:
Name Type Default Description
reporterFn function null

Called with instance information (optional)

(async) agent() → {Agent}

Description:

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

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

(async) clearCoreTraceFilter()

Description:

  • Clear CoreTrace filter

Source:
Example
await instance.clearCoreTraceFilter();

(async) clearCoreTraceLog()

Description:

  • Clean CoreTrace log

Source:
Example
await instance.clearCoreTraceLog();

(async) clearPanics()

Description:

  • Clear the recorded kernel panics of this instance.

Source:
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:
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.<{id: string, name: string}>

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

Description:

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

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

(async) consoleLog() → {string}

Description:

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

Source:
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:
Parameters:
Name Type Description
kernelImage Image | KernelImage | FirmwareImage

(async) deleteIotFirmware(firmwareImage)

Description:

  • Delete Iot Firmware that is attached to an instance

Source:
Parameters:
Name Type Description
firmwareImage FirmwareImage

(async) deleteKernel(kernelImage)

Description:

  • Delete kernel that is attached to an instance

Source:
Parameters:
Name Type Description
kernelImage KernelImage

(async) destroy()

Description:

  • Destroy this instance.

Source:
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:

(async) downloadCoreTraceLog()

Description:

  • Download CoreTrace Log

Source:
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:
Example
const pcap = await instance.downloadPcap();
console.log(pcap.toString());
Parameters:
Name Type Attributes Description
pcapFile string

Which pcap file you want to download
asStream boolean <optional>

If true, return pcap as stream instead of buffer.
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:

(async) executeFridaScript(filePath)

Description:

  • Execute FRIDA script by name

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

path to FRIDA script

(async) finishRestore(reporterFn)

Description:

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

Source:
Example

Wait for VM to finish restore

instance.finishRestore();
Parameters:
Name Type Default Description
reporterFn function null

Called with instance information (optional)

(async) finishUpgrade(reporterFn)

Description:

  • Wait for the instance to finish upgrading.

Source:
Example

Wait for VM to finish OS upgrade

instance.finishUpgrade();
Parameters:
Name Type Default Description
reporterFn function null

Called with instance information (optional)

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

Description:

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

Source:
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:
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:
Parameters:
Name Type Description
type string

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

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

Description:

  • Get peripheral/sensor data

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

(async) message(number, message)

Description:

  • Send a message to an jailbroken iOS device

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

Description:

  • Send a raw message to an jailbroken iOS device

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

hex encoded data to send

(async) modifyBootOptions(bootOptions)

Description:

  • Change boot options for an instance.

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

Description:

  • Change device peripheral/sensor values.

    Currently available for Android only.

Source:
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) netdump() → {Netdump}

Description:

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

Source:
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:
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:
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:
Returns:
Type
Netdump

(async) newNetworkMonitor() → {NetworkMonitor}

Description:
Source:
Returns:
Type
NetworkMonitor

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

Description:

  • Return an array of recorded kernel panics.

Source:
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:
Example
await instance.pause();

(async) reboot()

Description:

  • Reboot this instance.

Source:
Example
await instance.reboot();

(async) rename(name)

Description:

  • Rename an instance.

Source:
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) restoreBackup(passwordopt)

Description:

  • Restore instance from backup

Source:
Example
await instance.restoreBackup();
Parameters:
Name Type Attributes Description
password string <optional>

Password for encrypted backups

(async) rotate(rotation)

Description:

  • Change device orientation.

Source:
Example
await instance.rotate(1);
Parameters:
Name Type Description
rotation RotationType

The new rotation for the instance.

(async) sendInput(input)

Description:

  • Send an input to this instance.

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

The input to send.

(async) setCoreTraceFilter(pids, names, tids)

Description:

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

Source:
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>}

Description:

  • Return an array of this instance's Snapshots.

Source:
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(options)

Description:

  • Start this instance.

Source:
Example
await instance.start({
 sockcap: true,
 paused: true
});
Parameters:
Name Type Description
options StartOptions

(async) startCoreTrace()

Description:

  • Start CoreTrace

Source:
Example
await instance.startCoreTrace();

(async) stop()

Description:

  • Stop this instance.

Source:
Example
await instance.stop();

(async) stopCoreTrace()

Description:

  • Stop CoreTrace

Source:
Example
await instance.stopCoreTrace();

(async) takeScreenshot(options)

Description:

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

Source:
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}

Description:

  • Take a new snapshot of this instance.

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

Description:

  • Unpause this instance

Source:
Example
await instance.unpause();

(async) upgrade(options)

Description:

  • Upgrade the iOS version of this instance.

Source:
Example
await instance.upgrade({
    os: '16.1',
    osbuild: '20B79'
});
Parameters:
Name Type Description
options UpgradeOptions

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

Description:

  • Add a device tree image to an instance.

Source:
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.<{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:
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.<{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:
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>}

Description:

  • Add a kernel image to an instance

Source:
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>}

Description:

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

Source:
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>}

Description:

  • Add a ram disk image to an instance

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

Description:

  • Waits for a specified line on console.

Source:
Example
await instance.waitForLineOnConsole(line)

(async) waitForState(state, reporterFn)

Description:

  • Wait for the instance to enter the given state.

Source:
Example

Wait for VM to be ON

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

state to wait
reporterFn function null

Called with instance information (optional)

(async) waitForTaskState(reporterFn, taskName)

Description:

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

Source:
Parameters:
Name Type Default Description
reporterFn function null

Called with instance information (optional)
taskName string

(async) waitForUserTask(reporterFn, userTaskName)

Description:

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

Source:
Parameters:
Name Type Default Description
reporterFn function null

Called with instance information (optional)
userTaskName string

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

Description:

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

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