feat: add GitHub REST connection infrastructure (CIS GH PR 1 of 2)

[thetechgy]

📑 Description

Adds the connection layer needed to run GitHub Enterprise Cloud security checks against the GitHub REST API. This is the first of two PRs that bring the CIS GitHub Enterprise Cloud Benchmark v1.2.0 (org-level controls) into Maester. No CIS tests ship in this PR — the consuming Test-MtCisGh* helpers, their .md companions, Pester tests, and TestSettings entries land in PR 2 so each PR stays focused on a single type of change.

What this PR introduces:

• Connect-MtGitHub (public) — establishes a session against api.github.com or a GHE.com EMU host, with token resolution via -Token (SecureString), MAESTER_GITHUB_TOKEN, or GH_TOKEN. Validates the PAT with GET /user and probes org reachability with GET /orgs/{org} plus a membership check. Connection success means the token works and the org is reachable; per-control field visibility is validated by each helper in PR 2 so a partially-scoped token still produces useful skip messages instead of a hard failure at connect time.
• Disconnect-MtGitHub (public) and updated Disconnect-Maester — clears GitHubConnection, GitHubAuthHeader, and GitHubCache on disconnect (and on reconnect, to prevent cross-org cache bleed).
• Invoke-MtGitHubRequest (internal) — authenticated GET wrapper with per-session response caching, opt-in -Paginate (Link: rel="next" follow with per_page=100), and rate-limit detection on both success and error responses. Built on Invoke-WebRequest + ConvertFrom-Json for PowerShell 5.1 compatibility (Invoke-RestMethod -ResponseHeadersVariable is 7+ only).
• Internal helpers — Get-MtGitHubErrorStatusCode, Get-MtGitHubErrorMessage, Get-MtGitHubResponseHeaderValue (cross-version WebHeaderCollection vs. PS7 Dictionary<string,string[]> access with case-insensitive lookup), and Get-MtGitHubRateLimitMessage (covers primary rate limits, secondary/abuse-detection responses including the body-wording fallback when GitHub omits retry-after).
• Test-MtConnection — adds a GitHub service region. -Service All does not auto-include GitHub, so existing users running Connect-Maester without a GitHub PAT see no behavior change.
• Add-MtTestResultDetail and Get-MtSkippedReason — new NotConnectedGitHub skip reason. Reserved strictly for the truly-not-connected case; all other failures (no token, invalid token, org access denied, missing required field on a 200 response, 403/429 at call time) use Custom with a specific, GitHub-API-message-preserving reason so the report tells you what to fix.
• tests/maester-config.json — three new GlobalSettings keys (GitHubOrganization, GitHubApiBaseUri, GitHubApiVersion). GitHubEnterpriseSlug is intentionally not added until enterprise-level endpoints are implemented in a later phase.
• Maester.psd1 — exports Connect-MtGitHub and Disconnect-MtGitHub. Internal helpers and Invoke-MtGitHubRequest are not exported; the visibility of the request wrapper can be revisited in PR 2 if maintainers prefer it public.

A few design points worth flagging for review:

• ApiBaseUri allowlist. Only api.github.com and api.<subdomain>.ghe.com are accepted, with no path/query/fragment and only the default port. Rejected URIs short-circuit before any web request runs, so a misconfigured or attacker-supplied host can't receive the PAT.
• Probe error classification. /user, /orgs/{org}, and the membership probe each distinguish transport failures (ApiBaseUriFailed), 5xx (ApiUnavailable), token problems (TokenInvalid), org access (OrgAccessFailed), and rate limits, so the resulting FailureReason drives a useful skip message in PR 2's helpers instead of collapsing to a single "couldn't connect" string.
• Token storage. The bearer token lives on $__MtSession.GitHubAuthHeader only; the connection object on $__MtSession.GitHubConnection exposes login, plan, org, ApiBaseUri, and ApiVersion but not the secret. Get-MtSession and Test-MtConnection -Details redact accordingly.
• EMU 2FA caveat (relevant to PR 2). In EMU, MFA enforcement is at the IdP level; two_factor_requirement_enabled reflects the GitHub org setting only. This will be documented on the corresponding Test-MtCisGhOrgTwoFactorRequired.md companion when PR 2 lands.

✅ Checks

• My pull request adheres to the code style of this project.
• My code requires changes to the documentation.
• I have updated the documentation as required.
• The build and unit tests pass after running /powershell/tests/pester.ps1 locally.

