GitHub Security Score

A command-line tool that comprehensively assesses the health, maintainability, and security posture of GitHub repositories across 12 key indicators.

Features

The tool evaluates repositories based on the following metrics:

1. Archive Status - Checks if repository is archived (read-only)
2. Recent Activity - Checks if repository has recent commits and is actively maintained
3. Documentation Quality - Evaluates presence and quality of README, CONTRIBUTING, and LICENSE files
4. CI/CD Workflow - Checks for GitHub Actions workflows for automated testing/deployment
5. Open Issues Ratio - Analyzes ratio of open vs closed issues
6. Dependency Vulnerabilities - Scans dependencies for known vulnerabilities using OSV.dev API
7. .github Directory Analysis - Checks for proper GitHub directory structure and configurations
8. Security Policy - Verifies presence of SECURITY.md file
9. Branch Protection - Validates default branch requires PR reviews and signed commits
10. Issue Response Time - Measures average time to first response on issues
11. PR Review Response Time - Measures average time to first review on pull requests
12. Signed Commits - Calculates percentage of GPG/SSH signed commits

Each metric contributes to a final score from 0 to 12, with 12 being the best repository health.

Key Features

🔍 Comprehensive Dependency Scanning

• Automatically detects dependency files (package.json, go.mod, requirements.txt, etc.)
• Queries OSV.dev (Open Source Vulnerabilities) database for known CVEs
• Supports multiple ecosystems: npm, Go, PyPI, RubyGems, Maven, Crates.io, Packagist
• Real-time vulnerability detection without requiring Dependabot to be enabled

📊 Multi-Dimensional Analysis

• Combines security, maintenance, and community health metrics
• Provides actionable insights into repository quality
• Scores repositories on an 11-point scale

⚡ Fast and Lightweight

• Single binary with no external dependencies
• Direct GitHub API integration
• Efficient API usage to minimize rate limit impact

Installation

Download Pre-built Binary

Download the latest release for your platform from the releases page.

# Linux/macOS
wget https://github.com/securecodelabs/gh-security-score/releases/download/v0.1.0/githubsecurityscore_0.1.0_linux_amd64
chmod +x githubsecurityscore_0.1.0_linux_amd64
sudo mv githubsecurityscore_0.1.0_linux_amd64 /usr/local/bin/githubsecurityscore

Build from Source

# Clone the repository
git clone https://github.com/securecodelabs/gh-security-score.git
cd gh-security-score

# Build using make
make build

# Or build directly with go
go build -o githubsecurityscore

# Install to $GOPATH/bin
make install

Usage

# Basic usage (unauthenticated - limited functionality)
githubsecurityscore owner/repo

# With GitHub token (recommended for full functionality)
export GITHUB_TOKEN="your_github_personal_access_token"
githubsecurityscore owner/repo

Examples

# Analyze Google's go-github repository
githubsecurityscore google/go-github

# Analyze with authentication
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
githubsecurityscore kubernetes/kubernetes

# Using make for quick testing
make run  # Analyzes google/go-github by default

GitHub Token

For full functionality, you need a GitHub Personal Access Token (PAT):

• For Public Repositories: No specific scopes required (classic token) or public_repo scope
• For Private Repositories: repo scope required
• For Branch Protection Checks: Admin access to repository or appropriate permissions

Note: Many metrics work without authentication, but a token is recommended for:

• Higher API rate limits (5000/hour vs 60/hour)
• Access to branch protection rules
• More detailed repository information

Creating a GitHub Token

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Select the public_repo scope (and repo if analyzing private repositories)
4. Generate and copy the token
5. Set it as an environment variable:

export GITHUB_TOKEN="your_token_here"

Output Example

Analyzing security posture for vercel/next.js...

Security Posture Score for vercel/next.js:
============================================================
1. Recent Activity: Very Active
   Last commit 1 days ago
2. Documentation Quality: Excellent
   README: 12500+ chars, has CONTRIBUTING.md, has docs folder
