mondoo-github-best-practices.mql.yaml

# Copyright (c) Mondoo, Inc.
# SPDX-License-Identifier: BUSL-1.1

policies:
  - uid: mondoo-github-repository-best-practices
    name: GitHub Repository Best Practices
    version: 1.1.0
    license: BUSL-1.1
    tags:
      mondoo.com/category: best-practices
      mondoo.com/platform: github
    authors:
      - name: Mondoo, Inc
        email: hello@mondoo.com
    docs:
      desc: |
        # Overview

        GitHub Repository Best Practices by Mondoo provides assessments of public and private GitHub repositories to ensure a minimum recommended operational best practices.

        ## About remote scanning

        Remote scans with cnspec provide on demand security assessments of infrastructure and services without the need to install any agents or integrations. cnspec comes with a growing list of providers to connect and scan local and remote targets.

        A complete list of providers can be found by running this command:

        ```bash
        cnspec scan --help
        ```

        ### cnspec GitHub provider

        This policy uses the `github` provider to authenticate with GitHub's API in order to remotely scan GitHub repositories. Additional information on the `github` provider can be found by running this command:

        ```bash
        cnspec scan github --help
        ```

        ## Configuring the GitHub provider

        The `github` provider for cnspec requires a GitHub personal access token to authenticate with GitHub's API. The personal access token is required regardless of whether you are scanning a public or a private repository. Access to private repositories is determined by the level of access the token cnspec is configured with when it runs.

        ### Create a personal access token

        To create a read-only personal access token, see [Creating a personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) on GitHub's documentation site.

        ### Configure a GITHUB_TOKEN environment variable

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

        #### Linux / macOS

        ```bash
        export GITHUB_TOKEN=<your personal access token>
        ```

        #### Windows

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

        ## Scanning GitHub repositories

        To scan the configuration of a GitHub repository:

        ```bash
        cnspec scan github repo <ORG_NAME/REPO_NAME>
        ```

        ## Join the community!

        Our goal is to build policies that are simple to deploy, accurate, and actionable.

        If you have any suggestions for how to improve this policy, or if you need support, [join the community](https://github.com/orgs/mondoohq/discussions) in GitHub Discussions.
    groups:
      - title: GitHub Repo
        filters: |
          asset.platform == "github-repo"
        checks:
          - uid: mondoo-github-repository-best-practices-code-of-conduct
          - uid: mondoo-github-repository-best-practices-include-authors
          - uid: mondoo-github-repository-best-practices-license
          - uid: mondoo-github-repository-best-practices-readme-getting-started
          - uid: mondoo-github-repository-best-practices-support-resources
    scoring_system: highest impact
queries:
  - uid: mondoo-github-repository-best-practices-support-resources
    title: Ensure repository has a support policy
    impact: 30
    mql: |
      // if a .github repo exists, then check if the SUPPORT.md is there
      if ( github.organization.repositories.one(name == ".github") ) {
        github.organization.repositories.where( name == ".github").all(
          files.one( name.downcase == "support.md")
        ) || github.repository.files.one( name.downcase == "support.md")
      } else {
          github.repository.files.one( name.downcase == "support.md")
      }
    docs:
      desc: |
        GitHub repositories should include a SUPPORT.md file to let people know how to get help with the project.

        To direct people to specific support resources, you can add a SUPPORT.md file to your repository's root, docs, or .github directory. When someone creates an issue in your repository, they will see a link to your project's SUPPORT.md file.
      remediation: ""
    refs:
      - url: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-support-resources-to-your-project
        title: Adding support resources to your project
  - uid: mondoo-github-repository-best-practices-code-of-conduct
    title: Ensure repository has a CODE_OF_CONDUCT.md policy
    impact: 30
    mql: |
      // if a .github repo exists, then check if the CODE_OF_CONDUCT.md is there
      if ( github.organization.repositories.one(name == ".github") ) {
        github.organization.repositories.where( name == ".github").all(
          files.one( name.downcase == "code_of_conduct.md")
        ) || github.repository.files.one( name.downcase == "code_of_conduct.md")
      } else {
        github.repository.files.one( name.downcase == "code_of_conduct.md")
      }
    docs:
      desc: |
        Open source code repositories should include a CODE_OF_CONDUCT.md. Including a CODE_OF_CONDUCT.md helps to clarify the project's values and principles.

        You can add a CODE_OF_CONDUCT.md file to your repository's root, docs, or .github directory.
      audit: |
        __cnspec shell__

        1. Open a terminal
        2. Connect cnspec shell to GitHub  `cnspec shell github repo <org/repo_name> --token $GITHUB_TOKEN`
        3. Run this query:

           ```mql
           github.repository.files.where( name.downcase == "code_of_conduct.md")
           ```
      remediation: |
        See [Adding a CODE_OF_CONDUCT.md to your project](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project) on the GitHub docs site.
    refs:
      - url: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project
        title: Adding a CODE_OF_CONDUCT.md to your project
  - uid: mondoo-github-repository-best-practices-include-authors
    title: Ensure the README.md includes authors
    impact: 20
    mql: |
      github.repository.files.where(name.downcase  == "readme.md") {
        content == /Authors/i
      }
    docs:
      desc: |
        Including the authors in the README.md provides transparency to the users looking to use the project in their environments.
      audit: |
        __cnspec shell__

        1. Open a terminal
        2. Connect cnspec shell to GitHub  `cnspec shell github repo <org/repo_name> --token $GITHUB_TOKEN`
        3. Run this query:

           ```mql
           github.repository.files.where( name.downcase == "README.md") { content }
           ```
      remediation: |
        Update the `README.md` with information about the project's authors.
  - uid: mondoo-github-repository-best-practices-readme-getting-started
    title: Ensure the README.md includes getting started guide
    impact: 30
    mql: |
      github.repository.files.where(name.downcase  == "readme.md") {
        content == /Getting started/i
      }
    docs:
      desc: |
        This check ensures the repository README file contains a getting started guide.
      remediation: |
        Update the repository README file with a section titled "Getting Started" for your users.
  - uid: mondoo-github-repository-best-practices-license
    title: Ensure repository declares a license
    impact: 30
    mql: github.repository.files.one( name == /LICENSE/ )
    docs:
      desc: |
        Check tries to determine if the project has published a license. It works by checking standard locations for a file named according to common license conventions.

        A license can give users information about how the source code may or may not be used. The lack of a license will impede any kind of security review or audit and creates a legal risk for potential users.
      audit: |
        __cnspec shell__

        1. Open a terminal
        2. Connect cnspec shell to GitHub  `cnspec shell github repo <org/repo_name> --token $GITHUB_TOKEN`
        3. Run this query:

           ```mql
           github.repository.files.where( name == /LICENSE/ )
           ```
      remediation: |
        See [Adding a license to a repository](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository) on the GitHub documentation site.
    refs:
      - url: https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository
        title: GitHub Docs - Adding a security policy to your repository