agent.js

  1. 'use strict'
  3. const WebSocket = require('ws')
  4. const stream = require('stream')
  6. const { sleep } = require('./util/sleep')
  8. /**
  9.  * @typedef {object} CommandResult
  10.  * @property {integer} id - ID
  11.  * @property {boolean} success - command result
  12.  */
  14. /**
  15.  * @typedef {object} ShellExecResult
  16.  * @property {integer} id - ID
  17.  * @property {integer} exit-status
  18.  * @property {string} output - command output
  19.  * @property {boolean} success - command result
  20.  */
  22. /**
  23.  * @typedef {object} FridaPsResult
  24.  * @property {integer} id - ID
  25.  * @property {integer} exit-status -
  26.  * @property {string} output - frida-ps output
  27.  * @property {boolean} success - command result
  28.  */
  30. /**
  31.  * @typedef {object} AppListEntry
  32.  * @property {string} applicationType
  33.  * @property {string} bundleID
  34.  * @property {integer} date
  35.  * @property {integer} diskUsage
  36.  * @property {boolean} isLaunchable
  37.  * @property {string} name
  38.  * @property {boolean} running
  39.  */
  41. /**
  42.  * @typedef {object} StatEntry
  43.  * @property {integer} atime
  44.  * @property {integer} ctime
  45.  * @property {object[]} entries
  46.  * @property {integer} entries[].atime
  47.  * @property {integer} entries[].stime
  48.  * @property {integer} entries[].gid
  49.  * @property {integer} entries[].mode
  50.  * @property {integer} entries[].mtime
  51.  * @property {string} entries[].name
  52.  * @property {integer} entries[].size
  53.  * @property {integer} entries[].uid
  54.  * @property {integer} gid
  55.  * @property {integer} mode
  56.  * @property {integer} mtime
  57.  * @property {string} name
  58.  * @property {integer} size
  59.  * @property {integer} uid
  60.  */
  62. /**
  63.  * @typedef {object} ProvisioningProfileInfo
  64.  * @property {string} name
  65.  * @property {string} uuid
  66.  * @property {string} teamId
  67.  * @property {string[]} certs
  68.  */
  70. /**
  71.  * A connection to the agent running on an instance.
  72.  *
  73.  * Instances of this class
  74.  * are returned from {@link Instance#agent} and {@link Instance#newAgent}. They
  75.  * should not be created using the constructor.
  76.  * @hideconstructor
  77.  */
  78. class Agent {
  79.   constructor (instance) {
  80.     this.instance = instance
  81.     this.connected = false
  82.     this.uploading = false
  83.     this.connectPromise = null
  84.     this.id = 0
  85.     this._keepAliveTimeout = null
  86.     this._startKeepAliveTimeout = null
  87.     this._lastPong = null
  88.     this._lastPing = null
  89.   }
  91.   /**
  92.    * Ensure the agent is connected.
  93.    * @private
  94.    */
  95.   async connect () {
  96.     this.pendingConnect = true
  97.     if (!this.connected) {
  98.       return await this.reconnect()
  99.     }
  100.   }
  102.   /**
  103.    * Ensure the agent is disconnected, then connect the agent.
  104.    * @private
  105.    */
  106.   async reconnect () {
  107.     if (this.connected) this.disconnect()
  109.     if (this.connectPromise) return this.connectPromise
  111.     this.connectPromise = await (async () => {
  112.       while (this.pendingConnect) {
  113.         try {
  114.           await this._connect()
  115.           break
  116.         } catch (err) {
  117.           if (err.stack.includes('Instance likely does not exist')) {
  118.             throw err
  119.           }
  120.           if (err.stack.includes('self-signed certificate')) {
  121.             throw err
  122.           }
  123.           if (err.stack.includes('unexpected server response (502)')) {
  124.             // 'Error: unexpected server response (502)' means the device is not likely up yet
  125.             await sleep(10 * 1000)
  126.           }
  127.           if (err.stack.includes('closed before the connection')) {
  128.             // Do nothing this is normal when trying to settle a connection for a vm coming up
  129.           } else {
  130.             await sleep(7.5 * 1000)
  131.           }
  132.         }
  133.       }
  135.       this.connectPromise = null
  136.     })()
  138.     return this.connectPromise
  139.   }
  141.   async _connect () {
  142.     this.pending = new Map()
  144.     const endpoint = await this.instance.agentEndpoint()
  145.     if (!endpoint) {
  146.       this.pendingConnect = false
  147.       throw new Error('Instance likely does not exist')
  148.     }
  150.     // Detect if a disconnection happened before we were able to get the agent endpoint.
  151.     if (!this.pendingConnect) throw new Error('connection cancelled')
  153.     const ws = new WebSocket(
  154.       /^https/.test(endpoint)
  155.         ? endpoint.replace(/^https/, 'wss')
  156.         : /^http/.test(endpoint)
  157.           ? endpoint.replace(/^http/, 'ws')
  158.           : endpoint
  159.     )
  161.     this.ws = ws
  163.     ws.on('message', data => {
  164.       try {
  165.         let message
  166.         let id = -1
  167.         if (typeof data === 'string') {
  168.           message = JSON.parse(data)
  169.           id = message.id
  170.         } else if (Buffer.isBuffer(data)) {
  171.           try {
  172.             message = JSON.parse(data.toString('utf8'))
  173.             id = message.id
  174.           } catch (e) {
  175.             if (data.length >= 8) {
  176.               id = data.readUInt32LE(0)
  177.               message = data.slice(8)
  178.             }
  179.           }
  180.         }
  182.         if (id === -1) {
  183.           throw new Error(`handler not found for id: ${id}`)
  184.         }
  186.         const handler = this.pending.get(id)
  187.         if (handler) {
  188.           // will work regardless of whether handler returns a promise
  189.           Promise.resolve(handler(null, message)).then(shouldDelete => {
  190.             if (shouldDelete) this.pending.delete(id)
  191.           })
  192.         }
  193.       } catch (err) {
  194.         console.error('error in agent message handler', err)
  195.       }
  196.     })
  198.     ws.on('close', (code, _reason) => {
  199.       this.pending.forEach(handler => {
  200.         handler(new Error(`disconnected with code ${code}`))
  201.       })
  202.       this.pending = new Map()
  203.       this._disconnect()
  204.     })
  206.     return await new Promise((resolve, reject) => {
  207.       ws.once('open', () => {
  208.         if (this.ws !== ws) {
  209.           try {
  210.             ws.close()
  211.           } catch (e) {
  212.             // Swallow ws.close() errors.
  213.           }
  215.           reject(new Error('connection cancelled'))
  216.           return
  217.         }
  219.         ws.on('error', err => {
  220.           this.pending.forEach(handler => {
  221.             handler(err)
  222.           })
  223.           this.pending = new Map()
  225.           if (this.ws === ws) {
  226.             this._disconnect()
  227.           } else {
  228.             try {
  229.               ws.close()
  230.             } catch (e) {
  231.               // Swallow ws.close() errors.
  232.             }
  233.           }
  235.           console.error('error in agent socket', err)
  236.         })
  238.         resolve()
  239.       })
  241.       ws.once('error', err => {
  242.         if (this.ws === ws) {
  243.           this._disconnect()
  244.         } else {
  245.           try {
  246.             ws.close()
  247.           } catch (e) {
  248.             // Swallow ws.close() errors.
  249.           }
  250.         }
  252.         reject(err)
  253.       })
  254.     })
  255.       .then(() => {
  256.         this.pendingConnect = false
  257.         this.connected = true
  258.         clearTimeout(this._startKeepAliveTimeout)
  259.         this._startKeepAlive()
  260.       })
  261.       .catch(async err => {
  262.         await this.instance.update()
  263.         throw err
  264.       })
  265.   }
  267.   _startKeepAlive () {
  268.     if (!this.connected) return
  270.     const ws = this.ws
  271.     // clean up any existing keepalive timers before registering new ones.  This prevents a bug that occurs if _startKeepAlive() is invoked multiple times.
  272.     // _startKeepAlive() invoked once -> this._keepAliveTimeout is registered in state with the pong listener relying on that state to clear it.
  273.     // _startKeepAlive() invoked second -> overwrites this._keepAliveTimeout.
  274.     // Now, when original pong listener goes to clear timer based on this._keepAliveTimeout state, it has lost the reference to the first timer which results in it blowing up at 10 seconds
  275.     this._stopKeepAlive()
  277.     ws.ping()
  279.     this._keepAliveTimeout = setTimeout(() => {
  280.       if (this.ws !== ws) {
  281.         try {
  282.           ws.close()
  283.         } catch (e) {
  284.           // Swallow ws.close() errors.
  285.         }
  286.         return
  287.       }
  289.       const err = new Error('Agent did not get a response to ping in 10 seconds, disconnecting.')
  290.       console.error('Agent did not get a response to ping in 10 seconds, disconnecting.')
  292.       this.pending.forEach(handler => {
  293.         handler(err)
  294.       })
  295.       this.pending = new Map()
  297.       this._disconnect()
  298.     }, 10 * 1000)
  300.     ws.once('pong', async () => {
  301.       if (ws !== this.ws) {
  302.         return
  303.       }
  305.       clearTimeout(this._keepAliveTimeout)
  306.       this._keepAliveTimeout = null
  308.       if (!this.uploading) {
  309.         // use arrow function to ensure the "this" binding references the Agent context, NOT a Timer.
  310.         this._startKeepAliveTimeout = setTimeout(() => this._startKeepAlive(), 10 * 1000)
  311.       }
  312.     })
  313.   }
  315.   _stopKeepAlive () {
  316.     if (this._startKeepAliveTimeout) {
  317.       clearTimeout(this._startKeepAliveTimeout)
  318.       this._startKeepAliveTimeout = null
  319.     }
  320.     if (this._keepAliveTimeout) {
  321.       clearTimeout(this._keepAliveTimeout)
  322.       this._keepAliveTimeout = null
  323.     }
  324.   }
  326.   /**
  327.    * Disconnect an agent connection. This is usually only required if a new
  328.    * agent connection has been created and is no longer needed, for example
  329.    * if the `crashListener` in the example at {@link Agent#crashes} is not
  330.    * needed anymore.
  331.    * @example
  332.    * agent.disconnect();
  333.    */
  334.   disconnect () {
  335.     this.pendingConnect = false
  336.     this._disconnect()
  337.   }
  339.   _disconnect () {
  340.     this.connected = false
  341.     this._stopKeepAlive()
  342.     if (this.ws) {
  343.       try {
  344.         this.ws.close()
  345.       } catch (e) {
  346.         // Swallow ws.close() errors.
  347.       }
  348.       this.ws = null
  349.     }
  350.   }
  352.   /**
  353.    * Send a command to the agent.
  354.    *
  355.    * When the command is responded to with an error, the error is thrown.
  356.    * When the command is responded to with success, the handler callback is
  357.    * called with the response as an argument.
  358.    *
  359.    * If the callback returns a value, that value will be returned from
  360.    * `command`; otherwise nothing will happen until the next response to the
  361.    * command. If the callback throws an exception, that exception will be
  362.    * thrown from `command`.
  363.    *
  364.    * If no callback is specified, it is equivalent to specifying the callback
  365.    * `(response) => response`.
  366.    *
  367.    * @param {string} type - passed in the `type` field of the agent command
  368.    * @param {string} op - passed in the `op` field of the agent command
  369.    * @param {Object} params - any other parameters to include in the command
  370.    * @param {function} [handler=(response) => response] - the handler callback
  371.    * @param {function} [uploadHandler] - a kludge for file uploads to work
  372.    * @private
  373.    */
  374.   async command (type, op, params, handler, uploadHandler) {
  375.     if (handler === undefined) handler = response => response
  377.     const id = this.id
  378.     this.id++
  379.     const message = Object.assign({ type, op, id }, params)
  381.     while (!this.ws) {
  382.       await this.connect()
  383.     }
  384.     this.ws.send(JSON.stringify(message))
  385.     if (uploadHandler) uploadHandler(id)
  387.     return await new Promise((resolve, reject) => {
  388.       this.pending.set(id, async (err, response) => {
  389.         if (err) {
  390.           reject(err)
  391.           return
  392.         }
  394.         if (response.error) {
  395.           reject(Object.assign(new Error(), response.error))
  396.           return
  397.         }
  399.         try {
  400.           const result = await handler(response)
  401.           if (result !== undefined) {
  402.             resolve(result)
  403.             return true // stop calling us
  404.           }
  405.           return false
  406.         } catch (e) {
  407.           reject(e)
  408.           return true
  409.         }
  410.       })
  411.     })
  412.   }
  414.   sendBinaryData (id, data) {
  415.     const idBuffer = Buffer.alloc(8, 0)
  416.     idBuffer.writeUInt32LE(id, 0)
  417.     if (data) this.ws.send(Buffer.concat([idBuffer, data]))
  418.     else this.ws.send(idBuffer)
  419.   }
  421.   /**
  422.    * Wait for the instance to be ready to use. On iOS, this will wait until Springboard has launched.
  423.    * @example
  424.    * let agent = await instance.agent();
  425.    * await agent.ready();
  426.    */
  427.   async ready () {
  428.     await this.command('app', 'ready')
  429.   }
  431.   /**
  432.    * Uninstalls the app with the given bundle ID.
  433.    * @param {string} bundleID - The bundle ID of the app to uninstall.
  434.    * @param {Agent~progressCallback} progress - The progress callback.
  435.    * @example
  436.    * await agent.uninstall('com.corellium.demoapp', (progress, status) => {
  437.    *     console.log(progress, status);
  438.    * });
  439.    */
  440.   async uninstall (bundleID, progress) {
  441.     await this.command('app', 'uninstall', { bundleID }, message => {
  442.       if (message.success) return message
  443.       if (progress && message.progress) progress(message.progress, message.status)
  444.     })
  445.   }
  447.   /**
  448.    * Launches the app with the given bundle ID.
  449.    * @param {string} bundleID - The bundle ID of the app to launch.
  450.    * @example
  451.    * await agent.run("com.corellium.demoapp");
  452.    */
  453.   async run (bundleID) {
  454.     await this.command('app', 'run', { bundleID })
  455.   }
  457.   /**
  458.    * Executes a given command
  459.    * @param {string} cmd - The cmd to execute
  460.    * @return {Promise<ShellExecResult>}
  461.    * @example
  462.    * await agent.shellExec("uname");
  463.    */
  464.   async shellExec (cmd) {
  465.     return await this.command('app', 'shellExec', { cmd })
  466.   }
  468.   /**
  469.    * Launches the app with the given bundle ID.
  470.    * @param {string} bundleID - The bundle ID of the app to launch, for android this is the package name.
  471.    * @param {string} activity fully qualified activity to launch from bundleID
  472.    * @example
  473.    * await agent.runActivity('com.corellium.test.app', 'com.corellium.test.app/com.corellium.test.app.CrashActivity');
  474.    */
  475.   async runActivity (bundleID, activity) {
  476.     await this.command('app', 'run', { bundleID, activity })
  477.   }
  479.   /**
  480.    * Kill the app with the given bundle ID, if it is running.
  481.    * @param {string} bundleID - The bundle ID of the app to kill.
  482.    * @example
  483.    * await agent.kill("com.corellium.demoapp");
  484.    */
  485.   async kill (bundleID) {
  486.     await this.command('app', 'kill', { bundleID })
  487.   }
  489.   /**
  490.    * Returns an array of installed apps.
  491.    * @return {Promise<AppListEntry[]>}
  492.    * @example
  493.    * let appList = await agent.appList();
  494.    * for (app of appList) {
  495.    *     console.log('Found installed app ' + app['bundleID']);
  496.    * }
  497.    */
  498.   async appList () {
  499.     const { apps } = await this.command('app', 'list')
  500.     return apps
  501.   }
  503.   /**
  504.    * 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
  505.    * the same structure (and an additional name field) for each immediate child of the directory.
  506.    * @return {Promise<StatEntry>}
  507.    * @example
  508.    * let scripts = await agent.stat('/data/corellium/frida/scripts/');
  509.    */
  510.   async stat (path) {
  511.     const response = await this.command('file', 'stat', { path })
  512.     return response.stat
  513.   }
  515.   /**
  516.    * A callback for file upload progress messages. Can be passed to {@link Agent#upload} and {@link Agent#installFile}
  517.    * @callback Agent~uploadProgressCallback
  518.    * @param {number} bytes - The number of bytes that has been uploaded.
  519.    */
  521.   /**
  522.    * A callback for progress messages. Can be passed to {@link Agent#install}, {@link Agent#installFile}, {@link Agent#uninstall}.
  523.    * @callback Agent~progressCallback
  524.    * @param {number} progress - The progress, as a number between 0 and 1.
  525.    * @param {string} status - The current status.
  526.    */
  528.   /**
  529.    * Installs an app. The app's IPA must be available on the VM's filesystem. A progress callback may be provided.
  530.    *
  531.    * @see {@link Agent#upload} to upload a file to the VM's filesystem
  532.    * @see {@link Agent#installFile} to handle both the upload and install
  533.    *
  534.    * @param {string} path - The path of the IPA on the VM's filesystem.
  535.    * @param {Agent~progressCallback} [progress] - An optional callback that
  536.    * will be called with information on the progress of the installation.
  537.    * @async
  538.    *
  539.    * @example
  540.    * await agent.install('/var/tmp/temp.ipa', (progress, status) => {
  541.    *     console.log(progress, status);
  542.    * });
  543.    */
  544.   async install (path, progress) {
  545.     await this.command('app', 'install', { path }, message => {
  546.       if (message.success) return message
  547.       if (progress && message.progress) progress(message.progress, message.status)
  548.     })
  549.   }
  551.   /**
  552.    * Returns an array of Mobile Configuration profile IDs
  553.    * @return {Promise<string[]>}
  554.    * @example
  555.    * let profiles = await agent.profileList();
  556.    * for (p of profiles) {
  557.    *     console.log('Found configuration profile: ' + p);
  558.    * }
  559.    */
  560.   async profileList () {
  561.     const { profiles } = await this.command('profile', 'list')
  562.     return profiles
  563.   }
  565.   /**
  566.    * Installs Mobile Configuration profile
  567.    * @param {Buffer} profile - profile binary
  568.    * @example
  569.    * var profile = fs.readFileSync(path.join(__dirname, "myprofile.mobileconfig"));
  570.    * await agent.installProfile(profile);
  571.    */
  572.   async installProfile (profile) {
  573.     await this.command('profile', 'install', {
  574.       profile: Buffer.from(profile).toString('base64')
  575.     })
  576.   }
  578.   /**
  579.    * Deletes Mobile Configuration profile
  580.    * @param {string} profileID - profile ID
  581.    * @example
  582.    * await agent.removeProfile('com.test.myprofile');
  583.    */
  584.   async removeProfile (profileID) {
  585.     await this.command('profile', 'remove', { profileID })
  586.   }
  588.   /**
  589.    * Gets Mobile Configuration profile binary
  590.    * @param {string} profileID - profile ID
  591.    * @return {Promise<Buffer>}
  592.    * @example
  593.    * var profile = await agent.getProfile('com.test.myprofile');
  594.    */
  595.   async getProfile (profileID) {
  596.     const { profile } = await this.command('profile', 'get', { profileID })
  597.     if (!profile) return null
  598.     // eslint-disable-next-line new-cap
  599.     return new Buffer.from(profile, 'base64')
  600.   }
  602.   /**
  603.    * Returns an array of Provisioning profile descriptions
  604.    * @return {Promise<ProvisioningProfileInfo[]>}
  605.    * @example
  606.    * let profiles = await agent.listProvisioningProfiles();
  607.    * for (p of profiles) {
  608.    *     console.log(p['uuid']);
  609.    * }
  610.    */
  611.   async listProvisioningProfiles () {
  612.     const { profiles } = await this.command('provisioning', 'list')
  613.     return profiles
  614.   }
  616.   /**
  617.    * Installs Provisioning profile
  618.    * @param {Buffer} profile - profile binary
  619.    * @param {Boolean} trust - immediately trust installed profile
  620.    * @example
  621.    * var profile = fs.readFileSync(path.join(__dirname, "embedded.mobileprovision"));
  622.    * await agent.installProvisioningProfile(profile, true);
  623.    */
  624.   async installProvisioningProfile (profile, trust = false) {
  625.     await this.command('provisioning', 'install', {
  626.       profile: Buffer.from(profile).toString('base64'),
  627.       trust: trust
  628.     })
  629.   }
  631.   /**
  632.    * Deletes Provisioning profile
  633.    * @param {string} profileID - profile ID
  634.    * @example
  635.    * await agent.removeProvisioningProfile('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa');
  636.    */
  637.   async removeProvisioningProfile (profileID) {
  638.     await this.command('provisioning', 'remove', {
  639.       uuid: profileID
  640.     })
  641.   }
  643.   /**
  644.    * Approves (makes trusted) profile which will be installed later in a future for example during app installation via Xcode.
  645.    * @param {string} certID - profile ID
  646.    * @param {string} profileID - profile ID
  647.    * @example
  648.    * await agent.preApproveProvisioningProfile('Apple Development: my@email.com (NKJDZ3DZJB)', 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa');
  649.    */
  650.   async preApproveProvisioningProfile (certID, profileID) {
  651.     await this.command('provisioning', 'preapprove', {
  652.       cert: certID,
  653.       uuid: profileID
  654.     })
  655.   }
  657.   /**
  658.    * Returns a temporary random filename on the VMs filesystem that by the
  659.    * time of invocation of this method is guaranteed to be unique.
  660.    * @return {Promise<string>}
  661.    * @see example at {@link Agent#upload}
  662.    */
  663.   async tempFile () {
  664.     const { path } = await this.command('file', 'temp')
  665.     return path
  666.   }
  668.   /**
  669.    * Reads from the specified stream and uploads the data to a file on the VM.
  670.    * @param {string} path - The file path to upload the data to.
  671.    * @param {ReadableStream} stream - The stream to read the file data from.
  672.    * @param {Agent~uploadProgressCallback} progress - The callback for install progress information.
  673.    * @example
  674.    * const tmpName = await agent.tempFile();
  675.    * await agent.upload(tmpName, fs.createReadStream('test.ipa'));
  676.    */
  677.   async upload (path, stream, progress) {
  678.     // Temporarily stop the keepalive as the upload appears to backlog
  679.     // the control packets (ping/pong) at the proxy which can cause issues
  680.     // and a disconnect
  681.     this._stopKeepAlive()
  682.     this.uploading = true
  683.     await this.command(
  684.       'file',
  685.       'upload',
  686.       { path },
  687.       message => {
  688.         // This is hit after the upload is completed and the agent
  689.         // on the other end sends the reply packet of success/fail
  690.         // Restart the keepalive as the upload buffer should be cleared
  691.         clearTimeout(this._startKeepAliveTimeout)
  692.         this._startKeepAlive()
  693.         this.uploading = false
  695.         // Pass back the message to the command() function to prevent
  696.         // blocking or returning an invalid value
  697.         return message
  698.       },
  699.       id => {
  700.         let total = 0
  702.         stream.on('data', data => {
  703.           this.sendBinaryData(id, data)
  704.           total += data.length
  705.           if (progress) progress(total)
  706.         })
  707.         stream.on('end', () => {
  708.           this.sendBinaryData(id)
  709.         })
  710.       }
  711.     )
  712.   }
  714.   /**
  715.    * Downloads the file at the given path from the VM's filesystem. Returns a node ReadableStream.
  716.    * @param {string} path - The path of the file to download.
  717.    * @return {Readable}
  718.    * @example
  719.    * const dl = agent.download('/var/tmp/test.log');
  720.    * dl.pipe(fs.createWriteStream('test.log'));
  721.    */
  722.   download (path) {
  723.     let command
  724.     const agent = this
  725.     return new stream.Readable({
  726.       read () {
  727.         if (command) return
  728.         command = agent.command('file', 'download', { path }, message => {
  729.           if (!Buffer.isBuffer(message)) return
  730.           if (message.length === 0) return true
  731.           this.push(message)
  732.         })
  733.         command.then(() => this.push(null)).catch(err => this.emit('error', err))
  734.       }
  735.     })
  736.   }
  738.   /**
  739.    * Reads a packaged app from the provided stream, uploads the app to the VM
  740.    * using {@link Agent#upload}, and installs it using {@link Agent#install}.
  741.    * @param {ReadableStream} stream - The app to install, the stream will be closed after it is uploaded.
  742.    * @param {Agent~progressCallback} installProgress - The callback for install progress information.
  743.    * @param {Agent~uploadProgressCallback} uploadProgress - The callback for file upload progress information.
  744.    * @example
  745.    * await agent.installFile(fs.createReadStream('test.ipa'), (installProgress, installStatus) => {
  746.    *     console.log(installProgress, installStatus);
  747.    * });
  748.    */
  749.   async installFile (stream, installProgress, uploadProgress) {
  750.     const path = await this.tempFile()
  752.     await this.upload(path, stream, uploadProgress)
  753.     stream.on('close', () => {
  754.       stream.destroy()
  755.     })
  757.     await this.install(path, installProgress)
  759.     try {
  760.       await this.stat(path)
  761.       await this.deleteFile(path)
  762.     } catch (err) {
  763.       if (!err.message.includes('Stat of file')) {
  764.         throw err
  765.       }
  766.     }
  767.   }
  769.   /**
  770.    * Delete the file at the specified path on the VM's filesystem.
  771.    * @param {string} path - The path of the file on the VM's filesystem to delete.
  772.    * @example
  773.    * await agent.deleteFile('/var/tmp/test.log');
  774.    */
  775.   async deleteFile (path) {
  776.     const response = await this.command('file', 'delete', { path })
  777.     return response.path
  778.   }
  780.   /**
  781.    * Change file attributes of the file at the specified path on the VM's filesystem.
  782.    * @param {string} path - The path of the file on the VM's filesystem to delete.
  783.    * @param {Object} attributes - 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.
  784.    * @return {Promise<CommandResult>}
  785.    * @example
  786.    * await agent.changeFileAttributes(filePath, {mode: 511});
  787.    */
  788.   async changeFileAttributes (path, attributes) {
  789.     const response = await this.command('file', 'modify', { path, attributes })
  790.     return response
  791.   }
  793.   /**
  794.    * 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.
  795.    *
  796.    * The callback takes two parameters:
  797.    *  - `err`, which is undefined unless an error occurred setting up or waiting for crash logs
  798.    *  - `crash`, which contains the full crash report data
  799.    *
  800.    * **Note:** Since this method blocks the communication channel of the
  801.    * agent to wait for crash reports, a new {@link Agent} connection should
  802.    * be created with {@link Instance#newAgent}.
  803.    *
  804.    * @see Agent#disconnect
  805.    *
  806.    * @example
  807.    * const crashListener = await instance.newAgent();
  808.    * crashListener.crashes("com.corellium.demoapp", (err, crashReport) => {
  809.    *     if (err) {
  810.    *         console.error(err);
  811.    *         return;
  812.    *     }
  813.    *     console.log(crashReport);
  814.    * });
  815.    */
  816.   async crashes (bundleID, callback) {
  817.     await this.command('crash', 'subscribe', { bundleID }, async message => {
  818.       const path = message.file
  819.       const crashReport = await new Promise(resolve => {
  820.         const stream = this.download(path)
  821.         const buffers = []
  822.         stream.on('data', data => {
  823.           buffers.push(data)
  824.         })
  825.         stream.on('end', () => {
  826.           resolve(Buffer.concat(buffers))
  827.         })
  828.       })
  830.       await this.deleteFile(path)
  831.       callback(null, crashReport.toString('utf8'))
  832.     })
  833.   }
  835.   /** Locks the device software-wise.
  836.    * @example
  837.    * await agent.lockDevice();
  838.    */
  839.   async lockDevice () {
  840.     await this.command('system', 'lock')
  841.   }
  843.   /** Unlocks the device software-wise.
  844.    * @example
  845.    * awaitagent.unlockDevice();
  846.    */
  847.   async unlockDevice () {
  848.     await this.command('system', 'unlock')
  849.   }
  851.   /** Enables UI Automation.
  852.    * @example
  853.    * await agent.enableUIAutomation();
  854.    */
  855.   async enableUIAutomation () {
  856.     await this.command('system', 'enableUIAutomation')
  857.   }
  859.   /** Disables UI Automation.
  860.    * @example
  861.    * await agent.disableUIAutomation();
  862.    */
  863.   async disableUIAutomation () {
  864.     await this.command('system', 'disableUIAutomation')
  865.   }
  867.   /** Checks if SSL pinning is enabled. By default SSL pinning is disabled.
  868.    * @returns {boolean}
  869.    * @example
  870.    * let enabled = await agent.isSSLPinningEnabled();
  871.    * if (enabled) {
  872.    *     console.log("enabled");
  873.    * } else {
  874.    *     console.log("disabled");
  875.    * }
  876.    */
  877.   async isSSLPinningEnabled () {
  878.     return (await this.command('system', 'isSSLPinningEnabled')).enabled
  879.   }
  881.   /** Enables SSL pinning.
  882.    * @example
  883.    * await agent.enableSSLPinning();
  884.    */
  885.   async enableSSLPinning () {
  886.     await this.command('system', 'enableSSLPinning')
  887.   }
  889.   /** Disables SSL pinning.
  890.    * @example
  891.    * await agent.disableSSLPinning();
  892.    */
  893.   async disableSSLPinning () {
  894.     await this.command('system', 'disableSSLPinning')
  895.   }
  897.   /** Shuts down the device.
  898.    * @example
  899.    * await agent.shutdown();
  900.    */
  901.   async shutdown () {
  902.     await this.command('system', 'shutdown')
  903.   }
  905.   async acquireDisableAutolockAssertion () {
  906.     await this.command('system', 'acquireDisableAutolockAssertion')
  907.   }
  909.   async releaseDisableAutolockAssertion () {
  910.     await this.command('system', 'releaseDisableAutolockAssertion')
  911.   }
  913.   /** Connect device to WiFi.
  914.    * @example
  915.    * await agent.connectToWifi();
  916.    */
  917.   async connectToWifi () {
  918.     await this.command('wifi', 'connect')
  919.   }
  921.   /** Disconnect device from WiFi.
  922.    * @example
  923.    * await agent.disconnectFromWifi();
  924.    */
  925.   async disconnectFromWifi () {
  926.     await this.command('wifi', 'disconnect')
  927.   }
  929.   /** Get device property. */
  930.   async getProp (property) {
  931.     return await this.command('system', 'getprop', { property })
  932.   }
  934.   /**
  935.    * Run frida on the device.
  936.    * Please note that both arguments (pid and name) need to be provided as they are required by the Web UI.
  937.    * @param {integer} pid
  938.    * @param {string} name
  939.    * @return {Promise<CommandResult>}
  940.    * @example
  941.    * await agent.runFrida(449, 'keystore');
  942.    */
  943.   async runFrida (pid, name) {
  944.     return await this.command('frida', 'run-frida', {
  945.       target_pid: pid.toString(),
  946.       target_name: name.toString()
  947.     })
  948.   }
  950.   /**
  951.    * Run frida-ps on the device and return the command's output.
  952.    * @return {Promise<FridaPsResult>}
  953.    * @example
  954.    * let procList = await agent.runFridaPs();
  955.    * let lines = procList.output.trim().split('\n');
  956.    * lines.shift();
  957.    * lines.shift();
  958.    * for (const line of lines) {
  959.    *     const [pid, name] = line.trim().split(/\s+/);
  960.    *     console.log(pid, name);
  961.    * }
  962.    */
  963.   async runFridaPs () {
  964.     return await this.command('frida', 'run-frida-ps')
  965.   }
  967.   /**
  968.    * Run frida-kill on the device.
  969.    * @return {Promise<CommandResult>}
  970.    * @example
  971.    * await agent.runFridaKill();
  972.    */
  973.   async runFridaKill () {
  974.     return await this.command('frida', 'run-frida-kill')
  975.   }
  976. }
  978. module.exports = Agent