README.md

June 16, 2026 · View on GitHub

PyShadow — Python ShadowCopy Analyzer & VHDX Export Tool

PyPI

A powerful Windows-only Python toolkit for cybersecurity researchers and forensic analysts.

Interact with Microsoft Volume Shadow Copy Service (VSS) to list, create, mount, and extract files from Shadow Copies—ideal for incident response, ransomware recovery, and forensic investigations.

Features • Installation • Usage • Examples • CLI • API

Overview

PyShadow provides a Pythonic interface to Windows Volume Shadow Copy Service (VSS), enabling security professionals and forensic analysts to:

🔍 Investigate system states at different points in time
📁 Recover deleted or encrypted files from shadow copies
💾 Export entire shadow copies to VHDX format for offline analysis
🛡️ Analyze malware and ransomware artifacts
🔧 Automate incident response workflows

⚠️ Disclaimer: This tool is for educational and lawful use only. Do not use on systems without authorization.

🚀 Features

Core VSS Operations

✅ List Shadow Copies — Enumerate all shadow copies on the local system
✅ Create Shadow Copies — Programmatically create new VSS snapshots
✅ Mount Shadow Copies — Access shadow copies via symlinks or named pipes
✅ Browse Contents — List directories and files within shadow copies
✅ Recover Files — Extract specific files to a destination location

VHDX Export (NEW!)

🆕 Export to VHDX — Export entire shadow copies to VHDX virtual disk format
🆕 Automatic File Copy — Recursively copy all files with progress tracking
🆕 Smart Sizing — Dynamic VHDX sizing based on source volume
🆕 Drive Selection — Automatic available drive letter detection
🆕 Error Recovery — Comprehensive error handling and reporting
🆕 Space Validation — Pre-check disk space before export

Advanced Features

🔐 Permission Handling — Automatic permission management for protected files
🧹 Cleanup — Safe symlink and drive removal
📊 Progress Reporting — Real-time status updates during operations

📦 Installation

Via PyPI

pip install pyshadow

From Source

git clone https://github.com/alicangnll/pyshadow
cd pyshadow
pip install -r requirements.txt
python setup.py install

Dependencies

pip install pywin32

Full dependencies: See requirements.txt

⚡ Quick Start

Interactive CLI

python example.py

This launches an interactive menu for all operations.

Python Script

from src.reshadow import ReShadowCode

# List all shadow copies
shadows = ReShadowCode.VSS_ListShadows()
for shadow in shadows:
    print(f"ID: {shadow['id']}")
    print(f"Created: {shadow['creation_time']}")
    print(f"Location: {shadow['shadowcopy']}\n")

📖 Usage Examples

Listing Shadow Copies

from src.reshadow import ReShadowCode

shadows = ReShadowCode.VSS_ListShadows()
for s in shadows:
    print(f"ID: {s['id']}\nCreated: {s['creation_time']}\nLocation: {s['shadowcopy']}\n")

Creating a New Shadow Copy

from src.reshadow import ReShadowCode

shadow_id = ReShadowCode.VSS_Create()
print(f"Created shadow copy: {shadow_id}")

Mounting a Shadow Copy

from src.reshadow import ReShadowCode

# Create a symlink to access the shadow copy
ReShadowCode.VSS_Create_Pipe(
    "C:\\ShadowMount",
    "{shadow-copy-id}"
)

# Now you can browse C:\ShadowMount like a regular folder

Recovering a Specific File

from src.reshadow import ReShadowCode

# 1. Mount the shadow copy
ReShadowCode.VSS_Create_Pipe("C:\\ShadowMount", "{shadow-copy-id}")

# 2. Copy the file
ReShadowCode.VSS_CopyFile(
    "C:\\ShadowMount\\Users\\User\\Documents\\important.docx",
    "C:\\Recovery\\important.docx"
)

# 3. Clean up
ReShadowCode.VSS_RemoveSymlink("C:\\ShadowMount")

Exporting to VHDX (NEW!)

from src.reshadow import ReShadowCode

# Manual export — creates VHDX, you copy files manually
ReShadowCode.VSS_ExportToVHD(
    shadow_copy_id="{shadow-copy-id}",
    vhd_path="D:\\VHDExports",
    vhd_name="backup.vhdx"
)

# Automatic export — copies all files recursively
ReShadowCode.VSS_ExportToVHD_AutoCopy(
    shadow_copy_id="{shadow-copy-id}",
    vhd_path="D:\\VHDExports",
    vhd_name="backup.vhdx",
    target_drive=None  # Auto-selects available drive (Z:, Y:, etc.)
)

VHDX Export Features:

