Instructions for running RegScale Standalone in a PodMan Orchestrator

Both the Community Edition (CE) and Enterprise Edition (EE) versions of RegScale can be installed in stand-alone mode. What this means is that the application can be installed on a single machine; whether laptop, desktop, Virtual Machine (VM), or physical server.

This version is perfect for test and evaluation, small businesses, individual auditors, or other use cases where high availability and scalability are not requirements for the system.

This document provides installation files and instructions for deploying RegScale in stand-alone mode running within PodMan.

Local PodMan

RegScale created a convenient and straightforward way to run RegScale locally, even without connecting to a remote database. This guide will allow a customer to spin up a local SQL container, connect to the database, initialize the database, and run RegScale; all within their stand-alone environment (laptop, desktop, or VM). This approach allows our customers to quickly and easily test and evaluate the product without external dependencies on infrastructure (which can take a long time to provision in Enterprise environments) and with no up-front costs for the evaluation.

NOTE: Stand-alone RegScale can also be used for Production purposes but RegScale recommends installing a production grade SQL Server database on a separate machine/environment.

In order to setup the stand-alone environment, the customer should take the following steps:

Pre-requisites

You need to have PodMan installed in Red Hat: PodMan Documentation
You need to have a user account and access to Docker Hub to pull the image
You can review the docker container here: RegScale Docker Hub

Architecture

Stand Alone Architecture

The overall components of this architecture are described below:

RegScale Core Platform - Linux Docker Container that runs on a Virtual Machine (VM) based on Red Hat Enterprise Linux (RHEL) or Ubuntu. It can also be installed locally on a Mac laptop or Windows workstation (using the Windows Subsytem for Linux) for test and evaluation purposes. This container is the core of the application and contains the Angular front end and middle tier of C# Application Programming Interfaces (APIs)
Docker Hub - repository that contains all published releases of RegScale containers which can be pulled for installations or upgrades
APIs - Representational State Transfer (REST) APIs that are well defined with a published Swagger interface for developing automations and integrations
Command Line Interface (CLI) - sidecar for bulk data processing via the command line (OPTIONAL and only available for Enterprise Customers). It should run on RHEL or Ubuntu in a separate VM which can schedule CRON jobs or other means to batch update large amounts of data.
SQL Server - relational database for storing RegScale data. It is typically installed into an existing database cluster or a cloud Relational Database Service (RDS). For test and evaluation, you can also install a local SQL Server Express instance on the same VM but this is not recommended or supported for Production use. NOTE: SQL Server containers for a local instance do not currently support Mac M1 chips due to a known Microsoft issue. If on a new Mac, you will need to provide a connection string to a remote SQL Server database.
File Storage - RegScale allows customers to upload and encrypt evidence inside of the platform. Storage is needed to hold this data and is typically thin provisioned to allow expansion over time.
Backups - both the database and file storage should be routinely backed up. The container does not need to be backed up as it is immutable and stateless.

Installation

Create an /atlas directory in your installation
Download all of the configuration files below:
- NOTE: All scripts are in our GitHub Community Repository
- RegScale Configurations
  - or pull via command line at wget https://raw.githubusercontent.com/RegScale/community/main/standalone/atlas.env
- RegScale Database Configurations
  - or pull via command line at wget https://raw.githubusercontent.com/RegScale/community/main/standalone/db.env