ℹ️ Additional Information

• Backward compatibility. No existing public surface changes. Test-MtConnection -Service All still completes without a GitHub connection. Connect-Maester is unchanged — GitHub requires explicit Connect-MtGitHub, since Maester-style GitHub testing is org-scoped and there is no sensible auto-detection path for a PAT.
• PowerShell 5.1. All new code is exercised under PS 5.1 in addition to PS 7.x. Header parsing, error classification, and pagination all use cross-version-safe APIs.
• Test coverage in this PR. New unit tests cover Connect-MtGitHub (token resolution, URI allowlist, all probe error classifications, membership states, rate-limit detection, redaction), Disconnect-MtGitHub, Disconnect-Maester (GitHub teardown via try/finally), Invoke-MtGitHubRequest (caching, pagination, rate-limit headers on success and error paths, empty-array pages, cross-origin Link rejection), Get-MtGitHubResponseHeaderValue, Get-MtGitHubRateLimitMessage, Test-MtConnection, Get-MtSession, and Clear-ModuleVariable.

---

How to Contribute

🏗️ Read our full contributing guide for the Maester project.
🧪 We also have additional instructions and a checklist for creating tests.

Join us at the Maester repository discussions or Entra Discord for more help and conversations!
While you wait for a review, why not spread some Maester love on social media? Thank you! 💖

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[SamErde]

Thanks, @thetechgy! I'm a bit swamped right now, but look forward to testing this!

[Copilot]

Pull request overview

This PR introduces the GitHub REST API connection infrastructure that will be consumed by upcoming CIS GitHub Enterprise Cloud Benchmark tests in PR 2. It establishes a session-based GitHub API client with PAT authentication, validation probes, response caching, pagination, rate-limit detection, and integration with existing Maester connection/session management.

Changes:

• Adds Connect-MtGitHub/Disconnect-MtGitHub public cmdlets plus several internal helpers (Invoke-MtGitHubRequest, error/header/rate-limit utilities) with strict URI allowlisting and detailed failure classification.
• Extends Test-MtConnection, Disconnect-Maester, Add-MtTestResultDetail, Get-MtSession, and Clear-ModuleVariable to be GitHub-aware (with PAT redaction and lifecycle handling).
• Adds three GitHub-related GlobalSettings keys to maester-config.json and exports the new public functions in the manifest/format file.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/maester-config.json	Adds GitHubOrganization/ApiBaseUri/ApiVersion global settings
powershell/Maester.psd1	Exports Connect-MtGitHub and Disconnect-MtGitHub
powershell/Maester.psm1	Adds GitHubCache to $__MtSession
powershell/Maester.Format.ps1xml	Adds GitHub block to Maester.Connections list view
powershell/public/core/Connect-MtGitHub.ps1	New: PAT-based GitHub connection with four probes
powershell/public/core/Disconnect-MtGitHub.ps1	New: Clears GitHub session keys idempotently
powershell/public/core/Test-MtConnection.ps1	Adds GitHub service region with NotCalled sentinel
powershell/public/core/Get-MtSession.ps1	Redacts GitHubAuthHeader Authorization on output
powershell/public/Disconnect-Maester.ps1	Routes GitHub cleanup via try/finally for non-Graph aliases
powershell/public/Add-MtTestResultDetail.ps1	Adds NotConnectedGitHub skipped reason
powershell/internal/Invoke-MtGitHubRequest.ps1	New: GET wrapper with cache, pagination, rate-limit detection
powershell/internal/Get-MtGitHubErrorStatusCode.ps1	New: Extracts HTTP status from ErrorRecord
powershell/internal/Get-MtGitHubErrorMessage.ps1	New: Extracts message from JSON ErrorDetails or Exception
powershell/internal/Get-MtGitHubResponseHeaderValue.ps1	New: Cross-version case-insensitive header lookup
powershell/internal/Get-MtGitHubRateLimitMessage.ps1	New: Classifies 403/429 rate-limit responses
powershell/internal/Get-MtSkippedReason.ps1	Adds NotConnectedGitHub explanation
powershell/internal/Clear-ModuleVariable.ps1	Resets GitHubCache only; preserves connection across runs
powershell/tests/functions/*.Tests.ps1 (8 files)	Pester coverage for all new code paths

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.