Skip to main content

Give cnquery Access to GitHub using Custom App Credentials

To query GitHub organizations and repos, 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.

  • 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, 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

  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

  11. Under Permissions, select Read-only for all repository and organization settings that offer read-only access. If a setting doesn't offer read-only access, leave it set to No access.

    Permissions

  12. Under Where can this GitHub App be installed?, select Only on this account.

    Add a new GitHub app

  13. Select the Create GitHub App button.

    GitHub creates the app and displays its properties.

    Created GitHub app

  14. In the About section, copy the App ID value and save it somewhere that you can access later. You need it when you query.

  15. 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.

  16. In the left sidebar, select Install App.

  17. 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

    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-ORGThe name of the GitHub organization you want to query
YOUR-GITHUB-APP-IDThe app ID from step 13
YOUR-GITHUB-APP-INSTALL-IDThe installation ID from step 16
PATH-TO-PEM-FILEThe path you noted in step 14
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.