Skip to content

Latest commit

 

History

History
172 lines (112 loc) · 10.5 KB

configuration.md

File metadata and controls

172 lines (112 loc) · 10.5 KB
Raw

ScubaGear Configuration File

ScubaGear allows users to specify most of the Invoke-SCuBA cmdlet parameters in a configuration file. The path of the file is specified by the -ConfigFilePath parameter, and its contents can be formatted as YAML or JSON. Important details about executing ScubaGear with a configuration file are listed below.

  • Executing ScubaGear with a modified configuration file is required to pass or omit specific ScubaGear policy checks. See SCuBA compliance use and the associated sample configuration file for details.

  • The configuration file allows users to add additional fields to embed within the ScubaGear output JSON for supplemental metadata purposes.

  • The configuration files use the Pascal case convention for variables, and their names are consistent with the parameters.

Important: When a parameter is specified on both the command line and the configuration file, the parameter value provided on the command line has precedence and the configuration file value will be disregarded.

Sample Configuration Files

Sample config files are available in the repo. Several of these sample config files are explained in more detail in the sections below.

Basic Use

The basic use example config file only specifies a product name and an M365 environment.

ScubaGear can be invoked with this config file:

# Invoke with a config file
Invoke-SCuBA -ConfigFilePath basic_config.yaml

It can also be invoked while overriding the the M365Environment parameter:

# Invoke with an override
Invoke-SCuBA `
  -M365Environment gcc `
  -ConfigFilePath minimal_config.yaml

Typical Use

The typical use example config file includes multiple products specified as a list and an M365 environment. Additional product values are commented out and will not be included in the testing, but they are retained in the config file to easily add them back later.

ScubaGear can be invoked with this config file:

# Invoke with config file
Invoke-SCuBA -ConfigFilePath typical_config.yaml

It can also be invoked while specifying non-interactive mode authentication parameters:

# Invoke with non-interactive authentication
Invoke-SCuBA `
  -ConfigFilePath typical_config.yaml `
  -Organization contoso.onmicrosoft.com `
  -AppID abcdef0123456789abcde01234566789 `
  -CertificateThumbprint fedcba9876543210fedcba9876543210fedcba98

SCuBA compliance use

The SCuBA compliance example config file contains a base essential set of parameters for organizations seeking to meet SCuBA compliance checks. The configuration file contains a subset of ScubaGear parameters, fields for adding conditional access policy exceptions, fields for omitting ScubaGear policy checks, and additional fields for documenting the organization running ScubaGear. Users are highly encouraged to read all the configuration file documentation sections to comprehend what each field is for and to modify those fields to successfully pass ScubaGear's SCuBA baseline compliance checks.

Uniquely, this example configuration file contains the additional OrgName and OrgUnitName fields for documenting both the organization and organizational subunit owner of the M365 tenant ScubaGear is running against.

OrgName: Department of Example
OrgUnitName: Subdepartment of Example

ScubaGear can be invoked with this config file:

# Invoke with config file
Invoke-SCuBA -ConfigFilePath scuba_compliance.yaml

Credential Use

The credential user example config file supplies credentials using a service principal, appId, and certificate thumbprint. (The associated private key is still required.) Config files with sensitive data should be protected appropriately.

ScubaGear can be invoked with this config file:

# Invoke with config file
Invoke-SCuBA -ConfigFilePath creds_config.yaml

It can also be invoked by overriding the product names:

# Invoke with a different product name
Invoke-SCuBA `
  -ConfigFilePath typical_config.yaml `
  -ProductNames defender

Full Use

The full config file shows all of the global parameters supported by ScubaConfig specified in the config file. Any one of these parameters may be commented out. If not specified or if commented out, ScubaConfig will supply the default value, unless it's overridden on the command line. Default values do not apply to authentication parameters.

# Invoke without any overrides
Invoke-SCuBA -ConfigFilePath full_config.yaml

Generate an Empty Sample Configuration File

ScubaGear's support module can generate an empty sample config file. Running the New-SCuBAConfig cmdlet will generate a full sample config called SampleConfig.yaml that can be filled out based on the guidance below. Parameters can be passed to the New-SCuBAConfig cmdlet to change values inside the sample config.

# Create an empty config file
New-SCuBAConfig

Omit Policies

In some cases, it may be appropriate to omit specific policies from ScubaGear evaluation. For example:

  • When a policy is implemented by a third-party service that ScubaGear does not audit
  • When a policy is not applicable to your organization (e.g., policy MS.EXO.4.3v1 is only applicable to federal, executive branch, departments and agencies)

The OmitPolicy top-level key, shown in this example ScubaGear configuration file, allows the user to specify the policies that should be omitted from the ScubaGear report. Omitted policies will show up as "Omitted" in the HTML report and will be colored gray. Omitting policies must only be done if the omissions are approved within an organization's security risk management process. Exercise care when omitting policies because this can inadvertently introduce blind spots when assessing your system.

For each omitted policy, the config file allows you to indicate the following:

  • Rationale: The reason the policy should be omitted from the report. This value will be displayed in the "Details" column of the report. ScubaGear will output a warning if no rationale is provided.
  • Expiration: Optional. A date after which the policy should no longer be omitted from the report. The expected format is yyyy-mm-dd.

Product-specific Configuration

Config files can include a top-level level key for a given product whose values are related to that specific product. For example, look for the value of Defender in this Defender config file. Currently, only Entra ID and Defender use this extra configuration.

Under a product key, there can be policy keys that provide configuration values unique to the product. In the Defender config file, for example, there is the MS.DEFENDER.1.4v1 key.

Entra ID Configuration

The ScubaGear configuration file provides the capability to exclude specific users or groups from some of the Entra ID policy checks. For example, a user could exclude emergency access accounts from some of the policy checks. Exclusions must only be used if they are approved within an organization's security risk acceptance process. Exclusions can introduce grave risks to your system and must be managed carefully.

An example configuration file for Entra ID can be found in this sample configuration.

Conditional Access Policy Exclusions

The Aad top level key in the configuration allows the user to specify configurations specific to the Entra Id baseline. Under the Aad key is the policy identifier such as MS.AAD.1.1v1 and under that is the CapExclusions key where the excluded users or groups are defined. The CapExclusions key supports both a Users or Groups list with each entry representing the UUID of a user or group from the tenant that will be excluded from the respective policy check.

CapExclusions are supported for the following policies:

  • MS.AAD.1.1v1
  • MS.AAD.2.1v1
  • MS.AAD.2.3v1
  • MS.AAD.3.1v1
  • MS.AAD.3.2v1
  • MS.AAD.3.6v1
  • MS.AAD.3.8v1

Privileged User Policy Exclusions

In addition to defining exclusions for conditional access policies, the configuration also supports user or group exclusions related to Entra Id policy section 7 which is related to highly privileged user access. The RoleExclusions key supports both a Users and Groups list with each entry representing the UUID of a user or group from the tenant that will be excluded from the respective policy check.

RoleExclusions are supported for the following policies:

  • MS.AAD.7.4v1

Defender Configuration

An example for Defender can be found in this configuration. More details will be coming soon.

Anchors and Aliases

If YAML is chosen as the config file format, YAML anchors and aliases can be used to avoid repeating policy values. For example, in the Defender config file, &CommonSensitiveAccountFilter is an anchor whose value is referenced later by *CommonSensitiveAccountFilter, an alias.

Muting the Version Check Warnings

To prevent ScubaGear from trying to determine if a newer release is available and emitting a warning at import time, set the environment variable SCUBAGEAR_SKIP_VERSION_CHECK to any non-whitespace value.