- All files should in the same directory. Perform a ls command to verify that they are downloaded correctly.
Edit db.env using nano db.env
- Set SA_PASSWORD to a secure value of your choosing. Avoid most special characters as they will potentially cause issues (allowed special characters are listed below). NOTE: this password is stored locally with the customer and is not available or retrievable by RegScale.
- NOTE This password needs to meet the built-in complexity requirements of SQL Server:
  - At least 8 characters.
  - The password does not contain the account name of the user.
  - The password is at least eight characters long.
  - The password contains characters from three of the following four categories:
    - Latin uppercase letters (A through Z)
    - Latin lowercase letters (a through z)
    - Base 10 digits (0 through 9)
    - Non-alphanumeric characters such as: exclamation point (!), dollar sign ($), number sign (#), or percent (%)
  - Passwords can be up to 128 characters long. Use passwords that are as long and complex as possible.
Edit atlas.env using nano atlas.env
- StoredFilesPath: This is the location where the persistent storage will be mounted. Make sure the mount point exists.
  - Default value: /atlas/files
- FileSizeLimit: The file size limit per file in bytes. Please note the overall limit is 120 MB, even if you set this variable larger than that. This variable is optional and will be set to 100 MB by default if nothing is provided.
  - Default value: 104857600
- DB_SERVER: Name of the database server. DO NOT CHANGE IF USING docker-compose
  - Default value: atlas-db
- DB_PORT: Port for the database. DO NOT CHANGE IF USING docker-compose
  - Default value: 1433
- JWTSecretKey: This is your JWT Secret Key. This can be any random value that is 32, 64, or 128 characters/bytes in length (or 256, 512, or 1024 bits respectively).
  - For setting keys, we recommend this Online Encryption Key Generator (256 bit) for quickly generating random security keys.
  - You can use any other mechanism to create this key. However, we recommend a minimum of a 256-bit secure key as it will be changed infrequently (or never) as it will invalidate all open sessions after being deployed.
  - Default value: JWTSecretKeyFromSomeWhere6789012
- EncryptionKey: This is your Encryption Key for encrypted files and data in the database. This can be any random value that is 32, 64, or 128 characters/bytes in length (or 256, 512, or 1024 bits respectively).
  - For setting keys, we recommend this Online Encryption Key Generator (256 bit) for quickly generating random security keys.
  - You can use any other mechanism to create this key. However, we recommend a minimum of a 256-bit secure key as it will be changed infrequently (or never) as it will invalidate all encrypted files after being deployed.
  - Default value: YourEncryptionKeyFromSomeWhere12
  - WARNING: Once this key is used, it should not be changed as it can result in data becoming unreadable.
- SQLConn: This is the SQL Connection string from above.
  - If using the container-hosted DB, simply configure the password to match the one configured in db.env. All other components should stay the same. NOTE: If you wish to connect to an external database, you can provide a full connection string and avoid provisioning a local SQL Server Express database.
Create the Network

podman network create atlas_net

Create the pod

podman pod create --name regscale -p 8080:8080 -p 8443:443 -p 1433:1433 --network atlas_net

Run RegScale

podman run -d --pod=regscale --restart=always -e ACCEPT_EULA=Y -e MSSQL_PID=Developer -e SA_PASSWORD=4YourStrongPassword --name atlas-db mcr.microsoft.com/mssql/server:latest`
podman run -d --pod=regscale --restart=always --requires atlas-db --env-file=./atlas.env --volume /atlas/files:/atlas/files --name atlas  regscale/regscale:latest

Add Certificates (Stand-Alone)

When configuring the system in Stand-Alone mode, RegScale has the ability to support SSL certificates for secure/encrypted communications. These certificates can be self-signed, signed by an internal CA, or signed by an external CA. Self-signed should ONLY be used in test environments

Make the directory
sudo mkdir /atlas/ssl

Edit the atlas.env file and add the following:

ASPNETCORE_URLS=https\://+:443;http\://+:80  
Kestrel:Certificates:Default:Path=/atlas/ssl/https.pfx  
Kestrel:Certificates:Default:Password=YourCertPassword

Add the Certificates to the trust store
Enter the container:

podman exec -it atlas /bin/sh

Within the container, copy the .crt file to /atlas/ssl

cp /etc/ssl/cets/ca-certificates.crt /atlas/ssl

Exit the container

Copy a 'http.pfx' to '/atlas/ssl/'

cp http.pfx /atlas/ssl/

On the local machine attach your pem encoded certificate to the end of ca-certificate.crt
Create directory
/atlas/ca

cp ca-certificate.crt into /atlas/ca/

Update the launch command of atlas:
Add --volume /atlas/ca:/etc/ssl/certs to the podman run command

podman run -d --pod=regscale --restart=always --requires atlas-db --env-file=./atlas.env --volume /atlas/files:/atlas/files --volume /atlas/ssl:/atlas/ssl --volume /atlas/ca:/etc/ssl/certs --name atlas regscale/regscale:latest

Helpful utilities

podman pod ls - Lists all pods
podman ps -a --pod - Lists containers with associated pods
podman logs -f atlas - Follow (-f) atlas container logs
podman logs -f atlas-db - Follow (-f) atlas-db container logs
podman pod logs -f regscale - Follow (-f) the regscale pod logs
podman kube generate regscale - Generate a configuration file (yml) for running RegScale
podman kube play regscale - Start regscale using a configuration file generated in the step above
podman exec -it atlas /bin/sh - Open a shell inside the atlas container
podman volume list - List all volumes
podman volume rm -a - Remove unused volumes

Troubleshooting

If you get the following error:
Error: short-name "regscale/regscale:latest" did not resolve to an alias and no unqualified-search registries are defined in "/etc/containers/registries.conf"

Add the following to /etc/containers/registeries.conf

unqualified-search-registries = [ "docker.io"]
short-name-mode="enforcing"

Results should look like

# NOTE: RISK OF USING UNQUALIFIED IMAGE NAMES
# We recommend always using fully qualified image names including the registry
# server (full dns name), namespace, image name, and tag
# (e.g., registry.redhat.io/ubi8/ubi:latest). Pulling by digest (i.e.,
# quay.io/repository/name@digest) further eliminates the ambiguity of tags.
# When using short names, there is always an inherent risk that the image being
# pulled could be spoofed. For example, a user wants to pull an image named
# `foobar` from a registry and expects it to come from myregistry.com. If
# myregistry.com is not first in the search list, an attacker could place a
# different `foobar` image at a registry earlier in the search list. The user
# would accidentally pull and run the attacker's image and code rather than the
# intended content. We recommend only adding registries which are completely
# trusted (i.e., registries which don't allow unknown or anonymous users to
# create accounts with arbitrary names). This will prevent an image from being
# spoofed, squatted or otherwise made insecure.  If it is necessary to use one
# of these registries, it should be added at the end of the list.
#
# # An array of host[:port] registries to try when pulling an unqualified image, in order.
unqualified-search-registries = ["registry.fedoraproject.org", "registry.access.redhat.com", "docker.io", "quay.io"]
# unqualified-search-registries = ["example.com"]
#
# [[registry]]
# # The "prefix" field is used to choose the relevant [[registry]] TOML table;
# # (only) the TOML table with the longest match for the input image name
# # (taking into account namespace/repo/tag/digest separators) is used.
# #
# # The prefix can also be of the form: *.example.com for wildcard subdomain
# # matching.
# #
# # If the prefix field is missing, it defaults to be the same as the "location" field.
# prefix = "example.com/foo"
#
# # If true, unencrypted HTTP as well as TLS connections with untrusted
# # certificates are allowed.
# insecure = false
#
# # If true, pulling images with matching names is forbidden.
# blocked = false
#
# # The physical location of the "prefix"-rooted namespace.
# #
# # By default, this is equal to "prefix" (in which case "prefix" can be omitted
# # and the [[registry]] TOML table can only specify "location").
# #
# # Example: Given
# #   prefix = "example.com/foo"
# #   location = "internal-registry-for-example.net/bar"
# # requests for the image example.com/foo/myimage:latest will actually work with the
# # internal-registry-for-example.net/bar/myimage:latest image.
#
# # The location can be empty iff prefix is in a
# # wildcarded format: "*.example.com". In this case, the input reference will
# # be used as-is without any rewrite.
# location = internal-registry-for-example.com/bar"
#
# # (Possibly-partial) mirrors for the "prefix"-rooted namespace.
# #
# # The mirrors are attempted in the specified order; the first one that can be
# # contacted and contains the image will be used (and if none of the mirrors contains the image,
# # the primary location specified by the "registry.location" field, or using the unmodified
# # user-specified reference, is tried last).
# #
# # Each TOML table in the "mirror" array can contain the following fields, with the same semantics
# # as if specified in the [[registry]] TOML table directly:
# # - location
# # - insecure
# [[registry.mirror]]
# location = "example-mirror-0.local/mirror-for-foo"
# [[registry.mirror]]
# location = "example-mirror-1.local/mirrors/foo"
# insecure = true
# # Given the above, a pull of example.com/foo/image:latest will try:
# # 1. example-mirror-0.local/mirror-for-foo/image:latest
# # 2. example-mirror-1.local/mirrors/foo/image:latest
# # 3. internal-registry-for-example.net/bar/image:latest
# # in order, and use the first one that exists.
short-name-mode="enforcing"

Air Gap Deployments

The preceding steps require the installation target to be Internet accessible. To install RegScale on an "air-gapped" network (not connected to the Internet) the docker images will need to be copied from the Internet and loaded on a local server. There is a command line utility called "skopeo" that achieves this.

Install skopeo (use the appropriate package manager for the local version of linux) on an internet facing machine:

sudo yum install skopeo

Use skopeo to download the docker container images from https://docker.io:

skopeo login docker.io
<username>
<password>
skopeo copy docker://regscale/regscale:latest dir:./images/regscale
skopeo copy docker://mcr.microsoft.com/mssql/server:2019-latest dir:./images/mssql

This will create two directories under "images": "regscale" and "mssql". Use the tarcommand to compress these directories

tar -cvf containers.tar ./images

Copy the containers.tar file from the internet facing computer to the air-gapped server where RegScale is to be installed using sneakernet, one-way transfer, or other approved local methods.
On the air-gapped server, expand the tar file:

tar -xvf containers.tar

Use the docker command to load the images:

sudo podman load -i ./images/mssql
sudo podman load -i ./images/regscale

The Images are now available to be used by the podman run commands in the above instructions