Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

41 Commits
.github/workflows
.github/workflows
 
 
packages
packages
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
mcp-config-example.json
mcp-config-example.json
 
 
package.json
package.json
 
 

Repository files navigation

GitHub Security Checker

⚠️ Disclaimer: This is an unofficial, community-built tool and is not affiliated with, endorsed by, or supported by GitHub, Inc.

A comprehensive tool for scanning GitHub repositories for security configuration issues and best practices. Provides actionable recommendations and SOC 2 compliance reports.

Features

  • Security Scanning: 40+ checks across branch protection, security features, access controls, and repository settings
  • Recommendations: Provides specific mitigation steps with documentation links for each finding
  • SOC 2 Reports: Generates compliance reports mapped to SOC 2 Trust Services Criteria
  • Multiple Interfaces: CLI, MCP Server (for AI assistants), and Web Dashboard

Security Checks (40+)

Branch Protection (12 checks)

Check Severity Description
Branch protection enabled Critical Verifies protection rules exist on default branch
Required PR reviews High Requires pull request reviews before merging
Dismiss stale reviews Medium Dismisses approvals when new commits are pushed
Code owner reviews Medium Requires review from code owners
Required reviewers count Medium Enforces minimum number of reviewers (recommended: 2)
Admin bypass restrictions High Prevents administrators from bypassing rules
Required status checks High Requires CI/CD checks to pass before merging
Force push restrictions High Prevents force pushes that rewrite history
Branch deletion restrictions Medium Prevents deletion of protected branches
Conversation resolution Low Requires all review comments to be resolved
Signed commits required Medium Requires GPG/SSH signed commits
Linear history required Low Enforces squash or rebase merging

Security Features (9 checks)

Check Severity Description
Security policy (SECURITY.md) Medium Vulnerability reporting instructions
Dependabot alerts High Vulnerability alerts for dependencies
Dependabot config Medium Automatic dependency version updates
Code scanning (CodeQL) High Static analysis for security vulnerabilities
Secret scanning High Detects accidentally committed secrets
Push protection Info Blocks commits containing secrets
Critical vulnerability alerts Critical Unresolved critical Dependabot alerts
High vulnerability alerts High Unresolved high severity alerts
Private vulnerability reporting Info GitHub Security Advisories enabled

Access Control (8 checks)

Check Severity Description
Public repository warning Info Alerts when repo is publicly accessible
Administrator count Medium Flags excessive admin access (>5 users)
Outside collaborators Info Tracks non-org members with write access
Deploy keys with write access Medium Identifies deploy keys that can push
Old deploy keys Low Flags deploy keys older than 1 year
Insecure webhook URLs High Webhooks using HTTP instead of HTTPS
Webhooks without secrets Medium Webhooks lacking payload validation
Webhook configuration audit Info Reviews all webhook configurations

Repository Settings (14 checks)

Check Severity Description
Wiki on public repo Info Wiki enabled and publicly accessible
Issues disabled Low GitHub Issues disabled
Legacy branch name Info Using "master" instead of "main"
README file Low Repository documentation
LICENSE file Low License terms for the project
CODEOWNERS file Medium Automatic review assignment
GitHub Actions permissions Medium Unrestricted Actions allowed
.gitignore file Low Prevents accidental sensitive file commits
GITHUB_TOKEN permissions High Default token has write permissions
Actions can approve PRs Medium Workflows can approve pull requests
Private repo forking Medium Forking allowed for private repos
Merge strategies Info All merge types allowed
Auto-delete branches Low Merged branches not auto-deleted
Unprotected environments Medium Deployment environments without protection rules

Installation

# Clone the repository
git clone https://github.com/vdanniel/github-security-checker.git
cd github-security-checker

# Install dependencies
npm install

# Build all packages
npm run build

Usage

CLI

# Set your GitHub token
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Interactive scan (select repos)
npx @ghsec/cli scan

# Scan specific repos
npx @ghsec/cli scan -r owner/repo1 owner/repo2

# Scan all repos in an org
npx @ghsec/cli scan -o my-organization

# Generate SOC 2 report
npx @ghsec/cli report -r owner/repo1 owner/repo2 --output soc2-report.md

