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.
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 Creating a personal access token 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>
Windows
$Env:GITHUB_TOKEN = "<personal-access-token>"
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.
To learn more about the command, read cnspec scan github.
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
To learn more about the command, read [cnspec scan github org](/cnspec/cli/cnspec_scan_github_org/).
Scan GitHub repos
To scan the configuration of a GitHub repo:
cnspec scan github repo <ORG_NAME/REPO_NAME>
To learn more about the command, read cnspec scan github repo.
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
To learn about all the GitHub resources and properties, read the Mondoo GitHub Resource Pack Reference.
To learn how to write checks, read Write Effective MQL.
To learn about cnspec commands for GitHub, read: