Skip to content

Latest commit

 

History

History
90 lines (63 loc) · 7.23 KB

malcolm-iso.md

File metadata and controls

90 lines (63 loc) · 7.23 KB
Raw

Malcolm installer ISO

Malcolm's container-based deployment model allows Malcolm to run on a variety of platforms. However, in some circumstances (for example, as a long-running appliance as part of a security operations center, or inside a virtual machine) it may be desirable to install Malcolm as a dedicated standalone installation.

Malcolm can be packaged into an installer ISO based on the current stable release of Debian. This customized Debian installation is preconfigured with the bare minimum software needed to run Malcolm.

Generating the ISO

Official downloads of the Malcolm installer ISO can be downloaded from the GitHub releases page. It can also be built easily on an Internet-connected system with Vagrant:

The build should work with a variety of Vagrant providers:

To perform a clean build of the Malcolm installer ISO, navigate to the local Malcolm working copy and run:

$ ./malcolm-iso/build_via_vagrant.sh -f
…
Starting build machine...
Bringing machine 'default' up with 'virtualbox' provider...
…

Building the ISO may take 30 minutes or more depending on the system. As the build finishes, users will see the following message indicating success:

…
Finished, created "/malcolm-build/malcolm-iso/malcolm-{{ site.malcolm.version }}.iso"
…

By default, Malcolm's images are not packaged with the installer ISO. Malcolm assumes instead that users will pull the latest images with a docker compose --profile malcolm pull command as described in the Quick start section. To build an ISO with the latest Malcolm images included, follow the directions to create pre-packaged installation files, which include a tarball with a name such as malcolm_YYYYMMDD_HHNNSS_xxxxxxx_images.tar.xz. Then, pass that images tarball to the ISO build script with a -d, like this:

$ ./malcolm-iso/build_via_vagrant.sh -f -d malcolm_YYYYMMDD_HHNNSS_xxxxxxx_images.tar.xz
…

A system installed from the resulting ISO will load the Malcolm images upon first boot. This method is desirable when the ISO is to be installed in an "air gapped" environment or for distribution to non-networked machines.

Alternately, if users have forked Malcolm on GitHub, [workflow files]({{ site.github.repository_url }}/tree/{{ site.github.build_revision }}/.github/workflows/) are provided that contain instructions for GitHub to build the images and sensor and Malcolm installer ISOs - specifically [malcolm-iso-build-docker-wrap-push-ghcr.yml]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/.github/workflows/malcolm-iso-build-docker-wrap-push-ghcr.yml) for the Malcolm ISO. Users must run the workflows to build and push the fork's Malcolm images before building the ISO. The resulting ISO file is wrapped in a image that provides an HTTP server from which the ISO may be downloaded. See Using GitHub runners to build Malcolm images for more information.

Installation

The installer is designed to require as little user input as possible. For this reason, there are NO user prompts and confirmations about partitioning and reformatting hard disks for use by the operating system. The installer assumes all non-removable storage media (eg., SSD, HDD, NVMe, etc.) are available for use and ⛔🆘😭💀 will partition and format them without warning 💀😭🆘⛔.

The installer will ask for several pieces of information prior to installing the Malcolm base operating system:

  • Hostname
  • Domain name
  • Root password – (optional) a password for the privileged root account that is rarely needed
  • User name: the name for the non-privileged service account user account under which the Malcolm runs
  • User password – a password for the non-privileged sensor account
  • Encryption password (optional) – if encrypted installation option was selected at boot time, the encryption password must be entered every time the system boots

At the end of the installation process, users will be prompted with the following self-explanatory yes/no questions:

  • Format non-OS drive(s) for artifact storage?
  • Disable IPv6?
  • Automatically login to the GUI session?
  • Should the GUI session be locked due to inactivity?
  • Display the Standard Mandatory DoD Notice and Consent Banner? (only applies when installed on U.S. government information systems)
  • Allow SSH password authentication? (Caution: password authentication is less secure than public/private key pairs)

Following these prompts, the installer will reboot and the Malcolm base operating system will boot.

Setup

When the system boots for the first time, the Malcolm images will load if the installer was built with pre-packaged installation files as described above. Wait for this operation to continue (the progress dialog will disappear when they have finished loading) before continuing the setup.

Open a terminal (click the red terminal 🗔 icon next to the Debian swirl logo 🍥 menu button in the menu bar). At this point, setup is similar to the steps described in the Quick start section. Navigate to the Malcolm directory (cd ~/Malcolm) and run auth_setup to configure authentication. If the ISO does not include pre-packaged Malcolm images, or to retrieve the latest updates, run docker compose --profile malcolm pull. Finalize the configuration by running scripts/configure and follow the prompts as illustrated in the installation example.

Once Malcolm is configured, users can start Malcolm via the command line or by clicking the circular yellow Malcolm icon in the menu bar.