Binary Image Scan Guide

This document explains how to generate a Software Bill of Materials (SBOM) from binary disk images and ISO files using a CV client CLI tool. The guide focuses on safe, repeatable workflows that mount images in read-only mode where possible and then provide the mounted filesystem path to the CV client CLI for analysis.

Supported Binary Image Formats

Extension	Primary Owner	Description	Recommended OS
`.vmdk`	VMware	Binary disk image	Linux (Ubuntu/Debian)
`.vhdx`	Hyper-V	Binary disk format	Windows (PowerShell Admin)
`.iso`	ISO standard	Filesystem image	Linux (Ubuntu/Debian)
`.qcow2`	QEMU/KVM	Copy-on-write disk image	Linux (Ubuntu/Debian)
`.ova`	OVF package	Binary appliance archive	Linux (Ubuntu/Debian)
`.raw`	Generic	Raw disk image	Linux (Ubuntu/Debian)

1. Guide: Mounting image and binary formats.

Step-by-Step Procedures

This section explains how to mount each supported image type and provide the mounted path to the cvclient command-line tool.

1.1 Linux Disk Images: VMDK, QCOW2, RAW

All three formats (.vmdk, .qcow2, .raw) can be mounted using guestmount on Linux / WSL. The steps are identical except the file path and mount point name..

Step 1: Update packages and install dependencies

sudo apt update
sudo apt install -y qemu-utils libguestfs-tools

Step 2: Set the libguestfs backend

export LIBGUESTFS_BACKEND=direct

Step 3: Create a mount point on root level

sudo mkdir -p <path_where_you_want_to_mount>

Step 4: Mount the binary image using auto-detection

sudo guestmount -a "<path_to_image>" -i --ro -o allow_other -o uid=$(id -u) -o gid=$(id -g) <path_where_you_want_to_mount>

-- Note for RAW images: If auto-detection fails, add --format=raw:

sudo guestmount --format=raw -a "<path_to_image.raw>" -i --ro -o allow_other <path_where_you_want_to_mount>

Step 5: If auto-detection fails, inspect filesystems and partitions

sudo virt-filesystems -a "<path_to_image>" --all --long -h

Step 6: Mount a specific partition or filesystem if required

Replace /dev/sda1 with the correct partition shown in the inspection output.

sudo guestmount -a "<path_to_image>" -m /dev/sda1 --ro <path_where_you_want_to_mount>

Step 7: Provide the mounted path to the `cvclient` command-line tool

After the image is mounted successfully, provide this mounted path to the cvclient command-line tool:

cvclient -p <path_where_you_mounted_the_image> -u https://api-sca.complyvigilance.com -k <ACCESS_TOKEN> -pn "diskname_mount_projectname" -bi -o "output_results_dir"

Step 8: Unmount after scanning

sudo guestunmount <path_where_you_mounted_the_image>

1.2 ISO Files on Linux / WSL

.iso files are filesystem images mounted directly with the mount command.

Step 1: Create a mount point

sudo mkdir -p <path_where_you_mounted_the_image>

Step 2: Mount the ISO as a read-only loop device

sudo mount -o loop,ro "/path/to/image.iso" <path_where_you_mounted_the_image>

Step 3: Provide the mounted path to the `cvclient` command-line tool

cvclient -p <path_where_you_mounted_the_image> -u https://api-sca.complyvigilance.com -k <ACCESS_TOKEN> -pn "disk_mount_projectname" -bi -o "output_results_dir"

Step 4: Unmount after scanning

sudo umount <path_where_you_mounted_the_image>

1.3 OVA Images on Linux / WSL

.ova files are tar archives containing an OVF descriptor and disk images (usually .vmdk). You must extract them first.

Step 1: Install dependencies

sudo apt update
sudo apt install -y qemu-utils libguestfs-tools

Step 2: Set the libguestfs backend

export LIBGUESTFS_BACKEND=direct

Step 3: Create an extraction directory and mount point

mkdir -p extracted_ova
sudo mkdir -p <path_where_you_mounted_the_image>

Step 4: Extract the .ova file

tar -xvf "/path/to/image.ova" -C extracted_ova

