gitsec 1.1.0

Python tool that helps you enhance your GitHub security posture at scale.

gitsec

A modular Python CLI tool for auditing GitHub security posture at organization and repository level.

Overview

gitsec helps you secure your GitHub environment at scale. It checks all key security configurations at both organization and repository level, scans for hardcoded secrets and vulnerable, deprecated, or unpinned dependencies, and gives you one comprehensive report with everything you need to fix.

Features

gitsec provides comprehensive security auditing for GitHub repositories and organizations through three main modules:

1. Secret Scanning

Detect hardcoded secrets and credentials in your codebase using the detect-secrets library with custom plugins.

• API keys (AWS, Google Cloud, Azure, OpenAI, Anthropic, etc.)
• Database connection strings
• Private keys and certificates
• OAuth tokens and webhook secrets

2. Dependency Scanning

Identify vulnerabilities in your project dependencies using the deps.dev API.

• Known CVEs and security advisories
• CVSS severity scoring
• Deprecated packages detection
• Unpinned dependencies identification
• Support for multiple ecosystems (npm, pip, Maven, Go, etc.)

3. Security Checks

Audit GitHub security configurations at organization and repository level.

Organization-level checks:

• MFA requirement status
• SSO/SAML configuration
• Default repository permissions
• Members can create repositories
• Commit signing enforcement
• Pull request requirements
• Push protection
• Tag deletion protection
• Secrets and runners scope
• User access analysis

Repository-level checks:

• Commit signing requirements
• Pull request requirements
• Push protection
• Tag deletion protection
• Runners scope

Installation

Using pip (recommended)

pip install gitsec

Using pipx (isolated installation)

pipx install gitsec

For Development

1. Clone the repository:

git clone https://github.com/yourusername/gitsec.git
cd gitsec

2. Install dependencies:

poetry install

Authentication

Set your GitHub token:

export GITHUB_TOKEN=your_github_personal_access_token

Configuration File

gitsec supports configuration files for easier management of complex scans and consistent settings across runs. The tool automatically discovers configuration files in the following order:

1. .gitsec.yml or gitsec.yml in the current directory
2. .gitsec.yml in your home directory
3. Custom path via --config flag

Configuration features:

• Define default targets (org/repo/local-repo)
• Configure repository filtering (include/exclude patterns)
• Enable/disable scanning modules globally or per-repository
• Set custom branches for specific repositories
• Control output formats and locations

Example configuration:

# Target specification
target:
  org: my-organization

# Output folder
output_folder: audit-results

# Repository filtering
repositories:
  include:
    - "frontend-*"
    - "backend-api"
  exclude:
    - "*-archive"
    - "*-deprecated"
  max_count: 50
  sort_by: pushed_at

# Security checks configuration
security_checks:
  enabled_modules:
    - org-mfa
    - org-sso
    - org-commit-signing

# Per-repository overrides
repository_overrides:
  frontend-app:
    branch: develop
    enabled_modules:
      - repo-commit-signing
      - repo-pr-required

See examples/gitsec.example.yml for a comprehensive configuration template with all available options.

Note: CLI arguments always take precedence over configuration file settings.

Usage

Quick Start

Run a comprehensive audit on an organization:

gitsec audit-all --org your-org --out-folder results

Run a comprehensive audit on a single repository:

gitsec audit-all --repo owner/repo --out-folder results

Comprehensive Audit

The audit-all command runs all three security modules and generates a single Excel report.

# Organization
gitsec audit-all --org myorg

# Single repository
gitsec audit-all --repo owner/repo

# Single repository with custom branch
gitsec audit-all --repo owner/repo --branch develop

# Local repository
gitsec audit-all --local-repo /path/to/repo

# GitHub Enterprise Server
gitsec audit-all --org myorg --base-url https://github.mycorp.com

Output: Single Excel file (audit_all_<target>.xlsx) with all findings and a combined summary sheet.

Note: Security checks are not available for local repositories.

Secret Scanning

# Single repository
gitsec scan-secrets --repo owner/repo

# Organization
gitsec scan-secrets --org myorg

# Local repository
gitsec scan-secrets --local-repo /path/to/repo

# Choose output format (csv, xls, or csv,xls)
gitsec scan-secrets --repo owner/repo --format csv,xls --out-folder reports

Dependency Scanning

# Single repository
gitsec scan-dependencies --repo owner/repo

# Organization
gitsec scan-dependencies --org myorg

# Local repository
gitsec scan-dependencies --local-repo /path/to/repo

# Choose output format (csv, xls, or csv,xls)
gitsec scan-dependencies --repo owner/repo --format xls

Security Checks

Run all checks or specific modules:

# All organization-level checks
gitsec security-checks all-org --org myorg

# All repository-level checks
gitsec security-checks all-repo --repo owner/repo

# Specific checks (can combine multiple)
gitsec security-checks org-mfa org-sso --org myorg
gitsec security-checks repo-commit-signing repo-pr-required --repo owner/repo

# Check a specific branch instead of default branch
gitsec security-checks repo-pr-required --repo owner/repo --branch new-feat

Available Security Check Modules

Organization-level

• org-mfa - Check if MFA is required for all organization members
• org-sso - Check if SSO/SAML is configured
• org-default-repo-permission - Check for overly permissive default repository permissions
• org-members-can-create-repos - Check if members are allowed to create repositories
• org-commit-signing - Check commit signing enforcement across all repositories
• org-pr-required - Check PR requirements across all repositories
• org-push-protection - Check push protection across all repositories
• org-tag-deletion-protection - Check tag deletion protection across all repositories
• org-secrets-scope - Audit organization secrets visibility and scope
• org-runners-scope - Audit self-hosted runners scope and visibility
• org-user-access - Analyze user access patterns and permissions

Repository-level

• repo-commit-signing - Check if commit signing is required (supports --branch)
• repo-pr-required - Check if PRs are required on default branch (supports --branch)
• repo-push-protection - Check if direct pushes to default branch are blocked (supports --branch)
• repo-tag-deletion-protection - Check if tag deletion is protected
• repo-runners-scope - Audit self-hosted runners scope

Output

All commands generate reports in the specified output directory:

• CSV format: Individual CSV files for each finding type
• Excel format: Comprehensive Excel workbook with multiple sheets and summary
• Combined format: Both CSV and Excel (use --format csv,xls)

The audit-all command generates a single Excel file containing all findings with a summary sheet.

Example Reports

Here's some examples of what the output looks like:

Summary Overview:

Secret Scanning Results:

Dependency Vulnerabilities:

Security Checks:

GitHub Enterprise Server Support

All commands support GitHub Enterprise Server via the --base-url flag:

gitsec audit-all --org myorg --base-url https://github.mycorp.com

Performance

gitsec caches API responses during command execution to reduce redundant requests and avoid rate limits.

Token Permissions

The GitHub personal access token requires the following scopes:

• repo - Full control of private repositories
• read:org - Read organization data
• admin:org - Read organization security settings

For GitHub Enterprise Server, ensure the token has equivalent permissions.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.