Give cnspec Access to GitHub using Custom App Credentials

To scan GitHub organizations and repos, cnspec needs to authenticate with GitHub. You can use a personal access token for a quick setup, or create a custom GitHub application for better scalability (with API rate limits as much as 3x higher). This page walks you through the custom app approach.

It's a one-time setup: you create a GitHub app, then give cnspec three values — the app ID, a private key, and an installation ID.

Create the GitHub app

1. In the top-right corner of any page on GitHub, select your profile icon and open your account settings:

   • For a personal account, select Settings.
   • For an organization, select Your organizations and then select Settings for the organization you want.

2. Select Developer settings > GitHub Apps > New GitHub App.

   

3. Fill in the basic information:

   • GitHub App name: A name that helps you recognize the app is for Mondoo (must be unique across GitHub)
   • Description: Something like "Provides authentication for Mondoo security scans"
   • Homepage URL: https://mondoo.com/cnspec/ or your own company URL

4. Leave the default settings under Identifying and authorizing users and Post installation.

5. Under Webhooks, uncheck the Active box.

   

6. Under Permissions, select Read-only for every repository and organization setting that offers it. Leave all other settings at No access.

   

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

   

8. Select Create GitHub App.

   GitHub creates the app and displays its properties.

   

Now collect the three values cnspec needs to authenticate:

9. In the About section, note the App ID.

10. Scroll down to Private keys and select Generate a private key. GitHub downloads a PEM file to your workstation. Note the file path.

11. In the left sidebar, select Install App and install it to the organization or repositories you want to scan.

    

    In your browser's address bar, find the installation ID in the URL after /installations/. For example, the installation ID in the screenshot above is 56758584.

Scan using your custom app credentials

Run a scan using the three values you collected above:

cnspec scan github org YOUR-GITHUB-ORG \
  --app-id YOUR-APP-ID \
  --app-installation-id YOUR-INSTALL-ID \
  --app-private-key PATH-TO-PEM-FILE

For more scanning options, read Assess the Configuration of GitHub Organizations and Repositories with cnspec.