Command line usage

Binary Valentine comes with the command line utility (binary_valentine_cmd), which allows anything from quick manual scans of a single file to full-blown Secure Software Development Lifecycle (SSDLC) integration.

This page describes command line utility usage. If you need to support more advanced scenarios, head to the XML project page.

Getting help

Use the --help option to quickly see all supported command line parameters with descriptions:

General options:
  -h [ --help ]                        Print options description
  -c [ --config ] arg                  Path to external XML configuration file.
                                       Can not be used with any other options.
  -r [ --root-path ] arg               Root path. This path will be used as a
                                       root for all relative paths specified.
                                       If absent, current directory will be
                                       used as a root path.
  --threads arg                        Analysis thread count. If absent,
                                       hardware core number will be used.
  --max-loaded-targets-size arg (=1G)  Max loaded targets size. If specified,
                                       the analyzer will preload as many
                                       targets to analyze as possible until
                                       their size in memory is less than the
                                       value specified.Should have a numeric
                                       value together with the suffix (B -
                                       bytes, K - kilobytes, M - megabytes, G -
                                       gigabytes), e.g. 2G for 2 gigabytes.
                                       Can not be used together with
                                       --max-concurrent-tasks.
                                       Default is 1G.
  --max-concurrent-tasks arg           Max concurrent analysis tasks. If
                                       specified, the analyzer will preload at
                                       most max-concurrent-tasks targets for
                                       analysis.
                                       Can not be used together with
                                       --max-loaded-targets-size.

Combined analysis options:
  --do-combined-analysis arg (=1)      Do combined analysis of all specified
                                       targets. Default is true.

Targets options:
  -t [ --target ] arg                  Target file or directory to analyze.
                                       Required.
  --recursive arg (=1)                 Scan and analyze the target directory
                                       recursively. Default is true.
  --include-regex arg                  Analyze only targets with full paths
                                       which match the provided ECMAScript
                                       regex.
  --exclude-regex arg                  Analyze only targets with full paths
                                       which do not match the provided
                                       ECMAScript regex.

Report options:
  --exclude-reports arg                Exclude reports with the IDs listed. Can
                                       not be used together with
                                       --include-reports.
  --include-reports arg                Include only reports with the IDs
                                       listed. Can not be used together with
                                       --exclude-reports.
  --list-reports                       List all supported reports with brief
                                       descriptions.
  --exclude-levels arg                 Exclude report levels (info, warning,
                                       error, critical).
  --exclude-categories arg             Exclude report categories (system,
                                       optimization, security, configuration,
                                       format).
  --with-progress                      Report verbose analysis progress

Output options:
  --silent                             Do not output analysis results to
                                       terminal.
  -S [ --sarif ] arg                   Path to save the output report in SARIF
                                       format.
  -T [ --text ] arg                    Path to save the output report in
                                       plaintext.

Listing all supported rules

To list all supported rules, use the --list-reports option. It will produce the following output:

ID     Category       Level     Brief description
PE001  Security       WARNING   COFF/MPDB debug directory is present
PE002  Security       INFO      Debug directory is present
PE003  Configuration  INFO      MPX debug directory is present
PE004  Configuration  INFO      Export library name mismatch
PE005  Configuration  INFO      Non-DLL executable exports symbols
PE006  Configuration  WARNING   EXE file has DLL flag set
PE007  Security       ERROR     Relocations are absent
PE008  Optimization   WARNING   Relocations section is not discardable
PE009  Security       ERROR     SAFESEH is disabled
...

Scanning a file or a directory

With the plain command line (without using an XML project), you can scan a single executable file or a directory with files. If a directory contains non-executable files, Binary Valentine will skip them during enumeration. Recursive directory traversal is also supported and is enabled by default.

In the simplest case, the command to scan a file would look like this:

# Scan a single file
binary_valentine_cmd.exe file_to_scan.exe
# Or:
binary_valentine_cmd.exe --target file_to_scan.exe
# Or:
binary_valentine_cmd.exe -t file_to_scan.exe

# Scan a directory recursively
binary_valentine_cmd.exe dir/with/files

# Scan a directory non-recursively
binary_valentine_cmd.exe --recursive=0 dir/with/files

To gracefully interrupt the analysis, use Ctrl+C.

File path regular expression filters

You can skip analysis for some files in a directory by providing a ECMAScript regular expression to either include or exclude the paths which match it. For example:

# Scan a directory recursively, include only the DLL files
# On Windows:
binary_valentine_cmd.exe --include-regex "[dD][lL][lL]$" dir/with/files
# On Linux:
./binary_valentine_cmd --include-regex '[dD][lL][lL]$' dir/with/files

