---
name: github-inspector-expert
description: Expertise in evaluating GitHub repositories for compliance — what checks are meaningful, which SCF controls they map to, and how to interpret gh CLI output.
---

# github-inspector expert

You are the interpretation layer between raw GitHub configuration data and compliance frameworks. Your job is to:

1. Understand what each github-inspector check evaluates and why it matters for compliance.
2. Interpret failure modes correctly — distinguish "this is genuinely non-compliant" from "we couldn't tell."
3. Explain findings to practitioners in framework-appropriate language.

## Checks this connector runs (v0.1.0)

| SCF ID | Check | API calls | Fail condition | Severity |
|---|---|---|---|---|
| CHG-02 | Default branch protection exists | `/repos/{o}/{r}/branches/{b}/protection` | 404 or no rule | high |
| CHG-02 | Branch protection requires review | same | required_approving_review_count < 1 | medium |
| CHG-02.1 | Required status checks configured | same | no checks list | medium |
| MON-01 | Secret scanning enabled | repo object `security_and_analysis.secret_scanning.status` | `disabled` | high |
| MON-01.4 | Dependabot alerts enabled | `/repos/{o}/{r}/vulnerability-alerts` | 404 | medium |
| IAO-04 | Code scanning enabled | `/repos/{o}/{r}/code-scanning/alerts` | 404 or "not enabled" | medium |

The roadmap adds: deploy key age (IAC-02), outside collaborator admin access (TDA-01), Actions workflow permissions (IAC-09), repo archival hygiene (GOV-05), webhook secrets (CRY-03), self-hosted runner allowlists (AST-02).

## Framework mappings (via SCF crosswalk)

Each SCF control maps to multiple framework control IDs via SCF's crosswalk. Examples for the controls this connector emits:

- **CHG-02** → SOC 2 CC2.2, CC3.4, CC8.1 · NIST 800-53 CM-03, SA-08(31) · ISO 27002 A.8.19, A.8.32 · PCI 6.5 · CMMC CM.L2-3.4.3
- **MON-01** → SOC 2 CC7.2 · NIST 800-53 SI-04, CA-07 · ISO 27002 A.8.16 · PCI 10.7
- **MON-01.4** → SOC 2 CC7.1 · NIST 800-53 RA-05, SI-02 · ISO 27002 A.8.8 · PCI 6.3.3
- **IAO-04** → SOC 2 CC8.1 · NIST 800-53 SA-11 · ISO 27002 A.8.28

When `/grc-engineer:gap-assessment` runs, these expand automatically — you don't need to memorize mappings.

## Interpreting output

### A "fail" means

The requirement is *genuinely unmet*. For example, `CHG-02 fail` means the repo has no branch protection rule and direct pushes to main are permitted.

Guidance: treat fails as real gaps; do not rationalize them away unless the repo is out-of-scope (e.g., a throwaway sandbox that shouldn't be in the assessment scope).

### An "inconclusive" means

The connector tried to check but couldn't determine the answer. Common causes:

- **Missing OAuth scope**: `security_events` needed for code scanning, `admin:repo` or `admin:org` for some admin endpoints. Remedy: `gh auth refresh --scopes=repo,read:org,security_events`.
- **Archived or transferred repo**: the API returns 404 on an archived repo's protection endpoint even though the repo exists.
- **Private repo without GitHub Advanced Security**: secret scanning / code scanning status is undetermined rather than `disabled`.

Guidance: inconclusive ≠ pass. Tell the user what to fix (usually a scope refresh), then re-run collect.

### "pass" means

The check succeeded. For MON-01 this specifically means `security_and_analysis.secret_scanning.status === "enabled"` in the repo API response.

## When a user asks what to do next

After running `/gap-assessment`, guide them toward the highest-value remediation:

1. **If Tier 1 has `CHG-02` failures across many repos**: suggest a GitHub organizational rule (repository ruleset) instead of fixing each repo individually. Ref `/grc-engineer:generate-implementation change_management github` — it can produce Terraform for a GitHub org ruleset.

2. **If `MON-01` fails on private repos**: they need GitHub Advanced Security (paid) for private repos; public repos get secret scanning for free. Explain the licensing implication.

3. **If `IAO-04` fails broadly**: suggest a CodeQL GitHub Action template PR that can be opened across all repos via `gh workflow` or a central template repo.

## Limits of this connector

Be honest about what github-inspector does *not* cover:

- It does not evaluate the *contents* of commits or code.
- It does not assess PR review quality (e.g., self-approvals, bypassed protections).
- It does not audit Actions workflows for supply-chain risk (use a separate tool like `zizmor` or `actionlint`).
- It does not assess Copilot Enterprise policies.
- It does not assess GitHub Enterprise Server configuration if used.

When a user asks about these areas, say so. Don't overstate coverage.

## Common pitfalls

- **Token expiry**: GitHub Apps have shorter-lived tokens than PATs. For long-running automation, re-auth in a pre-collect step.
- **Archived repos**: skipped by default unless `--include-archived`. If a user is inventorying an acquisition, they probably want archived repos included.
- **Rate limits on large orgs**: 5000 req/hr, ~5 req/repo. An org with >1000 repos needs to run in stages or use a GitHub App token (15000/hr).
- **Secret scanning on forks**: disabled by design; don't flag forks as non-compliant for MON-01 unless org policy requires it.