From 4634071329b02d0e6579bce8e15da494e1f7c130 Mon Sep 17 00:00:00 2001 From: Alden Hilton <106177711+adhilto@users.noreply.github.com> Date: Thu, 19 Sep 2024 10:16:54 -0700 Subject: [PATCH 1/5] Update Troubleshooting.md with upgrading instructions --- docs/troubleshooting/Troubleshooting.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/troubleshooting/Troubleshooting.md b/docs/troubleshooting/Troubleshooting.md index 37ef3752..cd31780b 100644 --- a/docs/troubleshooting/Troubleshooting.md +++ b/docs/troubleshooting/Troubleshooting.md @@ -1,5 +1,18 @@ # Troubleshooting +## Upgrading ScubaGoggles +Assuming you installed ScubaGoggles as described in [Download and Install](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/DownloadAndInstall.md), upgrading to the lastest version of ScubaGoggles should be as simple as: +- Repeating the steps described in [Download and Install](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/DownloadAndInstall.md) with the new release. +- Making the OPA executable available, by either: + - downloading the executable again as described in [Download the OPA executable](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/OPA.md), + - copying the executable from the old release folder to the new release folder, or + - using the `--opapath` parameter to tell ScubaGoggles where to look for the executable. +- Making your credentials available, by either: + - copying your `credentials.json` file to the new release folder or + - using the `--credentials` parameter to tell ScubaGoggles where to look for your credentials. + +If instead you cloned the ScubaGoggles repo and wish to run ScubaGoggles on the latest code from main (only recommended for development purposes), be sure to run `python -m pip install .` inside the ScubaGoggles directory after pulling the latest code. + ## 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](/docs/usage/Limitations.md) for more details. From b478b2a3ae11fc1296787c67cf670f1836ebba80 Mon Sep 17 00:00:00 2001 From: Alden Hilton <106177711+adhilto@users.noreply.github.com> Date: Thu, 19 Sep 2024 10:23:05 -0700 Subject: [PATCH 2/5] Update DownloadAndInstall.md with link to troubleshooting --- docs/installation/DownloadAndInstall.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/installation/DownloadAndInstall.md b/docs/installation/DownloadAndInstall.md index fab7f53b..4abd1bed 100644 --- a/docs/installation/DownloadAndInstall.md +++ b/docs/installation/DownloadAndInstall.md @@ -1,4 +1,6 @@ # Download and Python Install +> [!NOTE] +> Previously installed a different version of ScubaGoggles? See [Troubleshooting: Upgrading ScubaGoggles](/docs/troubleshooting/Troubleshooting.md#upgrading-scubagoggles). ## Downloading the Latest Release To download ScubaGoggles: From 13fa122d8b57ec5f6d2d20858a39803b52269d3f Mon Sep 17 00:00:00 2001 From: Alden Hilton <106177711+adhilto@users.noreply.github.com> Date: Thu, 19 Sep 2024 10:23:49 -0700 Subject: [PATCH 3/5] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 8a50bc8c..61a1646b 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,7 @@ The majority of the conformance checks done by ScubaGoggles rely on [GWS Admin l - [Limitations](/docs/usage/Limitations.md) ### Troubleshooting +- [Upgrading ScubaGoggles](/docs/troubleshooting/Troubleshooting.md#upgrading-scubagoggles) - [Lots of Manual Checks](/docs/troubleshooting/Troubleshooting.md#lots-of-manual-checks) - [Not Authorized to Access This Resource](/docs/troubleshooting/Troubleshooting.md#not-authorized-to-access-this-resource) - [scubagoggles Not Found](/docs/troubleshooting/Troubleshooting.md#scubagoggles-not-found) From 92eff21d1314f829bb61f593e4bca246cd47b3d6 Mon Sep 17 00:00:00 2001 From: Alden Hilton <106177711+adhilto@users.noreply.github.com> Date: Tue, 1 Oct 2024 16:21:31 -0700 Subject: [PATCH 4/5] Update README.md with new upgrading section --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 61a1646b..131b0bea 100644 --- a/README.md +++ b/README.md @@ -56,8 +56,10 @@ The majority of the conformance checks done by ScubaGoggles rely on [GWS Admin l - [Reviewing Output](/docs/usage/ReviewOutput.md) - [Limitations](/docs/usage/Limitations.md) +### Upgrading and Maintenance +- [Upgrading ScubaGoggles](/docs/troubleshooting/Upgrading.md#upgrading-scubagoggles) +- [Upgrading OPA](/docs/troubleshooting/Upgrading.md#upgrading-opa) ### Troubleshooting -- [Upgrading ScubaGoggles](/docs/troubleshooting/Troubleshooting.md#upgrading-scubagoggles) - [Lots of Manual Checks](/docs/troubleshooting/Troubleshooting.md#lots-of-manual-checks) - [Not Authorized to Access This Resource](/docs/troubleshooting/Troubleshooting.md#not-authorized-to-access-this-resource) - [scubagoggles Not Found](/docs/troubleshooting/Troubleshooting.md#scubagoggles-not-found) From a3c8981d4a5cb7b66c91f7184b7625587247a13b Mon Sep 17 00:00:00 2001 From: Alden Hilton Date: Tue, 1 Oct 2024 16:59:11 -0700 Subject: [PATCH 5/5] Rework documentation for new upgrading section --- README.md | 7 ++++--- docs/installation/DownloadAndInstall.md | 2 +- docs/troubleshooting/Troubleshooting.md | 13 ------------- docs/upgrading/Upgrading.md | 22 ++++++++++++++++++++++ 4 files changed, 27 insertions(+), 17 deletions(-) create mode 100644 docs/upgrading/Upgrading.md diff --git a/README.md b/README.md index 131b0bea..1cb2cc2d 100644 --- a/README.md +++ b/README.md @@ -56,9 +56,10 @@ The majority of the conformance checks done by ScubaGoggles rely on [GWS Admin l - [Reviewing Output](/docs/usage/ReviewOutput.md) - [Limitations](/docs/usage/Limitations.md) -### Upgrading and Maintenance -- [Upgrading ScubaGoggles](/docs/troubleshooting/Upgrading.md#upgrading-scubagoggles) -- [Upgrading OPA](/docs/troubleshooting/Upgrading.md#upgrading-opa) +### Upgrading and Maintenance +- [Upgrading ScubaGoggles](/docs/upgrading/Upgrading.md#upgrading-scubagoggles) +- [Upgrading OPA](/docs/upgrading/Upgrading.md#upgrading-opa) + ### Troubleshooting - [Lots of Manual Checks](/docs/troubleshooting/Troubleshooting.md#lots-of-manual-checks) - [Not Authorized to Access This Resource](/docs/troubleshooting/Troubleshooting.md#not-authorized-to-access-this-resource) diff --git a/docs/installation/DownloadAndInstall.md b/docs/installation/DownloadAndInstall.md index 4abd1bed..9f6fc054 100644 --- a/docs/installation/DownloadAndInstall.md +++ b/docs/installation/DownloadAndInstall.md @@ -1,6 +1,6 @@ # Download and Python Install > [!NOTE] -> Previously installed a different version of ScubaGoggles? See [Troubleshooting: Upgrading ScubaGoggles](/docs/troubleshooting/Troubleshooting.md#upgrading-scubagoggles). +> Previously installed a different version of ScubaGoggles? See [Upgrading ScubaGoggles](/docs/upgrading/Upgrading.md#upgrading-scubagoggles). ## Downloading the Latest Release To download ScubaGoggles: diff --git a/docs/troubleshooting/Troubleshooting.md b/docs/troubleshooting/Troubleshooting.md index cd31780b..37ef3752 100644 --- a/docs/troubleshooting/Troubleshooting.md +++ b/docs/troubleshooting/Troubleshooting.md @@ -1,18 +1,5 @@ # Troubleshooting -## Upgrading ScubaGoggles -Assuming you installed ScubaGoggles as described in [Download and Install](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/DownloadAndInstall.md), upgrading to the lastest version of ScubaGoggles should be as simple as: -- Repeating the steps described in [Download and Install](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/DownloadAndInstall.md) with the new release. -- Making the OPA executable available, by either: - - downloading the executable again as described in [Download the OPA executable](https://github.com/cisagov/ScubaGoggles/blob/main/docs/installation/OPA.md), - - copying the executable from the old release folder to the new release folder, or - - using the `--opapath` parameter to tell ScubaGoggles where to look for the executable. -- Making your credentials available, by either: - - copying your `credentials.json` file to the new release folder or - - using the `--credentials` parameter to tell ScubaGoggles where to look for your credentials. - -If instead you cloned the ScubaGoggles repo and wish to run ScubaGoggles on the latest code from main (only recommended for development purposes), be sure to run `python -m pip install .` inside the ScubaGoggles directory after pulling the latest code. - ## 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](/docs/usage/Limitations.md) for more details. diff --git a/docs/upgrading/Upgrading.md b/docs/upgrading/Upgrading.md new file mode 100644 index 00000000..008ecb69 --- /dev/null +++ b/docs/upgrading/Upgrading.md @@ -0,0 +1,22 @@ +# Upgrading and Maintenance + +## Upgrading ScubaGoggles +Assuming you installed ScubaGoggles as described in [Download and Install](/docs/installation/DownloadAndInstall.md), upgrading to the lastest version of ScubaGoggles should be as simple as: +- Repeating the steps described in [Download and Install](/docs/installation/DownloadAndInstall.md) with the new release. +- Making the OPA executable available, by either: + - downloading the executable again as described in [Download the OPA executable](/docs/installation/OPA.md), + - copying the executable from the old release folder to the new release folder, or + - using the `--opapath` parameter to tell ScubaGoggles where to look for the executable. +- Making your credentials available, by either: + - copying your `credentials.json` file to the new release folder or + - using the `--credentials` parameter to tell ScubaGoggles where to look for your credentials. + +If instead you cloned the ScubaGoggles repo and wish to run ScubaGoggles on the latest code from main (only recommended for development purposes), be sure to run `python -m pip install .` inside the ScubaGoggles directory after pulling the latest code. + +## Upgrading OPA +While new versions of OPA are periodically released, it is only necessary to upgrade OPA if the version you have locally is unsupported. Running `python download_opa.py --help` lists the supported OPA versions. + +Upgrading OPA is as simple as downloading the desired executable, which can be done by running the `download_opa.py` script again. See [Download the OPA executable](/docs/installation/OPA.md) for detailed instructions. + +## Navigation +- Return to [Documentation Home](/README.md) \ No newline at end of file