github-sec-inspector — Architecture Specification

1. Overview

GitHub Enterprise Cloud is the most widely adopted platform for source code hosting, collaboration, and DevOps automation. Organizations use it to manage repositories, CI/CD pipelines (GitHub Actions), package registries, code review workflows, and developer access across thousands of contributors.

Misconfigurations at the organization or enterprise level — unenforced SSO, missing two-factor authentication requirements, overly permissive member base permissions, unprotected default branches, disabled security scanning, unrestricted Actions workflows, or unmonitored OAuth/GitHub App integrations — can expose source code, enable supply chain attacks, leak secrets, and undermine the software development lifecycle. Because GitHub is the central nervous system of modern software delivery, its security posture directly determines an organization's exposure to code tampering, credential theft, and insider threats.

github-sec-inspector is an automated compliance inspection tool that connects to a GitHub organization (or enterprise) via the REST API v3 and GraphQL API v4, collects security-relevant configuration data across organization settings, repositories, branch protection, code security features, and access controls, evaluates the configuration against hardened baselines derived from multiple compliance frameworks, and produces actionable reports with framework-specific control mappings.

2. APIs & SDKs

2.1 GitHub REST API v3

Base URL: https://api.github.com

Organization Settings & Members

Endpoint	Method	Purpose
/orgs/{org}	GET	Organization profile, settings, default permissions, 2FA requirement
/orgs/{org}/settings/billing/actions	GET	Actions usage and billing
/orgs/{org}/members	GET	List organization members (with filter, role params)
/orgs/{org}/members/{username}	GET	Check membership status
/orgs/{org}/memberships/{username}	GET	Get membership details (role: member/admin)
/orgs/{org}/outside_collaborators	GET	List outside collaborators across all repos
/orgs/{org}/teams	GET	List all teams
/orgs/{org}/teams/{team_slug}/members	GET	List team members
/orgs/{org}/teams/{team_slug}/repos	GET	List repos accessible to a team
/orgs/{org}/failed_invitations	GET	List failed membership invitations
/orgs/{org}/invitations	GET	List pending invitations
/orgs/{org}/blocks	GET	List blocked users

Security & Access Management

Endpoint	Method	Purpose
/orgs/{org}/security-managers	GET	List security manager teams (deprecated Jan 2026; use Organization Roles)
/orgs/{org}/organization-roles	GET	List organization roles and assignments
/orgs/{org}/credential-authorizations	GET	List SAML SSO credential authorizations for members
/orgs/{org}/installations	GET	List GitHub App installations on the org
/orgs/{org}/hooks	GET	List organization webhooks
/orgs/{org}/hooks/{hook_id}	GET	Get webhook details (config, events, SSL verification)

Audit Log

Endpoint	Method	Purpose
/orgs/{org}/audit-log	GET	Query organization audit log events (with phrase, include, after params)
/enterprises/{enterprise}/audit-log	GET	Enterprise-level audit log (Enterprise Cloud only)

Code Security (GHAS)

Endpoint	Method	Purpose
/orgs/{org}/code-scanning/alerts	GET	List code scanning alerts across all repos
/orgs/{org}/secret-scanning/alerts	GET	List secret scanning alerts across all repos
/orgs/{org}/dependabot/alerts	GET	List Dependabot alerts across all repos
/orgs/{org}/code-security/configurations	GET	List code security configurations
/repos/{owner}/{repo}/code-scanning/alerts	GET	Repository-level code scanning alerts
/repos/{owner}/{repo}/secret-scanning/alerts	GET	Repository-level secret scanning alerts
/repos/{owner}/{repo}/dependabot/alerts	GET	Repository-level Dependabot alerts
/repos/{owner}/{repo}/vulnerability-alerts	GET	Check if Dependabot alerts are enabled

Repository Settings & Branch Protection