# Output as JSON
npx @ghsec/cli scan -r owner/repo --json --output results.json

MCP Server (for Kiro/AI Assistants)

Add to your .kiro/settings/mcp.json:

{
  "mcpServers": {
    "github-security": {
      "command": "node",
      "args": ["path/to/github-security-checker/packages/mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Available MCP tools:

  • list_repos - List available repositories
  • scan_repo - Scan a single repository
  • scan_multiple_repos - Scan multiple repositories
  • generate_soc2_report - Generate SOC 2 compliance report
  • get_recommendations - Get detailed fix instructions

Web Dashboard

# Start the development server
cd packages/web
npm run dev

# Open http://localhost:3000

Features:

  • Enter GitHub token and repository list
  • Visual scan results with severity indicators
  • Expandable findings with recommendations
  • Summary statistics and scores

SOC 2 Control Mapping

Control Description Checks
CC6.1 Logical Access Controls Branch protection, admin access, deploy keys, GITHUB_TOKEN permissions
CC6.2 User Access Management Collaborator permissions, outside collaborators
CC6.7 Data Transmission Protection Webhook HTTPS, secret scanning, push protection
CC7.1 Vulnerability Management Dependabot, code scanning, dependency alerts
CC7.4 Security Incident Response Security policy, vulnerability reporting
CC8.1 Change Management PR reviews, status checks, code owners, signed commits

Security Score

Each repository receives a score from 0-100 based on findings:

Severity Point Deduction
Critical -25 points
High -15 points
Medium -8 points
Low -3 points
Info 0 points

Score Interpretation:

  • 90-100: Excellent security posture
  • 70-89: Good, minor improvements needed
  • 50-69: Fair, several issues to address
  • Below 50: Poor, immediate attention required

GitHub Token Permissions

Required scopes for your Personal Access Token:

Classic Token:

  • repo - Full control of private repositories
  • read:org - Read org membership (for org scanning)
  • security_events - Read security events

Fine-grained Token:

  • Repository access: All repositories (or select specific ones)
  • Permissions:
    • Actions: Read
    • Administration: Read
    • Contents: Read
    • Dependabot alerts: Read
    • Environments: Read
    • Metadata: Read
    • Secret scanning alerts: Read
    • Security events: Read
    • Webhooks: Read

Project Structure

github-security-checker/
├── .github/
│   └── workflows/
│       ├── vscode-extension.yml  # Build & publish VS Code extension
│       └── packages.yml          # Build & test core packages
├── packages/
│   ├── core/          # Core scanning logic and types
│   ├── cli/           # Command-line interface
│   ├── mcp/           # MCP server for AI assistants
│   ├── vscode/        # VS Code extension
│   └── web/           # Next.js web dashboard
├── package.json       # Workspace configuration
└── README.md

VS Code Extension

Install from VS Code Marketplace or Open VSX.

Commands:

  • GitHub Security: Connect to GitHub - Authenticate with GitHub
  • GitHub Security: Scan Repositories - Run security scan
  • GitHub Security: Show Results - View scan results
  • GitHub Security: Generate SOC 2 Report - Generate compliance report
  • GitHub Security: Fix Finding - Apply recommended fix

CI/CD

The project uses GitHub Actions for continuous integration:

  • vscode-extension.yml - Builds and publishes the VS Code extension to VS Code Marketplace and Open VSX on pushes to main
  • packages.yml - Builds, lints, and tests core packages on every push/PR

Required Secrets

Secret Description
VSCE_PAT Personal Access Token for VS Code Marketplace
OVSX_PAT Personal Access Token for Open VSX Registry

Development

# Build core package
npm run build -w @ghsec/core

# Run web app in development
npm run dev -w @ghsec/web

# Run MCP server in development
npm run dev -w @ghsec/mcp

Roadmap

  • Auto-fix capabilities for common issues
  • GitHub App integration (no PAT required)
  • Organization-wide scanning dashboard
  • Scheduled scans with notifications
  • Custom rule definitions
  • GitHub Rulesets support (new branch protection)
  • Export to CSV/PDF formats

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

License

MIT

About

GitHub repository security configuration checker and recommendation engine with CLI, MCP server, and web dashboard

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages