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, such as enforcing two-factor authentication, verifying organization domains, configuring branch protection, and setting appropriate default permissions.

You can also use cnspec to assess public repos and open source projects your team depends on. cnspec checks whether a project follows GitHub's recommended security practices, helping you understand the risk it poses to your environments.

Prerequisites

Before you begin, install cnspec.

Give cnspec access to your GitHub organization

To scan GitHub organizations and repos, cnspec needs access. Choose one of these approaches:

Give cnspec access using a personal access token

To give cnspec access through the GitHub API, you create a personal access token and then share it with cnspec using an environment variable.

Step 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. We recommend creating a classic token with these scopes:

• public_repo
• read:org
• read:repo_hook
• admin:org_hook
• read:project

Step 2: Configure a GITHUB_TOKEN environment variable

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

On Linux / macOS:

export GITHUB_TOKEN=<your personal access token>

On Windows, using PowerShell:

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

Test your connection

Before running a full scan, verify that your token works by opening a cnspec shell:

cnspec shell github org <ORG_NAME>

cnspec> github.organization.name
github.organization.name: "your-org-name"

If you see your organization name, cnspec is connected and ready to scan.

Scan GitHub organizations and repos

Scan an organization and all its repos

To scan the configuration of your GitHub organization and all repos within it:

cnspec scan github org <ORG_NAME>

Scan only the organization (not its repos)

To scan only your GitHub organization's settings without scanning individual repos, use the --discover organization flag:

cnspec scan github org <ORG_NAME> --discover organization

Scan a single repo

To scan the configuration of one GitHub repo:

cnspec scan github repo <ORG_NAME/REPO_NAME>

Scan specific repos in an organization

You can select which repos to scan within an organization. To scan only the specified repos (without scanning org-level settings), add the --discover repos flag:

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

To scan the specified repos and the organization's settings, omit the --discover flag:

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

Use an inventory file to scan specific repos

If you have a long list of repos to scan, use a Mondoo inventory file instead of listing them on the command line. Create a file named github-inventory.yml:

spec:
  assets:
    - connections:
        - type: github
          options:
            organization: <ORG>
            repos: <REPO1>,<REPO2>
            repos-exclude: <REPO3>,<REPO4>
          discover:
            targets:
              - auto

Set repos to the repos you want to include. Set repos-exclude to any repos you want to skip (leave it empty to include all specified repos).

Then run the scan using the inventory file:

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

Scan a GitHub Enterprise Server instance

By default, cnspec connects to github.com. To scan a GitHub Enterprise Server instance, set the GITHUB_URL environment variable:

export GITHUB_URL=https://github.example.com
cnspec scan github org <ORG_NAME>

Understand scan output

When a scan completes, cnspec prints a summary of all the checks it ran, grouped by policy. Each check shows a pass or fail result. For example:

✓ Pass:  Ensure two-factor authentication is required for all members
✕ Fail:  Ensure the organization domain is verified
✓ Pass:  Ensure default repository permissions are set to read

At the end of the output, cnspec shows a risk score from 0 (no risk) to 100 (highest risk). Failed checks include remediation guidance to help you fix issues.

By default, cnspec applies the Mondoo GitHub Security policy, which covers organization settings, two-factor authentication, branch protection, default permissions, and more. You can also create your own policies or specify a particular policy bundle with --policy-bundle.

Example checks

You can interactively explore and test checks using the cnspec shell. To open a shell connected to your GitHub organization:

cnspec shell github org <ORG_NAME>

Below are some example checks you can run from the shell.

Ensure two-factor authentication is enabled

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

Ensure the organization domain is verified

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

Ensure default permissions are set to read

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

Ensure the default branch has branch protection

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

Ensure members cannot fork private repositories

cnspec> github.organization.membersCanForkPrivateRepos == false
[ok] value: false

Ensure the repository has a security policy

cnspec> github.repository.securityFile != null
[ok] value: github.file name="SECURITY.md"

Continuously scan your fleet

To move beyond one-off scans, set up a GitHub integration in Mondoo Platform. You get continuous monitoring across your GitHub organizations and repos, a dashboard to track security posture over time, and integration with ticketing systems to manage remediation.

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.