Skip to content

Commit

Permalink
documentation: minor changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@rlxdev
rlxdev committed Nov 25, 2024
1 parent bdb1749 commit b9ae1d1
Show file tree
Hide file tree
Showing 4 changed files with 84 additions and 84 deletions.
4 changes: 2 additions & 2 deletions docs/installation/DownloadAndInstall.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ is still created.

### Windows Example

```lang-none
```
> scubagoggles setup
Setup: output directory
Scubagoggles output directory [C:\Users\userID\scubagoggles]?
Expand All @@ -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]?
Expand Down
86 changes: 40 additions & 46 deletions docs/troubleshooting/Troubleshooting.md
View file
Original file line number Diff line number Diff line change
@@ -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:
<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](../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:
<HttpError 403 ... returned "Not Authorized to access this resource/api">
```

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
Expand Down
9 changes: 6 additions & 3 deletions docs/usage/Examples.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
69 changes: 36 additions & 33 deletions docs/usage/Parameters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,67 +4,70 @@ Execute the ScubaGoggles tool using the `scubagoggles` command. For GWS,
all commands will be under the `gws` "subcommand".

```
usage: scubagoggles gws [-h] [--baselines <baseline> [<baseline> ...]] [--outputpath <directory>]
[--outjsonfilename <output-JSON-file>] [--credentials <credentials-JSON-file>]
[--subjectemail <email-address>] [--customerid <customer-id>]
[--opapath <opa-directory>] [--regopath <directory>] [--documentpath <directory>]
[--outputfoldername <name>] [--outputproviderfilename <name>]
[--outputregofilename <name>] [--outputreportfilename] [--quiet] [--debug]
[--runcached] [--skipexport]
usage: scubagoggles gws [-h]
[--baselines <baseline> [<baseline> ...]]
[--outputpath <directory>]
[--outjsonfilename <output-JSON-file>]
[--credentials <credentials-JSON-file>]
[--config <YAML-config-file>]
[--subjectemail <email-address>]
[--customerid <customer-id>]
[--opapath <opa-directory>]
[--regopath <directory>]
[--documentpath <directory>]
[--outputfoldername <name>]
[--outputproviderfilename <name>]
[--outputregofilename <name>]
[--outputreportfilename]
[--quiet]
[--debug]
[--runcached]
[--skipexport]
SCuBA automated conformance check for Google Workspace (GWS) products
options:
-h, --help show this help message and exit
--baselines <baseline> [<baseline> ...], -b <baseline> [<baseline> ...]
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 <directory>, -o <directory>
The folder path where both the output JSON & HTML report will be created.
--outjsonfilename <output-JSON-file>
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 <credentials-JSON-file>, -c <credentials-JSON-file>
The location and name of the OAuth / service account credentials json file.
--config <YAML-config-file>
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 <email-address>
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 <customer-id>
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 <opa-directory>
The directory containing the OPA executable.
--regopath <directory>
The relative path to the directory contain the folder containing the rego files.
--documentpath <directory>
The relative path to the directory containing the SCuBA baseline documents.
--outputfoldername <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.
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 <name>
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 <name>
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
Expand Down

0 comments on commit b9ae1d1

Please sign in to comment.