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.
- 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.
Install via PyPI:
pip install pyshadowOr clone the repo and install:
git clone https://github.com/alicangnll/pyshadow
cd pyshadow
pip install -r requirements.txt
python setup.py installfrom 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")from src.reshadow import ReShadowCode
ReShadowCode.VSS_Create()ReShadowCode.VSS_Create_Pipe("C:\\ShadowMount", "<shadow-copy-id>")files = ReShadowCode.VSS_Get_FileList("C:\\ShadowMount\\Users")
for f in files:
print(f)-
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")
The included example.py provides a CLI to:
- List ShadowCopies.
- Create symlinks for browsing.
- Recover files interactively.
Launch it via:
python example.py- Windows OS (must support VSS)
- Python 3.6+
- Administrator (elevated CMD) to enable/modify VSS
- Dependencies listed in
requirements.txt
- 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).
Licensed under the GPL‑3.0 license (github.com).
Created by Ali Can Gönüllü (@alicangnll), a cybersecurity researcher with expertise in penetration testing, malware analysis, and VSS tooling (github.com).
- 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.
- 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.