Agent - Documentation

Methods

(async) appList() → {Promise.<Array.<AppListEntry>>}

Description:

Returns an array of installed apps.

Source:

agent.js, line 478

Example

let appList = await agent.appList();
for (app of appList) {
    console.log('Found installed app ' + app['bundleID']);
}

Returns:

Type: Promise.<Array.<AppListEntry>>

(async) changeFileAttributes(path, attributes) → {Promise.<CommandResult>}

Description:

Change file attributes of the file at the specified path on the VM's filesystem.

Source:

agent.js, line 768

Example

await agent.changeFileAttributes(filePath, {mode: 511});

Parameters:

Name	Type	Description
`path`	string	The path of the file on the VM's filesystem to delete.
`attributes`	Object	An object whose members and values are the file attributes to change and what to change them to respectively. File attributes path, mode, uid and gid are supported.

Returns:

Type: Promise.<CommandResult>

(async) connectToWifi()

Description:

Connect device to WiFi.

Source:

agent.js, line 897

Example

await agent.connectToWifi();

(async) crashes()

Description:

Subscribe to crash events for the app with the given bundle ID. The callback will be called as soon as the agent finds a new crash log.

The callback takes two parameters:
- err, which is undefined unless an error occurred setting up or waiting for crash logs
- crash, which contains the full crash report data
Note: Since this method blocks the communication channel of the agent to wait for crash reports, a new Agent connection should be created with Instance#newAgent.

Source:

agent.js, line 796

See:

Agent#disconnect

Example

const crashListener = await instance.newAgent();
crashListener.crashes("com.corellium.demoapp", (err, crashReport) => {
    if (err) {
        console.error(err);
        return;
    }
    console.log(crashReport);
});

(async) deleteFile(path)

Description:

Delete the file at the specified path on the VM's filesystem.

Source:

agent.js, line 755

Example

await agent.deleteFile('/var/tmp/test.log');

Parameters:

Name	Type	Description
`path`	string	The path of the file on the VM's filesystem to delete.

(async) disableSSLPinning()

Description:

Disables SSL pinning.

Source:

agent.js, line 873

Example

await agent.disableSSLPinning();

(async) disableUIAutomation()

Description:

Disables UI Automation.

Source:

agent.js, line 843

Example

await agent.disableUIAutomation();

disconnect()

Description:

Disconnect an agent connection. This is usually only required if a new agent connection has been created and is no longer needed, for example if the crashListener in the example at Agent#crashes is not needed anymore.

Source:

agent.js, line 314

Example

agent.disconnect();

(async) disconnectFromWifi()

Description:

Disconnect device from WiFi.

Source:

agent.js, line 905

Example

await agent.disconnectFromWifi();

download(path) → {Readable}

Description:

Downloads the file at the given path from the VM's filesystem. Returns a node ReadableStream.

Source:

agent.js, line 702

Example

const dl = agent.download('/var/tmp/test.log');
dl.pipe(fs.createWriteStream('test.log'));

Parameters:

Name	Type	Description
`path`	string	The path of the file to download.

Returns:

Type: Readable

(async) enableSSLPinning()

Description:

Enables SSL pinning.

Source:

agent.js, line 865

Example

await agent.enableSSLPinning();

(async) enableUIAutomation()

Description:

Enables UI Automation.

Source:

agent.js, line 835

Example

await agent.enableUIAutomation();

(async) getProfile(profileID) → {Promise.<Buffer>}

Description:

Gets Mobile Configuration profile binary

Source:

agent.js, line 575

Example

var profile = await agent.getProfile('com.test.myprofile');

Parameters:

Name	Type	Description
`profileID`	string	profile ID

Returns:

Type: Promise.<Buffer>

(async) getProp()

Description:

Get device property.

Source:

agent.js, line 910

(async) install(path, progressopt)

Description:

Installs an app. The app's IPA must be available on the VM's filesystem. A progress callback may be provided.

Source:

agent.js, line 524

See:

Agent#upload to upload a file to the VM's filesystem
Agent#installFile to handle both the upload and install

Example

await agent.install('/var/tmp/temp.ipa', (progress, status) => {
    console.log(progress, status);
});

Parameters:

Name	Type	Attributes	Description
`path`	string		The path of the IPA on the VM's filesystem.
`progress`	Agent~progressCallback	<optional>	An optional callback that will be called with information on the progress of the installation.

(async) installFile(stream, installProgress, uploadProgress)

Description:

Reads a packaged app from the provided stream, uploads the app to the VM using Agent#upload, and installs it using Agent#install.

Source:

agent.js, line 729

Example

await agent.installFile(fs.createReadStream('test.ipa'), (installProgress, installStatus) => {
    console.log(installProgress, installStatus);
});

Parameters:

Name	Type	Description
`stream`	ReadableStream	The app to install, the stream will be closed after it is uploaded.
`installProgress`	Agent~progressCallback	The callback for install progress information.
`uploadProgress`	Agent~uploadProgressCallback	The callback for file upload progress information.

(async) installProfile(profile)

Description:

Installs Mobile Configuration profile

Source:

agent.js, line 552

Example

var profile = fs.readFileSync(path.join(__dirname, "myprofile.mobileconfig"));
await agent.installProfile(profile);

Parameters:

Name	Type	Description
`profile`	Buffer	profile binary

(async) installProvisioningProfile(profile, trust)

Description:

Installs Provisioning profile

Source:

agent.js, line 604

Example

var profile = fs.readFileSync(path.join(__dirname, "embedded.mobileprovision"));
await agent.installProvisioningProfile(profile, true);

Parameters:

Name	Type	Default	Description
`profile`	Buffer		profile binary
`trust`	Boolean	`false`	immediately trust installed profile

(async) isSSLPinningEnabled() → {boolean}

Description:

Checks if SSL pinning is enabled. By default SSL pinning is disabled.

Source:

agent.js, line 857

Example

let enabled = await agent.isSSLPinningEnabled();
if (enabled) {
    console.log("enabled");
} else {
    console.log("disabled");
}

Returns:

Type: boolean

(async) kill(bundleID)

Description:

Kill the app with the given bundle ID, if it is running.

Source:

agent.js, line 465

Example

await agent.kill("com.corellium.demoapp");

Parameters:

Name	Type	Description
`bundleID`	string	The bundle ID of the app to kill.

(async) listProvisioningProfiles() → {Promise.<Array.<ProvisioningProfileInfo>>}

Description:

Returns an array of Provisioning profile descriptions

Source:

agent.js, line 591

Example

let profiles = await agent.listProvisioningProfiles();
for (p of profiles) {
    console.log(p['uuid']);
}

Returns:

Type: Promise.<Array.<ProvisioningProfileInfo>>

(async) lockDevice()

Description:

Locks the device software-wise.

Source:

agent.js, line 819

Example

await agent.lockDevice();

(async) preApproveProvisioningProfile(certID, profileID)

Description:

Approves (makes trusted) profile which will be installed later in a future for example during app installation via Xcode.

Source:

agent.js, line 630

Example

