m365

GearConnect: Multi-Tenant App for ScubaGear

Table of Contents

• Overview
• Installation
  • Requirements
  • Deploying with Terraform
  • Onboarding a Tenant
  • Logging / Alerts
  • Maintenance
• Additional Code Information

This directory includes code for automating ScubaGear execution in an Azure environment against one or more tenants. Note that this document assumes knowledge of ScubaGear.

Overview

GearConnect consists of infrastructure deployed in a host tenant for running ScubaGear and an installation script used by tenants to install the ScubaConnect application. GearConnect is configured to automatically run ScubaGear against tenants on configurable schedule (e.g., daily, weekly, or monthly.) ScubaGear configuration files and results files are read from and written to Azure storage.

GearConnect can be used to run ScubaGear against the tenant it is deployed in or it can be used in a multi-tenant setting to run ScubaGear against multiple other tenants.

Note	GCC High environments are separated from commercial and GCC. Deploy GearConnect in the same environment as the tenants you intend to run on. (Commercial and GCC can communicate between each other.)

GearConnect Single-Tenant Architecture

GearConnect Multi-Tenant Architecture

Installation

GearConnect requires two primary steps to install and use.

1. Deploying resources to host tenant with terraform. See Deploying with Terraform

2. Onboarding tenants via uploading configuration files and running install script. See Onboarding a Tenant

Requirements

Before deploying GearConnect, the following will need to be installed on your machine:

• Terraform - Used for deploying and managing infrastructure

• Azure CLI - Used for authenticating and interacting with your Azure environment

  • Be sure to also follow the instructions to sign in

It is expected that this code is deployed by a user with administrator privledges.

Deploying with Terraform

1. Prepare a directory for your deployment

   1. Change directories to m365/terraform/env

   2. Create a copy of the example directory with a name of your choice (e.g., <myenv>). The remaining steps should be completed in this new directory

2. Update variables and configurations

   1. In your new directory, <myenv>, modify the variables.tfvars file to configure the deployment for your needs

      1. Set contact_emails to administrators' emails and set resource_group_name to the resource group to create and deploy infrastructure in

      2. Review the defaults used for optional variables in Terraform Variables. Some of these may need to be modified depending on your environment

   2. (Optional, but recommended) Modify the provider.tf file to configure Terraform to store state in Azure. See external documentation

3. Run terraform

   1. Run az login if not already done to configure your credentials

   2. In your <myenv> directory, Run terraform init. This only needs to be done once unless providers are updated

   3. In your <myenv> directory, Run terraform apply -var-file=variables.tfvars. Confirm changes meet your expectations then type "yes"

4. Onboard a tenant following the guidance in Onboarding a Tenant

Example of completing steps 1-3 in bash

$ cd m365/terraform/env
m365/terraform/env$ cp -r example myenv
m365/terraform/env$ cd myenv
m365/terraform/env/myenv$ vim variables.tfvars
m365/terraform/env/myenv$ az login
m365/terraform/env/myenv$ terraform init # only needed once
m365/terraform/env/myenv$ terraform apply -var-file=variables.tfvars

Terraform Variables

This section provides the description for all terraform variables sorted by their likelihood of being changed. For a typical deployment, set contact_emails and resource_group_name then review the defaults for the optional variables and override in the tfvars file as needed.

Required

contact_emails (string)

Emails to notify for alerts and before certificate expiry

resource_group_name (string)

Resource group to create and build resources in

Optional

location (string) [default=East US]

Region to build resources in

schedule_interval (string) [default=Week]

The interval to run the scheduled job on.

app_name (string) [default=ScubaConnect]

App name. Displayed in Azure console on installed tenants

app_multi_tenant (bool) [default=False]

If true, the app will be able to be installed in multiple tenants. By default, it is only available in this tenant

vnet (object) [default=None]

Configuration for the vnet, including the address space, ACI subnet, and a list of allowed IP ranges. All strings in CIDR format

firewall (object) [default=None]

Configuration for an Azure Firewall; if not null, traffic will be routed through this firewall

serial_number (string) [default=01]

Increment by 1 when re-provisioning with the same resource group name

image_path (string) [default=./cisa_logo.png]

Path to image used for app logo. Displayed in Azure console on installed tenants

Advanced

certificate_rotation_period_days (number) [default=30]

How many days between when the certificate key should be rotated. Note: rotation requires running terraform

create_app (bool) [default=True]

If true, the app will be created. If false, the app will be imported

prefix_override (string) [default=None]

Prefix for resource names. If null, one will be generated from app_name

input_storage_container_id (string) [default=None]

If not null, input container to read configs from (must give permissions to service account). Otherwise by default will create storage container.

output_storage_container_id (string) [default=None]

If not null, output container to put results in (must give permissions to service account). Otherwise by default will create storage container.

tenants_dir_path (string) [default=./tenants]

Relative path to directory containing tenant configuration files in yaml

container_registry (object) [default={'server': 'ghcr.io'}]

Credentials for logging into registry with container image

container_image (string) [default=ghcr.io/cisagov/scubaconnect-m365:latest]

Docker image to use for running ScubaGear.

Onboarding a Tenant

To onboard a tenant, open powershell and run ./Install-GearConnect.ps1 -AppId <app_id> where app_id is output by Terraform. This script must be run even in a single-tenant architecture to actually install the app.

Once completed, upload a ScubaGear configuration file to the input_storage_container_id named <tenant_fqdn>.yaml (e.g., myorg.onmicrosoft.com.yaml). You may upload the file directly to Azure, or place it in env/<your_env>/tenants/ and run terraform apply. Refer to the ScubaGear Configuration File documentation for details on creating the configuration file.

Repeat these steps for each tenant in a multi-tenant architecture.

Logging / Alerts

Terraform will create a Log Analytics Workspace (scubaconnect-monitor-loganalytics) which will hold logs from the container. There will be two pre-created searches available: scubaconnect Container Logs (7d) and scubaconnect Last Run Output. These allow you to quickly view output from the container.

The container will exit with a non-zero code if it fails to run ScubaGear on any tenant. A log-based alert is pre-configured to send an email to contact_emails when this occurs. Looks into the "Last Run Output" logs to determine the cause.

Maintenance

GearConnect’s architecture (limited by Managed Identity support in Windows containers) requires exporting the app’s certificate as a secret variable in the container. To mitigate this, the certificate is short-lived. Terraform is set up to automatically generate a new certificate every certificate_rotation_period_days (defaults to 30). To utilize this mechanism, you must run terraform apply on a regular basis. This can be done through scheduled CI/CD or manually (an email will be sent one week prior to expiration). This will ensure the certificate is always valid.

The container will be regularly rebuilt and updated overtime to support new versions of ScubaGear. No action is required for container updates as Azure Container Instances will grab the latest image by default.

Additional Code Information

scheduled vs adhoc container instances

GearConnect creates two nearly identical container instances named scheduled and adhoc. When either container is run, they output their respective name to a field in the ScubaResults file: MetaData/RunType. The runbook triggers the scheduled container instances and the adhoc container instance is intended for manual runs. Azure does not allow changing input variables to a container instance, so this is why both are created.