Endpoint	Method	Purpose
/orgs/{org}/repos	GET	List all organization repositories
/repos/{owner}/{repo}	GET	Repository details (visibility, default branch, settings)
/repos/{owner}/{repo}/branches/{branch}/protection	GET	Branch protection rules
/repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews	GET	Required review settings
/repos/{owner}/{repo}/branches/{branch}/protection/required_signatures	GET	Signed commit requirement
/repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks	GET	Required status checks
/repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins	GET	Admin enforcement of protections
/repos/{owner}/{repo}/rulesets	GET	Repository rulesets (newer API replacing branch protection)
/orgs/{org}/rulesets	GET	Organization-level rulesets

Deploy Keys, Secrets, and Actions

Endpoint	Method	Purpose
/repos/{owner}/{repo}/keys	GET	List deploy keys
/repos/{owner}/{repo}/actions/permissions	GET	Actions permissions for a repo
/orgs/{org}/actions/permissions	GET	Actions permissions for the org
/orgs/{org}/actions/permissions/workflow	GET	Default workflow permissions
/orgs/{org}/actions/permissions/selected-actions	GET	Allowed actions configuration
/orgs/{org}/actions/runner-groups	GET	Self-hosted runner groups
/orgs/{org}/actions/runners	GET	List self-hosted runners
/orgs/{org}/actions/secrets	GET	List organization-level Actions secrets
/orgs/{org}/dependabot/secrets	GET	List organization-level Dependabot secrets
/orgs/{org}/packages	GET	List packages in the organization registry

OAuth and GitHub Apps

Endpoint	Method	Purpose
/orgs/{org}/installations	GET	GitHub App installations
/app/installations/{installation_id}	GET	Installation details and permissions
/orgs/{org}/credential-authorizations	GET	OAuth credential authorizations (SAML SSO orgs)

2.2 GitHub GraphQL API v4

Base URL: https://api.github.com/graphql

Organization-Level Queries

# SAML Identity Provider configuration
query {
  organization(login: "org-name") {
    samlIdentityProvider {
      ssoUrl
      issuer
      digestMethod
      signatureMethod
      externalIdentities(first: 100) {
        edges {
          node {
            samlIdentity { nameId }
            scimIdentity { username }
            user { login, email }
          }
        }
      }
    }
  }
}

# IP Allow List entries
query {
  organization(login: "org-name") {
    ipAllowListEnabledSetting
    ipAllowListForInstalledAppsEnabledSetting
    ipAllowListEntries(first: 100) {
      nodes {
        allowListValue
        isActive
        name
        createdAt
      }
    }
  }
}

# Enterprise Managed Users (EMU) detection
query {
  organization(login: "org-name") {
    membersWithRole(first: 1) {
      nodes {
        login
        enterpriseUserAccount {
          login
          enterprise { slug }
        }
      }
    }
  }
}

# Repository security features
query {
  organization(login: "org-name") {
    repositories(first: 100) {
      nodes {
        name
        isPrivate
        defaultBranchRef {
          name
          branchProtectionRule {
            requiresApprovingReviews
            requiredApprovingReviewCount
            requiresCodeOwnerReviews
            requiresCommitSignatures
            requiresStatusChecks
            requiresLinearHistory
            dismissesStaleReviews
            restrictsReviewDismissals
            isAdminEnforced
            allowsForcePushes
            allowsDeletions
          }
        }
        hasVulnerabilityAlertsEnabled
        securityPolicyUrl
        deleteBranchOnMerge
        mergeCommitAllowed
        squashMergeAllowed
        rebaseMergeAllowed
      }
    }
  }
}

Enterprise-Level Queries (Enterprise Cloud)

# Enterprise audit log
query {
  enterprise(slug: "enterprise-slug") {
    ownerInfo {
      admins(first: 10) { nodes { login } }
      affiliatedUsersWithTwoFactorDisabled(first: 100) {
        nodes { login, email }
      }
      samlIdentityProvider {
        ssoUrl
        issuer
        externalIdentities(first: 100) {
          nodes {
            samlIdentity { nameId }
            user { login }
          }
        }
      }
    }
  }
}

2.3 SDKs and CLIs

Tool	Language	Package	Notes
go-github	Go	github.com/google/go-github/v68	Google-maintained Go client for GitHub REST API v3
shurcooL/githubv4	Go	github.com/shurcooL/githubv4	Go client for GitHub GraphQL API v4
gh CLI	Go	gh (Homebrew, apt, etc.)	Official GitHub CLI; extensible with extensions
PyGithub	Python	pip install PyGithub	Full-featured Python wrapper for REST API
ghapi	Python	pip install ghapi	Lightweight Python wrapper auto-generated from OpenAPI spec
octokit/rest.js	JS/TS	npm install @octokit/rest	Official JavaScript REST client
octokit/graphql.js	JS/TS	npm install @octokit/graphql	Official JavaScript GraphQL client
octokit.rb	Ruby	gem install octokit	Official Ruby client
Terraform GitHub Provider	HCL	integrations/github	Infrastructure-as-code for GitHub settings

2.4 API Rate Limits

API	Limit	Notes
REST API (authenticated)	5,000 requests/hour	Per PAT or OAuth token
REST API (GitHub App)	5,000 requests/hour per installation	Higher for large orgs
GraphQL API	5,000 points/hour	Cost varies by query complexity
Audit Log REST	1,750 queries/hour per user	Lower rate for audit log queries
Search API	30 requests/minute	Separate rate limit bucket

3. Authentication

3.1 Personal Access Token (Fine-Grained)

export GITHUB_TOKEN="github_pat_..."
export GITHUB_ORG="your-organization"

Fine-grained PATs (recommended) can be scoped to specific repositories and permissions. Required permissions for full audit:

• Organization: read:org, read:audit_log, admin:org (for some settings)
• Repository: read:repo, read:security_events
• Members: read:org

3.2 Personal Access Token (Classic)

export GITHUB_TOKEN="ghp_..."
export GITHUB_ORG="your-organization"

Classic PATs require the following scopes:

• repo — full repository access (needed for branch protection, security alerts)
• admin:org — organization settings, members, teams, webhooks
• read:audit_log — audit log access
• security_events — code scanning and secret scanning alerts
• read:packages — package registry access

3.3 GitHub App Authentication

export GITHUB_APP_ID="12345"
export GITHUB_APP_PRIVATE_KEY_PATH="/path/to/private-key.pem"
export GITHUB_APP_INSTALLATION_ID="67890"
export GITHUB_ORG="your-organization"

GitHub Apps provide the highest rate limits and finest-grained permissions. The app must be installed on the organization with the following permissions:

• Organization: Administration (read), Members (read), Plan (read)
• Repository: Administration (read), Code scanning alerts (read), Dependabot alerts (read), Secret scanning alerts (read), Metadata (read)

3.4 OAuth App (Interactive)

For interactive use or CI/CD systems using OAuth flow. Not recommended for automated inspection; prefer PAT or GitHub App.

3.5 SAML SSO Authorization

In organizations with SAML SSO enabled, tokens must be explicitly authorized for the organization. Classic PATs must be SSO-authorized via GitHub Settings > Developer settings > Personal access tokens > Authorize.

3.6 Environment Variables (github-sec-inspector)

Variable	Required	Description
GITHUB_TOKEN	Yes*	Personal access token (classic or fine-grained)
GITHUB_ORG	Yes	Target organization slug
GITHUB_ENTERPRISE	Optional	Enterprise slug (for enterprise-level checks)
GITHUB_APP_ID	Alt*	GitHub App ID
GITHUB_APP_PRIVATE_KEY_PATH	Alt*	Path to GitHub App private key PEM file
GITHUB_APP_INSTALLATION_ID	Alt*	GitHub App installation ID
GITHUB_API_URL	Optional	API base URL (default: https://api.github.com; set for GHES)
GITHUB_GRAPHQL_URL	Optional	GraphQL URL (default: https://api.github.com/graphql)

*Either GITHUB_TOKEN or all three GITHUB_APP_* variables are required.

4. Security Controls

Identity & Authentication

#	Control	Severity	What Is Checked
1	SAML SSO Enforcement	Critical	Verify SAML SSO is configured and enforced for the organization via GraphQL samlIdentityProvider; check that all members have active SAML identity bindings
2	Two-Factor Authentication Requirement	Critical	Verify two_factor_requirement_enabled is true on the organization; enumerate members without 2FA via /orgs/{org}/members?filter=2fa_disabled
3	Enterprise Managed Users (EMU)	High	Detect whether the organization uses EMU (managed by enterprise IdP); check enterprise user account bindings via GraphQL
4	IP Allow List	High	Via GraphQL, verify ipAllowListEnabledSetting is ENABLED; enumerate allow list entries; check ipAllowListForInstalledAppsEnabledSetting

Organization Permissions & Policies

#	Control	Severity	What Is Checked
5	Member Base Permissions	High	Check default_repository_permission on the org object; flag if set to write or admin (should be read or none)
6	Repository Visibility Defaults	Medium	Check members_can_create_public_repositories; verify members_can_create_private_repositories and members_can_create_internal_repositories policies
7	Fork Policy	Medium	Check members_can_fork_private_repositories; flag if private repo forking is unrestricted
8	Outside Collaborator Policy	High	Enumerate outside collaborators via /orgs/{org}/outside_collaborators; flag excessive external access; check if admin approval is required
9	OAuth App Restrictions	High	Verify OAuth application access policy is set to restricted; check /orgs/{org}/credential-authorizations for unauthorized OAuth apps

Repository & Code Protection

#	Control	Severity	What Is Checked
10	Branch Protection Rules	Critical	For every repo's default branch, verify protection is enabled; check requiresApprovingReviews, isAdminEnforced, allowsForcePushes=false, allowsDeletions=false
11	Required Pull Request Reviews	High	Verify requiredApprovingReviewCount >= 1; check requiresCodeOwnerReviews, dismissesStaleReviews, restrictsReviewDismissals
12	Required Status Checks	High	Verify requiresStatusChecks=true with specific required contexts; flag repos with no CI checks
13	Signed Commit Requirement	Medium	Check requiresCommitSignatures on branch protection; flag repos where unsigned commits are allowed on protected branches
14	Repository Rulesets	Medium	Enumerate org-level and repo-level rulesets; verify they enforce branch protection, tag protection, and push restrictions

Code Security Features (GHAS)

#	Control	Severity	What Is Checked
15	Code Scanning Enabled	High	Verify code scanning (CodeQL or third-party) is configured on all repositories; count open critical/high alerts via /orgs/{org}/code-scanning/alerts
16	Secret Scanning Enabled	Critical	Verify secret scanning is enabled on all repositories; check push protection is enabled; count open alerts via /orgs/{org}/secret-scanning/alerts
17	Dependabot Enabled	High	Verify Dependabot alerts and security updates are enabled; count open critical/high alerts via /orgs/{org}/dependabot/alerts
18	Security Policy	Low	Check each repo has a SECURITY.md or securityPolicyUrl configured

Audit & Monitoring

#	Control	Severity	What Is Checked
19	Audit Log Streaming	High	Verify audit log streaming is configured to an external SIEM; check via enterprise settings or audit log API
20	Webhook Security	High	Audit all organization webhooks; flag webhooks without secret configured, webhooks with insecure_ssl=1, webhooks sending to non-HTTPS URLs

Actions & CI/CD Security

#	Control	Severity	What Is Checked
21	Actions Permissions	High	Check org-level Actions permissions; flag if allowed_actions is all (should be selected or local_only); verify default_workflow_permissions is read not write
22	Runner Group Restrictions	Medium	Audit self-hosted runner groups; flag runners accessible to all repos; verify runner group repository access restrictions
23	Deploy Key Management	Medium	Enumerate deploy keys across all repos; flag keys with write access; flag keys older than 365 days without rotation
24	GitHub App Permissions Audit	High	Enumerate all GitHub App installations; flag apps with excessive permissions (admin access, write to all repos); check for inactive/unused apps
25	Package Registry Access	Medium	Audit package visibility settings; flag packages with public visibility in private organizations; check package access inheritance

5. Compliance Framework Mappings

#	Control	FedRAMP (800-53 r5)	CMMC 2.0	SOC 2 (TSC)	CIS GitHub Benchmark	PCI-DSS 4.0	DISA STIG	IRAP (ISM)	ISMAP
1	SAML SSO Enforcement	IA-2, IA-8	AC.L2-3.1.1	CC6.1	1.1.1	8.3.1	SRG-APP-000148	ISM-1557	5.1.1
2	Two-Factor Authentication	IA-2(1), IA-2(2)	IA.L2-3.5.3	CC6.1	1.1.2	8.4.2	SRG-APP-000149	ISM-1401	5.1.2
3	Enterprise Managed Users	IA-2, IA-5	IA.L2-3.5.1	CC6.1	1.1.3	8.2.1	SRG-APP-000163	ISM-1558	5.1.3
4	IP Allow List	SC-7, AC-17	SC.L2-3.13.1	CC6.1, CC6.6	1.2.1	1.3.1	SRG-APP-000142	ISM-1416	5.1.4
5	Member Base Permissions	AC-3, AC-6	AC.L2-3.1.5	CC6.3	1.3.1	7.2.1	SRG-APP-000033	ISM-1508	5.2.1
6	Repository Visibility Defaults	AC-3, AC-22	AC.L2-3.1.22	CC6.1	1.3.2	7.2.2	SRG-APP-000211	ISM-0264	5.2.2
7	Fork Policy	AC-3, AC-4	AC.L2-3.1.3	CC6.1	1.3.3	7.2.3	SRG-APP-000033	ISM-0405	5.2.3
8	Outside Collaborator Policy	AC-2, AC-6(5)	AC.L2-3.1.6	CC6.2, CC6.3	1.3.4	7.2.4	SRG-APP-000340	ISM-1509	5.2.4
9	OAuth App Restrictions	AC-3, AC-6	AC.L2-3.1.5	CC6.6, CC6.8	1.4.1	6.3.2	SRG-APP-000386	ISM-1490	5.2.5
10	Branch Protection Rules	CM-3, SI-7	CM.L2-3.4.5	CC8.1	2.1.1	6.5.1	SRG-APP-000133	ISM-1072	5.3.1
11	Required Pull Request Reviews	CM-3, CM-5	CM.L2-3.4.5	CC8.1	2.1.2	6.5.2	SRG-APP-000381	ISM-1525	5.3.2
12	Required Status Checks	SI-7, SA-11	SA.L2-3.13.10	CC8.1	2.1.3	6.5.3	SRG-APP-000456	ISM-1525	5.3.3
13	Signed Commit Requirement	SI-7(6)	SI.L2-3.14.1	CC8.1	2.1.4	6.5.4	SRG-APP-000411	ISM-1072	5.3.4
14	Repository Rulesets	CM-3, CM-5	CM.L2-3.4.5	CC8.1	2.1.5	6.5.5	SRG-APP-000133	ISM-1072	5.3.5
15	Code Scanning Enabled	RA-5, SA-11	RA.L2-3.11.2	CC7.1	3.1.1	6.5.6	SRG-APP-000456	ISM-1163	5.4.1
16	Secret Scanning Enabled	IA-5(7), SC-12	SC.L2-3.13.10	CC6.1, CC7.1	3.1.2	6.5.7	SRG-APP-000175	ISM-1590	5.4.2
17	Dependabot Enabled	RA-5, SI-2	RA.L2-3.11.2	CC7.1	3.1.3	6.3.3	SRG-APP-000456	ISM-1163	5.4.3
18	Security Policy	PL-2, IR-8	IR.L2-3.6.1	CC2.2	3.1.4	12.10.1	SRG-APP-000516	ISM-0043	5.4.4
19	Audit Log Streaming	AU-2, AU-6, SI-4	AU.L2-3.3.1	CC7.2, CC7.3	4.1.1	10.2.1	SRG-APP-000095	ISM-0580	5.5.1
20	Webhook Security	SC-8, SI-4	SC.L2-3.13.8	CC6.7	4.1.2	4.2.1	SRG-APP-000439	ISM-1139	5.5.2
21	Actions Permissions	CM-7, AC-3	CM.L2-3.4.7	CC6.8, CC8.1	5.1.1	6.3.2	SRG-APP-000386	ISM-1490	5.6.1
22	Runner Group Restrictions	AC-3, CM-7	AC.L2-3.1.3	CC6.3	5.1.2	7.2.5	SRG-APP-000033	ISM-0405	5.6.2
23	Deploy Key Management	IA-5, SC-12	IA.L2-3.5.10	CC6.1, CC6.6	5.2.1	8.6.3	SRG-APP-000175	ISM-1590	5.6.3
24	GitHub App Permissions Audit	AC-6(10), CM-11	AC.L2-3.1.7	CC6.3, CC6.8	5.2.2	6.3.2	SRG-APP-000342	ISM-1490	5.6.4
25	Package Registry Access	AC-3, AC-22	AC.L2-3.1.22	CC6.1	5.3.1	7.2.6	SRG-APP-000211	ISM-0264	5.6.5

6. Existing Tools

Tool	Type	Relevance
github/safe-settings	GitHub App	Declarative repo/org settings management via YAML; enforces branch protection, collaborators, labels, and org settings; apply-and-drift-detect model
ossf/allstar	GitHub App	OpenSSF project for continuous security policy enforcement; checks branch protection, binary artifacts, CI tests, pinned dependencies, SECURITY.md, admin access
ossf/scorecard	CLI / GitHub Action	OpenSSF Scorecard assesses 18+ security heuristics (branch protection, code review, dependency pinning, fuzzing, SAST, signed releases, etc.); assigns 0-10 score per check
github/codeql-action	GitHub Action	CodeQL static analysis for code scanning; detects vulnerabilities in supported languages
trufflesecurity/trufflehog	CLI	Secret scanning across git history, live endpoints, and filesystems
aquasecurity/trivy	CLI	Vulnerability scanner for code repos, container images, IaC; includes GitHub integration
bridgecrewio/checkov	CLI	IaC and supply chain scanner; includes GitHub Actions workflow checks
Legit Security	SaaS	Commercial SDLC security platform with GitHub security posture management
Apiiro	SaaS	Risk-based application security platform with GitHub integration
GitGuardian	SaaS/CLI	Secret detection and remediation for GitHub repos
Terraform GitHub Provider	IaC	integrations/github Terraform provider for declarative management of GitHub settings as code

7. Architecture

The project is written in Go and mirrors the modular architecture of okta-inspector.

github-sec-inspector/
├── cmd/
│   └── github-sec-inspector/
│       └── main.go                  # Entrypoint, CLI parsing, orchestration
├── internal/
│   ├── client/
│   │   ├── client.go                # Unified client (REST + GraphQL)
│   │   ├── rest.go                  # REST API v3 client (wraps go-github)
│   │   ├── graphql.go               # GraphQL API v4 client (wraps shurcooL/githubv4)
│   │   ├── auth.go                  # PAT, GitHub App, and OAuth authentication
│   │   └── ratelimit.go             # Rate limiting, retry, and pagination helpers
│   ├── collector/
│   │   ├── collector.go             # Top-level data collector orchestrator
│   │   ├── org.go                   # Collect org settings, member policies, teams
│   │   ├── members.go               # Collect members, 2FA status, SAML identities
│   │   ├── repos.go                 # Collect repositories and visibility settings
│   │   ├── branches.go              # Collect branch protection rules and rulesets
│   │   ├── security.go              # Collect GHAS: code scanning, secret scanning, Dependabot
│   │   ├── actions.go               # Collect Actions permissions, runners, workflows
│   │   ├── apps.go                  # Collect GitHub App installations, OAuth apps
│   │   ├── webhooks.go              # Collect organization webhooks
│   │   ├── keys.go                  # Collect deploy keys across repos
│   │   ├── packages.go              # Collect package registry configurations
│   │   ├── audit.go                 # Collect audit log events and streaming config
│   │   └── enterprise.go            # Collect enterprise-level settings (if applicable)
│   ├── models/
│   │   ├── githubdata.go            # GitHubData: container for all collected API data
│   │   ├── finding.go               # ComplianceFinding: individual check result
│   │   └── result.go                # AuditResult: aggregated audit output
│   ├── analyzers/
│   │   ├── base.go                  # Analyzer interface and registry
│   │   ├── common.go                # Shared analysis helpers
│   │   ├── fedramp.go               # FedRAMP (NIST 800-53 r5) analyzer
│   │   ├── cmmc.go                  # CMMC 2.0 analyzer
│   │   ├── soc2.go                  # SOC 2 (TSC) analyzer
│   │   ├── cis.go                   # CIS GitHub Benchmark analyzer
│   │   ├── pci_dss.go               # PCI-DSS 4.0 analyzer
│   │   ├── stig.go                  # DISA STIG analyzer
│   │   ├── irap.go                  # IRAP (ISM) analyzer
│   │   └── ismap.go                 # ISMAP analyzer
│   ├── reporters/
│   │   ├── base.go                  # Reporter interface and registry
│   │   ├── executive.go             # Executive summary (pass/fail counts, risk score)
│   │   ├── matrix.go                # Cross-framework compliance matrix
│   │   ├── fedramp.go               # FedRAMP-formatted report
│   │   ├── cmmc.go                  # CMMC-formatted report
│   │   ├── soc2.go                  # SOC 2 formatted report
│   │   ├── cis.go                   # CIS benchmark report
│   │   ├── pci_dss.go               # PCI-DSS 4.0 report
│   │   ├── stig.go                  # DISA STIG checklist (CKL/XCCDF)
│   │   ├── irap.go                  # IRAP assessment report
│   │   ├── ismap.go                 # ISMAP assessment report
│   │   └── validation.go            # Finding validation and deduplication
│   ├── engine/
│   │   └── engine.go                # AuditEngine: collect → analyze → report → archive
│   └── tui/
│       ├── app.go                   # Bubble Tea TUI application
│       ├── components/
│       │   ├── spinner.go           # Progress spinner
│       │   ├── table.go             # Results table
│       │   └── summary.go           # Summary dashboard
│       └── views/
│           ├── audit.go             # Audit progress view
│           └── results.go           # Results browser view
├── testdata/
│   ├── fixtures/                    # Mock API response JSON files
│   └── golden/                      # Golden file test outputs
├── go.mod
├── go.sum
├── Makefile
├── Dockerfile
├── .goreleaser.yml
├── .github/
│   └── workflows/
│       ├── ci.yml                   # Lint, test, build
│       └── release.yml              # GoReleaser publish
├── COPYING                          # GPL v3
├── README.md
└── spec.md                          # This file

Data Flow

┌──────────────────┐     ┌──────────────┐     ┌────────────┐     ┌────────────┐
│      Client      │────>│  Collector   │────>│  Analyzers │────>│  Reporters │
│ (REST + GraphQL) │     │ (GitHubData) │     │ (Findings) │     │ (Reports)  │
└──────────────────┘     └──────────────┘     └────────────┘     └────────────┘
       │                                             │
       │               ┌────────────┐                │
       └──────────────>│   Engine   │<───────────────┘
                       │ (Orchestr.)│
                       └────────────┘

8. CLI Interface

# Basic audit with personal access token
github-sec-inspector audit \
  --org your-organization \
  --token $GITHUB_TOKEN

# Audit with GitHub App authentication
github-sec-inspector audit \
  --org your-organization \
  --app-id 12345 \
  --app-private-key /path/to/private-key.pem \
  --app-installation-id 67890

# Include enterprise-level checks
github-sec-inspector audit \
  --org your-organization \
  --enterprise your-enterprise \
  --token $GITHUB_TOKEN

# Run only specific frameworks
github-sec-inspector audit \
  --org your-organization \
  --token $GITHUB_TOKEN \
  --frameworks fedramp,stig,pci-dss

# Audit specific repositories only
github-sec-inspector audit \
  --org your-organization \
  --token $GITHUB_TOKEN \
  --repos repo1,repo2,repo3

# Output to custom directory
github-sec-inspector audit \
  --org your-organization \
  --token $GITHUB_TOKEN \
  --output-dir ./github-audit-results

# JSON-only output (no TUI)
github-sec-inspector audit \
  --org your-organization \
  --token $GITHUB_TOKEN \
  --format json \
  --quiet

# List available frameworks
github-sec-inspector frameworks

# Validate connectivity and permissions
github-sec-inspector validate \
  --org your-organization \
  --token $GITHUB_TOKEN

# Scan a single repository
github-sec-inspector repo \
  --owner your-organization \
  --repo your-repo \
  --token $GITHUB_TOKEN

# Environment variable usage
export GITHUB_TOKEN="ghp_..."
export GITHUB_ORG="your-organization"
export GITHUB_ENTERPRISE="your-enterprise"
github-sec-inspector audit

9. Build Sequence

Phase 1 — Foundation (Weeks 1-2)

• Initialize Go module, project scaffolding, CI/CD pipeline
• Implement internal/client/ — REST and GraphQL clients with PAT and GitHub App auth
• Implement internal/models/ — GitHubData, ComplianceFinding, AuditResult
• Implement internal/collector/org.go, members.go — org settings, member enumeration, 2FA status
• Write unit tests with mock API responses in testdata/fixtures/

Phase 2 — Core Analyzers (Weeks 3-4)

• Implement internal/analyzers/base.go — analyzer interface and registry
• Implement controls 1-9 (identity, authentication, org permissions)
• Implement internal/collector/repos.go, branches.go — repo enumeration and branch protection
• Implement controls 10-14 (repository and code protection)
• Build first analyzer: fedramp.go
• Build stig.go and cmmc.go analyzers

Phase 3 — GHAS & Actions (Weeks 5-6)

• Implement internal/collector/security.go — code scanning, secret scanning, Dependabot
• Implement internal/collector/actions.go, apps.go, webhooks.go, keys.go
• Implement controls 15-25 (GHAS, audit, Actions, apps, packages)
• Build remaining analyzers: soc2.go, cis.go, pci_dss.go, irap.go, ismap.go

Phase 4 — Reporting & CLI (Weeks 7-8)

• Implement internal/reporters/ — all report formatters
• Implement internal/engine/engine.go — orchestration pipeline
• Implement cmd/github-sec-inspector/main.go — CLI with cobra or stdlib flags
• STIG CKL/XCCDF export support
• JSON, CSV, and Markdown output formats

Phase 5 — TUI & Polish (Weeks 9-10)

• Implement internal/tui/ — Bubble Tea interactive interface
• Implement GraphQL-based collectors for SAML, IP allow list, enterprise data
• Dockerfile and GoReleaser configuration
• Integration tests against a GitHub organization
• Documentation, README, and usage examples
• Golden file tests for report output stability

10. Status

Not yet implemented. Spec only.