Add GitHub app auth to cnquery

docs/cnquery/saas/gh-app.mdx

@@ -0,0 +1,95 @@
+---
+title: Give cnquery Access to GitHub using Custom App Credentials
+sidebar_label: GitHub with Custom App Credentials
+sidebar_position: 5
+displayed_sidebar: cnquery
+description: Give cnquery access to GitHub using a custom application.
+image: /img/featured_img/mondoo-feature.jpg
+---
+
+To [query GitHub organizations and repos](/cnquery/saas/github/), cnquery needs to authenticate with GitHub. There are two ways to do this:
+
+- Option 1: Give cnquery 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 cnquery access using a personal access token, read [Give cnquery access using a personal access token and an environment variable](/cnquery/saas/github/).
+
+- Option 2: Give cnquery access using custom GitHub application credentials. This approach takes longer to set up, but scales for very large GitHub organizations (with API rate limits as much as 3x higher than personal access tokens). To learn how to give cnquery access using custom app credentials, continue reading below.
+
+For cnquery to authenticate with GitHub using [custom GitHub application credentials](https://docs.github.com/en/apps/creating-github-apps), create a GitHub application and give cnquery the app ID, private key, and installation ID.
+
+## Create a GitHub application and get the authentication information cnquery 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 queries.
+
+8. In the **Homepage URL** box, type `https://cnquery.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 query.
+
+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 query.
+
+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 query.
+
+## Query using your custom app credentials
+
+Enter the `cnquery shell` command, passing the information you stored in the steps above:
+
+| For...                       | Substitute...                                         |
+|------------------------------|-------------------------------------------------------|
+| `YOUR-GITHUB-ORG`            | The name of the GitHub organization you want to query |
+| `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
+cnquery shell 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 querying GitHub organizations and repositories, read [Assess the Configuration of GitHub Organizations and Repositories with cnspec](/cnspec/saas/github/).
+
+---

docs/cnquery/saas/github.md

@@ -9,11 +9,15 @@ image: /img/featured_img/mondoo-feature.jpg
 
 Rely on cnquery to query and inventory your GitHub organizations and private repositories (repos) as well as public repos and open source projects your team depends on.
 
-## Give cnquery access using the GitHub API
+## Give cnquery access to your GitHub organization
 
-To query GitHub organizations and repos, cnquery needs access. You give cnquery the access it needs through the GitHub API. First, you create GitHub personal access token. Then you share that token with cnquery using an environment variable.
+To scan GitHub organizations and repos, cnquery needs access. There are two ways to do this:
 
-### Option 1: Create a GitHub personal access token
+- Option 1: Give cnquery 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 cnquery access using a personal access token, continue reading below.
+
+- Option 2: Give cnquery access using custom GitHub application credentials. This approach takes longer to set up, but scales for very large GitHub organizations (with API rate limits as much as 3x higher than personal access tokens). To learn how to give cnquery access using custom app credentials, read [Give cnquery Access to GitHub Using Custom GitHub App Credentials](/cnquery/saas/gh-app/).
+
+### Create a GitHub personal access token
 
 cnquery needs a personal access token to query a GitHub organization, public repo, or private repo. The token's level of access determines how much information cnquery can retrieve.
 
@@ -25,7 +29,7 @@ To learn how to create a personal access token, read [Creating a personal access
 - admin:org_hook
 - read:project
 
-#### Configure a GITHUB_TOKEN environment variable
+### Configure a GITHUB_TOKEN environment variable
 
 You supply your personal access token to cnquery using the `GITHUB_TOKEN` environment variable.
 
@@ -41,14 +45,6 @@ export GITHUB_TOKEN=<your personal access token>
 $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>
-```
-
 ## Query GitHub
 
 To answer any question about your environment, use cnquery's interactive shell. It has auto-complete to guide you, which is especially helpful when you're new to cnquery and learning MQL.

docs/cnquery/saas/google_workspace.mdx

@@ -1,7 +1,7 @@
 ---
 title: Query Google Workspace
 sidebar_label: Google Workspace
-sidebar_position: 3
+sidebar_position: 10
 displayed_sidebar: cnquery
 description: Query Google Workspace configuration with cnquery
 ---

docs/cnquery/saas/ms365.md

@@ -2,7 +2,7 @@
 title: Query Microsoft 365
 sidebar_label: Microsoft 365
 displayed_sidebar: cnquery
-sidebar_position: 4
+sidebar_position: 20
 description: Use cnquery to inventory and Microsoft 365
 image: /img/featured_img/mondoo-365.jpg
 ---

docs/cnquery/saas/okta.md

@@ -1,7 +1,7 @@
 ---
 title: Query Okta
 sidebar_label: Okta
-sidebar_position: 5
+sidebar_position: 30
 displayed_sidebar: cnquery
 description: Query Okta configuration with cnquery
 image: /img/featured_img/mondoo-feature.jpg

docs/cnquery/saas/slack.md

@@ -1,7 +1,7 @@
 ---
 title: Query Slack
 sidebar_label: Slack
-sidebar_position: 6
+sidebar_position: 40
 displayed_sidebar: cnquery
 description: Query your Slack workspaces with cnquery
 image: /img/featured_img/mondoo-feature.jpg

docs/cnquery/saas/snowflake.mdx

@@ -1,7 +1,7 @@
 ---
 title: Query Snowflake Configuration and Identities
 sidebar_label: Snowflake
-sidebar_position: 7
+sidebar_position: 50
 displayed_sidebar: cnquery
 description: Query Snowflake account and database configuration and identities with cnquery
 image: /img/featured_img/mondoo-feature.jpg