Skip to main content

Give cnspec Access to GitHub using Custom App Credentials

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

  • Option 2: Give cnspec 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 cnspec access using custom app credentials, continue reading below.

For cnspec to authenticate with GitHub using custom GitHub application credentials, 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

  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

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

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

  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 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-ORGThe name of the GitHub organization you want to scan
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
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.