# Git Security Scanner
[](https://pypi.org/project/git-security-scanner/)
[](https://pypi.org/project/git-security-scanner/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/vyacheslavmeyerzon/security-scanner/actions/workflows/tests.yml)
A comprehensive Python tool to detect API keys, passwords, and secrets in Git repositories before they get exposed.
## 🚀 Features
- **🔍 Detects 25+ Secret Types**: AWS keys, API tokens, passwords, private keys, and more
- **🎯 Multiple Scan Modes**: Staged files, working directory, commit history
- **⚡ High Performance**: Parallel scanning with progress bars and caching
- **📊 Rich Reports**: Export to JSON, HTML, CSV, or Markdown
- **🎨 Customizable**: Add custom patterns, ignore files, configure severity levels
- **🔧 CI/CD Ready**: Pre-commit hooks and pipeline integration
- **🌍 Cross-Platform**: Works on Linux, macOS, and Windows
## 📦 Installation
### From PyPI (Recommended)
```bash
pip install git-security-scanner
```
### From Source
```bash
git clone https://github.com/vyacheslavmeyerzon/security-scanner.git
cd security-scanner
pip install -e .
```
## 🔧 Quick Start
### Basic Scan
Scan your current repository:
```bash
git-security-scanner
```
### Scan Specific Repository
```bash
git-security-scanner /path/to/repository
```
### Pre-commit Mode
Check only staged files:
```bash
git-security-scanner --pre-commit
```
### Export Results
```bash
# JSON format
git-security-scanner --export results.json
# HTML report
git-security-scanner --export report.html
# CSV format
git-security-scanner --export findings.csv
# Markdown report
git-security-scanner --export report.md
```
## 🎯 What It Detects
### Cloud Services
- AWS Access Keys and Secret Keys
- Azure Storage Keys
- Google Cloud API Keys and OAuth Tokens
### AI/ML Platforms
- OpenAI API Keys
- Anthropic (Claude) API Keys
- HuggingFace Tokens
- Cohere API Keys
### Version Control
- GitHub Personal Access Tokens
- GitLab Access Tokens
- Bitbucket App Passwords
### Databases
- MongoDB Connection Strings
- PostgreSQL Connection URLs
- MySQL Connection Strings
### Communication & More
- Slack Tokens
- Discord Bot Tokens
- Stripe API Keys
- JWT Tokens
- Private Keys (RSA, EC, DSA)
- Generic Passwords and Secrets
## 📋 Command Line Options
```bash
usage: git-security-scanner [-h] [-v] [-c CONFIG] [--pre-commit] [--no-history]
[--history-limit N] [--export FILE] [--quiet]
[--min-severity {LOW,MEDIUM,HIGH,CRITICAL}]
[--show-patterns] [--no-color] [--no-progress]
[path]
Detect API keys, passwords, and secrets in Git repositories
positional arguments:
path Path to Git repository (default: current directory)
optional arguments:
-h, --help Show help message
-v, --version Show version
-c, --config Path to config file
--pre-commit Scan only staged files
--no-history Skip commit history scan
--history-limit N Limit history scan to N commits (default: 100)
--export FILE Export findings (.json, .html, .csv, .md)
--quiet Minimal output
--min-severity LEVEL Minimum severity to report
--show-patterns Show all detection patterns
--no-color Disable colored output
--no-progress Disable progress bars
```
## ⚙️ Configuration
### Configuration File
Create `.gitscannerrc.json` or `.gitscannerrc.yaml`:
```json
{
"patterns": {
"custom": [
{
"name": "Company API Key",
"pattern": "COMP-[A-Z0-9]{32}",
"severity": "HIGH",
"description": "Internal company API key"
}
],
"disabled": ["Generic Secret", "Environment Variable"]
},
"scan": {
"history_limit": 50,
"max_file_size_mb": 5,
"parallel_workers": 4
},
"output": {
"format": "console",
"min_severity": "MEDIUM",
"color": true
},
"cache": {
"enabled": true,
"ttl_hours": 48
}
}
```
### Environment Variables
```bash
export SCANNER_HISTORY_LIMIT=25
export SCANNER_MIN_SEVERITY=HIGH
export SCANNER_QUIET=true
export SCANNER_NO_COLOR=true
```
### Ignore Files
Create `.gitscannerignore`:
```
# Ignore test files
tests/
*.test.py
# Ignore vendor directories
vendor/
node_modules/
# Ignore specific files
config.example.json
```
## 🪝 Git Hook Setup
### Pre-commit Hook
```bash
# Install as pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
git-security-scanner --pre-commit
EOF
chmod +x .git/hooks/pre-commit
```
### Using pre-commit Framework
Add to `.pre-commit-config.yaml`:
```yaml
repos:
- repo: local
hooks:
- id: security-scanner
name: Git Security Scanner
entry: git-security-scanner --pre-commit
language: system
pass_filenames: false
```
## 🔄 CI/CD Integration
### GitHub Actions
```yaml
name: Security Scan
on: [push, pull_request]
jobs:
security-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0 # Full history for commit scanning
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install scanner
run: pip install git-security-scanner
- name: Run security scan
run: git-security-scanner --export results.json
- name: Upload results
uses: actions/upload-artifact@v3
if: failure()
with:
name: security-scan-results
path: results.json
```
### GitLab CI
```yaml
security_scan:
stage: test
script:
- pip install git-security-scanner
- git-security-scanner --quiet --export report.html
artifacts:
reports:
expose_as: 'Security Report'
paths: ['report.html']
when: on_failure
```
## 📈 Understanding Results
### Severity Levels
- 🔴 **CRITICAL**: Immediate action required (database credentials, private keys)
- 🟡 **HIGH**: Serious issues (API keys, access tokens)
- 🟣 **MEDIUM**: Should be reviewed (generic secrets, weak patterns)
- 🔵 **LOW**: Minor concerns (environment variables, configuration)
### Example Output
```
=== Scanning working directory ===
Scanning 150 files in working directory...
100%|████████████| 150/150 [00:02<00:00, 68.42files/s]
[CRITICAL] MongoDB Connection
Description: MongoDB Connection String with credentials
File: config/database.py
Line: 15
Secret: mongodb://user:****@localhost:27017/db
[HIGH] GitHub Token
Description: GitHub Personal Access Token
File: .env.example
Line: 3
Secret: ghp_****************************1234
Summary: Found 2 potential secrets:
CRITICAL: 1
HIGH: 1
```
## 🛡️ Best Practices
### If Secrets Are Found
1. **Immediately rotate** the exposed credentials
2. **Remove from history** using `git filter-branch` or BFG Repo-Cleaner
3. **Audit access logs** to check if credentials were compromised
4. **Enable 2FA** where possible
### Prevention
- Use environment variables for sensitive data
- Implement secret management tools (HashiCorp Vault, AWS Secrets Manager)
- Add `.env` files to `.gitignore`
- Use `.gitscannerignore` for false positives
- Run scanner in CI/CD pipelines
- Set up pre-commit hooks
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Thanks to all contributors who have helped improve this tool
- Inspired by similar tools like truffleHog and GitLeaks
- Built with love for the security community
---
**Remember**: Never commit secrets to Git. If you do, rotate them immediately! 🔐
## 📚 Documentation
For detailed documentation, visit our [Wiki](https://github.com/vyacheslavmeyerzon/security-scanner/wiki).
Raw data
{
"_id": null,
"home_page": "https://github.com/vyacheslavmeyerzon/security-scanner",
"name": "git-security-scanner",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "security, git, secrets, scanner, api-keys, passwords, security-tools, devsecops, secret-detection, code-security",
"author": "Vyacheslav Meyerzon",
"author_email": "Vyacheslav Meyerzon <vyacheslav.meyerzon@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/74/1a/94930d7dd7900dd3fa3520d026c02226485313c9648237bb086ec0314fa9/git_security_scanner-0.1.4.tar.gz",
"platform": null,
"description": "# Git Security Scanner\r\n\r\n[](https://pypi.org/project/git-security-scanner/)\r\n[](https://pypi.org/project/git-security-scanner/)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://github.com/vyacheslavmeyerzon/security-scanner/actions/workflows/tests.yml)\r\n\r\nA comprehensive Python tool to detect API keys, passwords, and secrets in Git repositories before they get exposed.\r\n\r\n## \ud83d\ude80 Features\r\n\r\n- **\ud83d\udd0d Detects 25+ Secret Types**: AWS keys, API tokens, passwords, private keys, and more\r\n- **\ud83c\udfaf Multiple Scan Modes**: Staged files, working directory, commit history\r\n- **\u26a1 High Performance**: Parallel scanning with progress bars and caching\r\n- **\ud83d\udcca Rich Reports**: Export to JSON, HTML, CSV, or Markdown\r\n- **\ud83c\udfa8 Customizable**: Add custom patterns, ignore files, configure severity levels\r\n- **\ud83d\udd27 CI/CD Ready**: Pre-commit hooks and pipeline integration\r\n- **\ud83c\udf0d Cross-Platform**: Works on Linux, macOS, and Windows\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\npip install git-security-scanner\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/vyacheslavmeyerzon/security-scanner.git\r\ncd security-scanner\r\npip install -e .\r\n```\r\n\r\n## \ud83d\udd27 Quick Start\r\n\r\n### Basic Scan\r\n\r\nScan your current repository:\r\n\r\n```bash\r\ngit-security-scanner\r\n```\r\n\r\n### Scan Specific Repository\r\n\r\n```bash\r\ngit-security-scanner /path/to/repository\r\n```\r\n\r\n### Pre-commit Mode\r\n\r\nCheck only staged files:\r\n\r\n```bash\r\ngit-security-scanner --pre-commit\r\n```\r\n\r\n### Export Results\r\n\r\n```bash\r\n# JSON format\r\ngit-security-scanner --export results.json\r\n\r\n# HTML report\r\ngit-security-scanner --export report.html\r\n\r\n# CSV format\r\ngit-security-scanner --export findings.csv\r\n\r\n# Markdown report\r\ngit-security-scanner --export report.md\r\n```\r\n\r\n## \ud83c\udfaf What It Detects\r\n\r\n### Cloud Services\r\n- AWS Access Keys and Secret Keys\r\n- Azure Storage Keys\r\n- Google Cloud API Keys and OAuth Tokens\r\n\r\n### AI/ML Platforms\r\n- OpenAI API Keys\r\n- Anthropic (Claude) API Keys\r\n- HuggingFace Tokens\r\n- Cohere API Keys\r\n\r\n### Version Control\r\n- GitHub Personal Access Tokens\r\n- GitLab Access Tokens\r\n- Bitbucket App Passwords\r\n\r\n### Databases\r\n- MongoDB Connection Strings\r\n- PostgreSQL Connection URLs\r\n- MySQL Connection Strings\r\n\r\n### Communication & More\r\n- Slack Tokens\r\n- Discord Bot Tokens\r\n- Stripe API Keys\r\n- JWT Tokens\r\n- Private Keys (RSA, EC, DSA)\r\n- Generic Passwords and Secrets\r\n\r\n## \ud83d\udccb Command Line Options\r\n\r\n```bash\r\nusage: git-security-scanner [-h] [-v] [-c CONFIG] [--pre-commit] [--no-history]\r\n [--history-limit N] [--export FILE] [--quiet]\r\n [--min-severity {LOW,MEDIUM,HIGH,CRITICAL}]\r\n [--show-patterns] [--no-color] [--no-progress]\r\n [path]\r\n\r\nDetect API keys, passwords, and secrets in Git repositories\r\n\r\npositional arguments:\r\n path Path to Git repository (default: current directory)\r\n\r\noptional arguments:\r\n -h, --help Show help message\r\n -v, --version Show version\r\n -c, --config Path to config file\r\n --pre-commit Scan only staged files\r\n --no-history Skip commit history scan\r\n --history-limit N Limit history scan to N commits (default: 100)\r\n --export FILE Export findings (.json, .html, .csv, .md)\r\n --quiet Minimal output\r\n --min-severity LEVEL Minimum severity to report\r\n --show-patterns Show all detection patterns\r\n --no-color Disable colored output\r\n --no-progress Disable progress bars\r\n```\r\n\r\n## \u2699\ufe0f Configuration\r\n\r\n### Configuration File\r\n\r\nCreate `.gitscannerrc.json` or `.gitscannerrc.yaml`:\r\n\r\n```json\r\n{\r\n \"patterns\": {\r\n \"custom\": [\r\n {\r\n \"name\": \"Company API Key\",\r\n \"pattern\": \"COMP-[A-Z0-9]{32}\",\r\n \"severity\": \"HIGH\",\r\n \"description\": \"Internal company API key\"\r\n }\r\n ],\r\n \"disabled\": [\"Generic Secret\", \"Environment Variable\"]\r\n },\r\n \"scan\": {\r\n \"history_limit\": 50,\r\n \"max_file_size_mb\": 5,\r\n \"parallel_workers\": 4\r\n },\r\n \"output\": {\r\n \"format\": \"console\",\r\n \"min_severity\": \"MEDIUM\",\r\n \"color\": true\r\n },\r\n \"cache\": {\r\n \"enabled\": true,\r\n \"ttl_hours\": 48\r\n }\r\n}\r\n```\r\n\r\n### Environment Variables\r\n\r\n```bash\r\nexport SCANNER_HISTORY_LIMIT=25\r\nexport SCANNER_MIN_SEVERITY=HIGH\r\nexport SCANNER_QUIET=true\r\nexport SCANNER_NO_COLOR=true\r\n```\r\n\r\n### Ignore Files\r\n\r\nCreate `.gitscannerignore`:\r\n\r\n```\r\n# Ignore test files\r\ntests/\r\n*.test.py\r\n\r\n# Ignore vendor directories\r\nvendor/\r\nnode_modules/\r\n\r\n# Ignore specific files\r\nconfig.example.json\r\n```\r\n\r\n## \ud83e\ude9d Git Hook Setup\r\n\r\n### Pre-commit Hook\r\n\r\n```bash\r\n# Install as pre-commit hook\r\ncat > .git/hooks/pre-commit << 'EOF'\r\n#!/bin/bash\r\ngit-security-scanner --pre-commit\r\nEOF\r\n\r\nchmod +x .git/hooks/pre-commit\r\n```\r\n\r\n### Using pre-commit Framework\r\n\r\nAdd to `.pre-commit-config.yaml`:\r\n\r\n```yaml\r\nrepos:\r\n - repo: local\r\n hooks:\r\n - id: security-scanner\r\n name: Git Security Scanner\r\n entry: git-security-scanner --pre-commit\r\n language: system\r\n pass_filenames: false\r\n```\r\n\r\n## \ud83d\udd04 CI/CD Integration\r\n\r\n### GitHub Actions\r\n\r\n```yaml\r\nname: Security Scan\r\n\r\non: [push, pull_request]\r\n\r\njobs:\r\n security-scan:\r\n runs-on: ubuntu-latest\r\n steps:\r\n - uses: actions/checkout@v3\r\n with:\r\n fetch-depth: 0 # Full history for commit scanning\r\n \r\n - name: Set up Python\r\n uses: actions/setup-python@v4\r\n with:\r\n python-version: '3.11'\r\n \r\n - name: Install scanner\r\n run: pip install git-security-scanner\r\n \r\n - name: Run security scan\r\n run: git-security-scanner --export results.json\r\n \r\n - name: Upload results\r\n uses: actions/upload-artifact@v3\r\n if: failure()\r\n with:\r\n name: security-scan-results\r\n path: results.json\r\n```\r\n\r\n### GitLab CI\r\n\r\n```yaml\r\nsecurity_scan:\r\n stage: test\r\n script:\r\n - pip install git-security-scanner\r\n - git-security-scanner --quiet --export report.html\r\n artifacts:\r\n reports:\r\n expose_as: 'Security Report'\r\n paths: ['report.html']\r\n when: on_failure\r\n```\r\n\r\n## \ud83d\udcc8 Understanding Results\r\n\r\n### Severity Levels\r\n\r\n- \ud83d\udd34 **CRITICAL**: Immediate action required (database credentials, private keys)\r\n- \ud83d\udfe1 **HIGH**: Serious issues (API keys, access tokens)\r\n- \ud83d\udfe3 **MEDIUM**: Should be reviewed (generic secrets, weak patterns)\r\n- \ud83d\udd35 **LOW**: Minor concerns (environment variables, configuration)\r\n\r\n### Example Output\r\n\r\n```\r\n=== Scanning working directory ===\r\nScanning 150 files in working directory...\r\n100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 150/150 [00:02<00:00, 68.42files/s]\r\n\r\n[CRITICAL] MongoDB Connection\r\n Description: MongoDB Connection String with credentials\r\n File: config/database.py\r\n Line: 15\r\n Secret: mongodb://user:****@localhost:27017/db\r\n\r\n[HIGH] GitHub Token\r\n Description: GitHub Personal Access Token\r\n File: .env.example\r\n Line: 3\r\n Secret: ghp_****************************1234\r\n\r\nSummary: Found 2 potential secrets:\r\n CRITICAL: 1\r\n HIGH: 1\r\n```\r\n\r\n## \ud83d\udee1\ufe0f Best Practices\r\n\r\n### If Secrets Are Found\r\n\r\n1. **Immediately rotate** the exposed credentials\r\n2. **Remove from history** using `git filter-branch` or BFG Repo-Cleaner\r\n3. **Audit access logs** to check if credentials were compromised\r\n4. **Enable 2FA** where possible\r\n\r\n### Prevention\r\n\r\n- Use environment variables for sensitive data\r\n- Implement secret management tools (HashiCorp Vault, AWS Secrets Manager)\r\n- Add `.env` files to `.gitignore`\r\n- Use `.gitscannerignore` for false positives\r\n- Run scanner in CI/CD pipelines\r\n- Set up pre-commit hooks\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n1. Fork the repository\r\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\r\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\r\n4. Push to the branch (`git push origin feature/AmazingFeature`)\r\n5. Open a Pull Request\r\n\r\n## \ud83d\udcdd License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- Thanks to all contributors who have helped improve this tool\r\n- Inspired by similar tools like truffleHog and GitLeaks\r\n- Built with love for the security community\r\n\r\n---\r\n\r\n**Remember**: Never commit secrets to Git. If you do, rotate them immediately! \ud83d\udd10\r\n\r\n## \ud83d\udcda Documentation\r\n\r\nFor detailed documentation, visit our [Wiki](https://github.com/vyacheslavmeyerzon/security-scanner/wiki).\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive tool to detect secrets and sensitive information in Git repositories",
"version": "0.1.4",
"project_urls": {
"Documentation": "https://github.com/vyacheslavmeyerzon/security-scanner/wiki",
"Homepage": "https://github.com/vyacheslavmeyerzon/security-scanner",
"Issues": "https://github.com/vyacheslavmeyerzon/security-scanner/issues",
"Repository": "https://github.com/vyacheslavmeyerzon/security-scanner"
},
"split_keywords": [
"security",
" git",
" secrets",
" scanner",
" api-keys",
" passwords",
" security-tools",
" devsecops",
" secret-detection",
" code-security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "35741fd9d4a6ce7e6324b526fc73716cd95bb06d4978528a58c5fb30da385790",
"md5": "c1ab8e89d187a5d9e5a80ff98c5594cf",
"sha256": "672b93d192cf2716e18193628a93b433157d2b0af25f40a2a841a490d259baf0"
},
"downloads": -1,
"filename": "git_security_scanner-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c1ab8e89d187a5d9e5a80ff98c5594cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32098,
"upload_time": "2025-08-02T09:24:46",
"upload_time_iso_8601": "2025-08-02T09:24:46.245650Z",
"url": "https://files.pythonhosted.org/packages/35/74/1fd9d4a6ce7e6324b526fc73716cd95bb06d4978528a58c5fb30da385790/git_security_scanner-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "741a94930d7dd7900dd3fa3520d026c02226485313c9648237bb086ec0314fa9",
"md5": "e2dea80f9ac36a70502d7ed6215f8760",
"sha256": "38b29cafb49ae31825f8dba19c15428d69071c7bb9f2acfa0f70ad142547335f"
},
"downloads": -1,
"filename": "git_security_scanner-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "e2dea80f9ac36a70502d7ed6215f8760",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 59539,
"upload_time": "2025-08-02T09:24:48",
"upload_time_iso_8601": "2025-08-02T09:24:48.274646Z",
"url": "https://files.pythonhosted.org/packages/74/1a/94930d7dd7900dd3fa3520d026c02226485313c9648237bb086ec0314fa9/git_security_scanner-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 09:24:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vyacheslavmeyerzon",
"github_project": "security-scanner",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "colorama",
"specs": [
[
">=",
"0.4.6"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.65.0"
]
]
}
],
"lcname": "git-security-scanner"
}
JSON
