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:

# 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.
idevicebackup2 backup --full

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

Drag and drop your backup file into the box, then 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:

  • Upload a backup image: corellium image create
  • Restore the backup: corellium instance restore-backup

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

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.