await agent.preApproveProvisioningProfile('Apple Development: my@email.com (NKJDZ3DZJB)', 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa');

Parameters:

Name	Type	Description
`certID`	string	profile ID
`profileID`	string	profile ID

(async) profileList() → {Promise.<Array.<string>>}

Description:

Returns an array of Mobile Configuration profile IDs

Source:

agent.js, line 540

Example

let profiles = await agent.profileList();
for (p of profiles) {
    console.log('Found configuration profile: ' + p);
}

Returns:

Type: Promise.<Array.<string>>

(async) ready()

Description:

Wait for the instance to be ready to use. On iOS, this will wait until Springboard has launched.

Source:

agent.js, line 407

Example

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

(async) removeProfile(profileID)

Description:

Deletes Mobile Configuration profile

Source:

agent.js, line 564

Example

await agent.removeProfile('com.test.myprofile');

Parameters:

Name	Type	Description
`profileID`	string	profile ID

(async) removeProvisioningProfile(profileID)

Description:

Deletes Provisioning profile

Source:

agent.js, line 617

Example

await agent.removeProvisioningProfile('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa');

Parameters:

Name	Type	Description
`profileID`	string	profile ID

(async) run(bundleID)

Description:

Launches the app with the given bundle ID.

Source:

agent.js, line 433

Example

await agent.run("com.corellium.demoapp");

Parameters:

Name	Type	Description
`bundleID`	string	The bundle ID of the app to launch.

(async) runActivity(bundleID, activity)

Description:

Launches the app with the given bundle ID.

Source:

agent.js, line 455

Example

await agent.runActivity('com.corellium.test.app', 'com.corellium.test.app/com.corellium.test.app.CrashActivity');

Parameters:

Name	Type	Description
`bundleID`	string	The bundle ID of the app to launch, for android this is the package name.
`activity`	string	fully qualified activity to launch from bundleID

(async) runFrida(pid, name) → {Promise.<CommandResult>}

Description:

Run frida on the device. Please note that both arguments (pid and name) need to be provided as they are required by the Web UI.

Source:

agent.js, line 923

Example

await agent.runFrida(449, 'keystore');

Parameters:

Name	Type	Description
`pid`	integer
`name`	string

Returns:

Type: Promise.<CommandResult>

(async) runFridaKill() → {Promise.<CommandResult>}

Description:

Run frida-kill on the device.

Source:

agent.js, line 953

Example

await agent.runFridaKill();

Returns:

Type: Promise.<CommandResult>

(async) runFridaPs() → {Promise.<FridaPsResult>}

Description:

Run frida-ps on the device and return the command's output.

Source:

agent.js, line 943

Example

let procList = await agent.runFridaPs();
let lines = procList.output.trim().split('\n');
lines.shift();
lines.shift();
for (const line of lines) {
    const [pid, name] = line.trim().split(/\s+/);
    console.log(pid, name);
}

Returns:

Type: Promise.<FridaPsResult>

(async) shellExec(cmd) → {Promise.<ShellExecResult>}

Description:

Executes a given command

Source:

agent.js, line 444

Example

await agent.shellExec("uname");

Parameters:

Name	Type	Description
`cmd`	string	The cmd to execute

Returns:

Type: Promise.<ShellExecResult>

(async) shutdown()

Description:

Shuts down the device.

Source:

agent.js, line 881

Example

await agent.shutdown();

(async) stat() → {Promise.<StatEntry>}

Description:

Gets information about the file at the specified path. Fields are atime, mtime, ctime (in seconds after the epoch), size, mode (see mode_t in man 2 stat), uid, gid. If the path specified is a directory, an entries field will be present with the same structure (and an additional name field) for each immediate child of the directory.

Source:

agent.js, line 490

Example

let scripts = await agent.stat('/data/corellium/frida/scripts/');

Returns:

Type: Promise.<StatEntry>

(async) tempFile() → {Promise.<string>}

Description:

Returns a temporary random filename on the VMs filesystem that by the time of invocation of this method is guaranteed to be unique.

Source:

agent.js, line 643

See:

example at Agent#upload

Returns:

Type: Promise.<string>

(async) uninstall(bundleID, progress)

Description:

Uninstalls the app with the given bundle ID.

Source:

agent.js, line 420

Example

await agent.uninstall('com.corellium.demoapp', (progress, status) => {
    console.log(progress, status);
});

Parameters:

Name	Type	Description
`bundleID`	string	The bundle ID of the app to uninstall.
`progress`	Agent~progressCallback	The progress callback.

(async) unlockDevice()

Description:

Unlocks the device software-wise.

Source:

agent.js, line 827

Example

awaitagent.unlockDevice();

(async) upload(path, stream, progress)

Description:

Reads from the specified stream and uploads the data to a file on the VM.

Source:

agent.js, line 657

Example

const tmpName = await agent.tempFile();
await agent.upload(tmpName, fs.createReadStream('test.ipa'));

Parameters:

Name	Type	Description
`path`	string	The file path to upload the data to.
`stream`	ReadableStream	The stream to read the file data from.
`progress`	Agent~uploadProgressCallback	The callback for install progress information.

Type Definitions

progressCallback(progress, status)

Description:

A callback for progress messages. Can be passed to Agent#install, Agent#installFile, Agent#uninstall.

Source:

agent.js, line 501

Parameters:

Name	Type	Description
`progress`	number	The progress, as a number between 0 and 1.
`status`	string	The current status.

uploadProgressCallback(bytes)

Description:

A callback for file upload progress messages. Can be passed to Agent#upload and Agent#installFile

Source:

agent.js, line 495

Parameters:

Name	Type	Description
`bytes`	number	The number of bytes that has been uploaded.