GRC connector for GitHub: branch protection, secret scanning, Dependabot, code scanning → v1 finding contract

version
0.1.0
GitHub stars
436

Install

/plugin install github-inspector@grc-engineering-suite

Run it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.

Contents

Discovered from source

Skills 1

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 IDCheckAPI callsFail conditionSeverity
CHG-02Default branch protection exists/repos/{o}/{r}/branches/{b}/protection404 or no rulehigh
CHG-02Branch protection requires reviewsamerequired_approving_review_count < 1medium
CHG-02.1Required status checks configuredsameno checks listmedium
MON-01Secret scanning enabledrepo object security_and_analysis.secret_scanning.statusdisabledhigh
MON-01.4Dependabot alerts enabled/repos/{o}/{r}/vulnerability-alerts404medium
IAO-04Code scanning enabled/repos/{o}/{r}/code-scanning/alerts404 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.

Commands 3

/github-inspector:collect

Scans GitHub repositories in the configured scope and emits one Finding document per repository.

How to run

node plugins/connectors/github-inspector/scripts/collect.js [options]

Arguments

  • --scope=<value> — repository scope. Overrides the config default.
    • @me — all repos you own
    • org:<name> — all repos in an org you're a member of
    • repo:<owner>/<name> — single repo
  • --refresh — ignore cache; always re-query GitHub
  • --output=<fmt> — silent (default for CLI piping) | summary (one-line summary) | json
  • --limit=<n> — cap the number of repos scanned (useful for testing)
  • --concurrency=<n> — parallel API calls (default 4, max 8 to respect rate limits)
  • --quiet — no stderr progress

What it evaluates

For each repository in scope, the connector emits evaluations against SCF controls:

SCF IDCheckTypical severity
CHG-02 — Configuration Change ControlDefault branch has protection with required reviewshigh if missing
CHG-02.1 — Change ApprovalRequired status checks configuredmedium
IAO-04 — Secure CodingCodeQL / code scanning enabledmedium
MON-01 — Continuous MonitoringSecret scanning enabledhigh
MON-01.4 — Dependency monitoringDependabot alerts enabledmedium
TDA-01 — Third-party RiskOutside collaborators with admin accessmedium
IAC-02 — AuthenticationDeploy keys rotated and scoped read-onlymedium
GOV-05 — GovernanceRepository is not archived without noticelow

More checks land as the connector matures; see the SKILL for the authoritative list.

Output

  • Writes ~/.cache/claude-grc/findings/github-inspector/<run_id>.json — one JSON file per run containing an array of Findings (one per repository).

  • Appends a run manifest to ~/.cache/claude-grc/runs.log.

  • Prints a one-line summary to stdout unless --quiet:

    github-inspector: 127 resources, 512 evaluations, 38 findings (6 high, 15 medium, 17 low).
    

Exit codes

  • 0 — success, cache written
  • 2 — auth failure (re-run /github-inspector:setup)
  • 3 — rate-limited (the connector waited but still hit the ceiling; retry later)
  • 4 — partial result (some repos unreadable; a report is still written)
  • 5 — config missing (run /github-inspector:setup first)

Rate limits

GitHub's REST API gives you 5,000 requests/hour authenticated. The connector budgets ~5 requests per repo and reports remaining headroom in the Finding's metadata.rate_limit_remaining.

Examples

# Personal account
/github-inspector:collect --scope=@me

# Whole org
/github-inspector:collect --scope=org:acme --concurrency=6

# Single repo for testing
/github-inspector:collect --scope=repo:acme/prod-api

CI/CD usage

gh auth login --with-token < $GH_TOKEN_FILE
node plugins/connectors/github-inspector/scripts/collect.js --scope=org:acme --quiet
node plugins/grc-engineer/scripts/gap-assessment.js SOC2 --sources=github-inspector --output=sarif --quiet > gap.sarif

/github-inspector:setup

Prepares the github-inspector connector. Confirms gh CLI is installed and authenticated, writes ~/.config/claude-grc/connectors/github-inspector.yaml, and runs a read-only health check.

How to run

bash plugins/connectors/github-inspector/scripts/setup.sh

The script exits 0 on success, 2 on missing auth, 5 on missing gh binary.

Arguments

None. Reads from the environment:

  • GH_TOKEN — optional; if set, gh uses it directly. Otherwise the script honors whatever gh auth login already configured.
  • CLAUDE_GRC_CONFIG_DIR — override ~/.config/claude-grc.

What it does

  1. Check that gh is on PATH. If not, fail with remediation (brew install gh or apt install gh).

  2. Run gh auth status to verify an active token.

  3. Run gh api user --jq .login to confirm the token actually works.

  4. Write ~/.config/claude-grc/connectors/github-inspector.yaml with defaults:

    version: 1
    source: github-inspector
    source_version: "0.1.0"
    authenticated_as: <your-login>
    defaults:
      scope: "@me"         # "@me" | "org:<name>" | "repo:<owner>/<name>"
      include_archived: false
      include_forks: false
    
  5. Print a one-line success message and a reminder of next steps.

Typical output

github-inspector:setup ✓
  gh version:       2.59.0
  authenticated as: octocat
  config written:   ~/.config/claude-grc/connectors/github-inspector.yaml

Next: /github-inspector:collect --scope=@me

Failure modes

  • gh not installed: exit 5. Install gh and re-run.
  • gh not authenticated: exit 2. Run gh auth login, then re-run.
  • Token has no user scope: exit 2. Re-login with gh auth login --scopes=repo,read:org,read:packages.

Safe to re-run

Yes. Running again re-validates auth and rewrites the config. It does not destroy cached findings.

/github-inspector:status

Non-destructive health check. Shows whether the connector is configured, whether credentials still work, and when it last produced findings.

How to run

bash plugins/connectors/github-inspector/scripts/status.sh

Output

github-inspector
  status:         ready
  gh:             /usr/local/bin/gh v2.59.0
  auth:           valid (octocat, scopes: repo,read:org)
  config:         ~/.config/claude-grc/connectors/github-inspector.yaml
  scope:          @me
  last run:       2 hours ago (run_id 20260413-a1b2c3d4)
  cached findings: 127 resources, 512 evaluations
  rate limit:     4,872/5000 remaining

Status values

  • ready — all systems go
  • not-configured — setup has not been run
  • auth-expired — gh token revoked or expired
  • stale — last run > 7 days ago; consider refreshing
  • no-cache — configured but never run

Exit codes

  • 0 — ready or stale
  • 2 — auth-expired or not-configured

Sponsors

Details

Marketplace
GRCEngClub/claude-grc-engineering
Source
plugins/connectors/github-inspector
Category
Community

More from GRCEngClub/claude-grc-engineering

All 70