README

Screenshot Guard

🔐 Secret Scanner with OCR Superpowers

The first secret scanner that finds secrets in code AND screenshots.


_{Powered by german-ocr}

🚨 The Problem

Developers take screenshots. Screenshots of terminals, dashboards, documentation.

And sometimes those screenshots contain secrets:

Regular secret scanners miss all of this.

💡 The Solution

Screenshot Guard scans your code AND your images using OCR.

# Install
pip install screenshot-guard[ocr]

# Scan
screenshot-guard scan ./your-project

✨ Features

📦 Installation

pip install screenshot-guard[ocr]

npm install screenshot-guard

composer require keyvan/screenshot-guard

Python Installation Options

💡 Note: You don't need to install german-ocr separately - it comes automatically with [ocr]!

⚡ Quick Start

💻 CLI Usage

# Scan current directory
screenshot-guard scan .

# Scan with JSON output
screenshot-guard scan ./src --format json --output report.json

# Only critical and high severity
screenshot-guard scan . --severity high

# Disable OCR (faster, but misses images)
screenshot-guard scan . --no-ocr

# Use Ollama backend for OCR
screenshot-guard scan . --backend ollama

🤖 GitHub Action

name: Security Scan

on: [push, pull_request]

jobs:
  secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan for secrets
        uses: Keyvanhardani/screenshot-guard@v1
        with:
          path: '.'
          severity: 'medium'
          ocr: 'true'
          fail-on-findings: 'true'

🪝 Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Keyvanhardani/screenshot-guard
    rev: v0.1.0
    hooks:
      - id: screenshot-guard
        args: ['--severity', 'high', '--no-ocr']

🎯 Supported Patterns

Provider	Patterns	Examples
	5	Access Keys, Secret Keys, Session Tokens
	5	Storage Keys, Connection Strings, SAS Tokens
	5	API Keys, Service Accounts, OAuth Secrets
	6	PATs, OAuth Tokens, App Private Keys
	2	Bot Tokens, Webhooks
	2	Secret Keys, Restricted Keys
🔐 Generic	15+	Passwords, Private Keys, JWTs, Database URLs

# List all patterns
screenshot-guard patterns

📊 Output Formats

Table (default)

┌──────────────────┬──────┬────────────────────┬──────────┬────────┐
│ File             │ Line │ Type               │ Severity │ Source │
├──────────────────┼──────┼────────────────────┼──────────┼────────┤
│ screenshot.png   │ 3    │ AWS Access Key ID  │ CRITICAL │ OCR    │
│ config.yaml      │ 12   │ Database URL       │ CRITICAL │ Text   │
└──────────────────┴──────┴────────────────────┴──────────┴────────┘

Export Options

🔧 OCR Backends

# Use specific backend
screenshot-guard scan . --backend llamacpp
screenshot-guard scan . --backend ollama

🔌 API Usage

from screenshot_guard import Scanner, SecretDetector, OCREngine

# Initialize
detector = SecretDetector(min_severity="high")
ocr = OCREngine(backend="llamacpp")
scanner = Scanner(detector=detector, ocr_engine=ocr)

# Scan
findings = scanner.scan("./your-project")

for finding in findings:
    print(f"{finding.file_path}:{finding.line_number} - {finding.pattern_name}")
    print(f"  Severity: {finding.severity}")
    print(f"  From OCR: {finding.from_ocr}")

const { scan } = require('screenshot-guard');

// Scan a directory
const findings = await scan({
  path: './your-project',
  severity: 'high',
  ocr: true
});

findings.forEach(finding => {
  console.log(`${finding.file}:${finding.line} - ${finding.type}`);
  console.log(`  Severity: ${finding.severity}`);
});

use ScreenshotGuard\Client;

$guard = new Client();
$findings = $guard->scan('./your-project', [
    'severity' => 'high'
]);

foreach ($findings as $finding) {
    echo "{$finding['file_path']}:{$finding['line_number']} - {$finding['pattern_name']}\n";
}

🙈 Ignoring Files

Create .screenshotguardignore in your project root:

# Ignore test fixtures
tests/fixtures/*

# Ignore vendor
vendor/

# Ignore specific files
docs/example-config.yaml

😱 Why OCR?

Real examples where OCR would have helped:

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

📄 License

Apache 2.0 - see LICENSE

👤 Author

Keyvan Hardani

Made with ❤️ for security

⭐ Star us on GitHub!