Step 5: Identify the extracted disk image (usually a .vmdk file)

ls extracted_ova/

Step 6: Inspect the disk image partitions

sudo virt-filesystems -a "./extracted_ova/disk-file.vmdk" --all --long -h

Step 7: Mount the correct partition or filesystem if required in read-only mode

Replace /dev/sda2 and the VMDK filename as appropriate.

sudo guestmount -a "./extracted_ova/disk-file.vmdk" -m /dev/sda2 --ro -o allow_other <path_where_you_mounted_the_image>

Step 8: Provide the mounted path to the `cvclient` command-line tool

cvclient -p <path_where_you_mounted_the_image> -u https://api-sca.complyvigilance.com -k <ACCESS_TOKEN> -pn "ova_mount_projectname" -bi -o "output_results_dir"

Step 9: Unmount after scanning

sudo guestunmount <path_where_you_mounted_the_image>

1.4 VHDX Images on Windows

.vhdx files are Hyper-V binary disk images. Use PowerShell as Administrator.

Step 1: Mount the VHDX image

Mount-DiskImage -ImagePath "\path\to\image.vhdx"

Step 2: Identify the assigned drive letter

Get-Volume

For example, if Windows assigns drive (lets say E:) then move to Step 4.

If no drive letter appears, use one of the methods below.

Step 3: Manually assign a drive letter First, get the disk number and partition number:

Get-DiskImage -ImagePath "\path\to\image.vhdx" | Get-Disk | Get-Partition

Then assign a drive letter (replace X and partition number as needed):

Set-Partition -DriveLetter X -PartitionNumber 1

Step 4: Provide the mounted drive path to the `cvclient` command-line tool

cvclient -p <dir:path_to_mounted_dir:\> -u https://api-sca.complyvigilance.com -k <ACCESS_TOKEN> -pn "vhdx_mount_projectname" -bi -o "output_results_dir"

Step 5: Dismount the image after scanning

Dismount-DiskImage -ImagePath "\path\to\image.vhdx"

2. Expected Results and Verification

Use this section to confirm whether mounting and scanning were successful.

2.1 Successful Mount

A successful mount usually means:

The mount command completes without errors.
The mount point contains guest filesystem contents.
For Linux guests, expected folders may include:
- /bin
- /etc
- /usr
- /var
- /home
For Windows guests, expected folders may include:
- Windows
- Program Files
- Users
The mounted location appears in filesystem checks.

Verify mounted files

ls /mnt/<mount_point>

Verify mounted filesystem usage

df -h

2.2 Successful `cvclient` CLI Scan

A successful cvclient CLI scan usually means:

The cvclient CLI accepts the mounted filesystem path.
The scan completes without critical errors.

3. Common Issues and Troubleshooting

Issue	Possible Cause	Recommended Fix
Permission denied	Command was not executed with sufficient privileges	Run the mount command with `sudo` or use an elevated PowerShell session.
Auto-detection fails	Image contains multiple partitions, LVM, or unsupported layout	Use `virt-filesystems` to inspect partitions and mount the correct partition manually.
Mount point is empty	Wrong partition was mounted	Inspect the image and mount the partition that contains the operating system filesystem.
Mount point busy during unmount	Terminal, file explorer, or another process is using the mounted directory	Close file explorers and terminals using the path, then retry unmounting.
`cvclient` CLI cannot scan path	Incorrect or inaccessible mounted path	Verify that the path exists and contains filesystem files before providing it to the `cvclient` command-line tool.
Windows shows mounted Linux image folder as empty	The mount exists inside Linux/WSL context and is not exposed correctly to Windows Explorer	Check the mounted path from Linux terminal using `ls -la`. Provide the Linux mount path to the `cvclient` command-line tool if the tool runs inside Linux.
`guestmount` shows empty result	Auto-detection mounted the wrong filesystem or did not detect the OS properly	Use `virt-filesystems` and mount the correct partition manually with `-m`.
Cannot unmount image	A process is still using the mounted directory	Move out of the mount directory, close related terminals, then run `guestunmount` or `umount` again.

Binary Image Scan Guide

On this page