scubagoggles 0.5.0__tar.gz

scubagoggles-0.5.0/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

scubagoggles-0.5.0/MANIFEST.in

@@ -0,0 +1,10 @@
+# This manifest is used to ensure that certain non-Python files are included
+# in the ScubaGoggles distribution.  The following subdirectories (and their
+# contents) are included:
+
+graft scubagoggles/baselines
+graft scubagoggles/rego
+graft scubagoggles/reporter
+graft scubagoggles/sample-report
+graft scubagoggles/Testing
+graft scubagoggles/utils

scubagoggles-0.5.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: scubagoggles
+Version: 0.5.0
+Summary: SCuBA security baseline assessment tool
+Author: CISA
+License-Expression: CC0-1.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Security
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dnspython>=2.6.1
+Requires-Dist: google-api-python-client>=2.142.0
+Requires-Dist: google-auth-httplib2>=0.2.0
+Requires-Dist: google-auth-oauthlib>=1.2.1
+Requires-Dist: MarkupSafe>=2.1.5
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: requests>=2.32.3
+Requires-Dist: tqdm>=4.66.5
+Dynamic: license-file
+
+![ScubaGoggles Logo](https://github.com/cisagov/ScubaGoggles/raw/main/docs/images/ScubaGoggles%20GitHub%20Graphic%20v2.jpg)
+<div align='center' style="margin:0;" id="user-content-toc">
+  <ul>
+    <h1 style="display: inline-block;">ScubaGoggles</h1>
+  </ul>
+  <ul>
+        <a href="https://github.com/cisagov/ScubaGoggles/releases">
+        <img src="https://img.shields.io/badge/ScubaGoggles-v0.5.0-%2385B065?labelColor=%23005288"  alt="ScubaGoggles version #"></a>
+        <a href="https://github.com/cisagov/ScubaGoggles/tree/main/baselines">
+        <img src="https://img.shields.io/badge/GWS_SCB-v0.5-%2385B065?labelColor=%23005288" alt="GWS SCB version #"></a>
+        <a href="">
+        <img src="https://img.shields.io/github/downloads/cisagov/ScubaGoggles/total.svg"  alt="Downloads"></a>
+  </ul>
+</div>
+<h2 align='center' style="margin:0;">GWS Secure Configuration Baseline Assessment Tool </h2>
+
+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](https://cisa.gov/scuba)) Secure Configuration
+Baseline [documents](https://github.com/cisagov/ScubaGoggles/blob/main/scubagoggles/baselines/README.md).
+
+For the Microsoft 365 (M365) rendition of this tool, see [ScubaGear](https://github.com/cisagov/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.
+
+## Overview
+We use a three-step process:
+1. **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.
+2. **Verify**. Compare the exported settings from the previous step with the configuration prescribed in the baselines. We do this using [OPA Rego](https://www.openpolicyagent.org/docs/latest/policy-language/#what-is-rego), a declarative query language for defining policy.
+3. **Report**. Package the results as HTML and JSON.
+
+## Table of Contents
+
+### Installation
+
+- [Download and Python Install](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/DownloadAndInstall.md)
+- [Download the OPA Executable](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/OPA.md)
+- [Configure Defaults](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/Defaults.md)
+
+### Prerequisites
+
+- [Permissions](https://github.com/cisagov/ScubaGoggles/blob/main/docs/prerequisites/Prerequisites.md#permissions)
+- [Create a Project](https://github.com/cisagov/ScubaGoggles/blob/main/docs/prerequisites/Prerequisites.md#create-a-project)
+
+### Authentication
+- [Authentication Methods](https://github.com/cisagov/ScubaGoggles/blob/main/docs/authentication/AuthenticationMethods.md)
+- [Using OAuth](https://github.com/cisagov/ScubaGoggles/blob/main/docs/authentication/OAuth.md)
+- [Using a Service Account](https://github.com/cisagov/ScubaGoggles/blob/main/docs/authentication/ServiceAccount.md)
+
+### Usage
+
+- [Usage: Parameters](https://github.com/cisagov/ScubaGoggles/blob/main/docs/usage/Parameters.md)
+- [Usage: Config File](https://github.com/cisagov/ScubaGoggles/blob/main/docs/usage/Config.md)
+- [Usage: Examples](https://github.com/cisagov/ScubaGoggles/blob/main/docs/usage/Examples.md)
+- [Reviewing Output](https://github.com/cisagov/ScubaGoggles/blob/main/docs/usage/ReviewOutput.md)
+- [Limitations](https://github.com/cisagov/ScubaGoggles/blob/main/docs/usage/Limitations.md)
+
+### Troubleshooting
+- [Not Authorized to Access This Resource](https://github.com/cisagov/ScubaGoggles/blob/main/docs/troubleshooting/Troubleshooting.md#not-authorized-to-access-this-resource)
+- [WinError 10013 Permission Error](https://github.com/cisagov/ScubaGoggles/blob/main/docs/troubleshooting/Troubleshooting.md#windows--winerror-10013-permission-error)
+- [Unable to view HTML report due to environment limitations](https://github.com/cisagov/ScubaGoggles/blob/main/docs/troubleshooting/Troubleshooting.md#unable-to-view-html-report-due-to-environment-limitations)
+
+## Project License
+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.

scubagoggles-0.5.0/README.md

@@ -0,0 +1,69 @@
+![ScubaGoggles Logo](https://github.com/cisagov/ScubaGoggles/raw/main/docs/images/ScubaGoggles%20GitHub%20Graphic%20v2.jpg)
+<div align='center' style="margin:0;" id="user-content-toc">
+  <ul>
+    <h1 style="display: inline-block;">ScubaGoggles</h1>
+  </ul>
+  <ul>
+        <a href="https://github.com/cisagov/ScubaGoggles/releases">
+        <img src="https://img.shields.io/badge/ScubaGoggles-v0.5.0-%2385B065?labelColor=%23005288"  alt="ScubaGoggles version #"></a>
+        <a href="https://github.com/cisagov/ScubaGoggles/tree/main/baselines">
+        <img src="https://img.shields.io/badge/GWS_SCB-v0.5-%2385B065?labelColor=%23005288" alt="GWS SCB version #"></a>
+        <a href="">
+        <img src="https://img.shields.io/github/downloads/cisagov/ScubaGoggles/total.svg"  alt="Downloads"></a>
+  </ul>
+</div>
+<h2 align='center' style="margin:0;">GWS Secure Configuration Baseline Assessment Tool </h2>
+
+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](https://cisa.gov/scuba)) Secure Configuration
+Baseline [documents](https://github.com/cisagov/ScubaGoggles/blob/main/scubagoggles/baselines/README.md).
+
+For the Microsoft 365 (M365) rendition of this tool, see [ScubaGear](https://github.com/cisagov/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.
+
+## Overview
+We use a three-step process:
+1. **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.
+2. **Verify**. Compare the exported settings from the previous step with the configuration prescribed in the baselines. We do this using [OPA Rego](https://www.openpolicyagent.org/docs/latest/policy-language/#what-is-rego), a declarative query language for defining policy.
+3. **Report**. Package the results as HTML and JSON.
+
+## Table of Contents
+
+### Installation
+
+- [Download and Python Install](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/DownloadAndInstall.md)
+- [Download the OPA Executable](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/OPA.md)
+- [Configure Defaults](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/Defaults.md)
+
+### Prerequisites
+
+- [Permissions](https://github.com/cisagov/ScubaGoggles/blob/main/docs/prerequisites/Prerequisites.md#permissions)
+- [Create a Project](https://github.com/cisagov/ScubaGoggles/blob/main/docs/prerequisites/Prerequisites.md#create-a-project)
+
+### Authentication
+- [Authentication Methods](https://github.com/cisagov/ScubaGoggles/blob/main/docs/authentication/AuthenticationMethods.md)
+- [Using OAuth](https://github.com/cisagov/ScubaGoggles/blob/main/docs/authentication/OAuth.md)
+- [Using a Service Account](https://github.com/cisagov/ScubaGoggles/blob/main/docs/authentication/ServiceAccount.md)
+
+### Usage
+
+- [Usage: Parameters](https://github.com/cisagov/ScubaGoggles/blob/main/docs/usage/Parameters.md)
+- [Usage: Config File](https://github.com/cisagov/ScubaGoggles/blob/main/docs/usage/Config.md)
+- [Usage: Examples](https://github.com/cisagov/ScubaGoggles/blob/main/docs/usage/Examples.md)
+- [Reviewing Output](https://github.com/cisagov/ScubaGoggles/blob/main/docs/usage/ReviewOutput.md)
+- [Limitations](https://github.com/cisagov/ScubaGoggles/blob/main/docs/usage/Limitations.md)
+
+### Troubleshooting
+- [Not Authorized to Access This Resource](https://github.com/cisagov/ScubaGoggles/blob/main/docs/troubleshooting/Troubleshooting.md#not-authorized-to-access-this-resource)
+- [WinError 10013 Permission Error](https://github.com/cisagov/ScubaGoggles/blob/main/docs/troubleshooting/Troubleshooting.md#windows--winerror-10013-permission-error)
+- [Unable to view HTML report due to environment limitations](https://github.com/cisagov/ScubaGoggles/blob/main/docs/troubleshooting/Troubleshooting.md#unable-to-view-html-report-due-to-environment-limitations)
+
+## Project License
+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.

scubagoggles-0.5.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scubagoggles"
+dynamic = ["version"]
+classifiers = ["Development Status :: 4 - Beta",
+               "Intended Audience :: Information Technology",
+               "Topic :: Security",
+               "Programming Language :: Python :: 3.9",
+               "Programming Language :: Python :: 3.10",
+               "Programming Language :: Python :: 3.11",
+               "Programming Language :: Python :: 3.12",
+               "Programming Language :: Python :: 3.13"]
+dependencies = ["dnspython>=2.6.1",
+                "google-api-python-client>=2.142.0",
+                "google-auth-httplib2>=0.2.0",
+                "google-auth-oauthlib>=1.2.1",
+                "MarkupSafe>=2.1.5",
+                "pyyaml>=6.0.2",
+                "requests>=2.32.3",
+                "tqdm>=4.66.5"]
+requires-python = ">= 3.9"
+description='SCuBA security baseline assessment tool'
+authors = [{name = "CISA"}]
+license = "CC0-1.0"
+license-files = ["LICENSE"]
+readme = "README.md"
+
+[project.scripts]
+scubagoggles = "scubagoggles.main:dive"
+
+[tool.setuptools.dynamic]
+version = {attr = "scubagoggles.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["."]

scubagoggles-0.5.0/scubagoggles/Testing/Functional/SmokeTests/README.md

@@ -0,0 +1,142 @@
+# ScubaGoggles Functional Smoke Testing Automation
+The ScubaGoggles repository consists of an automation suite to help test the functionality of the ScubaGoggles tool itself. The test automation is geared towards contributors who want to execute the functional smoke testing orchestrator as part of their development/testing activity.
+
+This README outlines the ScubaGoggles software test automation structure and its usage. The document also contains instructions for adding new tests to the existing automation suite if necessary.
+
+## Table of Contents
+- [Smoke Testing Prerequisites](#smoke-testing-prerequisites)
+  - [Pytest and Selenium](#pytest-and-selenium)
+  - [Google Service Account](#google-service-account)
+- [Functional Smoke Testing Structure](#functional-smoke-testing-structure)
+  - [Smoke Testing Classes and Methods](#smoke-testing-classes-and-methods)
+  - [Automated workflow via GitHub Actions](#automated-workflow-via-github-actions)
+- [Functional Smoke Testing Usage](#functional-smoke-testing-usage)
+  - [Running in a Local Development Environment](#running-in-a-local-development-environment)
+  - [Running Remotely via GitHub Actions](#running-remotely-via-github-actions)
+- [Adding New Tests](#adding-new-tests)
+
+## Smoke Testing Prerequisites ##
+Running the ScubaGoggles functional smoke tests requires a Windows, MacOS, or Linux computer or VM. The development environment should have Python v3.10.x installed at a minimum ([refer to our installing Python dependencies documentation if its not already installed](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/DownloadAndInstall.md#installing-python-dependencies)), Pytest, and Selenium installed locally.
+
+### Pytest and Selenium ###
+Pytest is a Python testing framework which is commonly used for unit, integration, and functional testing. ([Pytest Get Started](https://docs.pytest.org/en/stable/getting-started.html))
+
+Selenium supports automation of all the major browsers in the market through the use of WebDriver. ([Selenium Get Started](https://www.selenium.dev/documentation/webdriver/getting_started/))
+
+To install Pytest and Selenium on your development environment, open a new terminal session and run the following command:
+
+```
+pip install pytest selenium
+```
+
+> [!NOTE]
+> The functional smoke tests use Chrome as its WebDriver when running Selenium tests. [Setup ChromeDriver](https://developer.chrome.com/docs/chromedriver/get-started) if you don't already have the Google Chrome web browser installed.
+
+### Google Service Account ###
+The ScubaGoggles functional smoke tests must be executed with a service account. [Refer to our service account documentation on how to get setup.](https://github.com/cisagov/ScubaGoggles/blob/main/docs/authentication/ServiceAccount.md#using-a-service-account)
+
+A `credentials.json` file is required at the root directory of the ScubaGoggles project if running the functional smoke tests in a local development environment.
+
+Take note of the `subjectemail`, the email used to authenticate with GWS that has necessary administrator permissions, and the GWS `customerdomain` that ScubaGoggles is run against. Both credentials are required in a later step.
+
+## Functional Smoke Testing Structure ##
+ScubaGoggles functional smoke testing has two main components: the smoke testing orchestrator and the automated workflow run via GitHub Actions.
+
+### Smoke Testing Classes and Methods ###
+The smoke testing orchestrator ([/Testing/Functional/SmokeTests/smoke_test.py](https://github.com/cisagov/ScubaGoggles/blob/main/Testing/Functional/SmokeTests/smoke_test.py)) executes each test declared inside the `SmokeTest` class. The tests currently cover:
+- if the `scubagoggles gws` command generates valid output for all baselines
+- if ScubaResults.json contains API errors or exceptions
+- if the generated baseline reports, i.e. BaselineReports.html, CalendarReport.html, ChatReport.html, etc., contain valid content and all links redirect accordingly
+
+The smoke testing utils ([/Testing/Functional/SmokeTests/smoke_test_utils.py](https://github.com/cisagov/ScubaGoggles/blob/main/Testing/Functional/SmokeTests/smoke_test_utils.py)) stores helper methods which perform various operations.
+
+The Selenium Browser class ([/Testing/Functional/SmokeTests/selenium_browser.py](https://github.com/cisagov/ScubaGoggles/blob/main/Testing/Functional/SmokeTests/selenium_browser.py)) encapsulates the setup, usage, and teardown of Selenium WebDriver instances.
+
+The Pytest configuration methods ([/Testing/Functional/SmokeTests/conftest.py](https://github.com/cisagov/ScubaGoggles/blob/main/Testing/Functional/conftest.py)) declare various Pytest fixtures, allowing for the use of CLI arguments when invoking the Pytest command.
+
+### Automated Workflow via GitHub Actions ###
+The automated workflow for running the functional smoke tests ([/.github/workflows/run_smoke_test.yml](https://github.com/cisagov/ScubaGoggles/blob/main/.github/workflows/run_smoke_test.yml)) is triggered on `push` events to the main branch, `pull_request` events when a pull request is opened/reopened/reviewed, and manually with custom user input via workflow_dispatch.
+
+## Functional Smoke Testing Usage ##
+After completing all of the prerequisite steps, the functional smoke tests can be run in a local development environment or remotely via GitHub Actions.
+
+### Running in a Local Development Environment ###
+> [!IMPORTANT]
+> Ensure that you have correctly setup a Google service account and that the `credentials.json` stored at the root directory of the ScubaGoggles project is up to date. If you haven't already, please refer back to the [prerequisite step on Google Service Accounts](#google-service-account) for how to setup before proceeding.
+
+The following arguments are required when running the functional smoke tests:
+- `--subjectemail="user@domain.com"` (the email used to authenticate with GWS, must have necessary administrator permissions)
+- `--customerdomain="domain.com"` (the domain that ScubaGoggles is run against)
+
+Replace `user@domain.com` with your email and `domain.com` with your domain, then run the following command to execute the functional smoke tests:
+```
+pytest ./Testing/Functional/SmokeTests/ -vvv --subjectemail="user@domain.com" --customerdomain="domain.com"
+```
+
+Common Pytest parameters and their use cases:
+- `-v` or `--verbose` (shows individual test names and results)
+- `-vv` (increases verbosity further, shows detailed output about each test)
+- `-vvv` (shows even more detailed output and debug-level information)
+- `-s` (disables output capturing allowing print() statements and logs to be shown in the console)
+- `-k` (run tests that match a keyword)
+
+    Example (only runs test_scubagoggles_output, deselects the rest):
+    ```
+    pytest ./Testing/Functional/SmokeTests/ -vvv -k test_scubagoggles_output --subjectemail="user@domain.com" --customerdomain="domain.com"
+    ```
+
+- `--tb=short`, `tb=long`, or `tb=no` (provide either brief, full, or suppress the traceback output for failed tests)
+- `-q` (reduces output to show only minimal information)
+
+Run `pytest -h` for a full list of CLI options or [learn more about Pytest usage here.](https://docs.pytest.org/en/7.1.x/how-to/usage.html)
+
+### Running Remotely via GitHub Actions ###
+Go to the [run_smoke_test.yml workflow](https://github.com/cisagov/ScubaGoggles/actions/workflows/run_smoke_test.yml) in the GitHub Actions tab, then click the "Run workflow" dropdown button.
+
+The default values are the following:
+- ref branch: `main` but can be set to any branch
+- operating system: `['windows-latest', 'macos-latest']` ([list of supported GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories))
+- python version: `['3.10']`
+- opa version: "0.60.0"
+
+![Screenshot (226)](https://github.com/user-attachments/assets/6f25b7a9-3981-4866-a413-93df4bae1130)
+
+Feel free to play around with the inputs then click the "Run workflow" button when ready. The workflow will create a matrix strategy for each combination. For example, passing `['windows-latest', 'macos-latest']`, `['3.10', '3.11', 3.12']`, and OPA version `0.60.0` will create the following:
+
+![Screenshot (218)](https://github.com/user-attachments/assets/212b4e4b-d552-4dc9-a3f6-7f0e29accc4b)
+
+Some factors to consider:
+- Each input is required so an empty string will fail validation. `[]`, `['']`, `['', ]` may also cause the workflow to error out, although this is expected behavior.
+- `ubuntu-latest` has not been tested as a value for operating system. Support can be added for this, although its dependent on if this is something we want to test for ScubaGoggles as a whole.
+- Python versions <3.10.x are not supported and will cause the smoke test workflow to fail.
+- [Due to the lack of an array input type from GitHub](https://github.com/orgs/community/discussions/11692), the required format is an array of strings for the operating system and python version inputs. This is something to capture as a future todo once arrays are available.
+
+## Adding New Tests ##
+A new smoke test should be added as a method in the [SmokeTest class](https://github.com/cisagov/ScubaGoggles/blob/main/Testing/Functional/SmokeTests/smoke_test.py). Helper methods should be added in [smoke_test_utils.py](https://github.com/cisagov/ScubaGoggles/blob/main/Testing/Functional/SmokeTests/smoke_test_utils.py).
+
+Below is an example that tests the `scubagoggles gws` command:
+
+```
+class SmokeTest:
+  ...
+
+  def test_scubagoggles_execution(self, subjectemail):
+    """
+    Test if the `scubagoggles gws` command succeeds or fails.
+
+    Args:
+      subjectemail: The email address of an admin user who created the service account
+    """
+    try:
+      command: str = f"scubagoggles gws --subjectemail {subjectemail} --quiet"
+      result = subprocess.run(command, shell=True, check=True, capture_output=True)
+
+      if result.returncode != 0:
+        print(f"Scubagoggles execution failed with error:\n{result.stderr}")
+        assert False
+      else:
+        print("Scubagoggles execution succeeded")
+        print(f"Output:\n{result.stdout}")
+    except Exception as e:
+      pytest.fail(f"An error occurred, {e}")
+```

scubagoggles-0.5.0/scubagoggles/Testing/Functional/SmokeTests/requirements.txt

@@ -0,0 +1,3 @@
+# These packages are only required for the functional smoke testing
+pytest
+selenium

scubagoggles-0.5.0/scubagoggles/Testing/Functional/SmokeTests/selenium_browser.py

@@ -0,0 +1,81 @@
+"""
+selenium_browser.py declares a Browser class for use in ScubaGoggles testing.
+"""
+
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options
+
+
+class Browser:
+    """
+    The Browser class encapsulates the setup, usage, and teardown of a
+    Selenium WebDriver instance for automated browser interactions.
+    """
+    def __init__(self):
+        chrome_options = Options()
+        chrome_options.add_argument('--headless=new')
+        chrome_options.add_argument('--log-level=3')
+        chrome_options.add_argument('--window-size=1200,800')
+        chrome_options.add_argument('--no-sandbox')
+        chrome_options.add_argument('--disable-dev-shm-usage')
+
+        self.driver = webdriver.Chrome(options=chrome_options)
+
+    def get(self, url):
+        """
+        Load a new web page in the current browser window.
+
+        Args:
+            url: The URL to load. Must be a fully qualified URL
+        """
+        self.driver.get(url)
+
+    def quit(self):
+        """
+        Quits the driver, closing every associated window.
+        """
+        self.driver.quit()
+
+    def find_element(self, by, value):
+        """
+        Find the first WebElement using the given method. This method is
+        affected by the 'implicit wait' times in force at the time and
+        execution. The find_element(...) invocation will return a matching
+        row, or try again repeatedly until the configured timeout is reached.
+
+        Args:
+            by: The locating mechanism to use, i.e. By.CLASS_NAME, By.TAG_NAME
+            value: The locator, i.e. "h1", "header"
+
+        Returns:
+            WebElement: The first matching element on the current page
+        """
+        return self.driver.find_element(by, value)
+
+    def find_elements(self, by, value):
+        """
+        Find all WebElements within the current page. This method is affected
+        by the 'implicit wait' times in force at the time and execution. The
+        find_elements(...) invocation will return as soon as there are more
+        than 0 items in the found collection, or will return an empty list of
+        the timeout is reached.
+
+        Args:
+            by: The locating mechanism to use, i.e. By.CLASS_NAME, By.TAG_NAME
+            value: The locator, i.e. "h1", "header"
+
+        Returns:
+            WebElement: A list of all matching WebElements, or an empty list
+            if nothing matches
+        """
+        return self.driver.find_elements(by, value)
+
+    def current_url(self):
+        """
+        Get a string representing the current URL that the browser is looking
+        at.
+
+        Returns:
+            The URL of the page currently loaded in the browser
+        """
+        return self.driver.current_url

scubagoggles-0.5.0/scubagoggles/Testing/Functional/SmokeTests/smoke_test.py

@@ -0,0 +1,82 @@
+"""
+smoke_test.py declares a SmokeTest class for ScubaGoggles automation testing.
+"""
+
+import subprocess
+
+import pytest
+
+from smoke_test_utils import (get_output_path,
+                              get_required_entries,
+                              run_selenium,
+                              sample_report_dir,
+                              top_report_url,
+                              verify_all_outputs_exist,
+                              verify_output_type,
+                              verify_scubaresults)
+
+
+class SmokeTest:
+    """
+    Pytest class to encapsulate the following test cases:
+
+    - Generate the correct output files (BaselineReports.html,
+      ScubaResults.json, etc)
+    - Check the content of html files, verify href attributes are
+      correct, etc
+    - Check if ScubaResults.json contains errors in the summary. If errors
+      exist, then either API calls or functions produced exceptions which
+      need to be handled
+    """
+
+    @staticmethod
+    def test_scubagoggles_output(subjectemail: str):
+        """
+        Test if the `scubagoggles gws` command generates correct output for
+        all baselines.
+
+        Args:
+            subjectemail: The email address of a user for the service account.
+            If None (or the empty string), the user's OAuth credentials are
+            used instead.
+        """
+
+        svc_account_option = (f' --subjectemail {subjectemail}' if subjectemail
+                              else '')
+        command = f'scubagoggles gws{svc_account_option} --quiet '
+
+        try:
+            subprocess.run(command, shell=True, check=True)
+            output_path = get_output_path()
+            output: list = verify_output_type(output_path, [])
+            report_dir = sample_report_dir()
+            required_entries = get_required_entries(report_dir, [])
+            verify_all_outputs_exist(output, required_entries)
+        except (OSError, ValueError, Exception) as e:
+            pytest.fail(f'An error occurred, {e}')
+
+    @staticmethod
+    def test_scubaresults():
+        """
+        Determine if ScubaResults.json contains API errors or exceptions.
+        """
+        try:
+            output_path = get_output_path()
+            verify_scubaresults(output_path)
+        except (ValueError, Exception) as e:
+            pytest.fail(f'An error occurred, {e}')
+
+    @staticmethod
+    def test_scubagoggles_report(browser, customerdomain):
+        """
+        Test if the generated baseline reports are correct,
+        i.e. BaselineReports.html, CalendarReport.html, ChatReport.html
+        """
+        try:
+            output_path = get_output_path()
+            report_path: str = top_report_url(output_path)
+            browser.get(report_path)
+            run_selenium(browser, customerdomain)
+        except (ValueError, AssertionError, Exception) as e:
+            browser.quit()
+            pytest.fail(f'An error occurred, {e}')