Authenticate to GitHub with a Custom App

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 App 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

You can also open a shell to explore interactively:

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

Provide the private key without a file

When you run scans in CI/CD and your private key comes from a secret manager (such as Google Cloud Secret Manager), you don't have to write the PEM to disk first. cnspec accepts the key in three ways:

When more than one is set, cnspec uses the content flag first, then the environment variable, then the file path.

For example, pipe the key straight from a secret manager into the environment variable:

export GITHUB_APP_PRIVATE_KEY="$(gcloud secrets versions access latest --secret=github-app-key)"

cnspec scan github org YOUR-GITHUB-ORG \
  --app-id YOUR-APP-ID \
  --app-installation-id YOUR-INSTALL-ID

For more scanning options, read Secure GitHub with cnspec.