This command will analyze files with names which match the provided regex. Alternatively, you can use the --exclude-regex option, which will make Binary Valentine analyze files with names which do not match the provided regex. Note that the regular expressions are case sensitive, and they are used to match the absolute path to the file being considered for analysis.

Note that you can not use --include-regex and --exclude-regex options together at the same time.

Rule filtering

To filter out some reports, use the --exclude-reports options. Alternatively, to include only the specified reports, use the --include-reports option. For example, if you need to only detect Portable Executable files with the absent relocation directory or disabled SAFESEH, you can use the following command line:

binary_valentine_cmd.exe --include-reports PE007 --include-reports PE009 dir/with/files

Here, PE007 is the Relocations are absent rule, and PE009 is the SAFESEH is disabled rule. You can list all rules by using the --list-reports option (see above).

Note that you can not use --include-reports and --exclude-reports together at the same time.

Report levels and categories filtering

To exclude some issue levels or categories from the output, use the --exclude-levels and --exclude-categories options. By default, Binary Valentine reports all levels (info, warning, error, critical) and categories (system, optimization, security, configuration, format).

For example, to make Binary Valentine report only the critical and error level issues, use the following command line:

binary_valentine_cmd.exe --exclude-levels info --exclude-levels warning dir/with/files

You can use the --list-reports option to see the level and the category for each supported rule.

Progress reporting

By default, Binary Valentine outputs only the detected issues to the terminal. If you need a more detailed progress report, use the --with-progress option. This option will make Binary Valentine additionally output directory traversal, file loading and scanning progress messages. Example:

binary_valentine_cmd.exe --with-progress dir/with/files

Output options

By default, Binary Valentine outputs each detected issue directly to the terminal. There are several options to customize this behavior.

Binary Valentine supports several output formats: plaintext and Static Analysis Results Interchange Format (SARIF) 2.1.0. In addition to terminal output, you can make Binary Valentine write one or more reports in this formats. Examples:

# Save report in SARIF format to sarif_report.json
binary_valentine_cmd.exe -S sarif_report.json dir/with/files
# Or
binary_valentine_cmd.exe --sarif sarif_report.json dir/with/files

# Save report in both SARIF format to sarif_report.json and
# plaintext format to report.txt
binary_valentine_cmd.exe -S sarif_report.json -T report.txt dir/with/files

# Save report in both SARIF format to sarif_report.json and
# plaintext format to report.txt. In addition, disable terminal output.
binary_valentine_cmd.exe -S sarif_report.json -T report.txt --silent dir/with/files

Reports will always have the UTF-8 encoding.

Combined analysis options

By default, Binary Valentine performs both single-executable and cross-executable analysis. Cross-executable rules detect issues across all executables which are being scanned in the same invocation. For example, there are rules which detect PE version information inconsistencies across all analyzed files.

To disable combined analysis, use the --do-combined-analysis=0 option.

Execution options

Binary Valentine is a multithreaded application, and it allocates a number of threads which corresponds to the number of processor cores. Each file is analyzed by a separate thread, and there is also a common thread which loads the files. To change the number of analysis threads, use the --threads option.

By default, Binary Valentine reads up to 1 gigabyte of data into 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. You can alter this behavior:

# Load up to 2Gb of data into memory
binary_valentine_cmd.exe --max-loaded-targets-size 2G dir/with/files

Instead of limiting the preloaded data by size, you can limit the amount of simultaneously loaded files:

# Load up to 10 files at the same time
binary_valentine_cmd.exe --max-concurrent-tasks 10 dir/with/files

Note that you can not use both --max-loaded-targets-size and --max-concurrent-tasks options at the same time.

Root path

Binary Valentine uses the current directory as a root path to figure out all relative paths you provide in the command line. You can change the root path by using the --root-path option:

# Scan all files from C:/analysis/dir/with/files and write the SARIF
# report to C:/analysis/out.sarif
binary_valentine_cmd.exe --root-path C:/analysis --sarif out.sarif dir/with/files

Command line return values

Binary Valentine returns several different return values when it completes the analysis:

  • 0 - No issues detected for the scanned files.
  • 1 - Some issues were detected for the scanned files.
  • 2 - There were some issues with the analysis (for example, some files are not accessible).
  • 3 - A combination of 1 and 2.
  • 4 - Invalid options were provided to the command line.
  • 5 - Analysis was interrupted.
  • -1 - Internal error.