Proposal: Add GitHub Enterprise Cloud CIS Benchmark tests to Maester

[thetechgy]

Summary

I’d like to work on adding Maester support for GitHub Enterprise Cloud Enterprise Managed Users (EMU) security posture checks aligned to the CIS GitHub Enterprise Cloud Benchmark v1.2.0.

Before opening a PR, I wanted to confirm that this direction fits Maester’s scope and get maintainer feedback on a few design decisions that are not already covered by the existing contribution guidance.

Goal

Add read-only Maester tests for GitHub Enterprise Cloud organization-level security settings, starting with a small set of CIS-mapped controls that can be validated through documented GitHub REST API endpoints.

The initial target is GitHub Enterprise Cloud EMU environments, but the implementation should also work for standard GitHub Enterprise Cloud organizations where the same REST API fields are available.

Proposed contribution strategy

I’m proposing two small PRs rather than one large PR.

PR 1 — GitHub connection foundation

Add GitHub connection infrastructure:

• Connect-MtGitHub
• GitHub session/cache state
• GitHub support in Test-MtConnection
• GitHub-specific skipped reason handling
• Internal GitHub REST helper, tentatively Invoke-MtGitHubRequest
• maester-config.json global settings:
  • GitHubOrganization
  • GitHubApiBaseUri
  • GitHubApiVersion

The request helper would default to internal/private unless maintainers prefer exposing it for custom test authors.

PR 2 — Initial CIS GitHub controls

Add the first set of organization-level CIS GitHub Enterprise Cloud checks, with one helper .ps1, one companion .md, and one Pester test file per control, following existing Maester CIS conventions.

Initial candidate controls:

CIS ID	Check	API endpoint
CIS.GH.1.1.9	Require 2FA for organization members	GET /orgs/{org}
CIS.GH.1.1.5	Default Actions workflow token permission is read-only	GET /orgs/{org}/actions/permissions/workflow
CIS.GH.1.1.6	Actions cannot approve pull requests	GET /orgs/{org}/actions/permissions/workflow
CIS.GH.2.1.2	Actions restricted to selected/local actions	GET /orgs/{org}/actions/permissions
CIS.GH.1.2.1	Default repository permission is None or Read	GET /orgs/{org}
CIS.GH.1.3.2	Organization owner count between 2 and 4	GET /orgs/{org}/members?role=admin
CIS.GH.1.1.2	Members cannot create public repositories	GET /orgs/{org}

Candidate after confirming exact CIS wording:

CIS ID	Check	API endpoint
CIS.GH.2.1.1	Fork PR workflows must not receive secrets	GET /orgs/{org}/actions/permissions/fork-pr-workflows-private-repos

Proposed implementation principles

• Read-only and non-destructive
• Compatible with GitHub Enterprise Cloud EMU
• Uses documented GitHub REST API endpoints only
• No GitHub PowerShell module dependency
• PowerShell 5.1 compatible
• Internal request wrapper uses Invoke-WebRequest + ConvertFrom-Json
• Explicit pagination only where needed
• Per-session cache cleared on reconnect and module state reset
• Required field presence validated in each helper because GET /orgs/{org} can return partial org data depending on token visibility
• GitHub-specific Custom skipped messages for 403, rate limit, missing field, and token visibility issues

Authentication model

Initial implementation would support PAT-based auth:

• Classic PAT: admin:org
• Fine-grained PAT: expected to require organization Administration: read and Members: read, but this needs live validation
• GitHub App authentication would be a future enhancement

Maintainer questions

1. Is GitHub Enterprise Cloud / EMU CIS coverage considered in scope for Maester?
2. Is Connect-MtGitHub an acceptable new public connection command?
3. Should Invoke-MtGitHubRequest remain internal, or would you prefer it public for custom test authors?
4. Would you prefer PR 1 to be foundation-only, or should it include one minimal GitHub CIS control as the first consumer?
5. Is CIS.GH.* an acceptable test/tag namespace for GitHub CIS Benchmark controls?
6. If the CIS benchmark does not provide severity values that map cleanly to Maester, how would you prefer severity to be assigned?

I’m happy to keep the first PR intentionally small and adjust the design before implementing the CIS controls.

[thetechgy]

#1756 has been submitted to cover what was listed under PR 1 here
While that's pending review, I'm moving on to PR 2

[SamErde]

Thanks @thetechgy! We’re grateful for the contribution and would definitely like to see GitHub security coverage in Maester.

I reviewed the proposed design against our existing Maester framework and the Maester Test Expert guidance. The overall direction looks well aligned: a focused connection/infrastructure PR followed by CIS-mapped checks fits our contribution guidance to keep PRs small, discuss larger changes first, and follow existing patterns. The proposed per-control structure also matches the Maester pattern we use for checks: helper .ps1, companion .md, and Pester test file per control, with read-only evaluation, clear skip handling, and documentation-backed remediation.

A few things we’d want to keep consistent as this moves into the CIS GitHub checks:

• The helper functions should return $true, $false, or $null, use the null-check assertion pattern in Pester, and use Add-MtTestResultDetail for actionable output.
• The GitHub connection behavior should align with Connect-Maester and Test-MtConnection instead of introducing new connection patterns.
• CIS.GH.* seems like a reasonable namespace. What do the tags and titles look like in the CIS benchmark itself?
• Keeping Invoke-MtGitHubRequest internal for the first built-in controls is reasonable; if we expect users to author custom GitHub tests, making it public later would align with how Invoke-MtGraphRequest supports custom Microsoft Graph tests.
• For the first CIS test PR, please include tests for the GitHub security checks themselves, not only the connection layer.

Could you also share the public CIS URL you plan to reference for the CIS GitHub Enterprise Cloud Benchmark v1.2.0? I found the general CIS WorkBench benchmark area (https://workbench.cisecurity.org/benchmarks?q=GitHub%20Enterprise%20Cloud), but I didn’t find a stable public benchmark-specific URL yet. We’ll want that reference in the companion markdown/docs for the new Maester tests.

I know you're busy, @merill, but any thoughts? :)