Screenshot Guard

Secret Scanner with OCR Superpowers

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

The Problem

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

And sometimes those screenshots contain secrets:

• AWS keys in terminal output
• API tokens in dashboard screenshots
• "Example" credentials that are actually real

Regular secret scanners miss all of this.

The Solution

Screenshot Guard scans your code AND your images using OCR powered by german-ocr.

# Install
pip install screenshot-guard[ocr]

# Scan
screenshot-guard scan ./your-project

Features

• OCR-powered - Finds secrets in PNG, JPG, GIF, BMP, WebP images
• 50+ patterns - AWS, Azure, GCP, GitHub, Stripe, Slack, and more
• Local processing - No cloud, no data leaves your machine
• GitHub Action - Easy CI/CD integration with SARIF support
• Pre-commit hook - Catch secrets before they're committed

Quick Start

Installation

# Basic (no OCR)
pip install screenshot-guard

# With OCR support (recommended)
pip install screenshot-guard[ocr]

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: v1.0.0
    hooks:
      - id: screenshot-guard
        args: ['--severity', 'high', '--no-ocr']  # OCR in pre-commit is slow

Supported Patterns

# 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   │
└──────────────────┴──────┴────────────────────┴──────────┴────────┘

JSON

screenshot-guard scan . --format json --output report.json

SARIF (GitHub Security)

screenshot-guard scan . --format sarif --output results.sarif

Markdown

screenshot-guard scan . --format markdown --output report.md

OCR Backends

Screenshot Guard uses german-ocr for image analysis:

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

Ignoring Files

Create .screenshotguardignore in your project root:

# Ignore test fixtures
tests/fixtures/*

# Ignore vendor
vendor/

# Ignore specific files
docs/example-config.yaml

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}")

Why OCR?

Real examples where OCR would have helped:

1. Terminal screenshot committed to docs

   • AWS Access Key visible in output
   • Cost: $47,000 cloud bill

2. Dashboard screenshot in README

   • "Example" API key was actually real
   • Exposed for 2 months

3. Slack screenshot in GitHub issue

   • GitHub token visible in chat
   • Repository compromised

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

License

Apache 2.0 - see LICENSE

Author

Keyvan Hardani

• Website: keyvan.ai
• GitHub: @Keyvanhardani
• HuggingFace: Keyven

If this tool helped you, please star the repo!