S3 Versioned Object Recovery Tool

A specialized disaster recovery utility designed to restore accidentally deleted objects from AWS S3 versioned buckets. The tool intelligently identifies and recovers the most recent valid version of each object, bypassing delete markers and handling bulk restoration operations efficiently.

Key Features

• Smart Version Detection - Automatically identifies the latest non-deleted version of objects, skipping delete markers
• Bulk Recovery Operations - Processes multiple S3 URLs from a single input file for efficient batch restoration
• URL-based Input - Accepts S3 URLs in any format, automatically extracting bucket and key information
• Regex-based Parsing - Robust URL parsing that handles various S3 URL formats and edge cases
• Safe Restoration Method - Uses S3 copy-object operations to restore previous versions without data loss
• Error Resilience - Continues processing remaining objects even if individual restorations fail
• Environment Configuration - Flexible AWS region and credential management via environment variables
• Comprehensive Logging - Detailed console output for monitoring restoration progress and debugging

Technical Implementation

Built with Python 3.12 and boto3, leveraging AWS S3’s versioning capabilities for data recovery. The tool uses the list_object_versions API to discover all versions of an object, then intelligently filters to find the most recent non-delete-marker version.

The restoration process uses S3’s copy_object operation with the VersionId parameter to promote an older version back to the current state. This approach is safer than alternative methods because it creates a new version rather than permanently deleting the delete marker.

The project uses uv as the package manager for faster dependency resolution and installation compared to traditional pip workflows. Environment configuration is handled through python-dotenv, allowing secure credential management without hardcoding sensitive information.

Architecture Highlights

• Sequential Processing - Processes URLs one at a time to avoid API throttling and improve observability
• Graceful Degradation - Individual failures don’t halt the entire restoration job
• Regex Pattern Matching - Flexible URL parsing supporting various S3 URL structures
• Version-aware Logic - Understands S3’s delete marker behavior and version lifecycle

Use Cases

Ideal for scenarios requiring:

• Disaster Recovery - Quickly restore accidentally deleted production assets
• Bulk Undelete Operations - Recover multiple objects deleted in error (user actions, automation bugs)
• Version Rollback - Revert objects to previous states after unwanted updates
• Data Forensics - Investigate and recover specific versions of objects
• Migration Recovery - Restore data after failed migration or cleanup operations
• Emergency Response - Provide rapid recovery capability for critical business assets

Real-World Application

This tool was developed to address a critical business need at Dejavu CRM, where product images stored in S3 were accidentally deleted. The utility successfully restored 38 deleted images by identifying their previous versions from a versioned S3 bucket, preventing data loss and business disruption.

The ability to process bulk URLs from a file made it possible to restore all affected assets in a single operation, reducing recovery time from hours to minutes. The tool’s error handling ensured that any problematic objects didn’t block the restoration of others.

Development Status

Production-ready and battle-tested in real disaster recovery scenarios. The tool can be easily adapted for different S3 buckets and object path structures by modifying the configuration constants.