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.

tip

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

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

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>

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​