
github-inspector
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-suiteRun it inside Claude Code after adding the marketplace with /plugin marketplace add GRCEngClub/claude-grc-engineering.
Contents
Discovered from sourceSkills 1
github-inspector expert
You are the interpretation layer between raw GitHub configuration data and compliance frameworks. Your job is to:
- Understand what each github-inspector check evaluates and why it matters for compliance.
- Interpret failure modes correctly — distinguish "this is genuinely non-compliant" from "we couldn't tell."
- 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_eventsneeded for code scanning,admin:repooradmin:orgfor 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:
-
If Tier 1 has
CHG-02failures 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. -
If
MON-01fails on private repos: they need GitHub Advanced Security (paid) for private repos; public repos get secret scanning for free. Explain the licensing implication. -
If
IAO-04fails broadly: suggest a CodeQL GitHub Action template PR that can be opened across all repos viagh workflowor 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
zizmororactionlint). - 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 ownorg:<name>— all repos in an org you're a member ofrepo:<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 ID | Check | Typical severity |
|---|---|---|
CHG-02 — Configuration Change Control | Default branch has protection with required reviews | high if missing |
CHG-02.1 — Change Approval | Required status checks configured | medium |
IAO-04 — Secure Coding | CodeQL / code scanning enabled | medium |
MON-01 — Continuous Monitoring | Secret scanning enabled | high |
MON-01.4 — Dependency monitoring | Dependabot alerts enabled | medium |
TDA-01 — Third-party Risk | Outside collaborators with admin access | medium |
IAC-02 — Authentication | Deploy keys rotated and scoped read-only | medium |
GOV-05 — Governance | Repository is not archived without notice | low |
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 written2— 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:setupfirst)
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,ghuses it directly. Otherwise the script honors whatevergh auth loginalready configured.CLAUDE_GRC_CONFIG_DIR— override~/.config/claude-grc.
What it does
-
Check that
ghis onPATH. If not, fail with remediation (brew install ghorapt install gh). -
Run
gh auth statusto verify an active token. -
Run
gh api user --jq .loginto confirm the token actually works. -
Write
~/.config/claude-grc/connectors/github-inspector.yamlwith 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 -
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
ghand 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 gonot-configured—setuphas not been runauth-expired—ghtoken revoked or expiredstale— last run > 7 days ago; consider refreshingno-cache— configured but never run
Exit codes
0— ready or stale2— 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- glbav0.1.0
- grc-auditorv0.1.0
- grc-diagramsv0.1.0
- grc-engineerv0.1.0
- grc-internalv0.1.0
- grc-loopv0.1.0
- grc-portfoliov0.1.0
- grc-reporterv0.1.0
- grc-tprmv0.1.0
- hitrustv0.1.0
- ind-dpdpav0.1.0
- irapv0.1.0
- ismapv0.1.0
- iso27001v0.1.0
- jp-appiv0.1.0
- nist-800-53v0.1.0
- nist-ai-600-1v0.1.0
- nist-ai-rmfv0.1.0
- nist-csf-20v0.1.0
- nydfsv0.1.0
- okta-inspectorv0.1.0
- onepassword-connectorv0.1.0
- oscalv0.1.0
- pbmmv0.1.0