From 6c1b8ee62fc2f813b4240a921f6d26534af05860 Mon Sep 17 00:00:00 2001 From: Ben Zarboni Date: Tue, 27 Aug 2024 10:54:56 -0400 Subject: [PATCH 1/7] Updated the docs, based on GoC feedback --- GUARDRAILS.md | 10 ++++++++++ README.md | 13 +++++++------ organizations/README.md | 11 +++++++++-- 3 files changed, 26 insertions(+), 8 deletions(-) diff --git a/GUARDRAILS.md b/GUARDRAILS.md index 63bb22b..0349859 100644 --- a/GUARDRAILS.md +++ b/GUARDRAILS.md @@ -18,6 +18,16 @@ For this document the following definitions will be used: ## Applicable Service Models This guardrail document relates to Software as a Service (SaaS), specifically DevOps and Source Code management tools. +## Guardrail Activities + +The `Activities` listed under each guardrail are intended to provide a high-level overview of the actions organizations should consider to achieve the desired outcome. They are not prescriptive instructions but rather guidelines that can be adapted to fit the specific needs and circumstances of each organization. + +While the activities offer general recommendations, the implementation details, such as the choice of specific tools or services, configuration settings, and thresholds for suspicious activity, will vary depending on factors like the organization's size, risk tolerance, and existing security infrastructure. + +``` +For more in-depth guidance and technical references, organizations are encouraged to consult your organization's best practices, standards, and specialized resources. +``` + ## SCM Guardrails | ID. | SCM Guardrails | diff --git a/README.md b/README.md index 3d8f084..cb78d7f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## Securing Your GitHub Environment at Scale -### Quick Start: [Get Started Now!](./README.md#getting-started) +### [Get Started Now!](./README.md#getting-started) Managing GitHub for multiple groups introduces complex security and consistency challenges. Misaligned permission levels, team structures, incomplete change rollouts across groups, and status reporting are just a few of the obstacles that can manifest with manual processes. The GitHub Foundations Toolkit offers a secure and efficient way to manage your organization's GitHub environment through automation and centralized control. @@ -50,11 +50,12 @@ Initial setup of your state file backend, and creation of all organizations unde Management of organizations, repositories, and teams, Review results of drift detection, and execution of pull request plans for your organizations. #### Included Tools: -- **Drift Detection:** Detects when someone makes a change to configuration, outside of the source-controlled configuration. Gives the ability to reapply the correct state. -- **Deletion Protection:** When a PR change requests resources be deleted, this tool forces the user to confirm the action -- **GitHub Advanced Security (GHAS) checks:** Checks the state of GHAS for the repos that have it enabled. Reports all of the GHAS scans in one report. -- **Assessment tool:** Used to assess the readiness of your repo, before importing it with the toolkit. Can be used to check whether toolkit guardrails are already in place in the repo. -- **Import tool:** Import repos not currently managed by the toolkit. +- [**Interactive HCL tool:**](./organizations/GEN_INTERACTIVE.md) A CLI tool to help you write HCL interactively for `repositories` and `teams`. +- [**Drift Detection:**](./organizations/DRIFT_DETECTION.md) Detects when someone makes a change to configuration, outside of the source-controlled configuration. Gives the ability to reapply the correct state. +- [**Deletion Protection:**](./organizations/DELETION_PROTECTION.md) When a PR change requests resources be deleted, this tool forces the user to confirm the action +- [**GitHub Advanced Security (GHAS) checks:**](./organizations/GH_ADVANCED_SECURITY.md) Runs GHAS scans for the eligible repos that have it enabled. Reports all of the GHAS scans in one report. +- [**Assessment tool:**](./organizations/ASSESSMENT_TOOL.md) Used to assess the readiness of your repo, before importing it with the toolkit. Can be used to check whether toolkit guardrails are already in place in the repo. +- [**Import tool:**](./organizations/IMPORT_TOOL.md) Import repos not currently managed by the toolkit. ## How to Contribute diff --git a/organizations/README.md b/organizations/README.md index 3117fb1..408515c 100644 --- a/organizations/README.md +++ b/organizations/README.md @@ -12,6 +12,7 @@ * [Secret Management](#secret-management) * [Running the Organizations Layer locally](#running-the-organizations-layer-locally) * [Prerequisites](#prerequisites) + * [Pre-installed tools](#pre-installed-tools) ## Introduction @@ -171,6 +172,12 @@ Before running the organizations layer, please ensure you have the following pre * GCP CLI: [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install) * GCP IAM Roles: [https://cloud.google.com/iam/docs/understanding-roles](https://cloud.google.com/iam/docs/understanding-roles) -## Drift Detection +## Pre-installed tools -The GitHub Foundations toolkit comes with a [drift-detection](./DRIFT_DETECTION.md) tool pre-installed. For more information, see the [documentation here](./DRIFT_DETECTION.md) +The GitHub Foundations toolkit comes with: +* A [Drift Detection](./DRIFT_DETECTION.md) tool +* An [Interactive HCL generation](./GEN_INTERACTIVE.md) tool +* A [Deletion Protection](./DELETION_PROTECTION.md) tool +* [GitHub Advanced Security (GHAS) checks](./GH_ADVANCED_SECURITY.md) +* An [Assessment](./ASSESSMENT_TOOL.md) tool +* An [Import](./IMPORT_TOOL.md) tool From b4af581c06a5494a7e1e407cb9c54e3ab8bd9c6a Mon Sep 17 00:00:00 2001 From: Ben Zarboni Date: Tue, 27 Aug 2024 10:57:39 -0400 Subject: [PATCH 2/7] Updated the docs, based on GoC feedback --- organizations/ASSESSMENT_TOOL.md | 17 ++++++++++++++ organizations/DELETION_PROTECTION.md | 32 +++++++++++++++++++++++++++ organizations/GEN_INTERACTIVE.md | 19 ++++++++++++++++ organizations/GH_ADVANCED_SECURITY.md | 29 ++++++++++++++++++++++++ organizations/IMPORT_TOOL.md | 15 +++++++++++++ 5 files changed, 112 insertions(+) create mode 100644 organizations/ASSESSMENT_TOOL.md create mode 100644 organizations/DELETION_PROTECTION.md create mode 100644 organizations/GEN_INTERACTIVE.md create mode 100644 organizations/GH_ADVANCED_SECURITY.md create mode 100644 organizations/IMPORT_TOOL.md diff --git a/organizations/ASSESSMENT_TOOL.md b/organizations/ASSESSMENT_TOOL.md new file mode 100644 index 0000000..e15ef34 --- /dev/null +++ b/organizations/ASSESSMENT_TOOL.md @@ -0,0 +1,17 @@ +# Assessment Tool + +The assessment tool is a tool that allows you to assess the readiness of your pre-existing GitHub `repository`, before importing it with the toolkit. +It is used to check whether toolkit guardrails are already in place in the `repository`, as well as any settings required at the `organization` level. + +## Running the Assessment Tool + +The Assessment Tool is available as part of the `GitHub Foundations CLI` tool, found [here](https://github.com/FociSolutions/github-foundations-cli/releases) + +To run an assessment check on a repository, run the following command: + +```bash + Usage: + gh_foundations check +``` + +Where `` is the organization slug to check. See the [documentation](https://github.com/FociSolutions/github-foundations-cli/blob/main/README.md#check) for more information. diff --git a/organizations/DELETION_PROTECTION.md b/organizations/DELETION_PROTECTION.md new file mode 100644 index 0000000..c968d18 --- /dev/null +++ b/organizations/DELETION_PROTECTION.md @@ -0,0 +1,32 @@ +# Deletion Protection + +The `Deletion Protection` tool is automatically installed on all GitHub Foundations organizations. + +`Deletion Protection` is a feature that helps to prevent accidental deletion of resources. When a resource is removed from the Terraform configuration, a mechanism kicks-in to ask for confirmation before the resource is deleted. + +## Deletion Protection GitHub Action + +The `Deletion Protection` tool is a GitHub Action that helps prevent accidental deletion of resources in your GitHub organization. It is invoked when a Pull Request (PR) into the default branch is opened, and works by checking for any resources that are about to be deleted and asking for confirmation before proceeding with the deletion. + +### Confirmation + +When a PR is opened that deletes resources, the `Deletion Protection` tool will comment on the PR with a message telling the user: + +```bash +#### ⚠️ The Terraform Plan contains ${process.env.DELETIONS} Deletion(s) ⚠️ + Please review the plan and ensure that the deletions are expected. + + If the deletions are expected, you must: + + 1. Create a new comment on this PR. + 2. Set the contents to 'delete' (no quotes) + 3. Press the comment button. + + before you can merge. +``` + +The status of the PR Review is then set to `Changes Requested` until the user follows the instructions and confirms the deletions. + +The user should review the plan, which is also a comment on the PR, and if the deletions are expected, they should create a new comment on the PR with the contents: `delete`. + +Once the user has confirmed the deletions, the status of the PR Review is set to `Approved`. diff --git a/organizations/GEN_INTERACTIVE.md b/organizations/GEN_INTERACTIVE.md new file mode 100644 index 0000000..8f68d6f --- /dev/null +++ b/organizations/GEN_INTERACTIVE.md @@ -0,0 +1,19 @@ +# Interactive `Generate` Tool + +The `Generate` tool is a CLI tool to help you write HCL interactively for `repositories` and `teams`. + +## Running the Generate Tool + +The Generate Tool is available as part of the `GitHub Foundations CLI` tool, found [here](https://github.com/FociSolutions/github-foundations-cli/releases). To run the Generate Tool, run the following command: + +```bash +Usage: + github-foundations-cli gen +```` + +Where `` is one of the following: + +* `repository_set` +* `team_set` + +See the [documentation](https://github.com/FociSolutions/github-foundations-cli?tab=readme-ov-file#generate) for more information. diff --git a/organizations/GH_ADVANCED_SECURITY.md b/organizations/GH_ADVANCED_SECURITY.md new file mode 100644 index 0000000..c27288e --- /dev/null +++ b/organizations/GH_ADVANCED_SECURITY.md @@ -0,0 +1,29 @@ +# GitHub Advanced Security (GHAS) checks + +The `GHAS Checks` tool is automatically installed on all GitHub Foundations organizations. + +It runs [GitHub Advanced Security (GHAS)](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) scans for eligible repositories that have it enabled and reports all of the GHAS scans in one report. + +## GHAS Checks GitHub Action + +The `GHAS Checks` tool is a GitHub Action that runs on a cron schedule (02:00 daily), and works by checking for any repositories that have GHAS enabled and running a scan on them. + +### Changing the Schedule + +The schedule for the `GHAS Checks` tool can be changed by modifying the `schedule` field in the `.github/workflows/ghas-policy-check.yml` file. + +```yaml +on: + schedule: + - cron: '0 2 * * *' +``` + +The schedule is set to run at 02:00 daily by default. +To learn how cron schedules work, see the [GitHub Actions documentation](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule). + +### Repository Eligibility + +To be eligible for a GHAS scan, the repository must have GHAS enabled. A repository can have GHAS enabled if: + +1. The repository is public. +2. The repository is private and GHAS has been purchased. diff --git a/organizations/IMPORT_TOOL.md b/organizations/IMPORT_TOOL.md new file mode 100644 index 0000000..baf297d --- /dev/null +++ b/organizations/IMPORT_TOOL.md @@ -0,0 +1,15 @@ +# Import Tool + +An Import tool is provided with the [GitHub Foundations CLI](https://github.com/FociSolutions/github-foundations-cli). This tool will start an interactive process to import resources into Terraform state. It uses the results of a terraform plan to determine which resources are available for import. + + +To run an import check for a repository, run the following command: + +```bash +Usage: + github-foundations-cli import [module_path] +``` + +Where `` is the path to the Terragrunt module to import. + +For more information, see the [documentation](https://github.com/FociSolutions/github-foundations-cli?tab=readme-ov-file#import). From 49e5e23127311849778321fa572d910bb6004557 Mon Sep 17 00:00:00 2001 From: Ben Zarboni Date: Tue, 27 Aug 2024 11:19:41 -0400 Subject: [PATCH 3/7] Added a back button to tools pages --- organizations/ASSESSMENT_TOOL.md | 2 ++ organizations/DELETION_PROTECTION.md | 2 ++ organizations/DRIFT_DETECTION.md | 2 ++ organizations/GEN_INTERACTIVE.md | 2 ++ organizations/GH_ADVANCED_SECURITY.md | 2 ++ organizations/IMPORT_TOOL.md | 2 ++ 6 files changed, 12 insertions(+) diff --git a/organizations/ASSESSMENT_TOOL.md b/organizations/ASSESSMENT_TOOL.md index e15ef34..3b80789 100644 --- a/organizations/ASSESSMENT_TOOL.md +++ b/organizations/ASSESSMENT_TOOL.md @@ -1,3 +1,5 @@ +([Back](../README.md#included-tools)) + # Assessment Tool The assessment tool is a tool that allows you to assess the readiness of your pre-existing GitHub `repository`, before importing it with the toolkit. diff --git a/organizations/DELETION_PROTECTION.md b/organizations/DELETION_PROTECTION.md index c968d18..dcd60bd 100644 --- a/organizations/DELETION_PROTECTION.md +++ b/organizations/DELETION_PROTECTION.md @@ -1,3 +1,5 @@ +([Back](../README.md#included-tools)) + # Deletion Protection The `Deletion Protection` tool is automatically installed on all GitHub Foundations organizations. diff --git a/organizations/DRIFT_DETECTION.md b/organizations/DRIFT_DETECTION.md index a0a2b05..46b3416 100644 --- a/organizations/DRIFT_DETECTION.md +++ b/organizations/DRIFT_DETECTION.md @@ -1,3 +1,5 @@ +([Back](../README.md#included-tools)) + # Drift Detection The `Drift Detection` tool is automatically installed on all GitHub Foundations organizations. diff --git a/organizations/GEN_INTERACTIVE.md b/organizations/GEN_INTERACTIVE.md index 8f68d6f..ceb4a0c 100644 --- a/organizations/GEN_INTERACTIVE.md +++ b/organizations/GEN_INTERACTIVE.md @@ -1,3 +1,5 @@ +([Back](../README.md#included-tools)) + # Interactive `Generate` Tool The `Generate` tool is a CLI tool to help you write HCL interactively for `repositories` and `teams`. diff --git a/organizations/GH_ADVANCED_SECURITY.md b/organizations/GH_ADVANCED_SECURITY.md index c27288e..2cfae6f 100644 --- a/organizations/GH_ADVANCED_SECURITY.md +++ b/organizations/GH_ADVANCED_SECURITY.md @@ -1,3 +1,5 @@ +([Back](../README.md#included-tools)) + # GitHub Advanced Security (GHAS) checks The `GHAS Checks` tool is automatically installed on all GitHub Foundations organizations. diff --git a/organizations/IMPORT_TOOL.md b/organizations/IMPORT_TOOL.md index baf297d..288f5fe 100644 --- a/organizations/IMPORT_TOOL.md +++ b/organizations/IMPORT_TOOL.md @@ -1,3 +1,5 @@ +([Back](../README.md#included-tools)) + # Import Tool An Import tool is provided with the [GitHub Foundations CLI](https://github.com/FociSolutions/github-foundations-cli). This tool will start an interactive process to import resources into Terraform state. It uses the results of a terraform plan to determine which resources are available for import. From 675c0e270defe9508100952f18c19bbb3f6636da Mon Sep 17 00:00:00 2001 From: jpound Date: Tue, 3 Sep 2024 16:14:52 -0400 Subject: [PATCH 4/7] Update ASSESSMENT_TOOL.md Smoothing out flow. Signed-off-by: jpound --- organizations/ASSESSMENT_TOOL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/organizations/ASSESSMENT_TOOL.md b/organizations/ASSESSMENT_TOOL.md index 3b80789..5f71f1a 100644 --- a/organizations/ASSESSMENT_TOOL.md +++ b/organizations/ASSESSMENT_TOOL.md @@ -2,7 +2,7 @@ # Assessment Tool -The assessment tool is a tool that allows you to assess the readiness of your pre-existing GitHub `repository`, before importing it with the toolkit. +The Assessment Tool allows you to assess the readiness of your pre-existing GitHub `repository`, before importing it with the toolkit. It is used to check whether toolkit guardrails are already in place in the `repository`, as well as any settings required at the `organization` level. ## Running the Assessment Tool @@ -16,4 +16,4 @@ To run an assessment check on a repository, run the following command: gh_foundations check ``` -Where `` is the organization slug to check. See the [documentation](https://github.com/FociSolutions/github-foundations-cli/blob/main/README.md#check) for more information. +`` is the organization slug to check. See the [documentation](https://github.com/FociSolutions/github-foundations-cli/blob/main/README.md#check) for more information. From 4f146d8cb1c15d8b8c2c3f756b6018af0e825ab2 Mon Sep 17 00:00:00 2001 From: jpound Date: Tue, 3 Sep 2024 16:15:59 -0400 Subject: [PATCH 5/7] Update ASSESSMENT_TOOL.md Adding format for consistency. Signed-off-by: jpound --- organizations/ASSESSMENT_TOOL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/organizations/ASSESSMENT_TOOL.md b/organizations/ASSESSMENT_TOOL.md index 5f71f1a..85ec254 100644 --- a/organizations/ASSESSMENT_TOOL.md +++ b/organizations/ASSESSMENT_TOOL.md @@ -2,12 +2,12 @@ # Assessment Tool -The Assessment Tool allows you to assess the readiness of your pre-existing GitHub `repository`, before importing it with the toolkit. +The `Assessment Tool` allows you to assess the readiness of your pre-existing GitHub `repository`, before importing it with the toolkit. It is used to check whether toolkit guardrails are already in place in the `repository`, as well as any settings required at the `organization` level. ## Running the Assessment Tool -The Assessment Tool is available as part of the `GitHub Foundations CLI` tool, found [here](https://github.com/FociSolutions/github-foundations-cli/releases) +The `Assessment Tool` is available as part of the `GitHub Foundations CLI` tool, found [here](https://github.com/FociSolutions/github-foundations-cli/releases) To run an assessment check on a repository, run the following command: From 8dbb5f60a3771b0a210794696cd028398bcf4c48 Mon Sep 17 00:00:00 2001 From: jpound Date: Tue, 3 Sep 2024 16:17:47 -0400 Subject: [PATCH 6/7] Update DELETION_PROTECTION.md Adjustments for flow. Signed-off-by: jpound --- organizations/DELETION_PROTECTION.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/organizations/DELETION_PROTECTION.md b/organizations/DELETION_PROTECTION.md index dcd60bd..9f32979 100644 --- a/organizations/DELETION_PROTECTION.md +++ b/organizations/DELETION_PROTECTION.md @@ -4,13 +4,9 @@ The `Deletion Protection` tool is automatically installed on all GitHub Foundations organizations. -`Deletion Protection` is a feature that helps to prevent accidental deletion of resources. When a resource is removed from the Terraform configuration, a mechanism kicks-in to ask for confirmation before the resource is deleted. +`Deletion Protection` is a feature that helps to prevent accidental deletion of resources. When a resource is removed from the Terraform configuration, a mechanism kicks-in to ask for confirmation before the resource is deleted. It is implemented as a GitHub Action that is invoked when a Pull Request (PR) into the default branch is opened, and works by checking for any resources that are about to be deleted and asking for confirmation before proceeding with the deletion. -## Deletion Protection GitHub Action - -The `Deletion Protection` tool is a GitHub Action that helps prevent accidental deletion of resources in your GitHub organization. It is invoked when a Pull Request (PR) into the default branch is opened, and works by checking for any resources that are about to be deleted and asking for confirmation before proceeding with the deletion. - -### Confirmation +## Confirmation When a PR is opened that deletes resources, the `Deletion Protection` tool will comment on the PR with a message telling the user: From 5edb9d52a3c2859aa0304b081d340971744d0a65 Mon Sep 17 00:00:00 2001 From: jpound Date: Tue, 3 Sep 2024 16:21:00 -0400 Subject: [PATCH 7/7] Update GH_ADVANCED_SECURITY.md Adjusting for flow. Signed-off-by: jpound --- organizations/GH_ADVANCED_SECURITY.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/organizations/GH_ADVANCED_SECURITY.md b/organizations/GH_ADVANCED_SECURITY.md index 2cfae6f..0a1fec1 100644 --- a/organizations/GH_ADVANCED_SECURITY.md +++ b/organizations/GH_ADVANCED_SECURITY.md @@ -4,13 +4,9 @@ The `GHAS Checks` tool is automatically installed on all GitHub Foundations organizations. -It runs [GitHub Advanced Security (GHAS)](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) scans for eligible repositories that have it enabled and reports all of the GHAS scans in one report. +It runs [GitHub Advanced Security (GHAS)](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) scans for eligible repositories that have it enabled and reports all of the GHAS scans in one report. It is implemented as a GitHub Action that runs on a cron schedule (02:00 daily), and works by checking for any repositories that have GHAS enabled and running a scan on them. -## GHAS Checks GitHub Action - -The `GHAS Checks` tool is a GitHub Action that runs on a cron schedule (02:00 daily), and works by checking for any repositories that have GHAS enabled and running a scan on them. - -### Changing the Schedule +## Changing the Schedule The schedule for the `GHAS Checks` tool can be changed by modifying the `schedule` field in the `.github/workflows/ghas-policy-check.yml` file. @@ -23,7 +19,7 @@ on: The schedule is set to run at 02:00 daily by default. To learn how cron schedules work, see the [GitHub Actions documentation](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule). -### Repository Eligibility +## Repository Eligibility To be eligible for a GHAS scan, the repository must have GHAS enabled. A repository can have GHAS enabled if: