Agent

Agent

A connection to the agent running on an instance.

Instances of this class are returned from Instance#agent and Instance#newAgent. They should not be created using the constructor.

Methods

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

Source:

Returns an array of installed apps.

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

Source:

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

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

Source:

Connect device to WiFi.

Example
await agent.connectToWifi();

(async) crashes()

Source:
See:

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.

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)

Source:

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

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

Source:

Disables SSL pinning.

Example
await agent.disableSSLPinning();

(async) disableUIAutomation()

Source:

Disables UI Automation.

Example
await agent.disableUIAutomation();

disconnect()

Source:

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.

Example
agent.disconnect();

(async) disconnectFromWifi()

Source:

Disconnect device from WiFi.

Example
await agent.disconnectFromWifi();

download(path) → {Promise.<Readable>}

Source:

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

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
Promise.<Readable>

(async) enableSSLPinning()

Source:

Enables SSL pinning.

Example
await agent.enableSSLPinning();

(async) enableUIAutomation()

Source:

Enables UI Automation.

Example
await agent.enableUIAutomation();

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

Source:

Gets Mobile Configuration profile binary

Example
var profile = await agent.getProfile('com.test.myprofile');
Parameters:
Name Type Description
profileID string

profile ID

Returns:
Type
Promise.<Buffer>

(async) getProp()

Source:

Get device property.

(async) install(path, progressopt)

Source:
See:

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

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)

Source:

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

Example
await agent.installFile(fs.createReadStream('test.ipa'), (installProgress, installStatus) => {
    console.log(installProgress, installStatus);
});
Parameters:
Name Type Description
stream ReadableStream

The app to install.

installProgress Agent~progressCallback

The callback for install progress information.

uploadProgress Agent~uploadProgressCallback

The callback for file upload progress information.

(async) installProfile(profile)

Source:

Installs Mobile Configuration profile

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)

Source:

Installs Provisioning profile

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}

Source:

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

Example
let enabled = await agent.isSSLPinningEnabled();
if (enabled) {
    console.log("enabled");
} else {
    console.log("disabled");
}
Returns:
Type
boolean

(async) kill(bundleID)

Source:

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

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

Source:

Returns an array of Provisioning profile descriptions

Example
let profiles = await agent.listProvisioningProfiles();
for (p of profiles) {
    console.log(p['uuid']);
}
Returns:
Type
Promise.<Array.<ProvisioningProfileInfo>>

(async) lockDevice()

Source:

Locks the device software-wise.

Example
await agent.lockDevice();

(async) network()

Source:

Get device network infor

Example
let info = await agent.network();
console.log(info);

(async) preApproveProvisioningProfile(certID, profileID)

Source:

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

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

Source:

Returns an array of Mobile Configuration profile IDs

Example
let profiles = await agent.profileList();
for (p of profiles) {
    console.log('Found configuration profile: ' + p);
}
Returns:
Type
Promise.<Array.<string>>

(async) ready()

Source:

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

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

(async) removeProfile(profileID)

Source:

Deletes Mobile Configuration profile

Example
await agent.removeProfile('com.test.myprofile');
Parameters:
Name Type Description
profileID string

profile ID

(async) removeProvisioningProfile(profileID)

Source:

Deletes Provisioning profile

Example
await agent.removeProvisioningProfile('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa');
Parameters:
Name Type Description
profileID string

profile ID

(async) run(bundleID)

Source:

Launches the app with the given bundle ID.

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)

Source:

Launches the app with the given bundle ID.

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

Source:

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.

Example
await agent.runFrida(449, 'keystore');
Parameters:
Name Type Description
pid integer
name string
Returns:
Type
Promise.<CommandResult>

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

Source:

Run frida-kill on the device.

Example
await agent.runFridaKill();
Returns:
Type
Promise.<CommandResult>

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

Source:

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

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

Source:

Executes a given command

Example
await agent.shellExec("uname");
Parameters:
Name Type Description
cmd string

The cmd to execute

Returns:
Type
Promise.<ShellExecResult>

(async) shutdown()

Source:

Shuts down the device.

Example
await agent.shutdown();

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

Source:

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.

Example
let scripts = await agent.stat('/data/corellium/frida/scripts/');
Returns:
Type
Promise.<StatEntry>

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

Source:
See:

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

Returns:
Type
Promise.<string>

(async) uninstall(bundleID, progress)

Source:

Uninstalls the app with the given bundle ID.

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

Source:

Unlocks the device software-wise.

Example
awaitagent.unlockDevice();

(async) upload(path, stream, progress)

Source:

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

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)

Source:

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

Parameters:
Name Type Description
progress number

The progress, as a number between 0 and 1.

status string

The current status.

uploadProgressCallback(bytes)

Source:

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

Parameters:
Name Type Description
bytes number

The number of bytes that has been uploaded.