3. CI/CD Workflow: Enabled
   Found 8 GitHub Actions workflow(s)
4. Open Issues Ratio: Good
   18.5% open issues (350/1890 total)
5. Dependency Vulnerabilities: Good
   Scanning for dependency files...
   Found package.json (npm ecosystem), checking vulnerabilities...
   Found 2 low severity vulnerabilities
6. GitHub Directory: Present
   Found .github/ directory with 5 item(s)
7. Security Policy: Present
   Security policy found at SECURITY.md
8. Branch Protection: Fully Protected
   Branch requires PR reviews and signed commits
9. Issue Response Time: Excellent
   Average response time: 1.2 days (20 issues analyzed)
10. PR Review Response Time: Excellent
    Average review response time: 8.5 hours (20 PRs analyzed)
11. Signed Commits: Excellent
    95.0% signed (95/100 commits)
------------------------------------------------------------
Total Security Score: 10.2/12
============================================================

Scoring Logic

• Archive Status: 1.0 (active), 0.0 (archived)
• Recent Activity: 1.0 (≤30 days), 0.8 (≤90 days), 0.5 (≤180 days), 0.0 (>180 days)
• Documentation Quality: Scored by presence of README.md, CONTRIBUTING.md, and LICENSE files
• CI/CD Workflow: 1.0 if GitHub Actions workflows exist, 0.0 if none
• Open Issues Ratio: 1.0 (≤20% open), 0.7 (≤40% open), 0.4 (≤60% open), 0.0 (>60% open)
• Dependency Vulnerabilities: 1.0 (no vulnerabilities), 0.7 (low severity only), 0.4 (medium), 0.0 (high/critical)
• GitHub Directory: 1.0 if .github/ directory exists with proper structure, 0.0 if missing
• Security Policy: 1.0 if SECURITY.md exists, 0.0 if missing
• Branch Protection: 1.0 if fully protected, 0.5 if partial, 0.25 if weak, 0.0 if none
• Issue Response Time: 1.0 (≤2 days), 0.7 (≤7 days), 0.4 (≤14 days), 0.0 (>14 days)
• PR Review Response Time: 1.0 (≤24h), 0.7 (≤48h), 0.4 (≤1 week), 0.0 (>1 week)
• Signed Commits: 1.0 (≥90%), 0.7 (≥70%), 0.5 (≥50%), 0.3 (>0%), 0.0 (none)

Limitations

• Authentication Recommended: While many metrics work without authentication, a token provides higher rate limits and access to more repository details
• Rate Limits: GitHub API has rate limits (60 requests/hour unauthenticated, 5000/hour authenticated)
• Permissions: Some checks require specific repository permissions or may not work on private repositories without proper access
• Public Repositories: Works best with public repositories that have sufficient activity and history

Technical Details

• Built with Go 1.21+
• Uses google/go-github/v80 for GitHub API interactions
• Uses golang.org/x/oauth2 for authentication
• Integrates with OSV.dev API for real-time vulnerability scanning
• Evaluates repository health across activity, documentation, CI/CD, licensing, security, and maintenance metrics
• All checks run sequentially to avoid API rate limiting issues

How Vulnerability Scanning Works

Unlike tools that only check if Dependabot is enabled, this tool:

1. Detects dependency files in the repository (package.json, go.mod, etc.)
2. Queries OSV.dev - Google's comprehensive vulnerability database
3. Reports actual vulnerabilities found in dependencies
4. Works for any public repository - no need for special permissions or Dependabot configuration

This means you get real vulnerability data even for repositories that haven't enabled GitHub's Dependabot alerts.

Development

# Run tests
make test

# Format code
make fmt

# Lint code
make lint

# Clean build artifacts
make clean

# Tidy dependencies
make tidy

Release Process

# Create a new release (requires proper git permissions)
make release VERSION=x.y.z

This will create and push a git tag. The GitHub Actions workflow will automatically build binaries for multiple platforms using GoReleaser.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is open source and available under the MIT License.