01.08 Installing the VirtualBox Appliance

Why this matters

The VirtualBox appliance is the shortest path from "I want to look at SimpleRisk" to a working instance. It's a pre-built Ubuntu virtual machine with Apache, PHP, MySQL, and SimpleRisk already installed and already configured — the appliance ships past the initial configuration wizard, so there's no health check to satisfy, no database to create, and no schema to fetch. Download, verify, import, boot, log in. For evaluations, proof-of-concept work, training environments, and air-gapped demonstrations, it removes every install-time variable at once.

That convenience comes with an ownership transfer that's easy to miss. The appliance is a starting image, not a managed product. The moment it boots on your hypervisor you own the operating system inside it: the OS patching, the MySQL administration, the TLS certificate, the backups, and — most urgently — the set of published default credentials it ships with. An appliance imported and left at its defaults is a SimpleRisk instance whose OS login, root account, and administrator account are documented on our public knowledge base. That's entirely appropriate for a laptop evaluation and entirely inappropriate for anything holding real risk data.

This article covers importing, networking, and hardening the appliance. Once it's up, it behaves exactly like a native Linux installation — same application, same Extras, same upgrade mechanics, same cron jobs — and the rest of this guide covers it from there.

Before you start

VirtualBox 7.0 or newer. The appliance is exported in VirtualBox machine format 1.19-linux, which is 7.x. Older releases can generally import the OVF 1.0 envelope, but the screens described here are the 7.x import wizard's, and settings from a newer machine format may be silently dropped on an older host.
Hardware virtualization enabled in firmware (Intel VT-x or AMD-V). The appliance is a 64-bit guest and VirtualBox refuses to start one without it. Usually on by default on business laptops, and the first thing to check if the machine won't power on.
Free disk space on the host — roughly 6 GB to get started, with headroom toward 64 GB. The download is about 850 MiB compressed, the unpacked disk image another 870 MiB, and the imported virtual disk is thin-provisioned with a 64 GiB maximum. It starts small, grows as data accumulates, and never shrinks on its own.
A networking decision, made before first boot. The exported adapter is NAT, which your host browser cannot reach without an extra step. Step 4 covers the three options; choosing one up front saves a confusing first boot.
A password manager, open. Step 7 rotates five secrets in one sitting. Generating and storing them as you go beats reconstructing afterwards which ones you changed.

Step-by-step

1. Download the appliance and verify the checksum

Go to https://www.simplerisk.com/download/vm and use the VirtualBox appliance link. You'll get a single zip archive named for the release — simplerisk-{version}-virtualbox.zip, roughly 850 MiB.

Alongside the link, the page publishes an MD5 checksum for that specific release. Verify before unpacking anything. The archive carries no internal manifest, so that checksum is the only integrity control available — a truncated or tampered file will otherwise present itself as a perfectly ordinary appliance.

# Windows, PowerShell
Get-FileHash -Algorithm MD5 .\simplerisk-{version}-virtualbox.zip

md5sum simplerisk-{version}-virtualbox.zip   # Linux
md5 simplerisk-{version}-virtualbox.zip      # macOS

Compare against the checksum next to the link you actually used — the VMware and VirtualBox appliances have different checksums, and every release has its own. If they don't match, delete the file and download it again. Don't import a mismatched image.

2. Unpack the archive

Extract to somewhere with room to spare. It contains exactly two files:

simplerisk-{version}.ovf — the appliance descriptor, and the file you point VirtualBox at.
simplerisk-{version}-disk001.vmdk — the disk image, in stream-optimized VMDK format.

Keep both together in the same directory. The descriptor references the disk by relative filename, so separating them fails the import with a missing-disk error.

3. Import the appliance

File → Import Appliance, select the .ovf, and continue to the appliance settings page. Two choices matter here:

Generate new MAC addresses for all network adapters. Take this. The appliance ships a fixed MAC, and a second copy — or any copy on a bridged network beside another — produces duplicate-MAC symptoms that are genuinely unpleasant to diagnose.
Import hard drives as VDI. Leave this ticked unless you have a reason not to. VirtualBox can only resize VDI and VHD, so importing as VMDK means a format conversion later if you ever need a bigger disk.

4. Correct two exported settings, and choose your networking

Turn off Remote Display. The appliance was exported with VirtualBox's remote display server enabled, TLS-secured, and pointed at certificate paths belonging to the machine that built the image — paths that won't exist on your host. The listener is bound to 127.0.0.1:5908, so it isn't a network exposure, but the server can't initialize against missing certificates and you may see a remote-display error at startup. Nothing in SimpleRisk depends on it. Settings → Display → Remote Display, clear Enable Server.

Then decide how the machine reaches the network. This is the step that most often derails a first appliance installation, because the exported adapter is NAT and NAT does not let your host browser reach the guest. Under NAT the guest gets a private address, typically 10.0.2.15, on a segment that exists only inside VirtualBox. Reading that off the console and typing it into your browser cannot work.

