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: Personal access token. This is easier to set up but isn't recommended for very large GitHub organizations. To learn how, read Query GitHub organizations and repositories.

• Option 2: Custom GitHub application credentials. This 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. Continue reading below to learn how.

Requirements

To set up custom app authentication, you must have:

• cnquery installed on your workstation
• Owner or admin access to the GitHub organization you want to query
• Permission to create and install GitHub Apps in the organization

Create a GitHub application

For cnquery to authenticate using custom GitHub application credentials, you create a GitHub App and give cnquery the app ID, private key, and installation ID.

Step 1: Register the app

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.

   

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://mondoo.com/cnquery/ 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.

    

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.

    

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

    

13. Select the Create GitHub App button.

    GitHub creates the app and displays its properties.

    

Step 2: Record the app ID

In the About section, copy the App ID value and save it somewhere you can access later.

Step 3: Generate a private key

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 as a PEM file. Note the path to the PEM file.

Step 4: Install the app and record the installation ID

1. In the left sidebar, select Install App.

2. Install your custom app to the organization or repos you want to query.

   GitHub installs the app and displays a confirmation.

   

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

Connect to GitHub with custom app credentials

Use the app ID, installation ID, and private key to launch the cnquery shell:

cnquery shell github org YOUR-GITHUB-ORG --app-id YOUR-APP-ID --app-installation-id YOUR-INSTALL-ID --app-private-key PATH-TO-PEM-FILE

You can also run queries directly from the command line:

cnquery run github org YOUR-GITHUB-ORG --app-id YOUR-APP-ID --app-installation-id YOUR-INSTALL-ID --app-private-key PATH-TO-PEM-FILE -c "github.organization.repositories { name visibility }"

Example queries

Once connected, you can query the same GitHub resources as with a personal access token. Here are some examples:

List all repositories and their visibility:

cnquery> github.organization.repositories { name visibility }
github.organization.repositories: [
  0: {
    name: "api-server"
    visibility: "private"
  }
  1: {
    name: "docs"
    visibility: "public"
  }
  ...
]

Check whether two-factor authentication is required:

cnquery> github.organization.twoFactorRequirementEnabled
github.organization.twoFactorRequirementEnabled: true

List organization members:

cnquery> github.organization.members { login }
github.organization.members: [
  0: {
    login: "alice-johnson"
  }
  1: {
    login: "bob-smith"
  }
  ...
]

List teams and their members:

cnquery> github.organization.teams { name members { login } }
github.organization.teams: [
  0: {
    name: "Engineering"
    members: [
      0: {
        login: "alice-johnson"
      }
    ]
  }
  ...
]

Learn more

• To learn more about querying GitHub organizations and repositories, read Query GitHub organizations and repositories.

• For a list of all the GitHub resources and fields you can query, read the Mondoo GitHub Resource Pack Reference.

• To learn more about how the MQL query language works, read Write Effective MQL.