Scenario creation guide

Table of Contents

• Scenario creation guide
  • Reducing the length of your scenario
  • Troubleshooting

Scenario creation guide

Scenario generation is a tricky subject. It is a crucial part of your analysis because it will determine the relevance of your execution trace. However, it must be as short as possible so it is still workable.

From a user's perspective, a scenario is simply a short period of time when things that we want to analyse will happen. The scenario generation process is:

• REVEN restores a VM's snapshot
• It uploads the project's files on the VMs via a mounted CD-ROM iso.
• It then waits for the VM to stop: this is when you should launch the dump_process binary and then start and stop the scenario.
• Once the VM is stopped, it saves the scenario file and starts the execution.

REVEN can generate an automatic scenario: it will start dump_process, then the selected binary, waits for it to reach a (configurable) certain symbol or address, start the scenario recording, and stop it when the binary exits.

If your case is more complex than that you can manually generate a scenario: REVEN will restore the selected VM snapshot, then wait for you to do the rest. You have to connect to that VM via VNC, launch the dump_process binary manually, and then record your scenario. We provide keys (see the scenario GUI) that, when pressed inside the VNC view, will start and stop the scenario recording; we are also working on providing other, more adaptable triggers.

Note that dump_process, located on the mounted CD-Rom, should be run with administrator privileges.

Reducing the length of your scenario

It is mandatory to reduce the duration of your scenario as much as possible. Not doing so will make the execution way too long to be practical and could cause desynchronizations. If you want an idea of the scale, know that the symbolic execution of a 2-second scenario performing heavy computing tasks like cryptographic operations - which is one of the worst cases - can take up to 50 hours. On the other hand, a CPU idly waiting for inputs from a network card for seconds does not impact the execution time very much.

In any case, the challenge is to precisely start and stop the scenario recording when it's relevant. For now your only handles are the shortcut keys, so don't hesitate to get creative to make sure your scenarios start as close as possible to what you want to analyse. Make sure you stop them as soon as possible as well, although you can always pause the execution manually.

Here are two examples of methods we've previously used here at Tetrane:

Activating a button

You want to analyse the behavior a single program's action, which can be triggered with a GUI button.

Once connected via VNC, you start you program, then dump_process as Administrator. Back to your program, you select the button, press F9 to activate the shortcuts and press Enter: As soon as you do, the scenario starts recording, and the program perform its action. You quickly stop the recording with F7.

Note that starting the dump_process after your program will ensure REVEN gathers as much information as possible about the latter: symbols, etc.

Displaying a window

This one is a bit trickier: you want to analyze the behavior of a Windows program when it displays something on screen.

Once connected via VNC, you start you program, then dump_process as Administrator. Back to your program, you move its window offscreen. Then, you (blindly) right click on the title bar, select "Move" and with the cursor keys, move the bounding rectangle back on the screen. You press F9 to activate the shortcuts then Enter: the scenario starts recording, and the keypress validates the window move. The window gets drawn on screen. You quickly stop the recording with F7.

Note this method only works if you followed the optimisation recommendations while creating your VMs and deactivated most of the graphical effects so a window won't show its content while moving.

Troubleshooting

The scenario generation log will tell you if something goes wrong and if your scenario cannot be generated. If you encounter errors, here are a few checks you should make to make sure your user configuration file is consistent with your VirtualBox setup.

If you see the error message 'Cannot restore the latest snapshot of vm vmname' or if you see errors right after the message "Restoring the VM to the current snapshot...", please check that:

• There is indeed a vm named vmname in VirtualBox.
• There is at least one snapshot for this VM.

If you see "The VM is currently busy. Please try again later...", please check that:

• No one is currently generating a core using this VM
• If not, this VM is started by a different mean: stop it and try again.
• If not, try making sure no other VM is started as well. This may cause problems as well.

If you see "Waiting the VM to stop...", REVEN is waiting for the VM to stop before grabbing the recorded scenario. As a first step, you can connect to the VM via VNC and stop it manually (F9+F7). If the generation ends well but this behavior persists, try recreating your snapshot. On the other hand, if the generation ends with an error, check that:

• The CD-ROM autorun is activated (otherwise, you'll have to start your binary by hand)
• The address you configured for the scenario to start is valid (symbol or segment:offset)
• Try launching your binary manually. If it works, the loader might have a bug.

If you see "Cannot find the generated scenario (.core) file. Please ensure that the dump address was reached and that the loader was used to run the binary.":

• For an automatic scenario, check the address you configured is valid.
• For a manual scenario, make sure your started the scenario (F9+F6) before stopping it

In any case, check the consistency of your user configuration file, double check every parameter, and try generating a manual scenario.

If nothing works, please contact the support team so we can help you out.