git-shield

Name	git-shield JSON
Version	1.2.0 JSON
	download
home_page	None
Summary	Advanced secret detection for Git repositories
upload_time	2025-08-03 04:48:01
maintainer	None
docs_url	None
author	None
requires_python	>=3.8
license	MIT
keywords	cli detection git secrets security
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # 🚀 git-shield

`git-shield` is a lightweight, secure command-line tool that **detects hard-coded secrets, passwords, API keys, and random-looking sensitive data in your Git staged files before you commit.**

👌 Prevent accidental leaks
📊 Generate user-friendly reports
💪 Automate via Git pre-commit hooks
📈 Combines Regex + Shannon Entropy detection for maximum protection
🔍 Smart file type detection for comprehensive scanning

---

## ✨ Features

- 🔍 **Smart File Detection**: Automatically detects and scans text files including:

  - Code files (`.py`, `.js`, `.ts`, `.java`, `.cpp`, etc.)
  - Configuration files (`.env`, `.config`, `.yml`, `.json`, etc.)
  - Documentation (`.md`, `.txt`, `.rst`, etc.)
  - Certificate files (`.pem`, `.key`, `.crt`, etc.)
  - And many more supported formats

- 🛡 **Comprehensive Secret Detection**:

  - AWS Access Keys & Secret Keys
  - Private/Public Keys (RSA, DSA, EC, SSH)
  - API Keys (GitHub, Google, Stripe, Twilio, etc.)
  - Database URLs (PostgreSQL, MongoDB, Redis, MySQL)
  - OAuth tokens and client secrets
  - JWT tokens
  - Slack tokens and webhooks
  - Environment variables
  - Hardcoded credentials in code
  - Secrets in comments

- 🔧 **Git Hook Management**:

  - Easy installation/uninstallation of pre-commit hooks
  - Automatic scanning before every commit
  - Blocks commits when secrets are detected

- 📊 **Detailed Reports**: File, line number, pattern type, and code context
- ⚡ **Fast and Lightweight**: Minimal dependencies, runs locally
- 🔐 **Security Focused**: 100% local operation, no network calls

---

## 📦 Installation

Ensure you have **Python 3.8+** installed.

```bash
# Install via PyPI
pip install git-shield
```

Alternatively:

```bash
git clone https://github.com/yourusername/git-shield.git
cd git-shield
pip install .
```

---

## ⚡ Quick Start

### Basic Usage

Scan staged files in your Git repository:

```bash
git-shield scan --staged
```

Scan specific files:

```bash
git-shield scan --files config.env database.yml
```

### Git Hook Setup

Install git-shield as a pre-commit hook (recommended):

```bash
git-shield install
```

This will automatically scan for secrets before every commit and block commits if secrets are found.

Check hook status:

```bash
git-shield status
```

Uninstall the hook if needed:

```bash
git-shield uninstall
```

---

## 📋 Command Reference

### `git-shield scan`

Scan files for secrets.

**Options:**

- `--staged`: Scan all staged files in the current git repository
- `--files`: Scan specific files (can specify multiple files)

**Examples:**

```bash
# Scan staged files
git-shield scan --staged

# Scan specific files
git-shield scan --files .env config.py

# Scan multiple specific files
git-shield scan --files file1.txt file2.py file3.yml
```

### `git-shield install`

Install git-shield as a pre-commit hook.

**Example:**

```bash
git-shield install
```

### `git-shield uninstall`

Uninstall git-shield pre-commit hook.

**Example:**

```bash
git-shield uninstall
```

### `git-shield status`

Check the installation status of git-shield hooks.

**Example:**

```bash
git-shield status
```

---

## 📊 Output Examples

### ✅ No Secrets Detected

```
🔍 Scanning 3 file(s) for secrets...
✅ No secrets detected. Safe to commit.
```

### ❌ Secrets Detected

```
🔍 Scanning 2 file(s) for secrets...

❌ Secrets detected:
   📄 config.env:5 [Password] -> pass****
      Code: password=EXAMPLE_PASSWORD

   📄 api.py:12 [API Key] -> AKIA****
      Code: aws_access_key = "AKIAEXAMPLEKEY123"

🚫 Found 2 secret(s). Please remove them before committing.
```

---

## 🔍 Supported File Types

git-shield automatically detects and scans text files including:

**Code Files:**

