# ntfsdump
[](LICENSE)
[](https://badge.fury.io/py/ntfsdump)
[](https://pypi.org/project/ntfsdump/)
[](https://github.com/sumeshi/ntfsdump/actions/workflows/test.yaml)
An efficient tool for extracting files, directories, and alternate data streams directly from NTFS image files.
## Usage
**ntfsdump** can be executed from the command line or incorporated into a Python script.
```bash
$ ntfsdump {{query}} --output-path {{output_dir}} /path/to/imagefile.raw
```
```python
from ntfsdump import ntfsdump
# imagefile_path: str
# output_path: str
# target_queries: List[str]
# volume_num: Optional[int] = None
# file_type: Literal['raw', 'e01', 'vhd', 'vhdx', 'vmdk'] = 'raw'
ntfsdump(
imagefile_path='./path/to/your/imagefile.raw',
output_path='./path/to/output/directory',
target_queries=['/Windows/System32/winevt/Logs'],
volume_num=2,
file_type='raw'
)
```
### Query
This tool allows you to search for and extract file, directory, and ADS paths using regular expression queries.
Paths are separated by forward slashes (Unix/Linux-style) rather than backslashes (Windows-style).
e.g.
```
Original Path: C:\$MFT
Query: /$MFT
Original Path: C:\$Extend\$UsnJrnl\$J
Query: /$Extend/$UsnJrnl/$J
Original Path: C:\Windows\System32\winevt\Logs
Query: /Windows/System32/winevt/Logs
```
Queries will be expanded in the future.
If you have any questions, please feel free to submit an issue.
### Example
The target path can either be standalone or within a directory.
In the case of a directory, it recursively dumps the files within it.
```.bash
$ ntfsdump /Windows/System32/winevt/Logs -o ./dump ./path/to/your/imagefile.raw
```
extracting from E01 image (included splited-E01).
```.bash
$ ls
imagefile.E01
imagefile.E02
imagefile.E03
imagefile.E04
imagefile.E05
$ ntfsdump /Windows/System32/winevt/Logs --type=e01 -o ./dump ./path/to/your/imagefile.E01
```
#### When use with [ntfsfind](https://github.com/sumeshi/ntfsfind)
https://github.com/sumeshi/ntfsfind
```.bash
$ ntfsfind '.*\.evtx' ./path/to/your/imagefile.raw | ntfsdump ./path/to/your/imagefile.raw
```
### Options
```
--help, -h:
Display the help message and exit.
--version, -v:
Display the program's version number and exit.
--quiet, -q:
Flag to suppress standard output.
--nolog:
Flag to prevent any logs from being output.
--volume-num, -n:
NTFS volume number (default: autodetect).
--type, -t:
Image file format (default: raw(dd-format)).
Supported formats are (raw|e01|vhd|vhdx|vmdk).
--output-path, -o:
Output directory or file path.
If the target path is a directory, the directory specified by --output-path is created, and the target files are dumped under it.
Otherwise, the file is dumped with the filename specified in --output-path.
```
## Execution Environment
You can run ntfsdump in the following environments:
Windows: Precompiled binaries for Windows are available in the GitHub releases section.
Ubuntu: Precompiled binaries for Linux are also available in the GitHub releases section.
Python: If you prefer to run ntfsdump using Python, it is compatible with Python 3.11 and later versions (3.12 and above).
Make sure to choose the installation method that best suits your platform and requirements.
## Installation
### from PyPI
```bash
$ pip install ntfsdump
```
### from GitHub Releases
The version compiled into a binary using Nuitka is also available for use.
```bash
$ chmod +x ./ntfsdump
$ ./ntfsdump {{options...}}
```
```bat
> ntfsdump.exe {{options...}}
```
## NTFS File Prerequisites
The image file to be processed must meet the following conditions:
- The file format must be raw, e01, vhd, vhdx, or vmdk.
- It must use the NTFS (NT File System).
- It must have a GUID Partition Table (GPT).
Additional file formats will be added in the future.
If you have any questions, please feel free to submit an issue.
## Log Format
**ntfsdump** outputs logs in the following format.
By default, it outputs the files to the current directory, but if you do not need them, please use the `--nolog` option.
```
- ntfsdump v{{version}} -
2022-01-01T00:00:00.000000: [{{EventName}}] {{Description}}
2022-01-01T00:00:00.000000: [{{EventName}}] {{Description}}
2022-01-01T00:00:00.000000: [{{EventName}}] {{Description}}
...
```
## Contributing
The source code for ntfsdump is hosted at GitHub, and you may download, fork, and review it from this repository(https://github.com/sumeshi/ntfsdump).
Please report issues and feature requests. :sushi: :sushi: :sushi:
## License
ntfsdump is released under the [LGPLv3+](https://github.com/sumeshi/ntfsdump/blob/master/LICENSE) License.
Powered by following libraries.
- [pytsk3](https://github.com/py4n6/pytsk)
- [libewf](https://github.com/libyal/libewf)
- [libvhdi](https://github.com/libyal/libvhdi)
- [libvmdk](https://github.com/libyal/libvmdk)
- [ntfs-samples](https://github.com/msuhanov/ntfs-samples)
- [Nuitka](https://github.com/Nuitka/Nuitka)
Raw data
{
"_id": null,
"home_page": "https://github.com/sumeshi/ntfsdump",
"name": "ntfsdump",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "Security,Forensics,DFIR,Windows,NTFS",
"author": "sumeshi",
"author_email": "sum3sh1@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/8d/b0/da93c8350d1ad2eeafbe0faf6f8b4f42a21c4f76a817516413cb101ac745/ntfsdump-2.5.3.tar.gz",
"platform": null,
"description": "# ntfsdump\n\n[](LICENSE)\n[](https://badge.fury.io/py/ntfsdump)\n[](https://pypi.org/project/ntfsdump/)\n[](https://github.com/sumeshi/ntfsdump/actions/workflows/test.yaml)\n\n\n\nAn efficient tool for extracting files, directories, and alternate data streams directly from NTFS image files.\n\n## Usage\n\n**ntfsdump** can be executed from the command line or incorporated into a Python script.\n\n```bash\n$ ntfsdump {{query}} --output-path {{output_dir}} /path/to/imagefile.raw\n```\n\n```python\nfrom ntfsdump import ntfsdump\n\n# imagefile_path: str\n# output_path: str\n# target_queries: List[str]\n# volume_num: Optional[int] = None\n# file_type: Literal['raw', 'e01', 'vhd', 'vhdx', 'vmdk'] = 'raw'\n\nntfsdump(\n imagefile_path='./path/to/your/imagefile.raw',\n output_path='./path/to/output/directory',\n target_queries=['/Windows/System32/winevt/Logs'],\n volume_num=2,\n file_type='raw'\n)\n```\n\n### Query\n\nThis tool allows you to search for and extract file, directory, and ADS paths using regular expression queries. \nPaths are separated by forward slashes (Unix/Linux-style) rather than backslashes (Windows-style).\n\ne.g.\n```\nOriginal Path: C:\\$MFT\nQuery: /$MFT\n\nOriginal Path: C:\\$Extend\\$UsnJrnl\\$J\nQuery: /$Extend/$UsnJrnl/$J\n\nOriginal Path: C:\\Windows\\System32\\winevt\\Logs\nQuery: /Windows/System32/winevt/Logs\n```\n\nQueries will be expanded in the future. \nIf you have any questions, please feel free to submit an issue.\n\n### Example\nThe target path can either be standalone or within a directory. \nIn the case of a directory, it recursively dumps the files within it.\n\n```.bash\n$ ntfsdump /Windows/System32/winevt/Logs -o ./dump ./path/to/your/imagefile.raw\n```\n\nextracting from E01 image (included splited-E01).\n\n```.bash\n$ ls\nimagefile.E01\nimagefile.E02\nimagefile.E03\nimagefile.E04\nimagefile.E05\n\n$ ntfsdump /Windows/System32/winevt/Logs --type=e01 -o ./dump ./path/to/your/imagefile.E01\n```\n\n#### When use with [ntfsfind](https://github.com/sumeshi/ntfsfind)\n\nhttps://github.com/sumeshi/ntfsfind\n\n```.bash\n$ ntfsfind '.*\\.evtx' ./path/to/your/imagefile.raw | ntfsdump ./path/to/your/imagefile.raw\n```\n\n### Options\n```\n--help, -h:\n Display the help message and exit.\n\n--version, -v:\n Display the program's version number and exit.\n\n--quiet, -q:\n Flag to suppress standard output.\n\n--nolog:\n Flag to prevent any logs from being output.\n\n--volume-num, -n:\n NTFS volume number (default: autodetect).\n\n--type, -t:\n Image file format (default: raw(dd-format)).\n Supported formats are (raw|e01|vhd|vhdx|vmdk).\n\n--output-path, -o:\n Output directory or file path.\n\n If the target path is a directory, the directory specified by --output-path is created, and the target files are dumped under it.\n\n Otherwise, the file is dumped with the filename specified in --output-path.\n```\n\n## Execution Environment\nYou can run ntfsdump in the following environments:\n\nWindows: Precompiled binaries for Windows are available in the GitHub releases section.\n\nUbuntu: Precompiled binaries for Linux are also available in the GitHub releases section.\n\nPython: If you prefer to run ntfsdump using Python, it is compatible with Python 3.11 and later versions (3.12 and above). \n\nMake sure to choose the installation method that best suits your platform and requirements.\n\n## Installation\n\n### from PyPI\n\n```bash\n$ pip install ntfsdump\n```\n\n### from GitHub Releases\nThe version compiled into a binary using Nuitka is also available for use.\n\n```bash\n$ chmod +x ./ntfsdump\n$ ./ntfsdump {{options...}}\n```\n\n```bat\n> ntfsdump.exe {{options...}}\n```\n\n## NTFS File Prerequisites\nThe image file to be processed must meet the following conditions:\n\n- The file format must be raw, e01, vhd, vhdx, or vmdk.\n- It must use the NTFS (NT File System).\n- It must have a GUID Partition Table (GPT).\n\nAdditional file formats will be added in the future. \nIf you have any questions, please feel free to submit an issue.\n\n## Log Format\n**ntfsdump** outputs logs in the following format. \nBy default, it outputs the files to the current directory, but if you do not need them, please use the `--nolog` option.\n\n```\n- ntfsdump v{{version}} - \n2022-01-01T00:00:00.000000: [{{EventName}}] {{Description}}\n2022-01-01T00:00:00.000000: [{{EventName}}] {{Description}}\n2022-01-01T00:00:00.000000: [{{EventName}}] {{Description}}\n...\n```\n\n## Contributing\n\nThe source code for ntfsdump is hosted at GitHub, and you may download, fork, and review it from this repository(https://github.com/sumeshi/ntfsdump).\n\nPlease report issues and feature requests. :sushi: :sushi: :sushi:\n\n## License\n\nntfsdump is released under the [LGPLv3+](https://github.com/sumeshi/ntfsdump/blob/master/LICENSE) License.\n\nPowered by following libraries.\n- [pytsk3](https://github.com/py4n6/pytsk)\n- [libewf](https://github.com/libyal/libewf)\n- [libvhdi](https://github.com/libyal/libvhdi)\n- [libvmdk](https://github.com/libyal/libvmdk)\n- [ntfs-samples](https://github.com/msuhanov/ntfs-samples)\n- [Nuitka](https://github.com/Nuitka/Nuitka)\n",
"bugtrack_url": null,
"license": "LGPLv3+",
"summary": "An efficient tool for extracting files, directories, and alternate data streams directly from NTFS image files.",
"version": "2.5.3",
"project_urls": {
"Homepage": "https://github.com/sumeshi/ntfsdump",
"Repository": "https://github.com/sumeshi/ntfsdump"
},
"split_keywords": [
"security",
"forensics",
"dfir",
"windows",
"ntfs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3d894a6777d3acace4494cb4c8f2323d881b2df0cfa10dc85c9e599e6bfe2ed5",
"md5": "e376824190815a40f6cd86237b938bf3",
"sha256": "66691344a9e7d0a4a200c0b5d2fd3349fa82144d5968b02c5bd4eda6461a6707"
},
"downloads": -1,
"filename": "ntfsdump-2.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e376824190815a40f6cd86237b938bf3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 25735,
"upload_time": "2023-11-23T17:33:23",
"upload_time_iso_8601": "2023-11-23T17:33:23.564136Z",
"url": "https://files.pythonhosted.org/packages/3d/89/4a6777d3acace4494cb4c8f2323d881b2df0cfa10dc85c9e599e6bfe2ed5/ntfsdump-2.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8db0da93c8350d1ad2eeafbe0faf6f8b4f42a21c4f76a817516413cb101ac745",
"md5": "4909a5ade476e9d94ddad6eff39e878b",
"sha256": "74d4d2ca895fddee2c18dcbffc9fdc252e80dbc971947420fb6879044d355340"
},
"downloads": -1,
"filename": "ntfsdump-2.5.3.tar.gz",
"has_sig": false,
"md5_digest": "4909a5ade476e9d94ddad6eff39e878b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 23773,
"upload_time": "2023-11-23T17:33:25",
"upload_time_iso_8601": "2023-11-23T17:33:25.288570Z",
"url": "https://files.pythonhosted.org/packages/8d/b0/da93c8350d1ad2eeafbe0faf6f8b4f42a21c4f76a817516413cb101ac745/ntfsdump-2.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-23 17:33:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sumeshi",
"github_project": "ntfsdump",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ntfsdump"
}
JSON