NAT with port forwarding

Reaching the interface: http://localhost:8080/ on the host
Use when: Single-user evaluation on a laptop. The guest stays invisible to your network, which is the safest default while it still has stock credentials.

Bridged adapter

Reaching the interface: http://{guest-IP}/ from anywhere on the network
Use when: Shared demonstrations and pilots. The machine takes a DHCP address like a physical host.

Host-only adapter

Reaching the interface: http://{host-only-IP}/ from the host only
Use when: Isolated lab work. Note that Extras, framework downloads, and the update check all need outbound HTTPS, so plan a second adapter if you want them.

For NAT with port forwarding, go to Settings → Network → Adapter 1 → Advanced → Port Forwarding and add:

simplerisk-http

Protocol: TCP
Host IP: 127.0.0.1
Host Port: 8080
Guest IP: (blank)
Guest Port: 80

Binding the host IP to 127.0.0.1 keeps the forwarded port reachable only from your own machine. Add a second rule (host 8443 → guest 443) for the HTTPS listener, and a third (host 2222 → guest 22) if you'd rather administer over SSH than through the console window.

For bridged, set Settings → Network → Adapter 1 → Attached to: Bridged Adapter and pick the host interface carrying your local network. Two cautions: corporate port security or network access control may reject the machine's new MAC, and the appliance takes a DHCP lease rather than a fixed address. If people are going to bookmark this, either reserve the address on your DHCP server or give the guest a static one — see Giving the appliance a static address below.

5. Boot the appliance and log in at the console

Start the machine and let it boot to a console login prompt.

Login:    simplerisk
Password: simplerisk

This account has sudo, authenticated with the same password. You'll need it in Step 7.

6. Reach the web interface

On NAT with port forwarding, browse from the host to http://localhost:8080/.

On bridged or host-only, find the guest's address at the console with ip addr show, then browse to it.

7. Change every default credential

Do this before the appliance holds real data. The appliance ships five secrets at published defaults. Until they're rotated, treat the machine as an open instance and keep it on NAT with a loopback-bound port forward.

Rotate all five in one sitting:

The simplerisk OS user — run passwd at the console.
The OS root account — sudo passwd root.
The MySQL root user. The appliance generates a MySQL root password on first boot and leaves it in /root/root_mysql_password.txt. Read it, change the password with mysqladmin -u root -p password '{new-password}', then delete the file.
The MySQL simplerisk application user — ALTER USER 'simplerisk'@'localhost' IDENTIFIED BY '{new-password}'; then FLUSH PRIVILEGES;. This one has a second half that's easy to forget: update DB_PASSWORD in /var/www/simplerisk/includes/config.php to match, or the application loses its database connection on the very next request.
The SimpleRisk admin account — in the web interface, My Profile → change the password. While you're there, set a real email address so password resets and notifications work.

On a laptop that leaves the building with risk data on it, consider VirtualBox disk encryption too, under Settings → General → Disk Encryption. It needs the VirtualBox Extension Pack and costs you a startup password prompt.

8. Record your baseline and finish the standard setup

The appliance is now an ordinary SimpleRisk installation on a Linux host you own.

Record what you actually received. You're responsible for patching this stack:

cat /etc/os-release   # Ubuntu release, for the OS patch cadence
php -v                # SimpleRisk requires PHP 8.3.0 or newer
mysql --version

Then complete the post-installation work any deployment needs, none of which the appliance can do for you:

Set the base URL to the address your users will actually type, so emailed links resolve. A mismatched base URL is the usual cause of "the link in the notification goes nowhere."
Put a real certificate in front of it if this is more than a laptop demonstration — see HTTPS and TLS Configuration.
Confirm the cron jobs are scheduled and running. Notifications, scheduled reports, and maintenance all depend on them — see The Cron Jobs.
Set up database backups that ship the output off the host — see Database Backup and Restore.
Register the instance so you get the free Upgrade and SCF Extras — see Registration and Licensing.
Take a VirtualBox snapshot of the freshly hardened, freshly configured appliance. It's the cheapest rollback point you'll ever have, and the right thing to take again before every upgrade.

Giving the appliance a static address

A bridged appliance takes a DHCP lease, which is fine for a demonstration and wrong for anything people bookmark. To pin it, edit the guest's netplan configuration.

First find the adapter name:

ip addr show

Then edit the netplan file — sudo vi /etc/netplan/01-netcfg.yaml — replacing ens3 with your adapter name and the addresses with yours:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens3:
      dhcp4: no
      addresses:
        - 192.168.1.199/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8, 1.1.1.1]

Apply it with sudo netplan apply. No output means success; confirm with ip addr show.

Two things to get right, because both are easy to miss:

The address and the gateway must be on the same subnet. An address of 192.168.121.199/24 with a gateway of 192.168.1.1 cannot work — the gateway isn't reachable from that network. Match the first three octets.
Use routes:, not gateway4:. Older guides use gateway4, which netplan deprecated; current Ubuntu warns on it and it will eventually stop working. The routes: block above is the supported form.

