Skip to main content

Assess the configuration of GitHub organizations and repositories with cnspec

Rely on cnspec to ensure your GitHub organizations and private repositories (repos) follow recommended security and operational best practices.

You can also use cnspec to assess public repos and open source projects your team depends on. cnspec evaluates the risk a project poses to your business.


Open source projects that don't adhere to GitHub's recommended security best practices pose a higher risk of introducing malicious code into your environments.

Give cnspec access using the GitHub API

To scan GitHub organizations and repos, cnspec needs access. You give cnspec the access it needs through the GitHub API. First, you create GitHub personal access token. Then you share that token with cnspec using an environment variable.

Option 1: Create a GitHub personal access token

cnspec needs a personal access token to scan a GitHub organization, public repo, or private repo. The token's level of access determines how much information cnspec can retrieve.

To learn how to create a personal access token, read Managing your personal access tokens in the GitHub documentation.

Configure a GITHUB_TOKEN environment variable

You supply your personal access token to cnspec using the GITHUB_TOKEN environment variable.

Linux / macOS

export GITHUB_TOKEN=<your personal access token>


$Env:GITHUB_TOKEN = "<personal-access-token>"

Option 2: Use custom GitHub application credentials

Mondoo also supports the using custom GitHub application credentials. Create an application and then use the app ID and the private key to authenticate scans:

cnquery scan github org <ORG> --app-id <YOUR-APP-ID> --app-installation-id <YOUR-INSTALL-ID> --app-private-key <PATH-TO-PEM-FILE>

Scan a GitHub organization

To scan the configuration of your GitHub organization and all repos within it, run this command:

cnspec scan github org <ORG_NAME>

Scanning large GitHub organizations and all repositories may exceed GitHub API rate limits. To learn more, read About rate limits in the GitHub documentation.

Scan a GitHub organization but not its repos

Use the --discover organization flag to scan your GitHub organization and discover and scan all of the repos within it:

cnspec scan github org <ORG_NAME> --discover organization

Scan GitHub repos

To scan the configuration of a GitHub repo:

cnspec scan github repo <ORG_NAME/REPO_NAME>

Scan specific repos in an organization

You can specify which repos in an organization to scan. This command scans only two repos:

cnspec scan github org <ORG_NAME> --repos "<REPO1>,<REPO2>" --discover repos

This command scans the repos and the organization:

cnspec scan github org <ORG_NAME> --repos "<REPO1>,<REPO2>"

You can achieve the same scan using a Mondoo inventory file. This is especially helpful when you have a long list of repos to scan.


- connections:
- type: github
organization: <ORG>
repos: <REPO1>,<REPO2>
repos-exclude: ""
- auto

To run a scan using this inventory, enter:

cnspec scan --inventory-file github-inventory.yml

Example checks

Run cnspec shell to open the cnspec interactive shell. From there you can make checks like the examples below.

Ensure two-factor authentication is enabled for GitHub organizations:

cnspec> github.organization.twoFactorRequirementEnabled
[failed] github.organization.twoFactorRequirementEnabled
expected: == true
actual: false

Ensure the GitHub organization domain is verified:

cnspec> github.organization.isVerified
[failed] github.organization.isVerified
expected: == true
actual: false

Ensure the GitHub organization default permissions is set to read:

cnspec> github.organization.defaultRepositoryPermission == "read"
[ok] value: "read"

Ensure the default branch is configured with branch protection:

cnspec> github.repository.branches.where( isDefault == true ).all( protected == true )
[ok] value: true

Learn more