Add github app instructions (#440)

* very rough draft of github app instructions * add remaining bulk * fix errors * fix formatting * fix formatting * tweak link * changes per @tas50 * learn to spell, letha
mondoohq · Nov 4, 2024 · 3718940 · 3718940
1 parent 1de9fb5
commit 3718940
Show file tree

Hide file tree

Showing 13 changed files with 117 additions and 22 deletions.
diff --git a/docs/cnspec/saas/gh-app.mdx b/docs/cnspec/saas/gh-app.mdx
@@ -0,0 +1,95 @@
+---
+title: Give cnspec Access to GitHub using Custom App Credentials
+sidebar_label: GitHub with Custom App Credentials
+sidebar_position: 5
+displayed_sidebar: cnspec
+description: Give cnspec access to GitHub using a custom application.
+image: /img/featured_img/mondoo-feature.jpg
+---
+
+To [scan GitHub organizations and repos](/cnspec/saas/github/), cnspec needs to authenticate with GitHub. There are two ways to do this:
+
+- Option 1: Give cnspec access using a personal access token and an environment variable. This approach is easier to set up but results isn't recommended for very large GitHub organizations. To learn how to give cnspec access using a personal access token, read [Give cnspec access using a personal access token and an environment variable](/cnspec/saas/github/).
+
+- Option 2: Give cnspec access using custom GitHub application credentials. This approach takes longer to set up, but scales for very large GitHub organizations. To learn how to give cnspec access using custom app credentials, continue reading below.
+
+For cnspec to authenticate with GitHub using [custom GitHub application credentials](https://docs.github.com/en/apps/creating-github-apps), create a GitHub application and give cnspec the app ID, private key, and installation ID.
+
+## Create a GitHub application and get the authentication information cnspec needs
+
+1. In the top-right corner of any page on GitHub, select your profile icon.
+
+2. Open your account settings:
+
+   - To create an app owned by a personal account, select **Settings**.
+
+   - To create an app owned by an organization, select **Your organizations** and, to the right of the organization you want, select **Settings**.
+
+3. In the left sidebar, select **Developer settings**.
+
+4. In the left sidebar, select GitHub Apps.
+
+5. Select the **New GitHub App** button.
+
+    ![Add a new GitHub app](/img/cnspec/github/name-new-app.png)
+
+6. In the **GitHub App name** box, type a name for your app that helps you easily recognize that it's for Mondoo. The name must be unique across GitHub.
+
+7. In the **Description** box, write that this app provides authentication for Mondoo security scans.
+
+8. In the **Homepage URL** box, type `https://cnspec.io' or your own company URL.
+
+9. Skip past the settings under **Identifying and authorizing users** and **Post installation**.
+
+10. Under **Webhooks**, uncheck the **Active** box.
+
+    ![Webhooks](/img/cnspec/github/webhook.png)
+
+11. Under **Permissions**, assign **read-only** permission to all repository and organization data.
+
+    ![Permissions](/img/cnspec/github/perms.png)
+
+12. Under **Where can this GitHub App be installed?**, select **Only on this account**.
+
+    ![Add a new GitHub app](/img/cnspec/github/create-gh-app.png)
+
+12. Select the **Create GitHub App** button.
+
+    GitHub creates the app and displays its properties.
+
+    ![Created GitHub app](/img/cnspec/github/created-app.png)
+
+13. In the **About** section, copy the **App ID** value and save it somewhere that you can access later. You need it when you scan.
+
+14. Scroll down to the **Private keys** section and select the **Generate a private key** button.
+
+    GitHub creates a new private key and downloads it to your workstation in a PEM certificate file. Note the path to the PEM file; you need it when you scan.
+
+15. In the left sidebar, select **Install App**.
+
+16. Install your custom app to any repo so that you can see its installation ID.
+
+    GitHub installs the app and displays a confirmation.
+
+    ![Install a new GitHub app](/img/cnspec/github/install-success.png)
+
+    In your browser's address bar, find the installation ID in the URL, after `/installations/`. For example, the pictured app's installation ID is `56758584`. Copy this value and save it somewhere that you can access later. You need it when you scan.
+
+## Scan using your custom app credentials
+
+Enter the `cnspec scan` command, passing the information you stored in the steps above:
+
+| For...                       | Substitute...                                        |
+|------------------------------|------------------------------------------------------|
+| `YOUR-GITHUB-ORG`            | The name of the GitHub organization you want to scan |
+| `YOUR-GITHUB-APP-ID`         | The app ID from step 13                              |
+| `YOUR-GITHUB-APP-INSTALL-ID` | The installation ID from step 16                     |
+| `PATH-TO-PEM-FILE`           | The path you noted in step 14                        |
+
+```bash
+cnspec scan github org <YOUR-GITHUB-ORG> --app-id <YOUR-GITHUB-APP-ID> --app-installation-id <YOUR-GITHUB-APP-INSTALL-ID> --app-private-key <PATH-TO-PEM-FILE>
+```
+
+To learn more options for scanning GitHub organizations and repositories, read [Assess the Configuration of GitHub Organizations and Repositories with cnspec](/cnspec/saas/github/).
+
+---
diff --git a/docs/cnspec/saas/github.md b/docs/cnspec/saas/github.md
@@ -1,5 +1,5 @@
 ---
-title: Assess the configuration of GitHub organizations and repositories with cnspec
+title: Assess the Configuration of GitHub Organizations and Repositories with cnspec
 sidebar_label: GitHub
 sidebar_position: 2
 displayed_sidebar: cnspec
@@ -17,11 +17,19 @@ Open source projects that don't adhere to GitHub's recommended security best pra
 
 :::
 
-## Give cnspec access using the GitHub API
+## Give cnspec access to your GitHub organization
 
-To scan GitHub organizations and repos, cnspec needs access. You give cnspec the access it needs through the GitHub API. First, you create GitHub personal access token. Then you share that token with cnspec using an environment variable.
+To scan GitHub organizations and repos, cnspec needs access. There are two ways to do this:
 
-### Option 1: Create a GitHub personal access token
+- Option 1: Give cnspec access using a personal access token and an environment variable. This approach is easier to set up but isn't recommended for very large GitHub organizations. To learn how to give cnspec access using a personal access token, continue reading below.
+
+- Option 2: Give cnspec access using custom GitHub application credentials. This approach takes longer to set up, but scales for very large GitHub organizations. To learn how to give cnspec access using custom app credentials, read [Give cnspec Access to GitHub Using Custom GitHub App Credentials](/cnspec/saas/gh-app/).
+
+### Give cnspec access using a personal access token and an environment variable
+
+With this approach, you give cnspec the access it needs through the GitHub API. First, you create GitHub personal access token. Then you share that token with cnspec using an environment variable.
+
+#### Create a GitHub personal access token
 
 cnspec needs a personal access token to scan a GitHub organization, public repo, or private repo. The token's level of access determines how much information cnspec can retrieve.
 
@@ -35,34 +43,26 @@ To learn how to create a personal access token, read [Managing your personal acc
 
 #### Configure a GITHUB_TOKEN environment variable
 
-You supply your personal access token to cnspec using the `GITHUB_TOKEN` environment variable.
+You supply your personal access token to cnspec by setting the `GITHUB_TOKEN` environment variable.
 
-#### Linux / macOS
+**On Linux / macOS:**
 
 ```bash
 export GITHUB_TOKEN=<your personal access token>
 ```
 
-#### Windows
+**On Windows, using PowerShell:**
 
 ```powershell
-$Env:GITHUB_TOKEN = "<personal-access-token>"
-```
-
-### Option 2: Use custom GitHub application credentials
-
-Mondoo also supports the using [custom GitHub application credentials](https://docs.github.com/en/apps/creating-github-apps). Create an application and then use the app ID and the private key to authenticate scans:
-
-```bash
-cnquery scan github org <ORG> --app-id <YOUR-APP-ID> --app-installation-id <YOUR-INSTALL-ID> --app-private-key <PATH-TO-PEM-FILE>
+$Env:GITHUB_TOKEN = "<your personal access token>"
 ```
 
 ## Scan a GitHub organization
 
 To scan the configuration of your GitHub organization and all repos within it, run this command:
 
 ```bash
-cnspec scan github org <ORG_NAME>
+cnspec scan github org <YOUR-GITHUB-ORG>
 ```
 
 :::caution

diff --git a/docs/cnspec/saas/gitlab.md b/docs/cnspec/saas/gitlab.md
@@ -1,7 +1,7 @@
 ---
 title: Assess the configuration of GitLab organizations and repositories with cnspec
 sidebar_label: GitLab
-sidebar_position: 3
+sidebar_position: 10
 displayed_sidebar: cnspec
 description: Secure and enforce policy for GitLab
 image: /img/featured_img/mondoo-feature.jpg

diff --git a/docs/cnspec/saas/google_workspace.mdx b/docs/cnspec/saas/google_workspace.mdx
@@ -1,7 +1,7 @@
 ---
 title: Assess Google Workspace Security with cnspec
 sidebar_label: Google Workspace
-sidebar_position: 4
+sidebar_position: 20
 displayed_sidebar: cnspec
 description: Set up cnspec to perform security scans of Google Workspace
 ---

diff --git a/docs/cnspec/saas/ms365.md b/docs/cnspec/saas/ms365.md
@@ -2,7 +2,7 @@
 title: Assess Microsoft 365 Security with cnspec
 sidebar_label: Microsoft 365
 displayed_sidebar: cnspec
-sidebar_position: 5
+sidebar_position: 30
 description: Use cnspec to assess Microsoft 365 for security misconfigurations
 image: /img/featured_img/mondoo-365.jpg
 ---

diff --git a/docs/cnspec/saas/okta.md b/docs/cnspec/saas/okta.md
@@ -1,7 +1,7 @@
 ---
 title: Assess Okta Security with cnspec
 sidebar_label: Okta
-sidebar_position: 5
+sidebar_position: 40
 displayed_sidebar: cnspec
 description: Secure and enforce policy for Okta
 image: /img/featured_img/mondoo-feature.jpg

diff --git a/docs/cnspec/saas/slack.md b/docs/cnspec/saas/slack.md
@@ -1,7 +1,7 @@
 ---
 title: Asses Slack Security with cnspec
 sidebar_label: Slack
-sidebar_position: 7
+sidebar_position: 50
 displayed_sidebar: cnspec
 description: Secure and enforce policy for your Slack workspaces
 image: /img/featured_img/mondoo-feature.jpg

diff --git a/static/img/cnspec/github/create-gh-app.png b/static/img/cnspec/github/create-gh-app.png
diff --git a/static/img/cnspec/github/created-app.png b/static/img/cnspec/github/created-app.png
diff --git a/static/img/cnspec/github/install-success.png b/static/img/cnspec/github/install-success.png
diff --git a/static/img/cnspec/github/name-new-app.png b/static/img/cnspec/github/name-new-app.png
diff --git a/static/img/cnspec/github/perms.png b/static/img/cnspec/github/perms.png
diff --git a/static/img/cnspec/github/webhook.png b/static/img/cnspec/github/webhook.png