From b9ae1d10eb7fd71cab713b11b62893d6bac0e662 Mon Sep 17 00:00:00 2001 From: Roy Lane Date: Sun, 24 Nov 2024 20:23:47 -0500 Subject: [PATCH] documentation: minor changes --- docs/installation/DownloadAndInstall.md | 4 +- docs/troubleshooting/Troubleshooting.md | 86 ++++++++++++------------- docs/usage/Examples.md | 9 ++- docs/usage/Parameters.md | 69 ++++++++++---------- 4 files changed, 84 insertions(+), 84 deletions(-) diff --git a/docs/installation/DownloadAndInstall.md b/docs/installation/DownloadAndInstall.md index 4ad31c89..9fd629f5 100644 --- a/docs/installation/DownloadAndInstall.md +++ b/docs/installation/DownloadAndInstall.md @@ -159,7 +159,7 @@ is still created. ### Windows Example -```lang-none +``` > scubagoggles setup Setup: output directory Scubagoggles output directory [C:\Users\userID\scubagoggles]? @@ -176,7 +176,7 @@ Google credentials (JSON) file [C:\Users\userID\scubagoggles\credentials.json]? ### Linux Example -```lang-none +``` $ scubagoggles setup Setup: output directory Scubagoggles output directory [/home/userID/scubagoggles]? diff --git a/docs/troubleshooting/Troubleshooting.md b/docs/troubleshooting/Troubleshooting.md index 0bde7c1f..0e5f7199 100644 --- a/docs/troubleshooting/Troubleshooting.md +++ b/docs/troubleshooting/Troubleshooting.md @@ -1,73 +1,67 @@ # Troubleshooting -## Lots of Manual Checks -The report output by ScubaGoggles may indicate that many manual checks are needed (e.g., https://github.com/cisagov/ScubaGoggles/issues/260). This is a symptom of ScubaGoggles' primary limitation. As the API calls to check most of the settings relevant to ScubaGoggles are have not been made public by Google, ScubaGoggles relies on [GWS Admin log events](https://support.google.com/a/answer/4579579?hl=en) to determine the current state. If there are no log events corresponding to a SCuBA baseline policy (e.g., because the setting hasn't been changed within the past 6 months), ScubaGoggles will indicate that the setting needs to be checked manually. See [Limitations](../usage/Limitations.md) for more details. - ## Not Authorized to Access This Resource 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: - -``` -Ensure that you consented to the following API scopes as a user with the proper [permissions to consent](../prerequisites/Prerequisites.md#permissions) and have enabled the required [APIs and Services](../authentication/OAuth.md). -## Scubagoggles Not Found -If an error similar to the one below appears: ``` -command not found: scubagoggles +RuntimeWarning: An exception was thrown trying to get the tenant data: + ``` - -Ensure that you have properly [configured the virtual environment](../installation/DownloadAndInstall.md#installing-in-a-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`. +Ensure that you consented to the following API scopes as a user with the proper +[permissions to consent](../prerequisites/Prerequisites.md#permissions) and have +enabled the required [APIs and Services](../authentication/OAuth.md). ## Unable to view HTML report due to environment limitations -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. +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` parameter: +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` +parameter: ```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. +Once the scan is complete, navigate to the output folder. Within the output +folder, you can access the generated HTML reports, or view the results in JSON +format. To view the results as JSON, open the `ScubaResults.json` file. The output will resemble the following: -``` + +```json { "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 - } + "sites": { + "Manual": 0, + "Passes": 1, + "Errors": 0, + "Failures": 0, + "Warnings": 0, + "Omit": 0 + } }, "Results": { - "Gmail": [ - { - "GroupName": "Mail Delegation", - "GroupNumber": "1", - "Controls": [ - { - "Control ID": "GWS.GMAIL.1.1", - "Requirement": "Mail Delegation SHOULD be disabled.", - "Result": "Pass", - "Criticality": "Should", - "Details": "Requirement met in all OUs and groups." - } - ... + "sites": [ + { + "GroupName": "Sites Service Status", + "GroupNumber": "1", + "GroupReferenceURL": "https://github.com/cisagov...", + "Controls": [ + { + "Control ID": "GWS.SITES.1.1", + "Requirement": "Sites Service SHOULD be disabled for all users.", + "Result": "Pass", + "Criticality": "Should", + "Details": "Requirement met in all OUs and groups." + } + ] + } + ] + },... ``` ## Navigation diff --git a/docs/usage/Examples.md b/docs/usage/Examples.md index e1565254..292c1b9c 100644 --- a/docs/usage/Examples.md +++ b/docs/usage/Examples.md @@ -42,9 +42,12 @@ scubagoggles gws --config sample-config-files/basic_config.yaml > [!NOTE] > In all the above examples, 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] - The following is intended for developers **ONLY**: -> 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` - +> [!NOTE] +> The following is intended for developers **ONLY**: +> 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` ## Navigation - Continue to [Reviewing Output](ReviewOutput.md) diff --git a/docs/usage/Parameters.md b/docs/usage/Parameters.md index df7e41b6..f461ddbc 100644 --- a/docs/usage/Parameters.md +++ b/docs/usage/Parameters.md @@ -4,40 +4,49 @@ Execute the ScubaGoggles tool using the `scubagoggles` command. For GWS, all commands will be under the `gws` "subcommand". ``` -usage: scubagoggles gws [-h] [--baselines [ ...]] [--outputpath ] - [--outjsonfilename ] [--credentials ] - [--subjectemail ] [--customerid ] - [--opapath ] [--regopath ] [--documentpath ] - [--outputfoldername ] [--outputproviderfilename ] - [--outputregofilename ] [--outputreportfilename] [--quiet] [--debug] - [--runcached] [--skipexport] +usage: scubagoggles gws [-h] + [--baselines [ ...]] + [--outputpath ] + [--outjsonfilename ] + [--credentials ] + [--config ] + [--subjectemail ] + [--customerid ] + [--opapath ] + [--regopath ] + [--documentpath ] + [--outputfoldername ] + [--outputproviderfilename ] + [--outputregofilename ] + [--outputreportfilename] + [--quiet] + [--debug] + [--runcached] + [--skipexport] SCuBA automated conformance check for Google Workspace (GWS) products options: -h, --help show this help message and exit --baselines [ ...], -b [ ...] - A list of one or more abbreviated GWS baseline names that the tool will assess. - Defaults to all baselines. Choices: calendar, chat, classroom, commoncontrols, - drive, gmail, groups, meet, rules, sites + A list of one or more abbreviated GWS baseline names that the tool will assess. Defaults to all baselines. Choices: calendar, chat, + classroom, commoncontrols, drive, gmail, groups, meet, rules, sites --outputpath , -o The folder path where both the output JSON & HTML report will be created. --outjsonfilename - The name of the file that encapsulates all assessment output. Defaults to - ScubaResults. + The name of the file that encapsulates all assessment output. Defaults to ScubaResults. --credentials , -c The location and name of the OAuth / service account credentials json file. - --config - Local file path to a YAML formatted configuration file. Configuration file parameters can be used in place of command-line parameters. Additional parameters and variables not available on the command line can also be included in the file that will be provided to the tool for use in specific tests. - + Local file path to a YAML formatted configuration file. Configuration file parameters can be used in place of command-line + parameters. Additional parameters and variables not available on the command line can also be included in the file that will be + provided to the tool for use in specific tests. --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. + 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. + 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 directory containing the OPA executable. --regopath @@ -45,26 +54,20 @@ options: --documentpath The relative path to the directory containing the SCuBA baseline documents. --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. + 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. + 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. - --quiet This switch suppresses automatically launching a web browser to open the html - report output and the loading bar output. + The name of the main html file homepage created in --outputpath. Defaults to BaselineReports. + --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. Cached Mode options: - --runcached This switch when added will run in the tool in "RunCached mode". When combined with - --skipexport allows 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. + --runcached This switch when added will run in the tool in "RunCached mode". When combined with --skipexport allows 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. ``` ## Navigation