Graphical user interface#

Binary Valentine provides the fully featured graphical user interface (binary-valentine-ui), which allows to scan files and folders, and create, edit and save projects.

The interface is tab-based, meaning that you can open or create several projects at the same time.

Compared to the Command line utility, the GUI executable is fully autonomous and does not require any additional files from the data subfolder to run (all necessary files are embedded into it).

• Home page
• Project settings
• Global selector
• Report filter
• Targets to scan
• Specific target to scan
• Report outputs
• Scan
• Saving the project

Home page#

The home UI page allows to create and open projects, and to scan files and folders without creating a project in advance. It also supports drag-and-drop: you can drop any number of files and folders on it to do a quick analysis. If you drop an xml file, Binary Valentine will try to load it as a project.

Project settings#

When creating a new project or opening an existing one, and also when trying to analyze files or folders without creating a project in advance, you will see the following UI:

The tab name will show either "New project" or the corresponding project file name. It will be in bold if you have made any changes to it since opening.

On the "Project settings" tab, you can set the following options:

• Root path - this path will be used as a root path for all relative paths used in project. If absent, a current directory path will be used as a root path.
• Combined analysis - by default, Binary Valentine performs both single-executable and cross-executable analysis. Cross-executable rules detect issues across all executables which are being scanned within a single project. For example, there are rules which detect PE version information inconsistencies across all analyzed files.
• Analysis threads and Analysis thread count - Binary Valentine is a multithreaded application, and it allocates a number of threads which corresponds to the number of processor cores by default. Each file is analyzed by a separate thread, and there is also a common thread which loads the files. This option can be enabled to override the default number of threads used by the program.

You can also override the default File analysis limits. By default, Binary Valentine may load up to 1 gigabyte of data in memory. When a preloaded file gets analyzed and freed, Binary Valentine reads another file with the total size of loaded files not larger than 1 Gb. If needed, you can customize this behavior:

• Limit loaded files size - This option can be specified to override the maximum amount of memory to use for preloaded files waiting for analysis.
• Limit number of loaded files - Instead of limiting the preloaded data by size, you can limit the amount of simultaneously loaded files using this option.

Global selector#

This page allows to set up the rule selection which will be used during the analysis. Using this page, you can filter out particular rules, issue levels and categories, as well as set up rule-specific filtering by report messages.

Using the Report selection option, you can either exclude some reports from analysis, or include only the selected reports. You can group reports by rules which provide them to facilitate navigation.

With Report level selection and Report category selection, you can disable some report levels and report categories.

With Custom report filters, you can create a report filter for a specific report. The filter will exclude the report if its output does not match the regular expressions you provided. The next section describes the corresponding UI page.

Report filter#

This page is specific to each report and can be added from the rule selector page (either Global or target-specific).

In this example, the filter target is the PE082 rule, which is the "Deprecated WinAPI import" rule.

The input fields specify the case-sensitive ECMAScript regular expressions. In the example above, the filter will match if any of the two included regular expressions match the report output. The first one matches the dll report output argument, the second one - the api report output argument. As the mitigation regex is empty, it does not participate in filtering. You can see the full template of the report message (including arguments) in the Report description text label.

Overall, you can read this report filter as follows: exclude all reports from the PE082 (Deprecated WinAPI import) rule if any of the following regular expressions match the report output:

1. The DLL name matches kernel32.dll. This will filter out all deprecated WinAPI imports from kernel32.dll.
2. The API name matches RegOpenKey[AW]. This will additionally filter out functions with names which match the RegOpenKey[AW] regular expression (e.g. RegOpenKeyA, RegOpenKeyW).

Targets to scan#

This page allows you to add targets to be analyzed. Targets can be files and directories.

You can either use the File or folder to add input field to specify the path manually, or just drag-and-drop the files and folders on the area below that field.

When adding targets, you can either use absolute paths, or relative ones. In the latter case, the absolute path will be computed by concatenating with the root path (see Project settings).

Specific target to scan#

For each target (either a file or a directory) added to the project, there will be a separate page with analysis options.

You can scan the target recursively (applicable to directories) by enabling the Scan recursively option.

You can convert the target path from absolute to relative to the root path and vice versa by clicking the Use relative path and Use absolute path. Root path can be set up on the Project settings page.

In the Path filters section, you can specify one or more ECMAScript regular expressions to filter out paths during analysis (which is applicable to directories). The filter on the screenshot above will include only the dll files from the C:/Windows/System32 directory. Note that the regular expressions are case sensitive.

By clicking the Set up target-specific rule selector button, you can override the rule selector for the target. If no target-specific selector is specified, the global one is used. Otherwise, the target-specific one is used. The target-specific rule selector page interface is almost identical to the Global selector interface and will not be separately documented.

Report outputs#

On this page, you can specify the report outputs. These include the terminal output (when doing the analysis via the Command line) and any number of text or SARIF output files.

On the screenshot above, the terminal output is turned on, and the report will additionally be saved to the report.txt plaintext file (which will be created in a path relative to the project root path).

When running the analysis within the GUI, you will be also able to see the reports directly in the UI in real time.

Scan#

On this page, you can perform the analysis based on the project settings.

You can use the Start executables analysis button to kick off the analysis. After that, you will see the report and the analysis progress in real time. To stop the ongoing analysis, you can click and hold the corresponding button.

After the analysis had finished, you will see all files with at least one detected issue. You can filter the issues by levels and categories.

By selecting a specific file in the Reports list, you can view the issues detected for that file. Selecting a specific issue will show its detailed description with a link to this website, which suggests potential mitigations for every issue.

You can re-run the analysis any number of times.

Saving the project#

By pressing Ctrl+S (Windows) or selecting the File - Save project or Save project as... menu, you can save the current project into an xml file. The project would be usable across the Binary Valentine GUI and the Command line variants.