Changing the address changes the URL your users type, so update the SimpleRisk base URL to match afterwards.

Growing the appliance disk

The virtual disk is thin-provisioned with a 64 GiB ceiling. It grows as data accumulates and never shrinks, so the usual reason to resize is hitting that ceiling on a long-lived instance.

Two parts, and people routinely do only the first and wonder why nothing changed:

Grow the virtual disk. Power the machine off, then from the host:

bash VBoxManage modifymedium disk "/path/to/simplerisk-disk001.vdi" --resize 131072 # size in MB

This only works on VDI or VHD. If you imported as VMDK, convert first with VBoxManage clonemedium.

Grow the partition and filesystem inside the guest, so the OS can see the new space. Boot a live Ubuntu ISO, extend the partition with a partition editor, then extend the filesystem. On the appliance's LVM layout that means lvextend followed by resize2fs.

Take a snapshot before you start. Partition surgery on a machine holding real risk data is worth one cheap rollback point.

Common pitfalls

Trying to browse to the guest's NAT address. 10.0.2.15 is reachable from inside the machine and nowhere else. If the console shows a 10.0.2.x address and your browser times out, you're on NAT without a port-forwarding rule. Add the rule from Step 4 and browse to http://localhost:8080/, or switch to bridged.
Keeping the baked-in MAC address. One import on NAT is fine. A second copy, or any copy on a bridged network alongside another, produces duplicate-MAC symptoms that are genuinely unpleasant to diagnose: intermittent connectivity, ARP flapping, a switch port that quietly stops forwarding.
Chasing the remote-display error. The appliance exports with the remote display server enabled and certificate paths from the build machine. Any error concerns those missing certificates, not a broken appliance. Clear Enable Server and move on.
Leaving the defaults in place "just for now." The OS password, the root password, and the administrator password are published in our public knowledge base. An appliance on a bridged corporate network with stock credentials is an open instance.
Treating the appliance as maintained by SimpleRisk. The image is a point-in-time build. Nothing patches its Ubuntu packages, its PHP, or its MySQL but you. An appliance imported and never updated accumulates OS vulnerabilities indefinitely, however current the SimpleRisk application inside it is.
Upgrading by importing the next appliance. A newer appliance is a new, empty instance. Importing it doesn't carry your data across, and running the two side by side invites confusion about which one is real. Upgrade in place, exactly as you would any Linux installation, and snapshot first.
Running a real deployment on the exported 2 GB and 2 virtual CPUs. Those defaults suit an evaluation. A mid-size deployment wants 2–4 virtual CPUs and 4–8 GB, and the appliance runs Apache, PHP, and MySQL together on one host. Raise the allocation before you load frameworks or import scanner data, not after users start reporting slow pages.
Assuming the 64 GiB disk is fixed, or reducible. It's thin-provisioned: a few gigabytes at first, growing toward 64 GiB. It does not shrink when data is deleted, and VirtualBox cannot shrink it for you. Watch the host's free space.
Mistaking a snapshot for a backup. A snapshot of a running machine captures MySQL mid-transaction and lives on the same host disk as the machine itself. Excellent rollback point for an upgrade; not a backup strategy.
Skipping the checksum because the download "looks fine." The archive has no manifest and the import validates nothing. A truncated download can import successfully and fail later in ways that look like application defects. The verification is one command.
Clock drift after the host sleeps. Suspending a laptop suspends the guest's clock with it. A drifted guest produces cron jobs that fire late or not at all, notification timestamps that don't line up, and audit-trail entries in the wrong order. Confirm with timedatectl status inside the guest, and check that Guest Additions time synchronization is active.

What the appliance ships with

Artifacts: simplerisk-{version}-virtualbox.zip, containing simplerisk-{version}.ovf (OVF 1.0 envelope, VirtualBox machine format 1.19-linux) and simplerisk-{version}-disk001.vmdk (stream-optimized VMDK). No .mf manifest, so the published MD5 is the only integrity control.
Imported machine defaults: Ubuntu 64-bit guest; 2 virtual CPUs; 2048 MB RAM; 64 GiB thin-provisioned disk on a SATA/AHCI controller; VMSVGA graphics with 33 MB video memory; one E1000 adapter attached to NAT; fixed MAC address; remote display enabled on 127.0.0.1:5908 with build-host certificate paths.
Default credentials: OS: simplerisk / simplerisk (sudo-capable). MySQL root: generated at first boot, written to /root/root_mysql_password.txt. MySQL application user: simplerisk @ localhost. Application: admin / admin. All must be rotated — see Step 7.

Installing the VMware Appliance — the same appliance for a different hypervisor
System Requirements — what to size the machine for once it's past evaluation
Registration and Licensing — unlocking the free Upgrade and SCF Extras
The Upgrade Process — upgrading the appliance in place