- `.py`, `.js`, `.ts`, `.jsx`, `.tsx`, `.html`, `.css`, `.scss`, `.sass`
- `.java`, `.cpp`, `.c`, `.h`, `.hpp`, `.cs`, `.go`, `.rs`, `.swift`
- `.kt`, `.scala`, `.clj`, `.hs`, `.ml`, `.fs`, `.vb`, `.pl`, `.pm`
- `.tcl`, `.lua`, `.vim`, `.tex`, `.rst`, `.adoc`, `.wiki`

**Configuration Files:**

- `.env`, `.config`, `.conf`, `.ini`, `.cfg`, `.properties`
- `.json`, `.xml`, `.yaml`, `.yml`, `.toml`

**Documentation:**

- `.md`, `.txt`, `.log`, `.csv`, `.tsv`, `.tab`, `.dat`, `.asc`

**Certificate Files:**

- `.pem`, `.key`, `.crt`, `.cer`, `.der`, `.p12`, `.pfx`
- `.p7b`, `.p7c`, `.crl`, `.csr`

**Scripts:**

- `.sh`, `.bash`, `.zsh`, `.fish`, `.ps1`, `.bat`, `.cmd`

---

## 🛡 Detection Patterns

git-shield includes comprehensive patterns for detecting:

- **AWS**: Access keys, secret keys, session tokens
- **GitHub**: Personal access tokens, OAuth tokens, app tokens
- **Database**: PostgreSQL, MongoDB, Redis, MySQL connection strings
- **OAuth**: Client IDs, client secrets, access tokens
- **Slack**: Tokens, webhooks
- **Stripe**: Live/test keys, publishable keys
- **Google**: API keys, OAuth credentials
- **Social Media**: Facebook, Twitter tokens
- **Communication**: Twilio, SendGrid, Mailgun API keys
- **Generic**: Base64/hex encoded secrets, UUIDs, hardcoded credentials

---

## 🔐 Security Focus

- **100% Local**: No network calls, runs entirely on your machine
- **No Data Storage**: Does not store or upload your code
- **Open Source**: MIT Licensed, transparent codebase
- **Privacy First**: Your secrets never leave your system

---

## ❗ Exit Codes

| Exit Code | Meaning                           |
| --------- | --------------------------------- |
| 0         | No secrets found — commit allowed |
| 1         | Secrets detected — commit blocked |
| 2         | Environment/tool errors           |

---

## 🤝 Contributing

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

---

## 📝 License

MIT License — Free to use, modify, and distribute.

---

## ❤️ Support

If you like this project, ⭐ star the repo and share it!

