Feature: Commit Signing Verification

[flemzord]

Feature: Commit Signing Verification

Summary

Add a compliance check to verify that commits are signed with GPG/SSH keys and optionally enforce commit signing requirements on repositories.

Problem Statement

Unsigned commits can be impersonated, leading to potential security risks and compliance violations. Organizations need to ensure code integrity by verifying that commits are cryptographically signed by authorized developers.

Proposed Solution

Implement a new commit-signing check that audits commit signatures and enforces signing requirements at the repository level.

Detailed Design

Configuration Schema

defaults:
  commit_signing:
    require_signed_commits: true
    verification_period_days: 90  # Check commits from last N days
    enforcement_level: "strict"   # strict, warn, or off
    allowed_signature_types:
      - gpg
      - ssh
      - x509
    exemptions:
      bots: ["dependabot[bot]", "renovate[bot]"]
      users: []  # Users exempt from signing requirements
    branch_protection_signing: true  # Enforce via branch protection

Implementation Requirements

Check Logic

1. Fetch recent commits for specified branches
2. Verify signature status for each commit
3. Identify unsigned commits and their authors
4. Report compliance status
5. Optionally enforce signing via branch protection rules

API Endpoints

• GET /repos/{owner}/{repo}/commits - List commits with signature verification
• GET /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures - Check signing enforcement
• PUT /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures - Enable signing requirement

Verification Levels

• Strict: All commits must be signed and verified
• Warn: Report unsigned commits but don't fail
• Off: Skip verification for specific repositories

User Stories

• As a security engineer, I want to ensure all production code commits are cryptographically signed
• As a compliance officer, I need to audit repositories for unsigned commits over the past quarter
• As a developer, I want to be notified when my commits aren't properly signed
• As an admin, I want to enforce commit signing through branch protection rules

Technical Considerations

Challenges

• Historical commits cannot be retroactively signed
• Bot commits (Dependabot, GitHub Actions) need special handling
• Performance impact when checking large numbers of commits
• Different signature types (GPG, SSH, S/MIME) have different verification methods

Implementation Details

interface CommitSigningCheck extends BaseCheck {
  checkCommitSignatures(repo: Repository, options: SigningOptions): Promise<SignatureReport>;
  enforceSigningRequirement(repo: Repository, branch: string): Promise<void>;
  generateSigningReport(violations: SignatureViolation[]): Report;
}

interface SignatureViolation {
  commit_sha: string;
  author: string;
  date: string;
  branch: string;
  signature_status: 'unsigned' | 'unverified' | 'bad' | 'unknown';
  message: string;
}

Testing Strategy

• Unit tests for signature verification logic
• Mock different signature statuses (verified, unverified, unsigned)
• Test exemption handling for bots and specified users
• Integration tests with branch protection API
• Performance tests with repositories containing many commits

Documentation Needs

• Setup guide for GPG/SSH key configuration
• Troubleshooting guide for common signing issues
• Best practices for commit signing in CI/CD pipelines
• Migration guide for repositories with historical unsigned commits

Success Criteria

• Accurately identifies unsigned and unverified commits
• Supports GPG, SSH, and X.509 signature verification
• Configurable verification period (e.g., last 90 days)
• Bot and user exemptions work correctly
• Branch protection signing enforcement can be enabled
• Performance remains acceptable for large repositories
• Clear reporting of signature violations

Dependencies

• GitHub API commit signature verification endpoints
• Existing branch protection check (for enforcement)
• Performance optimization for large-scale verification

Open Questions

1. How to handle merge commits from GitHub web UI?
2. Should we verify signatures on all branches or just protected ones?
3. How to handle repositories migrated from other platforms with unsigned history?
4. Should we provide tooling to help developers set up commit signing?
5. How to handle signature verification for different git hosting providers in the future?

Future Enhancements

• Automated key rotation reminders
• Integration with corporate PKI systems
• Commit signing statistics dashboard
• Automated developer onboarding for commit signing setup
• Support for blockchain-based commit attestation