Skip to main content

Restoring a physical device to a Corellium virtual device

Overview​

On a Corellium virtual device, you can restore a backup of a physical device. This is useful for bringing a physical device into the virtual world for testing and analysis without risking the physical device.

Note: This feature is available to users with Business Standard and higher licenses.

Creating a backup​

You can create a backup of a physical device using a variety of tools, including:

For example, the following code shows how to create a backup using idevicebackup2 on MacOS using Homebrew:

tip

Our testing shows that idevicebackup2 on version 1.3.0 has issues performing backup with some physical devices, in this case one may compile from source (until a new release is available in package managers).

# Install idevicebackup2
brew install libimobiledevice

# Ensure idevicebackup2 is functioning
idevicebackup2 -v

# Enable backup encryption
idevicebackup2 encryption on "[PASSWORD]"

# Create a new backup. This will create a folder for the iPhone UDID within the current folder.
idevicebackup2 backup --full .

Finally, ZIP the backup folder created (named by the phone's UDID) into a ZIP file, which will be used for uploding to Corellium. (A properly formed ZIP will contain as a single top level folder the phone's UDID inside, with the sub-folders under it with all contents.)

tip

Ensure you enable backup encryption. Without encryption, the backup won't include some sensitive user data.

Restoring a backup​

Using the Corellium UI​

To restore a physical backup, you will need to go to Settings > General in the Corellium UI. Scroll down to the section titled "Restore a VM".

Upgrade Device Step 1

Enter a password for the backup if one is needed. Then, drag and drop your backup file into the box. Finally, scroll to the top of the page and press "Save changes".

Upgrade Device Step 2

You'll be presented with a confirmation dialog. Press "Restore" to continue.

Upgrade Device Step 3

Wait for the device to upgrade and reboot.

Upgrade Device Step 4

You'll be presented with a confirmation once the device has finished restoring.

Using the REST API​

Use the following endpoints from our REST API:

Using the JavaScript API (legacy)​

Use the following methods from our old JavaScript API:

Using the new JavaScript API​

Use the following methods from our new JavaScript API:

Here is an example that shows how to use the new JavaScript API to create a backup and restore it to an instance:

// NODE_TLS_REJECT_UNAUTHORIZED=0
var fs = require('fs');
var { ApiClient, CorelliumApi } = require('@corellium/client-api');
const path = require('path');

var defaultClient = new ApiClient('https://app.corellium.co/api');
// Configure Bearer (ApiToken or JWT) access token for authorization: BearerAuth
var BearerAuth = defaultClient.authentications['BearerAuth'];
BearerAuth.accessToken = '[access_token]';
// process.env.CORELLIUM_API_ACCESS_TOKEN;

var api = new CorelliumApi(defaultClient);

// var args = process.argv.slice(2);
var instance = '[instance_id]'; // args[0]

var backup = path.join(__dirname, 'backup.zip');

fs.readFile(backup, (err, data) => {
  if (err) {
    console.error('Error reading the file:', err);
    return;
  }

  var opts = {
    encapsulated: false,
    instance,
    name: 'backup.zip',
    file: data,
  };

  api
    .v1CreateImage('backup', 'plain', opts)
    .then((image) => {
      api
        .v1RestoreBackup(instance)
        .then(() => {
          console.log('Done');
        })
        .catch((error) => {
          console.error(error);
        });
    })
    .catch((error) => {
      console.error(error);
    });
});

Using the Python API​

Use the following methods from our Python API:

Here is an example that shows how to use the Python API to create a backup and restore it to an instance:

import os
import asyncio
import corellium_api
from corellium_api.rest import ApiException

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure Bearer authorization (ApiToken or JWT): BearerAuth
configuration = corellium_api.Configuration(
    host = "https://app.corellium.com/api"
    ssl_ca_cert = "./ca_cert.cer"
)
configuration.access_token = '[access_token]'

async def main():
    # Enter a context with an instance of the API client
    async with corellium_api.ApiClient(configuration) as api_client:
        # Create an instance of the API class
        api_instance = corellium_api.CorelliumApi(api_client)
        try:
            instance_id = '[instance_id]'

            image = await api_instance.v1_create_image('backup', 'plain', encapsulated='false',
              name='backup.zip', instance=instance_id, file='../backup.zip')

            print(f'Uploaded backup image ${image.id}')

            await api_instance.v1_restore_backup(instance_id)
            print(f'Backup restore successful')
        except ApiException as e:
            print('Exception when calling CorelliumApi->v1_restore_backup: %s\n' % e)

asyncio.run(main())

Using the CLI​

Use the following commands from our CLI (after saving credentials, see corellium login -h):

  • Upload a backup image using corellium image create:

    corellium image create <projectId> backup.zip backup plain ./your_local_backup_filename.zip

  • Restore the backup using corellium instance restore-backup:

    corellium instance restore-backup <instanceId> ./your_local_backup_filename.zip [password] [--verbose]

Using idevicebackup2 and USBFlux​

After installing USBFlux and synthetically connecting your virtual device, you can use the following code to restore a backup:

# Check that the virtual device is connected.
idevice_id

# Restore backup to Virtual Device
idevicebackup2 \
  --password "[PASSWORD]" \
  --remove \
  --system \
  --settings \
  -s '[IPHONE UDID]' \
  -u '[VM UDID]' \
  restore

Following this, the virtual device will reboot and show a progress bar under Apple logo restoring files, then boot to SpringBoard.

Interoperability​

If you're restoring a backup from a physical device to a Corellium virtual device on your own, you can use a combination of backup and restore methods. The following table shows the different combinations and the expected result:

Backup MethodRestore MethodResult
iTunesiTunesEverything is restored as expected
iTunesidevicebackup2Everything is restored as expected, assuming flags include --remove --system --settings
idevicebackup2iTunesUnknown
idevicebackup2idevicebackup2Everything is restored as expected, assuming flags include --remove --system --settings
tip

For device restores using idevicebackup2, the flags --remove --system --settings are required to restore everything. If you don't include these flags, only a partial restore will occur.

Notes​

  • If you're on an on-site instance, the relevant IPSWs will need to be sourced on a network-enabled device, then added to your on-site instance prior to updating. You can learn more about this process here.
  • Updating an iOS device only works via the "restore" process - not "over the air" (OTA) updates.
  • When an iOS device is updated, the stock Apple apps (Mail, Reminders, etc.) are automatically scheduled for an update due to a conflict in their current app signatures and those stored in the Trust Cache. Until the update is complete, they are marked as invalidated by iOS. This is a normal process and does not affect the functionality of the device, however it does mean you will need an internet connection to update the apps.
  • We do not support backups from iCloud.