Importing & exporting a scenario

A recorded scenario can be exported, with or without some associated replayed resources. The resulting archive can then be shared with other Reven users or stored away to free space on your working disk.

By default, the directory where archive files are stored is $DATA/reven/Reven2/Archives where $DATA is the main storage folder for esReven, as configured in the .env file at the root of the esReven installation.

Conversely, all archive files stored in the archives directory can be imported as scenarios to be analyzed with Reven.

A typical scenario archive will usually take between 500 MB and 1 GB. For instance, the scenario presented in the article Analysing CVE-2020-15999 - buffer overflow in Chrome requires about 30 GB of disk space when fully replayed, but its archive is only about 750 MB.

Exporting

To export a scenario:

  1. First, open your scenario's "Details" page. You can find it by clicking the scenario's name in the scenario list.
  2. Click "Export".
  3. The export page allows you to select what you want to export. You should keep the defaults.
    • The "OSSI" is selected by default, and highly recommended:
      • If not selected, you will not be able to get symbols after importing the archive.
      • If you cannot select it, you should first replay the OSSI on your scenario and come back to the export page.
    • See below for more details on the other items.
  4. Click on "Export the scenario".
  5. Wait for the operation to finish.

Once the export operation is done, you can access the resulting archive:

  • Either download it with the "Download" button on the export task log.
  • Or locate it on the server in the $DATA/reven/Reven2/Archives directory (see above).

NOTES:

  • The original scenario is not deleted after the export task succeeds.
  • Exporting a scenario a second time will overwrite the scenario's previous archive.
  • You cannot export a scenario while recording, replaying, importing or exporting it.

Importing

The Project Manager can import archives that were previously exported using the above method. This operation will create a new scenario, and extract the archive into it.

To import a scenario you can upload the scenario archive using the Project Manager:

  1. In the "Scenario Manager" page, click on "Import from archive".
  2. Use the "Upload scenario archive" form:
    1. Optionally set a "New name" for the archive
    2. Click "Browse" to select the file on your local machine
    3. Click "Upload" to start the upload.
  3. After the upload is complete, the scenario import starts automatically.
  4. Wait for the import task to finish.
  5. Archives usually do not contain all replayable resources: you should open the Replay page of the newly created scenario and click on "Replay" all.

You can also manually import a scenario:

  1. Copy the archive to your $DATA/reven/Reven2/Archives directory (see above).
  2. In the "Scenario List" page, click on "Import from archive".
  3. Use the combo-box to select the archive you want to import.
    • If you cannot see it, make sure it is in the correct $DATA/reven/Reven2/Archives directory (see above).
  4. Click on "Import".
  5. Wait for the task to finish.
  6. Archives usually do not contain all replayable resources: you should open the Replay page of the newly created scenario and click on "Replay" all.

NOTES:

  • The resulting scenario is a "Snapshot-less scenario", because it is not linked to a particular VM anymore.
  • You cannot overwrite the recording of a scenario from an imported archive.
  • As soon as you start importing an archive, its scenario becomes visible in the scenario list. However, as long as it is being imported, all actions on the scenario will be disabled.

About exported resources

Here are more details about the resources you can select for export in a scenario:

  • The record: it is mandatory, you cannot export a scenario without the original record included in the archive.
  • The replay: resources generated by a replay are optional. They can be regenerated after the import. We do not recommend keeping them since they add significant overhead to the archive size, which also increases the time necessary to export it.
  • The ossi: It is highly recommended to include the OS-specific information. If you don't include them, you won't be able to retrieve OSSI (like symbols) when you will import the archive.
  • The light PDBs: Light PDBs contain only the PDBs needed for the scenario. It is not mandatory, as you should be able to download them from the original sources again when importing the archive. However they are recommended: including them when exporting a scenario is a convenience for users who are not connected to the Internet. Moreover, PDBs could get deleted from sources out of your control. Finally, if the scenario requires custom PDBs (for binaries you compiled), then you should include them in the archive.
  • The user data contains files useful for the scenario, with user-generated information (bookmarks, scripts, readme, ...). You certainly want to include this information in an exported archive and retrieve it when importing one.

The archive will also always include information about the scenario (name, type, os, archi, ...) and Reven's version, necessary for later importing.

Some resources are immutable after importing an archive, because they cannot be regenerated. Hence, they cannot be deleted in the imported scenario. For instance, the OSSI's light filesystem is an immutable resource because it depends on the snapshot.

©2019-2023 eShard