Building 70 Projects ranging from beginner to advanced so anyone can β learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company π
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
metadata-scrubber-tool: refactored buggy implementation. png processing supports reading EXIF and pngInfo and not-serialized-to-human-readable-format data but not XMP OR IPTC.
HERITAGE-XION5aa7e1d01dba
diff --git a/src/commands/read.py b/src/commands/read.pyindex eb50d502..fb45e69b 100644--- a/src/commands/read.py+++ b/src/commands/read.py@@ -43,19 +43,19 @@ def get_metadata(handler = MetadataFactory.get_handler(str(file))# Read- console.print(f"π Processing [bold cyan]{file.name}[/bold cyan]...")+ console.print(f"π Reading [bold cyan]{file.name}[/bold cyan]...")current_data = handler.read()if log.isEnabledFor(logging.DEBUG):# if verbose mode is enabled, log the Info- log.info(f"Successfully read metadata from {file_path.name}")+ log.info(f"Successfully read metadata from {file.name}")print_metadata_table(current_data)except Exception as e:# display error in console- console.print(f"β [bold red]Skipped[/bold red] [cyan]{file_path.name}[/cyan]: [dim]{e}[/dim]")+ console.print(f"β [bold red]Skipped[/bold red] [cyan]{file.name}[/cyan]: [dim]{e}[/dim]")# LOG: Full technical details (Stack trace) for you to debugif log.isEnabledFor(logging.DEBUG):# if verbose mode is enabled, log the traceback- log.error(f"Failed to process {file_path}", exc_info=True)+ log.error(f"Failed to read metadata from {file}", exc_info=True)diff --git a/src/core/png_metadata.py b/src/core/png_metadata.pyindex 8d00fd08..f240a472 100644--- a/src/core/png_metadata.py+++ b/src/core/png_metadata.py@@ -1,11 +1,15 @@"""PNG metadata processor using PIL.-This module provides the PngProcessor class which handles EXIF metadata-extraction and manipulation for PNG images using PIL's built-in EXIF support.+This module provides the PngProcessor class which handles metadata+extraction and manipulation for PNG images, including both EXIF data+and PNG textual metadata (PngInfo chunks)."""-from PIL import ExifTags+from typing import Any, Dict, List, Optional++from PIL import ExifTags, PngImagePlugin+from PIL.Image import Exif, Imagefrom src.utils.exceptions import MetadataNotFoundError, MetadataProcessingError@@ -14,71 +18,110 @@ class PngProcessor:"""Processor for PNG image metadata.- Handles reading, extracting, and deleting EXIF metadata from PNG files.- Processes both standard EXIF tags and GPS IFD data.+ Handles reading, extracting, and deleting metadata from PNG files.+ Processes both EXIF data and PNG textual chunks (PngInfo).Attributes:tags_to_delete: List of EXIF tag IDs to remove.+ text_keys_to_delete: List of PngInfo text keys to remove.data: Dict of extracted metadata with human-readable keys."""+ # Privacy-sensitive PNG text keys to remove+ SENSITIVE_TEXT_KEYS = {+ "Author",+ "Comment",+ "Copyright",+ "Creation Time",+ "Description",+ "Disclaimer",+ "Software",+ "Source",+ "Title",+ "Warning",+ "XML:com.adobe.xmp", # XMP metadata+ }+def __init__(self):"""Initialize the PNG processor with empty data structures."""- self.tags_to_delete = []- self.data = {}+ self.tags_to_delete: List[int] = []+ self.text_keys_to_delete: List[str] = []+ self.data: Dict[str, Any] = {}- def get_metadata(self, img):+ def get_metadata(self, img: Image) -> Dict[str, Any]:"""- Extract EXIF metadata from a PNG image.+ Extract metadata from a PNG image.++ Extracts both EXIF data (if present) and PNG textual chunks (PngInfo).Args:img: PIL Image object.Returns:- Dict with 'data' (metadata dict) and 'tags_to_delete' (tag IDs list).+ Dict with 'data' (metadata dict), 'tags_to_delete' (EXIF tag IDs),+ and 'text_keys' (PngInfo keys to remove).Raises:- MetadataNotFoundError: If no EXIF data is found in the image.+ MetadataNotFoundError: If no metadata is found in the image."""img.load()- exif = img.getexif()-- if not exif:- raise MetadataNotFoundError("No EXIF data found in the image.")-- # Iterate through the (0th) IFD- for tag, value in exif.items():- # Get the human-readable name for the tag- tag_name = ExifTags.TAGS.get(tag, tag)-- # Save to list and dict- self.tags_to_delete.append(tag)- self.data[tag_name] = value- print(f"{tag_name}: {value}")+ found_metadata = False- # Iterate through the (GPS) IFD- gps_ifd = exif.get_ifd(ExifTags.IFD.GPSInfo)- for tag, value in gps_ifd.items():- # Get the human-readable name for the tag- tag_name = ExifTags.GPSTAGS.get(tag, tag)-- # Save to list and dict- self.tags_to_delete.append(tag)- self.data[tag_name] = value- print(f"{tag_name}: {value}")-- return {"data": self.data, "tags_to_delete": self.tags_to_delete}-- def delete_metadata(self, img, tags_to_delete):+ # Extract EXIF data (if present)+ exif = img.getexif()+ if exif:+ found_metadata = True+ # Main IFD+ for tag, value in exif.items():+ tag_name = ExifTags.TAGS.get(tag, f"Tag_{tag}")+ self.tags_to_delete.append(tag)+ self.data[f"EXIF:{tag_name}"] = value++ # GPS IFD+ gps_ifd = exif.get_ifd(ExifTags.IFD.GPSInfo)+ for tag, value in gps_ifd.items():+ tag_name = ExifTags.GPSTAGS.get(tag, f"GPSTag_{tag}")+ self.tags_to_delete.append(tag)+ self.data[f"GPS:{tag_name}"] = value++ # Extract PNG textual metadata (PngInfo chunks)+ if hasattr(img, "info") and img.info:+ for key, value in img.info.items():+ # Skip binary/internal data+ if key in ("icc_profile", "exif", "transparency", "gamma"):+ continue++ if isinstance(value, (str, bytes)):+ found_metadata = True+ if isinstance(value, bytes):+ try:+ value = value.decode("utf-8", errors="replace")+ except Exception:+ value = str(value)++ self.data[f"PNG:{key}"] = value+ if isinstance(key, str): # Only add string keys+ self.text_keys_to_delete.append(key)++ if not found_metadata:+ raise MetadataNotFoundError("No metadata found in the PNG image.")++ return {+ "data": self.data,+ "tags_to_delete": self.tags_to_delete,+ "text_keys": self.text_keys_to_delete,+ }++ def delete_metadata(self, img: Image, tags_to_delete: List[int]) -> Exif:"""- Remove specified EXIF tags from a PNG image.+ Remove EXIF tags from a PNG image.Args:img: PIL Image object.- tags_to_delete: List of tag IDs to remove.+ tags_to_delete: List of EXIF tag IDs to remove.Returns:- Modified EXIF data with specified tags removed.+ Mutated Exif object with specified tags removed.Raises:MetadataProcessingError: If an error occurs during processing.@@ -86,17 +129,53 @@ class PngProcessor:img.load()exif = img.getexif()try:- # Iterate through the (0th) IFD- for tag_id, value in exif.items():+ # Delete tags from main IFD (iterate over copy of keys)+ for tag_id in list(exif.keys()):if tag_id in tags_to_delete:del exif[tag_id]- # Iterate through the (GPS) IFD+ # Clear GPS IFD entirely (privacy-sensitive)gps_ifd = exif.get_ifd(ExifTags.IFD.GPSInfo)- for tag_id, value in gps_ifd.items():- if tag_id in tags_to_delete:- del gps_ifd[tag_id]+ gps_ifd.clear()- return exif + gps_ifd+ return exifexcept Exception as e:- raise MetadataProcessingError(f"Error Processing image: {str(e)}")+ raise MetadataProcessingError(f"Error processing PNG EXIF: {str(e)}")++ def get_clean_pnginfo(+ self, img: Image, keys_to_remove: Optional[List[str]] = None+ ) -> Optional[PngImagePlugin.PngInfo]:+ """+ Create a new PngInfo with sensitive keys removed.++ Args:+ img: PIL Image object.+ keys_to_remove: Specific keys to remove. If None, removes all sensitive keys.++ Returns:+ New PngInfo object with only safe metadata, or None if no safe metadata.+ """+ if not hasattr(img, "info") or not img.info:+ return None++ keys_to_remove = keys_to_remove or list(self.text_keys_to_delete)++ # Create new PngInfo with only safe keys+ pnginfo = PngImagePlugin.PngInfo()+ has_safe_data = False++ for key, value in img.info.items():+ # Skip keys to remove+ if key in keys_to_remove:+ continue++ # Skip binary/internal data+ if key in ("icc_profile", "exif", "transparency", "gamma"):+ continue++ # Only include text data with string keys+ if isinstance(key, str) and isinstance(value, str):+ pnginfo.add_text(key, value)+ has_safe_data = True++ return pnginfo if has_safe_data else Nonediff --git a/src/services/batch_processor.py b/src/services/batch_processor.pyindex de90d503..cb5eed82 100644--- a/src/services/batch_processor.py+++ b/src/services/batch_processor.py@@ -92,6 +92,8 @@ class BatchProcessor:Returns:FileResult with success status and details."""+ output_path: Optional[Path] = None # Track reserved path for cleanup+try:# Dry-run mode: just report what would happenif self.dry_run:@@ -131,6 +133,9 @@ class BatchProcessor:return resultexcept Exception as e:+ # Cleanup: remove empty placeholder file if reservation failed+ self._cleanup_reserved_path(output_path)+result = FileResult(filepath=file,success=False,@@ -223,6 +228,28 @@ class BatchProcessor:with self._results_lock:self.results.append(result)+ def _cleanup_reserved_path(self, output_path: Optional[Path]) -> None:+ """+ Remove empty placeholder file created during path reservation.++ Called when processing fails after _get_unique_output_path() reserved+ a path via touch(). Only removes files that are empty (0 bytes) to+ avoid deleting partially written data.++ Args:+ output_path: Path that was reserved, or None if not yet reserved.+ """+ if output_path is None:+ return++ try:+ if output_path.exists() and output_path.stat().st_size == 0:+ output_path.unlink()+ log.debug(f"Cleaned up empty placeholder: {output_path}")+ except OSError:+ # Best effort cleanup - don't fail if we can't delete+ pass+def _get_unique_output_path(self, file: Path) -> Path:"""Generate unique output path with suffix (_1, _2) if file exists.diff --git a/src/services/image_handler.py b/src/services/image_handler.pyindex 1134ffa2..0259d501 100644--- a/src/services/image_handler.py+++ b/src/services/image_handler.py@@ -16,6 +16,14 @@ from PIL import Imagefrom src.core.jpeg_metadata import JpegProcessorfrom src.core.png_metadata import PngProcessorfrom src.services.metadata_handler import MetadataHandler+from src.utils.exceptions import UnsupportedFormatError++# Map Pillow format names to processor keys+FORMAT_MAP = {+ "jpeg": "jpeg",+ "jpg": "jpeg",+ "png": "png",+}class ImageHandler(MetadataHandler):@@ -23,11 +31,13 @@ class ImageHandler(MetadataHandler):Metadata handler for image files (JPEG, PNG).Implements the MetadataHandler interface using format-specific processors- to read, wipe, and save image metadata. Uses piexif for EXIF manipulation.+ to read, wipe, and save image metadata. Uses Pillow's format detection+ to handle files with incorrect extensions.Attributes:- processors: Dict mapping file extensions to processor instances.+ processors: Dict mapping format names to processor instances.tags_to_delete: List of EXIF tags to remove during wipe operation.+ detected_format: Actual image format detected by Pillow."""def __init__(self, filepath: str):@@ -39,57 +49,121 @@ class ImageHandler(MetadataHandler):"""super().__init__(filepath)self.processors = {- ".jpeg": JpegProcessor(),- ".jpg": JpegProcessor(),- ".png": PngProcessor(),+ "jpeg": JpegProcessor(),+ "png": PngProcessor(),}self.tags_to_delete = []+ self.detected_format: Optional[str] = None+ self.text_keys_to_delete = []- def read(self):- """Extract metadata from the file."""+ def _detect_format(self) -> str:+ """+ Detect actual image format using Pillow, not file extension.++ This protects against misnamed files (e.g., a PNG saved as .jpg).++ Returns:+ Normalized format string ('jpeg' or 'png').++ Raises:+ UnsupportedFormatError: If format is not supported or undetectable.+ """with Image.open(Path(self.filepath)) as img:- extension = Path(self.filepath).suffix- processor = self.processors.get(extension)+ if img.format is None:+ raise UnsupportedFormatError(+ f"Could not detect format for: {self.filepath}"+ )++ pillow_format = img.format.lower()+ normalized = FORMAT_MAP.get(pillow_format)++ if normalized is None:+ raise UnsupportedFormatError(+ f"Unsupported format: {pillow_format} (file: {self.filepath})"+ )- if not processor:- raise ValueError(f"Unsupported format: {extension}")+ return normalized++ def read(self):+ """+ Extract metadata from the file.- self.metadata = processor.get_metadata(img)["data"]- self.tags_to_delete = processor.get_metadata(img)["tags_to_delete"]+ Uses actual format detection to select the appropriate processor.+ """+ self.detected_format = self._detect_format()+ processor = self.processors.get(self.detected_format)++ if not processor:+ raise UnsupportedFormatError(f"Unsupported format: {self.detected_format}")++ with Image.open(Path(self.filepath)) as img:+ result = processor.get_metadata(img)+ self.metadata = result["data"]+ self.tags_to_delete = result["tags_to_delete"]+ # Store text keys for PNG processing+ self.text_keys_to_delete = result.get("text_keys", [])return self.metadatadef wipe(self) -> None:- """Wipes internal metadata state."""- with Image.open(Path(self.filepath)) as img:- extension = Path(self.filepath).suffix- processor = self.processors.get(extension)+ """+ Remove privacy-sensitive metadata from the file.- if not processor:- raise ValueError(f"Unsupported format: {extension}")+ Uses actual format detection to select the appropriate processor.+ """+ # Use cached format if available, otherwise detect+ if not self.detected_format:+ self.detected_format = self._detect_format()++ processor = self.processors.get(self.detected_format)++ if not processor:+ raise UnsupportedFormatError(f"Unsupported format: {self.detected_format}")+ with Image.open(Path(self.filepath)) as img:self.processed_metadata = processor.delete_metadata(img, self.tags_to_delete)+ # For PNG, also get clean PngInfo+ if self.detected_format == "png" and hasattr(+ processor, "get_clean_pnginfo"+ ):+ self.clean_pnginfo = processor.get_clean_pnginfo(+ img, self.text_keys_to_delete+ )def save(self, output_path: Optional[str] = None) -> None:"""Writes the changes to a copy of the original file.+ Handles format-specific saving:+ - JPEG: Uses piexif to write cleaned EXIF data+ - PNG: Saves without EXIF and strips textual metadata+Args:- output_path: Can be a directory path (legacy behavior) or a full file path.- If a directory, generates filename as 'processed_{original_name}'.- If a file path, uses it directly.+ output_path: Full path to the destination file."""- destination_file_path = ""- if output_path:- # setup the destination directory.- # which was created by the batch_processor- destination_file_path = Path(output_path)-- # copies the original file to the destination directory- shutil.copy2(self.filepath, destination_file_path)-- # writes the processed metadata to the image in the destination directory- with Image.open(destination_file_path) as img:- exif_bytes = piexif.dump(self.processed_metadata)- img.save(destination_file_path, exif=exif_bytes)+ destination_file_path = Path(output_path) if output_path else None++ if not destination_file_path:+ raise ValueError("output_path is required")++ # Use detected format (falls back to extension if not detected)+ actual_format = self.detected_format or self._detect_format()++ if actual_format == "jpeg":+ # JPEG: Copy then write cleaned EXIF data+ shutil.copy2(self.filepath, destination_file_path)+ with Image.open(destination_file_path) as img:+ exif_bytes = piexif.dump(self.processed_metadata)+ img.save(destination_file_path, exif=exif_bytes)+ elif actual_format == "png":+ # PNG: Open original, save fresh copy without metadata+ with Image.open(Path(self.filepath)) as img:+ # Save without exif and without pnginfo to strip all metadata+ # Preserve image mode and data integrity+ img.save(+ destination_file_path,+ format="PNG",+ exif=None,+ pnginfo=getattr(self, "clean_pnginfo", None),+ )diff --git a/src/services/metadata_factory.py b/src/services/metadata_factory.pyindex 3502aebf..27089b17 100644--- a/src/services/metadata_factory.py+++ b/src/services/metadata_factory.py@@ -9,6 +9,7 @@ extensibility for supporting new file formats (PDF, Office docs, etc.).from pathlib import Pathfrom src.services.image_handler import ImageHandler+from src.utils.exceptions import UnsupportedFormatErrorclass MetadataFactory:@@ -36,8 +37,8 @@ class MetadataFactory:MetadataHandler: An instance of the appropriate handler subclass.Raises:- ValueError: If no handler is defined for the file type or- if the path is not a valid file.+ UnsupportedFormatError: If no handler is defined for the file type.+ ValueError: If the path is not a valid file."""ext = Path(filepath).suffix.lower()if Path(filepath).is_file():@@ -52,7 +53,7 @@ class MetadataFactory:# elif ext == ".pptx":# return PowerPointHandler(filepath)else:- raise ValueError(f"No handler defined for {ext} files.")+ raise UnsupportedFormatError(f"No handler defined for {ext} files.")else:raise ValueError(f"{filepath} is not a file. if you want to process a directory, use the --recursive flag."diff --git a/src/utils/get_target_files.py b/src/utils/get_target_files.pyindex 12b84c6c..89a3d9b8 100644--- a/src/utils/get_target_files.py+++ b/src/utils/get_target_files.py@@ -13,16 +13,19 @@ def get_target_files(input_path_str: Path, ext: str) -> Generator[Path, None, No"""Yield files to process based on input path and extension filter.- Recursively searches the input directory for files matching the- specified extension.+ Handles both directories (recursive search) and single files (defensive).Args:- input_path_str: Path object pointing to the target directory.+ input_path_str: Path object pointing to a file or directory.ext: File extension to filter by (without dot, e.g., 'jpg').Yields:Path objects for each matching file found."""- # If input is a directory, yield all files with the specified extensionif input_path_str.is_dir():- yield from input_path_str.rglob(f"*.{ext}")+ # Directory: recursively yield all files with the specified extension+ yield from input_path_str.rglob(f"*.{ext.lower()}")+ elif input_path_str.is_file():+ # Defensive: if a file is passed, yield it if extension matches+ if input_path_str.suffix.lstrip(".").lower() == ext.lower():+ yield input_path_str