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
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
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
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
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
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:
Create a new NetworkMonitor connection to this instance.
- 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
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
|
(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
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
}
});