<!-- **Author:** 👤 **Vamil Porwal** - [GitHub](https://github.com/VamilP) -->

**Author:** 👤 **Vamil Porwal**

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "git-shield",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "cli, detection, git, secrets, security",
    "author": null,
    "author_email": "Vamil Porwal <vamililporwal@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/ee/e3/41818ed5c852cb4edc6e998eaec10fc08ec00d01577d2456029bb7ab8fca/git_shield-1.2.0.tar.gz",
    "platform": null,
    "description": "# \ud83d\ude80 git-shield\n\n`git-shield` is a lightweight, secure command-line tool that **detects hard-coded secrets, passwords, API keys, and random-looking sensitive data in your Git staged files before you commit.**\n\n\ud83d\udc4c Prevent accidental leaks\n\ud83d\udcca Generate user-friendly reports\n\ud83d\udcaa Automate via Git pre-commit hooks\n\ud83d\udcc8 Combines Regex + Shannon Entropy detection for maximum protection\n\ud83d\udd0d Smart file type detection for comprehensive scanning\n\n---\n\n## \u2728 Features\n\n- \ud83d\udd0d **Smart File Detection**: Automatically detects and scans text files including:\n\n  - Code files (`.py`, `.js`, `.ts`, `.java`, `.cpp`, etc.)\n  - Configuration files (`.env`, `.config`, `.yml`, `.json`, etc.)\n  - Documentation (`.md`, `.txt`, `.rst`, etc.)\n  - Certificate files (`.pem`, `.key`, `.crt`, etc.)\n  - And many more supported formats\n\n- \ud83d\udee1 **Comprehensive Secret Detection**:\n\n  - AWS Access Keys & Secret Keys\n  - Private/Public Keys (RSA, DSA, EC, SSH)\n  - API Keys (GitHub, Google, Stripe, Twilio, etc.)\n  - Database URLs (PostgreSQL, MongoDB, Redis, MySQL)\n  - OAuth tokens and client secrets\n  - JWT tokens\n  - Slack tokens and webhooks\n  - Environment variables\n  - Hardcoded credentials in code\n  - Secrets in comments\n\n- \ud83d\udd27 **Git Hook Management**:\n\n  - Easy installation/uninstallation of pre-commit hooks\n  - Automatic scanning before every commit\n  - Blocks commits when secrets are detected\n\n- \ud83d\udcca **Detailed Reports**: File, line number, pattern type, and code context\n- \u26a1 **Fast and Lightweight**: Minimal dependencies, runs locally\n- \ud83d\udd10 **Security Focused**: 100% local operation, no network calls\n\n---\n\n## \ud83d\udce6 Installation\n\nEnsure you have **Python 3.8+** installed.\n\n```bash\n# Install via PyPI\npip install git-shield\n```\n\nAlternatively:\n\n```bash\ngit clone https://github.com/yourusername/git-shield.git\ncd git-shield\npip install .\n```\n\n---\n\n## \u26a1 Quick Start\n\n### Basic Usage\n\nScan staged files in your Git repository:\n\n```bash\ngit-shield scan --staged\n```\n\nScan specific files:\n\n```bash\ngit-shield scan --files config.env database.yml\n```\n\n### Git Hook Setup\n\nInstall git-shield as a pre-commit hook (recommended):\n\n```bash\ngit-shield install\n```\n\nThis will automatically scan for secrets before every commit and block commits if secrets are found.\n\nCheck hook status:\n\n```bash\ngit-shield status\n```\n\nUninstall the hook if needed:\n\n```bash\ngit-shield uninstall\n```\n\n---\n\n## \ud83d\udccb Command Reference\n\n### `git-shield scan`\n\nScan files for secrets.\n\n**Options:**\n\n- `--staged`: Scan all staged files in the current git repository\n- `--files`: Scan specific files (can specify multiple files)\n\n**Examples:**\n\n```bash\n# Scan staged files\ngit-shield scan --staged\n\n# Scan specific files\ngit-shield scan --files .env config.py\n\n# Scan multiple specific files\ngit-shield scan --files file1.txt file2.py file3.yml\n```\n\n### `git-shield install`\n\nInstall git-shield as a pre-commit hook.\n\n**Example:**\n\n```bash\ngit-shield install\n```\n\n### `git-shield uninstall`\n\nUninstall git-shield pre-commit hook.\n\n**Example:**\n\n```bash\ngit-shield uninstall\n```\n\n### `git-shield status`\n\nCheck the installation status of git-shield hooks.\n\n**Example:**\n\n```bash\ngit-shield status\n```\n\n---\n\n## \ud83d\udcca Output Examples\n\n### \u2705 No Secrets Detected\n\n```\n\ud83d\udd0d Scanning 3 file(s) for secrets...\n\u2705 No secrets detected. Safe to commit.\n```\n\n### \u274c Secrets Detected\n\n```\n\ud83d\udd0d Scanning 2 file(s) for secrets...\n\n\u274c Secrets detected:\n   \ud83d\udcc4 config.env:5 [Password] -> pass****\n      Code: password=EXAMPLE_PASSWORD\n\n   \ud83d\udcc4 api.py:12 [API Key] -> AKIA****\n      Code: aws_access_key = \"AKIAEXAMPLEKEY123\"\n\n\ud83d\udeab Found 2 secret(s). Please remove them before committing.\n```\n\n---\n\n## \ud83d\udd0d Supported File Types\n\ngit-shield automatically detects and scans text files including:\n\n**Code Files:**\n\n- `.py`, `.js`, `.ts`, `.jsx`, `.tsx`, `.html`, `.css`, `.scss`, `.sass`\n- `.java`, `.cpp`, `.c`, `.h`, `.hpp`, `.cs`, `.go`, `.rs`, `.swift`\n- `.kt`, `.scala`, `.clj`, `.hs`, `.ml`, `.fs`, `.vb`, `.pl`, `.pm`\n- `.tcl`, `.lua`, `.vim`, `.tex`, `.rst`, `.adoc`, `.wiki`\n\n**Configuration Files:**\n\n- `.env`, `.config`, `.conf`, `.ini`, `.cfg`, `.properties`\n- `.json`, `.xml`, `.yaml`, `.yml`, `.toml`\n\n**Documentation:**\n\n- `.md`, `.txt`, `.log`, `.csv`, `.tsv`, `.tab`, `.dat`, `.asc`\n\n**Certificate Files:**\n\n- `.pem`, `.key`, `.crt`, `.cer`, `.der`, `.p12`, `.pfx`\n- `.p7b`, `.p7c`, `.crl`, `.csr`\n\n**Scripts:**\n\n- `.sh`, `.bash`, `.zsh`, `.fish`, `.ps1`, `.bat`, `.cmd`\n\n---\n\n## \ud83d\udee1 Detection Patterns\n\ngit-shield includes comprehensive patterns for detecting:\n\n- **AWS**: Access keys, secret keys, session tokens\n- **GitHub**: Personal access tokens, OAuth tokens, app tokens\n- **Database**: PostgreSQL, MongoDB, Redis, MySQL connection strings\n- **OAuth**: Client IDs, client secrets, access tokens\n- **Slack**: Tokens, webhooks\n- **Stripe**: Live/test keys, publishable keys\n- **Google**: API keys, OAuth credentials\n- **Social Media**: Facebook, Twitter tokens\n- **Communication**: Twilio, SendGrid, Mailgun API keys\n- **Generic**: Base64/hex encoded secrets, UUIDs, hardcoded credentials\n\n---\n\n## \ud83d\udd10 Security Focus\n\n- **100% Local**: No network calls, runs entirely on your machine\n- **No Data Storage**: Does not store or upload your code\n- **Open Source**: MIT Licensed, transparent codebase\n- **Privacy First**: Your secrets never leave your system\n\n---\n\n## \u2757 Exit Codes\n\n| Exit Code | Meaning                           |\n| --------- | --------------------------------- |\n| 0         | No secrets found \u2014 commit allowed |\n| 1         | Secrets detected \u2014 commit blocked |\n| 2         | Environment/tool errors           |\n\n---\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n---\n\n## \ud83d\udcdd License\n\nMIT License \u2014 Free to use, modify, and distribute.\n\n---\n\n## \u2764\ufe0f Support\n\nIf you like this project, \u2b50 star the repo and share it!\n\n<!-- **Author:** \ud83d\udc64 **Vamil Porwal** - [GitHub](https://github.com/VamilP) -->\n\n**Author:** \ud83d\udc64 **Vamil Porwal**\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Advanced secret detection for Git repositories",
    "version": "1.2.0",
    "project_urls": null,
    "split_keywords": [
        "cli",
        " detection",
        " git",
        " secrets",
        " security"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "705dd3de292b073bca5608bec13e8e08015efc9b6502dd46a1450c8346ac2453",
                "md5": "32ee3a2f61e8756f206f14d07cd5cd57",
                "sha256": "253345853806016d2b9ac40318dbee293f4e4ebfa557e729cb998be710d48938"
            },
            "downloads": -1,
            "filename": "git_shield-1.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "32ee3a2f61e8756f206f14d07cd5cd57",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 10643,
            "upload_time": "2025-08-03T04:48:00",
            "upload_time_iso_8601": "2025-08-03T04:48:00.574579Z",
            "url": "https://files.pythonhosted.org/packages/70/5d/d3de292b073bca5608bec13e8e08015efc9b6502dd46a1450c8346ac2453/git_shield-1.2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "eee341818ed5c852cb4edc6e998eaec10fc08ec00d01577d2456029bb7ab8fca",
                "md5": "04a4f051f404191bd15deff55cc8e661",
                "sha256": "731fb1745872e527632872a4f65d8882969065d58a88bcf91d648376b77c6072"
            },
            "downloads": -1,
            "filename": "git_shield-1.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "04a4f051f404191bd15deff55cc8e661",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 11370,
            "upload_time": "2025-08-03T04:48:01",
            "upload_time_iso_8601": "2025-08-03T04:48:01.853660Z",
            "url": "https://files.pythonhosted.org/packages/ee/e3/41818ed5c852cb4edc6e998eaec10fc08ec00d01577d2456029bb7ab8fca/git_shield-1.2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-03 04:48:01",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "git-shield"
}