🔍 Automatic drive detection — Finds available drive letters
📏 Smart sizing — Matches source volume size
📁 Recursive copy — Captures entire directory structure
⚠️ Space validation — Checks available disk space before export
🔄 Error recovery — Continues on individual file failures
📊 Progress tracking — Real-time copy statistics

Run python example.py to access the interactive interface:

=============================================================
 pyShadow - The ShadowCopy Extractor / File Rescue Tool
 Version 1.0.0 | (c) 2024, Reshadow
=============================================================
 1. Rescue File from ShadowCopy
 2. Create Pipe / Symlink for ShadowCopy
 3. List ShadowCopies
 4. Create VSS Snapshot
 5. Export ShadowCopy to VHDX
 6. Exit
=============================================================

Option Details

Option	Description
1	Interactively select and recover specific files from any shadow copy
2	Create symlinks for browsing shadow copies in Explorer
3	List all available shadow copies with timestamps
4	Create a new VSS snapshot of the C: drive
5	Export a shadow copy to VHDX format (manual or auto-copy)
6	Exit the program

📚 API Reference

Core Functions

`VSS_ListShadows()`

Returns a list of all shadow copies on the system.

shadows = ReShadowCode.VSS_ListShadows()
# Returns: [{'id': '{guid}', 'creation_time': 'timestamp', 'shadowcopy': 'path'}, ...]

`VSS_Create()`

Creates a new shadow copy of the C: drive.

shadow_id = ReShadowCode.VSS_Create()
# Returns: Shadow copy ID as string

`VSS_Create_Pipe(location, id_and_directory)`

Creates a symlink to access a shadow copy.

ReShadowCode.VSS_Create_Pipe("C:\\ShadowMount", "{shadow-copy-id}")

`VSS_CopyFile(src, dest)`

Copies a file from a shadow copy to a destination.

ReShadowCode.VSS_CopyFile(
    "C:\\ShadowMount\\path\\to\\file.txt",
    "C:\\Recovery\\file.txt"
)

`VSS_RemoveSymlink(src)`

Removes a symlink created by VSS_Create_Pipe.

ReShadowCode.VSS_RemoveSymlink("C:\\ShadowMount")

VHDX Export Functions

`VSS_ExportToVHD(shadow_copy_id, vhd_path, vhd_name=None, temp_symlink="C:\\TempVSS")`

Exports a shadow copy to VHDX format (manual copy mode).

Parameters:

shadow_copy_id — VSS shadow copy ID (with or without braces)
vhd_path — Destination directory for VHDX file
vhd_name — Optional VHDX filename (auto-generated if None)
temp_symlink — Optional temporary symlink location

`VSS_ExportToVHD_AutoCopy(shadow_copy_id, vhd_path, vhd_name=None, temp_symlink="C:\\TempVSS", target_drive=None)`

Exports a shadow copy to VHDX and automatically copies all files.

Parameters:

shadow_copy_id — VSS shadow copy ID
vhd_path — Destination directory for VHDX file
vhd_name — Optional VHDX filename
temp_symlink — Optional temporary symlink location
target_drive — Optional drive letter (auto-selected if None)

Returns: True on success, raises exception on failure

Utility Functions

`FindAvailableDriveLetter()`

Finds an available drive letter (from Z backwards).

drive = ReShadowCode.FindAvailableDriveLetter()
# Returns: "Z:", "Y:", etc.

`DiskPart_Command(exec)`

Executes a DiskPart command and returns the output.

output = ReShadowCode.DiskPart_Command('LIST VDISK')

🛡️ Requirements

System Requirements

Operating System: Windows 7/8/10/11 or Windows Server 2008+
VSS Support: System must support Volume Shadow Copy Service
Disk Space: For VHDX export, destination drive needs space equal to source volume

Software Requirements

Python: 3.6 or higher
Privileges: Administrator (elevated) required for VSS operations

Dependencies

pywin32>=305

🧪 Release History

Version 1.0.0 (June 16, 2026)

✨ Added VHDX export functionality
✨ Implemented automatic file copy with recursive traversal
✨ Added disk space validation before export
✨ Implemented automatic drive letter selection
✨ Enhanced error handling and reporting
✨ Added progress tracking for file operations

Version 0.0.22 (August 15, 2024)

🐛 Fixed "Rescue file" error handling
📦 Added Windows executable to package
🔧 Improved symlink cleanup

Version 0.0.1 (Initial Release)

🎉 Initial release with basic VSS operations

📄 License

This project is licensed under the GPL-3.0 License.

PyShadow - Python ShadowCopy Analyzer & VHDX Export Tool
Copyright (c) 2024 Ali Can Gonullu

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.