metadata-scrubber 0.2.0

A privacy-focused CLI tool that removes sensitive metadata from image files

🔒 Metadata Scrubber

A privacy-focused CLI tool that removes sensitive metadata from files. Supports images, PDFs, and Microsoft Office documents. Perfect for protecting your privacy before sharing files online.

✨ Features

• Multi-format support - Images (JPEG, PNG), PDFs, and Office docs (Word, Excel, PowerPoint)
• Concurrent processing - Process 1000+ files efficiently with ThreadPoolExecutor
• Dry-run mode - Preview what would be scrubbed without making changes
• Smart format detection - Uses library-level format detection, not just file extensions
• Beautiful CLI - Rich progress bars and formatted output
• Privacy-first - Removes GPS coordinates, author info, timestamps, camera data

📁 Supported Formats

Category	Extensions	Metadata Removed
Images	.jpg, .jpeg, .png	EXIF, GPS, camera info, timestamps
PDF	.pdf	Author, creator, producer, dates
Word	.docx	Author, title, comments, keywords
Excel	.xlsx, .xlsm, .xltx, .xltm	Author, title, company, comments
PowerPoint	.pptx, .pptm, .potx, .potm	Author, title, comments, keywords

🚀 Quick Start

Installation

# Using uv (recommended)
uv pip install metadata-scrubber

# Or clone and install locally
git clone https://github.com/Heritage-XioN/metadata-scrubber-tool.git
cd metadata-scrubber-tool
uv sync

Basic Usage

# Read metadata from a file
mst read document.pdf

# Scrub metadata and save to output folder
mst scrub photo.jpg --output ./cleaned

# Batch process entire folder
mst scrub ./documents -r -ext docx --output ./cleaned

📖 Commands

mst read - View Metadata

mst read photo.jpg                      # Single file
mst read report.pdf                     # PDF file
mst read ./docs -r -ext docx            # All Word docs recursively

mst scrub - Remove Metadata

mst scrub photo.jpg --output ./out      # Single file
mst scrub ./photos -r -ext jpg -o ./out # All JPEGs in directory
mst scrub ./docs -r -ext pdf --dry-run  # Preview PDF scrubbing
mst scrub ./files -r -ext xlsx -w 8     # 8 concurrent workers

CLI Options

Option	Description
-r, --recursive	Process directories recursively
-ext, --extension	Filter by file extension
-o, --output	Output directory for cleaned files
-d, --dry-run	Preview without making changes
-w, --workers	Number of concurrent workers
-V, --verbose	Show detailed debug logs
-v, --version	Show version

🛠️ Development

Setup

git clone https://github.com/Heritage-XioN/metadata-scrubber-tool.git
cd metadata-scrubber-tool

# Install with dev dependencies
uv sync --all-extras

# Run tests
pytest

# Run linting
ruff check .

# Run type checking
mypy src

Project Structure

src/
├── main.py                 # CLI entry point (Typer app)
├── commands/
│   ├── read.py             # Read metadata command
│   └── scrub.py            # Scrub metadata command
├── services/
│   ├── metadata_factory.py # Factory for creating handlers
│   ├── metadata_handler.py # Abstract base class
│   ├── image_handler.py    # JPEG/PNG handler
│   ├── pdf_handler.py      # PDF handler
│   ├── excel_handler.py    # Excel handler
│   ├── powerpoint_handler.py # PowerPoint handler
│   ├── worddoc_handler.py  # Word document handler
│   └── batch_processor.py  # Concurrent batch processing
└── core/
    ├── jpeg_metadata.py    # JPEG EXIF processor
    └── png_metadata.py     # PNG metadata processor

⚠️ Security Considerations

• Original files are never modified - processed copies are created
• Use --dry-run to preview changes before committing
• GPS coordinates are completely stripped for privacy
• Author information is removed from all supported formats
• Always backup files before scrubbing in production

📄 License

MIT License - See LICENSE for details.

---

Made with ❤️ for privacy