Developed by CISA, ScubaGoggles is an assessment tool that verifies a Google Workspace (GWS) organization's configuration conforms to the policies described in the Secure Cloud Business Applications (SCuBA) Security Configuration Baseline documents.
For the Microsoft 365 (M365) rendition of this tool, see ScubaGear.
Warning
This tool is in an alpha state and in active development. At this time, outputs could be incorrect and should be reviewed carefully.
The majority of the conformance checks done by ScubaGoggles rely on GWS Admin log events. If there is no log event corresponding to a SCuBA baseline policy, ScubaGoggles will indicate that the setting currently can not be checked on its HTML report output. In this situation, we recommend you manually review your GWS security configurations with the SCuBA security baselines.
Additionally, some events will not be visible due to data retention time limits, as the admin logs are only retained for 6 months (see Data retention and lag times). However, if you wish to generate a log event for testing ScubaGoggles' capabilities, follow the implementation instructions in the SCuBA GWS baseline documents to change your GWS configuration settings. Toggling certain settings, off and on will be enough to generate a log event. Other settings will require implementing more substantive configuration changes.
Many of the these controls can be scoped down to the organizational unit level. We recommend creating a new organization unit and applying these controls just to that new organizational unit for testing. Rerun ScubaGoggles after you've saved your configuration changes to see if the policy requirement is met.
Important
Use of this tool requires access to an internet browser for initial setup and to view the html report output.
To download ScubaGoggles:
- Click here to see the latest release.
- Click scubagoggles-[latest-version].zip to download the release.
- Extract the folder in the zip file.
Minimum required Python version to run the tool is 3.7.16.
The following commands are used to set up a python virtual environment (venv) to install the needed python dependencies. Inside the release or repo folder, open up a terminal and run the following commands based on your OS.
pip3 install virtualenv
python -m venv .venv
.venv\Scripts\activate
pip3 install virtualenv
virtualenv -p python3 .venv
source .venv/bin/activate
Users can run the tool via the scuba.py script as a developer or by installing the scubagoggles package in a python venv.
Choose either of these next steps to install the needed python dependencies in the venv.
In the root directory of the release/repo, install the scubagoggles package and dependencies with the following command.
python3 -m pip install .
In the root directory of the release/repo, install the the required dependencies with the following command.
pip3 install -r requirements.txt
Important
Users will need to rerun the activate script from the OS specific directions above in each new terminal session to reactivate the venv containing the dependencies.
The tool makes use of Open Policy Agent's Rego Policy language.
An OPA executable is required to execute this tool and can be downloaded using our download_opa.py script.
python download_opa.py --help
usage: download_opa.py [-h] [-v] [-os]
Download executable the OPA executable file required to run this SCuBA tool.
options:
-h, --help show this help message and exit
-v {0.45.0,0.46.3,0.47.4,0.48.0,0.49.2,0.50.2,0.51.0,0.52.0,0.53.1,0.54.0,0.55.0,0.56.0,0.57.1,0.58.0,0.59.0,0.60.0}
What version of OPA to download: Default version: 0.59.0
-os {windows,macos,linux}
Operating system version of OPA to download. Default os: windows
--disablessl If there are proxy errors, try adding this switch to disable ssl verification
# example
python download_opa.py -v 0.60.0 -os macos
- If the above script can not execute for any reason or you would prefer to download OPA manually, go to the Open Policy Agent website
- Check the website for a compatible OPA version (Currently v0.45.0 and above) for ScubaGoggles and select the corresponding version on top left of the website
- Navigate to the menu on left side of the screen:
Introduction -> Running OPA -> Download OPA - Follow the instructions for downloading the respective OPA executable for your OS.
Note
The following notes apply only for MAC and Linux users.
- By default on MAC and Linux systems the OPA executable will be run with
sudo. - Use the
scubagoggles gws --omitsudoflag to omit running the executable withsudo. - MAC and Linux OS users should have their OPA executables named
opa_darwin_amd64oropa_linux_amd64_staticrespectively for scubagoggles execution. - The OPA executable must also be given execute permissions
chmod +x opa_darwin_amd64 # give the opa executable execute permissionsThe tool uses the following OAUTH API scopes.
https://www.googleapis.com/auth/admin.reports.audit.readonlyhttps://www.googleapis.com/auth/admin.directory.domain.readonlyhttps://www.googleapis.com/auth/admin.directory.group.readonlyhttps://www.googleapis.com/auth/admin.directory.orgunit.readonlyhttps://www.googleapis.com/auth/admin.directory.user.readonlyhttps://www.googleapis.com/auth/apps.groups.settings
When running ScubaGoggles for the first time you will be prompted to consent to these API scopes. Users with the Super Admin role automatically have the privilege to consent to these scopes. A custom admin role can also be made with the minimum permissions to consent to these scopes. See this Google Admin SDK Prerequisites guide for more information.
- If you already have a Google Cloud Project that you want to utilize skip to Authentication
- Otherwise start by signing into http://console.cloud.google.com/.
- Follow the directions outlined in this guide to create a project
ScubaGoggles supports both OAuth and Service Accounts for authorization/authentication. OAuth requires regular user consent while using a service account allows for more automation. Follow the instructions below for the authentication method of your choice.
- Be signed into http://console.cloud.google.com/.
- From the hamburger menu on the left, select APIs & Services -> OAuth consent screen
- Select Internal for User Type
- Click Create
- Fill in your App name and User support email
- Scroll down to the Authorized Domains section
- Under Authorized domains, add the primary domain of your GWS organization.
- Add another email address for Developer contact information
- Click SAVE AND CONTINUE
- Do nothing on the Scopes screen, just click SAVE AND CONTINUE
- Review summary, then click BACK TO DASHBOARD
- Click Credentials from the menu on the left
- Click CREATE CREDENTIALS
- Select Oauth client ID
- Select Web application for Application type
- Give name as appropriate
- Under Authorized redirect URIs, click "ADD URI." Add
http://localhostandhttp://localhost:8080/ - Click CREATE
- Click DOWNLOAD JSON from the resulting OAuth client created page
- Click OK
- Move the downloaded file (begins with
client_secret*.json) to the root directory folder of this repo, rename tocredentials.json - Go back the menu on the left and click Enabled API Services
- In the center screen click Enable APIS AND Services
- Search for and enable the Admin SDK API
- Search for and enable the Groups Settings API
- During the first run of this tool your default web browser will open up a page to consent to the API scopes needed to run this tool. Sign in with an account with the necessary privileges and click allow.
If you've limited application access to Google's APIs in your organization, the Common Controls: App Access to Google APIs baseline covers this topic, follow the directions below to allowlist the OAuth app.
- Login to https://console.cloud.google.com
- Navigate to the appropriate project
- Select API's & Services from the top left hamburger icon
- Select Credentials
- Copy your client ID under OAuth 2.0 Client IDs
- Now login to admin.google.com and navigate to Security -> Access and Data Control -> API Controls -> Manage Third-Party App Access
- Select Add App -> Oauth App Name or Client ID
- Search by your OAuth client ID
- Select the App
- Select your root organization as the domain
- Select Trusted
Important
ScubaGoggles requires the service account to have domain-wide delegation of authority to function.
- Login to https://console.cloud.google.com and navigate to your GCP project.
- From the hamburger menu, select IAM & Admin -> Service Accounts
- Select CREATE SERVICE ACCOUNT. Fill out the id field and then select DONE
- Click on the newly created service account then click KEYS -> ADD KEY -> Create new key -> JSON -> CREATE
- Move the downloaded file (begins with
<service account>*.json) to the root directory folder of this repo, rename tocredentials.json - Now login to admin.google.com and navigate to Security -> Access and data control -> API controls
- Select MANAGE DOMAIN WIDE DELEGATION
- Select Add new
- Enter the
client_idfrom the downloaded credentials (also visible after clicking on the created Service account under Details -> Unique ID) - Enter each OAuth scope as listed in OAuth API Scopes
- Select AUTHORIZE
- Finally, run ScubaGoggles with the
--subjectemailoption set to the email of an admin with necessary permissions to run ScubaGoggles.
Note
ScubaGoggles can be run using a service account in a different organization.
To do so, specify the --customerid argument with the customer ID of the target organization (found in admin.google.com under Account -> Account settings)
Execute the ScubaGoggles tool using the scubagoggles command. For GWS, all commands will be under the gws subparser.
scubagoggles gws -h
usage: scubagoggles gws [-h] [-b [...]] [-o] [-c] [--subjectemail] [--customerid] [--opapath] [--regopath] [--documentpath]
[--runcached] [--skipexport] [--outputfoldername] [--outputproviderfilename]
[--outputregofilename] [--outputreportfilename] [--omitsudo] [--quiet] [--debug]
optional arguments:
-h, --help show this help message and exit
-b [ ...], --baselines [ ...]
A list of one or more abbreviated GWS baseline names that the tool will assess. Defaults to
all baselines. Choices: gmail, calendar, groups, chat, drive, meet, sites, commoncontrols,
rules, classroom
-o , --outputpath The folder path where both the output JSON & HTML report will be created. Defaults to "./" The
current directory.
-c , --credentials The relative path and name of the OAuth / service account credentials json file. Defaults to
"./credentials.json" which means the tool will look for the file named credentials.json in the
current directory.
--outjsonfilename The name of the file that encapsulates all assessment output. Defaults to ScubaResults.
--subjectemail Only applicable when using a service account. The email address of a user the service account
should act on behalf of. This user must have the necessary privileges to run scubagoggles.
--customerid The customer ID the tool should run on. Defaults to "my_customer" which will be the domain of
the user / service account authenticating.
--opapath The relative path to the directory containing the OPA executable. Defaults to "./" the current
executing directory.
--regopath The relative path to the directory contain the folder containing the rego files. Defaults to
"./rego" the "rego" folder inside the current executing directory.
--documentpath The relative path to the directory containing the SCuBA baseline documents. Defaults to
"./baselines" the "baselines" folder inside the current executing directory.
--runcached This switch when added will run in the tool in "RunCached mode". When combined with -sa allows
to the user to skip authentication and provider export.
--skipexport This switch when added will skip the provider export.To be used in conjunction with
--runcached.
--outputfoldername The name of the folder created in --outputpath where both the output JSON and the HTML report
will be created. Defaults to GWSBaselineConformance. The client's local timestamp will be
appended to this name.
--outputproviderfilename
The name of the Provider output json in --outputpath. Defaults to ProviderSettingsExport.
--outputregofilename
The name of the Rego output json in --outputpath. Defaults to TestResults.
--outputreportfilename
The name of the main html file homepage created in --outputpath. Defaults to BaselineReports.
--omitsudo This switch prevents running the OPA executable with sudo.
--quiet This switch suppresses automatically launching a web browser to open the html report output
and the loading bar output.
--debug This switch is used to print debugging information for OPA.
scubagoggles gws
scubagoggles gws -b gmail calendar
scubagoggles gws -b calendar gmail groups chat meet sites -o ./output
# skip authentication and provider export stage
# used for running against a cached provider json
scubagoggles gws --runcached --skipexport
scubagoggles gws --customerid <customer_id> --subjectemail admin@example.com
See the help options yourself
scubagoggles gws -h
The html report should open automatically. If not, navigate to the output folder and open the *.html file using a browser of your choice. The json output will also be located in this folder.
Note
If you chose not install the scubagoggles package in a venv but do have the dependencies installed from requirements.txt, you may execute the tool using the scuba.py script located in the root directory of this repository. Replace any scubagoggles directions with python scuba.py
- The Python scripts are saved in the
scubagogglesfolder. - The
regofolder holds the Rego files. Each*.regofile holds the "desired state" for each product, per the baseline policy statements. - Style and developer guides are located in the
guidesfolder.
We use a three-step process:
- Export. In this step, we primarily use the Google Admin SDK API to export and serialize all the relevant logs and settings into json. ScubaGoggles also uses various other Google APIs to grab organization metadata, user privileges etc.
- Verify. Compare the exported settings from the previous step with the configuration prescribed in the baselines. We do this using OPA Rego, a declarative query language for defining policy.
- Report. Package the data output by Rego into a human-friendly html report.
If an authorization error similar to the one below appears:
/Users/scubagoggles/provider.py:463: RuntimeWarning: An exception was thrown trying to get the tenant info:
<HttpError 403 when requesting https://admin.googleapis.com/admin/directory/v1/customers/my_customer?alt=json returned "Not Authorized to access this resource/api">
Ensure that you consented to the following API scopes as a user with the proper permissions to consent and have enabled the required APIs and Services.
If an error similar to the one below appears:
command not found: scubagoggles
Ensure that you have properly configured the virtual environment and have activated the virtual environment using the OS appropriate commands.
Alternatively, to run scubagoggles without installing it as a package, you can replace the scubagoggles command with python scuba.py.
If you are unable to view the HTML report in a browser window, the results of the conformance scan can be viewed in their raw JSON format.
We recommend running the conformance report in quiet mode to stop the web browser from being opened automatically. This can be done with the --quiet command:
scubagoggles gws --quiet
Once the scan is complete, navigate to the output folder. Within the output folder, we can access the generated HTML reports, or view the results in JSON format.
To view the JSON, open the ScubaResults.json file.
Each baseline will appear in the following format:
{
"Summary": {
"Gmail": {
"Manual": 26,
"Passes": 9,
"Errors": 0,
"Failures": 6,
"Warnings": 2
},
"Groups for Business": {
"Manual": 0,
"Passes": 6,
"Errors": 0,
"Failures": 0,
"Warnings": 1
}
},
"Results": {
"Gmail": [
{
"GroupName": "Mail Delegation",
"GroupNumber": "1",
"Controls": [
{
"Control ID": "GWS.GMAIL.1.1v0.1",
"Requirement": "Mail Delegation SHOULD be disabled.",
"Result": "Pass",
"Criticality": "Should",
"Details": "Requirement met in all OUs and groups."
}
...
Unless otherwise noted, this project is distributed under the Creative Commons Zero license. With developer approval, contributions may be submitted with an alternate compatible license. If accepted, those contributions will be listed herein with the appropriate license.