Initial skeleton structure for Governing GitHub

docs/guides/github/decommission/index.md

@@ -0,0 +1,78 @@
+---
+title: Decommission GitHub Organization
+sidebar_label: Decommission GitHub Organization
+---
+
+# Decommission GitHub Organization
+
+In this guide, you will:
+
+- Learn how to decommission a GitHub organization from a Guardrails workspace while managing associated resources effectively.
+
+Guardrails allows administrators to remove a [GitHub Organization](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations) from a workspace. The delete action removes all associated policies and references from the Guardrails database, but `does not delete any resources` from the target GitHub organization.
+
+<!-- Careful consideration should be made when managing resources such as webhooks, as once removed, these changes cannot be undone. -->
+
+> [!IMPORTANT]
+> Before starting the process, administrators should determine whether Guardrails-managed resources (e.g., webhooks) should remain in the organization. The following policies can be configured in Guardrails to facilitate cleanup. Ensure that these changes are applied **only to the target GitHub organization**.
+
+## Prerequisites
+
+- **Turbot/Operator** permissions at the Turbot resource level.
+- Familiarity with the Guardrails console.
+- Familiarity with the GitHub.
+
+DISCUSS THE SEQUENCE, WEBHOOKS SETUP WITH SD
+
+## Disable Event Handlers
+
+Disable Event Handlers associated with `GitHub > Organization > Event Handlers` with value set to `Enforce: Disabled`. This removes Guardrails-configured webhooks. Once these policies have been applied and the associated controls have completed their cleanup, the GitHub organization can be safely removed from the Guardrails workspace.
+
+## Remove Credentials Policies
+
+Delete the policy `GitHub > Config > Personal Access Token` configured for the target GitHub organization. This ensures that Guardrails no longer has access to the organization.
+
+## Delete the Organization
+
+Login to the Guardrails console.
+
+![Guardrails Console Login](/images/docs/guardrails/guides/github/decommission-github-organization/guardrails-console-login.png)
+
+Navigate to the `Organization` that needs to be removed.
+
+Image
+
+Select the **Actions** button in the top-right corner and choose **Actions** button in the top-right corner.
+
+Image
+
+Select the **Remove from Turbot**.
+
+> [!NOTE]
+> If you don’t see this button, contact your Guardrails administrator for the required permissions.
+
+In the popup window, copy the `Organization ID` and paste it into the text box. Select **Delete**.
+
+Image
+
+> [!IMPORTANT]
+> While the deletion is reversible by re-importing the organization, it can be resource-intensive. Double-check all configurations before proceeding.
+
+## Verify
+
+Guardrails will begin the deletion process. The time to complete the process depends on the number of policies and resources associated with the organization. Larger organizations may take longer.
+
+After completing the steps above, verify that the GitHub organization no longer appears in the Guardrails console. Ensure that no residual event handlers or configurations remain.
+
+## Next Steps
+
+Please see the following resources to learn more about Turbot Guardrails:
+
+- Learn more about [Managing GitHub Organizations](guides/github/manage-organizations).
+
+## Troubleshooting
+
+| Issue                  | Description                                                                                                                                  | Guide                                                                                   |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| **Deletion Errors**    | Errors may occur due to database locks or incomplete cleanup. Ensure all event handlers and policies have been removed before retrying.      | [Troubleshoot Deletion Issues](/guardrails/docs/github/troubleshooting#deletion-errors) |
+| **Further Assistance** | If issues persist after troubleshooting, open a support ticket with details such as screenshots and error messages for efficient resolution. | [Open Support Ticket](https://support.turbot.com)                                       |

docs/guides/github/github-sidebar.json

@@ -0,0 +1,10 @@
+{
+  "type": "category",
+  "id": "github",
+  "link": "guides/github",
+  "items": [
+    "guides/github/import-github-organization",
+    "guides/github/decommission",
+    "guides/github/real-time-events"
+  ]
+}

docs/guides/github/import-github-organization/index.md

@@ -0,0 +1,108 @@
+---
+title: Import GitHub Organization
+sidebar_label: Import GitHub Organization
+---
+
+# Import GitHub Organization
+
+In this guide, you will:
+
+- Learn how to import an entire GitHub organization into Turbot Guardrails. This process allows Guardrails to discover and manage resources across your organization in real-time.
+- Monitor and troubleshoot the process.
+
+<!-- - Centralize governance for your GitHub resources within Guardrails.
+- Apply policies to enforce security, compliance, and operational best practices.
+- Monitor real-time activity within your organization.
+- Establish detailed audit logs to track all activities and changes for improved visibility and reporting. -->
+
+Importing a [GitHub Organization](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations) into Guardrails involves these key steps:
+
+- Configuring a GitHub with appropriate permissions at the Organization level.
+- Importing the Organization via the Guardrails Console.
+
+## Prerequisites
+
+- Access to the Guardrails console with *Turbot/Owner* or *Turbot/Admin* permissions at the Turbot resource level.
+- Familiarity with the GitHub.
+- GitHub mod should be installed in your Guardrails workspace.
+- Ensure access to [GitHub CLI](https://cli.github.com/) to fetch organization ID.
+- Ensure GitHub organization has allowed access via personal access tokens. Refer [Setting a personal access token policy for your organization](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) for more information.
+
+<!-- ## Supported Authentication -->
+
+## What Permissions to Grant
+
+<!-- To make sure all functionality of GitHub integration work, we suggest you to provide all the following permissions.
+
+- Organization Administration - Read and write
+- Organization Blocking users - Read and write
+- Organization Webhooks - Read and write
+- Repository Administration - Read and write
+- Repository Metadata - Read-only -->
+
+To ensure full functionality of the GitHub integration, we recommend granting the following permissions:
+
+| **Permission**                       | **Access Level**    | **Description**                                                                                       |
+|--------------------------------------|---------------------|-------------------------------------------------------------------------------------------------------|
+| Organization Administration          | Read and write      | Allows Guardrails to manage settings and configurations at the organization level.                   |
+| Organization Blocking Users          | Read and write      | Enables Guardrails to block and unblock users within the organization.                               |
+| Organization Webhooks                | Read and write      | Allows Guardrails to manage webhooks for capturing real-time events at the organization level.        |
+| Repository Administration            | Read and write      | Grants Guardrails the ability to manage repository settings, including access controls and policies.  |
+| Repository Metadata                  | Read-only           | Provides Guardrails with visibility into repository metadata without modifying its content.           |
+
+## Get GitHub Organization ID
+
+There are various ways to get the GitHub organization ID.
+
+Use [GitHub CLI](https://docs.github.com/en/github-cli/github-cli/quickstart) and run the following command to get the ID of the organization you want to import.
+
+```
+gh api orgs/<organization name> --jq '.id'
+```
+
+Alternatively, you can use `curl` command to get the organization ID.
+
+```
+curl -H "Authorization: Bearer ghp_iio5FzBF4OLbbes3AKasdre5f4mps50s7YXE" https://api.github.com/orgs/<your-org-name>
+```
+The result will be shown as below:
+
+```json
+{
+  "login": "your-org-name",
+  "id": 94844722,
+  "node_id": "O_kgDOBac5MQ",
+  "url": "https://api.github.com/orgs/your-org-name",
+  ....
+}
+```
+## Import Organization into Guardrails
+
+Login to your Guardrails workspace console and select the **CONNECT** card.
+
+![Guardrails Console Login](/images/docs/guardrails/guides/github/import-github-organization/select-connect-card.png)
+
+Select **GitHub** card from the connect panel.
+
+![Connect GitHub Card](/images/docs/guardrails/guides/github/import-github-organization/connect-github-card.png)
+
+Choose the location where you want to import the organization. Typically this would be done at the `Turbot` root level of your hierarchy, however it can reside in a [Folder](/guardrails/docs/concepts/resources/hierarchy#folders) based on your use-case.
+
+![Choose Location](/images/docs/guardrails/guides/github/import-github-organization/choose-location.png)
+
+Provide `Organization Name`, `Organization ID`, `Personal Access Token` and choose **Connect**.
+
+![Connect](/images/docs/guardrails/guides/github/import-github-organization/connect.png)
+
+Verify that the controls are executed by navigating to **Controls** tab and select GitHub.
+
+![Verify Controls](/images/docs/guardrails/guides/github/import-github-organization/verify-github-controls.png)
+
+
+## Troubleshooting
+
+| **Issue**                | **Description**                                                                                                                      | **Guide**                                                                                                                                |
+|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| Controls in Error    | Controls may enter various states, including errors, which can impact their functionality.                                           | [Learn More About Control States](/guardrails/docs/concepts/controls#control-state)                                                     |
+| Message: `Bad Credentials` | Guardrails GitHub controls may generate errors with a `Bad credentials` message, often caused by invalid or expired tokens.                                | [Token Expiration and Revocation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation) |
+| Further Assistance   | If issues persist, please open a ticket with us and attach relevant details for more efficient troubleshooting.                      | [Open Support Ticket](https://support.turbot.com)                                                                                       |

docs/guides/github/index.md

@@ -0,0 +1,24 @@
+---
+title: Governing GitHub
+sidebar_label: Governing GitHub
+---
+
+TO REVIEW FURTHER TO CHANGE
+
+# Governing GitHub
+
+Turbot Guardrails provides comprehensive governance for [GitHub](https://github.com/), enabling secure, compliant, and efficient management of your GitHub resources.
+
+Guardrails ensures effective management and real-time visibility into your GitHub organizations with the following capabilities:
+
+- **Policy Management**: Offers a variety of GitHub mods with policies and controls to manage repositories, and organizations.
+- **Real-Time Event Handling**: Updates the Guardrails CMDB as repositories, are created, modified, or deleted, enabling immediate policy enforcement.
+- **Activity Visibility**: Provides insights into all activity within GitHub organizations, including who made changes, what was changed, and when it occurred.
+
+| Section                                                                                   | Description                                                        |
+| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| [Import a GitHub Organization](guides/github/import-github-organization)                  | Guide to importing a GitHub organization into a Guardrails folder. |
+| [Set Up GitHub Real-Time Events](guides/github/real-time-events)                          | How to configure Guardrails to process real-time GitHub events.    |
+| [Enable GitHub Features](guides/github/features)                                          | Steps to enable the GitHub features required for governance.       |
+| [Explore GitHub Mods](https://hub.guardrails.turbot.com/mods/github/mods)                 | A detailed list of available GitHub mods in Turbot Guardrails.     |
+| [Set Up GitHub Policies](https://hub.guardrails.turbot.com/policy-packs?providers=github) | Learn how to configure Guardrails policies for GitHub.             |

docs/guides/github/real-time-events/event-handler/index.md

@@ -0,0 +1,141 @@
+---
+title: "Event Pollers (Optional)"
+template: Documentation
+nav:
+  title: "Event Pollers (Optional)"
+  order: 20
+---
+
+CHANGES TODO
+
+# GCP Event Pollers
+
+Turbot Guardrails offers a polling mechanism for obtaining relevant events from GCP and
+updating its CMDB. This mechanism is easy to configure and will not require
+sending events to a Guardrails public event ingestion endpoint. While it is
+possible to configure both event poller and event handlers, Turbot Support highly
+recommends using the **GCP event handlers**. Event Pollers and Event Handlers
+should never be enabled at the same time.
+
+- Choose **Event Poller** for ease of configuration. This is the **pull**
+  method.
+- Choose **Event Handler** for efficiency and timeliness. This is the **push**
+  method.
+
+In the case of the Guardrails GCP Event Poller, StackDriver is queried for relevant
+events on a schedule.  Events are then based back to Guardrails router for processing.
+
+<div className="alert alert-info font-weight-bold">
+  <p>Be aware of <a href="https://cloud.google.com/logging/quotas">logging limits and quotas</a>, including:</p>
+<ul>
+  <li>Limited to 1 <a href="https://cloud.google.com/logging/docs/reference/v2/rest/v2/entries/list">entries.list</a> call per second, per project.</li>
+  <li>Log retention is 400 days for system and admin activity logs, 30 days for data
+access logs.</li>
+</ul>
+</div>
+
+## Configuration of GCP Pollers
+
+The following policies will need to be configured in the environment to enable
+event polling:
+
+| Policy Type                            | Description                                                                                                                                                             |
+| -------------------------------------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| GCP > Turbot > Event Poller            | Enable/Disable polling. Enabled by default.  Automatically switches off when Event Handlers are enabled                                                                 |
+| GCP > Turbot > Event Poller > Interval | The polling interval - how often to poll                                                                                                                                |
+| GCP > Turbot > Event Poller > Window   | The polling window - how far back to retrieve events when polling. This must exceed the interval, and is required in case events are recieved by stackdriver out of order |
+| GCP > Turbot > Event Poller > Filter   | The GCP Logging filter to use when querying events (same as GCP > Turbot > Event Handlers > Logging > Sink > Compiled Filter )                                          |
+
+## Relevant policy schema
+
+### GCP > Turbot > Event Poller
+
+```yml
+description: |
+  Configure the GCP Event Poller. When set to Enabled, the poller will run at the interval specified to retrieve the latest events and forward them to Guardrails for further processing.
+
+  Note: Event Poller and Event Handlers are different mechanisms for sending information to Guardrails. You should enable one or the other, but not both.
+
+targets: GCP Project
+
+schema:
+  type: String
+  enum:
+    - Enabled
+    - Disabled
+  default: Enabled
+```
+
+### GCP > Turbot > Event Poller > Interval
+
+```yml
+description: |
+  The polling interval. This policy determines how often the event poller will run.
+
+targets: GCP Project
+
+schema:
+  type: String
+  enum:
+    - Every 1 minute
+    - Every 2 minutes
+    - Every 3 minutes
+    - Every 4 minutes
+    - Every 5 minutes
+    - Every 6 minutes
+    - Every 7 minutes
+    - Every 8 minutes
+    - Every 9 minutes
+    - Every 10 minutes
+
+  default: Every 2 minutes
+```
+
+### GCP > Turbot > Event Poller > Window
+
+```yml
+description: |
+  The polling window, in minutes. This policies determines the oldest events the event poller will retrieve. For example, setting the window to '5 minutes' will cause the poller to retrieve all events from the previous 5 minutes every time it runs.
+
+  The Window must be greater than the Interval, and it is recommended to be at least twice the Interval. For example, if the Interval is 'Every 5 Minutes', the Window should be at least '10 Minutes'.
+
+targets: GCP Project
+
+schema:
+  type: String
+  enum:
+    - 5 minutes
+    - 6 minutes
+    - 7 minutes
+    - 8 minutes
+    - 9 minutes
+    - 10 minutes
+    - 11 minutes
+    - 12 minutes
+    - 13 minutes
+    - 14 minutes
+    - 15 minutes
+    - 16 minutes
+    - 17 minutes
+    - 18 minutes
+    - 19 minutes
+    - 20 minutes
+  default: 5 minutes
+```
+
+### GCP > Turbot > Event Poller > Filter
+
+```yml
+description: |
+  A GCP logs [advanced filter](https://cloud.google.com/logging/docs/view/advanced-queries) used to specify a subset of log entries that will be queried by the event poller.
+
+  This is a read-only policy that is used internally by Guardrails
+
+targets: GCP Project
+
+schema:
+  type: String
+  default:
+    calculated - value of `GCP > Turbot > Event Handlers > Logging > Sink >
+    Compiled Filter`
+```