diff --git a/docs/cnquery/saas/gh-app.mdx b/docs/cnquery/saas/gh-app.mdx new file mode 100644 index 000000000..466443565 --- /dev/null +++ b/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 --app-id --app-installation-id --app-private-key +``` + +To learn more options for querying GitHub organizations and repositories, read [Assess the Configuration of GitHub Organizations and Repositories with cnspec](/cnspec/saas/github/). + +--- diff --git a/docs/cnquery/saas/github.md b/docs/cnquery/saas/github.md index 8b67df33d..8458de469 100644 --- a/docs/cnquery/saas/github.md +++ b/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= $Env:GITHUB_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 --app-id --app-installation-id --app-private-key -``` - ## 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. diff --git a/docs/cnquery/saas/google_workspace.mdx b/docs/cnquery/saas/google_workspace.mdx index a3a4503cd..903f1d41c 100644 --- a/docs/cnquery/saas/google_workspace.mdx +++ b/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 --- diff --git a/docs/cnquery/saas/ms365.md b/docs/cnquery/saas/ms365.md index 6d5a08b18..70a9d0d79 100644 --- a/docs/cnquery/saas/ms365.md +++ b/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 --- diff --git a/docs/cnquery/saas/okta.md b/docs/cnquery/saas/okta.md index 69b39405d..2938eb272 100644 --- a/docs/cnquery/saas/okta.md +++ b/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 diff --git a/docs/cnquery/saas/slack.md b/docs/cnquery/saas/slack.md index 0bb306335..28b841809 100644 --- a/docs/cnquery/saas/slack.md +++ b/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 diff --git a/docs/cnquery/saas/snowflake.mdx b/docs/cnquery/saas/snowflake.mdx index 8d7483334..7702ef75d 100644 --- a/docs/cnquery/saas/snowflake.mdx +++ b/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