Metadata-Version: 2.3
Name: gitsec
Version: 1.0
Summary: Python tool that helps you enhance your GitHub security posture at scale.
License: MIT
Author: Aplite hi@aplite.de
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: detect-secrets (==1.5.0)
Requires-Dist: gitpython (==3.1.45)
Requires-Dist: httpx (==0.28.1)
Requires-Dist: openpyxl (==3.1.5)
Requires-Dist: pydantic (==2.12.3)
Requires-Dist: typer (==0.20)
Description-Content-Type: text/markdown

# gitsec

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

## 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
- 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

### Requirements
- Python >= 3.10
- Poetry (for dependency management)

### Setup

1. Clone the repository:
```bash
git clone https://github.com/yourusername/gitsec.git
cd gitsec
```

2. Install dependencies:
```bash
poetry install
```

3. Set your GitHub token:
```bash
export GITHUB_TOKEN=your_github_personal_access_token
```

## Usage

### Quick Start

Run a comprehensive audit on an organization:
```bash
poetry run gitsec audit-all --org your-org --out results
```

Run a comprehensive audit on a single repository:
```bash
poetry run gitsec audit-all --repo owner/repo --out results
```

### Comprehensive Audit

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

```bash
# Organization
poetry run gitsec audit-all --org myorg --out out

# Single repository
poetry run gitsec audit-all --repo owner/repo --out out

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

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

**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

```bash
# Single repository
poetry run gitsec scan-secrets --repo owner/repo --out out

# Organization
poetry run gitsec scan-secrets --org myorg --out out

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

# Choose output format (csv, xls, or csv,xls)
poetry run gitsec scan-secrets --repo owner/repo --format csv,xls --out out
```

### Dependency Scanning

```bash
# Single repository
poetry run gitsec scan-dependencies --repo owner/repo --out out

# Organization
poetry run gitsec scan-dependencies --org myorg --out out

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

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

### Security Checks

Run all checks or specific modules:

```bash
# All organization-level checks
poetry run gitsec security-checks all-org --org myorg --out out

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

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

## 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-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
- `repo-pr-required` - Check if PRs are required on default branch
- `repo-push-protection` - Check if direct pushes to default branch are blocked
- `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.

## GitHub Enterprise Server Support

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

```bash
poetry run gitsec audit-all --org myorg --base-url https://github.mycorp.com --out out
```

## 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.

