PyShadow — Python ShadowCopy Analyzer 🛡️

PyShadow is a powerful Windows-only Python toolkit designed for cybersecurity researchers and forensic analysts. It interacts 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.

⚠️ Disclaimer: For educational and lawful use only. Do not use on systems without authorization.

🚀 Features

List all Shadow Copies on the local system.
Create new Shadow Copies programmatically.
Mount Shadow Copies using named pipes or symlinks.
Retrieve directory contents from within a ShadowCopy.
Recover files by copying them to a specified destination.
Delete symlinks safely to clean up artifacts.
(Work in progress) Export entire Shadow Copies to VHD format.

📦 Installation

Install via PyPI:

pip install pyshadow

Or clone the repo and install:

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

🧩 Usage Examples

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

Create a Shadow Copy

from src.reshadow import ReShadowCode

ReShadowCode.VSS_Create()

Mount a Shadow Copy

ReShadowCode.VSS_Create_Pipe("C:\\ShadowMount", "<shadow-copy-id>")

Retrieve a File List

files = ReShadowCode.VSS_Get_FileList("C:\\ShadowMount\\Users")
for f in files:
    print(f)

Recover a Specific File

Mount the Shadow Copy as above.

Use:

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

Unmount:

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

🛠️ Example Script (example.py)

The included example.py provides a CLI to:

List ShadowCopies.
Create symlinks for browsing.
Recover files interactively.

Launch it via:

python example.py

🛡️ Requirements

Windows OS (must support VSS)
Python 3.6+
Administrator (elevated CMD) to enable/modify VSS
Dependencies listed in requirements.txt

🧪 Release History

v0.0.22 (Aug 15, 2024) – Improved error handling (“Rescue file” fix) and added Windows executable in package (github.com, github.com, github.com, github.com, pypi.org).

📄 License

Licensed under the GPL‑3.0 license (github.com).

🔗 About the Author

Created by Ali Can Gönüllü (@alicangnll), a cybersecurity researcher with expertise in penetration testing, malware analysis, and VSS tooling (github.com).

🧑‍💻 Contribution & Support

Contributions and bug reports are welcome — feel free to open issues or PRs!
If you'd like to support via donations or sponsorships, details are available on the author's GitHub profile.

⚠️ Usage Warning

Requires elevated privileges to run VSS operations.
Always ensure you're compliant with local laws and organizational policies when using tools that access system-level snapshots.

Explore, analyze, and recover data safely with PyShadow!

Let me know if you'd like to add badges (e.g. for PyPI, license, version), GitHub Actions CI, or a quick-start guide.

alicangnll/pyshadow