ntfsfind


Namentfsfind JSON
Version 2.5.0 PyPI version JSON
download
home_pagehttps://github.com/sumeshi/ntfsfind
SummaryAn efficient tool for search files, directories, and alternate data streams directly from NTFS image files.
upload_time2023-11-24 20:27:41
maintainer
docs_urlNone
authorsumeshi
requires_python>=3.11,<4.0
licenseLGPLv3+
keywords security forensics dfir windows ntfs
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # ntfsfind

[![LGPLv3+ License](http://img.shields.io/badge/license-LGPLv3+-blue.svg?style=flat)](LICENSE)
[![PyPI version](https://badge.fury.io/py/ntfsfind.svg)](https://badge.fury.io/py/ntfsfind)
[![Python Versions](https://img.shields.io/pypi/pyversions/ntfsfind.svg)](https://pypi.org/project/ntfsfind/)

![ntfsfind](https://gist.githubusercontent.com/sumeshi/c2f430d352ae763273faadf9616a29e5/raw/baa85b045e0043914218cf9c0e1d1722e1e7524b/ntfsfind.svg)

An efficient tool for search files, directories, and alternate data streams directly from NTFS image files.

## Usage

**ntfsfind** can be executed from the command line or incorporated into a Python script.


```bash
$ ntfsfind {{query_regex}} /path/to/imagefile.raw
```

```python
from ntfsfind import ntfsfind

# imagefile_path: str
# search_query: str
# volume_num: Optional[int] = None
# file_type: Literal['raw', 'e01', 'vhd', 'vhdx', 'vmdk'] = 'raw'
# multiprocess: bool = False
#
# -> List[str]

records = ntfsfind(
    imagefile_path='./path/to/your/imagefile.raw',
    search_query='.*\.evtx',
    volume_num=2,
    file_type='raw',
    multiprocess=False
)

for record in records:
    print(record)
```


### Query
This tool allows you to search for file, directory, and ADS with 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'

# find Eventlogs
Query: '.*\.evtx'

# find Alternate Data Streams
Query: '.*:.*'
```


### Example
This tool can directly extract and search for $MFT information from image files (RAW, E01, VHD, VHDX, VMDK) containing recorded NTFS volumes as follows.

```.bash
$ ntfsfind '.*\.evtx' /path/to/imagefile.raw
Windows/System32/winevt/Logs/Setup.evtx
Windows/System32/winevt/Logs/Microsoft-Windows-All-User-Install-Agent%4Admin.evtx
Logs/Windows PowerShell.evtx
Logs/Microsoft-Windows-Winlogon%4Operational.evtx
Logs/Microsoft-Windows-WinINet-Config%4ProxyConfigChanged.evtx
Logs/Microsoft-Windows-Windows Firewall With Advanced Security%4ConnectionSecurity.evtx
Logs/Microsoft-Windows-UserPnp%4ActionCenter.evtx
Logs/Microsoft-Windows-TerminalServices-RemoteConnectionManager%4Admin.evtx
Logs/Microsoft-Windows-TerminalServices-LocalSessionManager%4Admin.evtx
Logs/Microsoft-Windows-SMBServer%4Security.evtx
Logs/Microsoft-Windows-SMBServer%4Connectivity.evtx
Logs/Microsoft-Windows-SMBServer%4Audit.evtx
Logs/Microsoft-Windows-SmbClient%4Security.evtx
Logs/Microsoft-Windows-SMBClient%4Operational.evtx
Logs/Microsoft-Windows-Shell-Core%4ActionCenter.evtx
Logs/Microsoft-Windows-SettingSync%4Operational.evtx
...

```


#### When use with [ntfsdump](https://github.com/sumeshi/ntfsdump)
When combined with ntfsdump, the retrieved files can be directly dumped from the image file.

```.bash
$ ntfsfind '.*\.evtx' /path/to/imagefile.raw | ntfsdump /path/to/your/imagefile
```

ntfsfind and ntfsdump are compatible if they share the same major and minor versions. For instance, they can be used together if both are version 2.5.x.

https://github.com/sumeshi/ntfsdump


### Options
```
--help, -h:
    Display the help message and exit.

--version, -v:
    Show the program's version number and exit.

--volume-num, -n:
    Specify the NTFS volume number (default is autodetect).

--type, -t:
    Set the image file format (default is raw(dd-format)).
    Supported formats include raw, e01, vhd, vhdx, and vmdk.

--ignore-case, -i:
    Enable case-insensitive search.

--multiprocess, -m:
    Enable multiprocessing for the operation.
```

## Execution Environment
You can run ntfsfind 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 ntfsfind 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 ntfsfind
```

### from GitHub Releases
The version compiled into a binary using Nuitka is also available for use.

```bash
$ chmod +x ./ntfsfind
$ ./ntfsfind {{options...}}
```

```bat
> ntfsfind .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.

## Contributing

The source code for ntfsfind is hosted at GitHub, and you may download, fork, and review it from this repository(https://github.com/sumeshi/ntfsfind).  
Please report issues and feature requests. :sushi: :sushi: :sushi:


## License

ntfsfind is released under the [LGPLv3+](https://github.com/sumeshi/ntfsfind/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)
- [pymft-rs](https://github.com/omerbenamram/pymft-rs)
- [Nuitka](https://github.com/Nuitka/Nuitka)

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/sumeshi/ntfsfind",
    "name": "ntfsfind",
    "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/63/d8/b7387c84e183b9b4d75a66a54433e4365f2eed30f2b24cec97fbda425e11/ntfsfind-2.5.0.tar.gz",
    "platform": null,
    "description": "# ntfsfind\n\n[![LGPLv3+ License](http://img.shields.io/badge/license-LGPLv3+-blue.svg?style=flat)](LICENSE)\n[![PyPI version](https://badge.fury.io/py/ntfsfind.svg)](https://badge.fury.io/py/ntfsfind)\n[![Python Versions](https://img.shields.io/pypi/pyversions/ntfsfind.svg)](https://pypi.org/project/ntfsfind/)\n\n![ntfsfind](https://gist.githubusercontent.com/sumeshi/c2f430d352ae763273faadf9616a29e5/raw/baa85b045e0043914218cf9c0e1d1722e1e7524b/ntfsfind.svg)\n\nAn efficient tool for search files, directories, and alternate data streams directly from NTFS image files.\n\n## Usage\n\n**ntfsfind** can be executed from the command line or incorporated into a Python script.\n\n\n```bash\n$ ntfsfind {{query_regex}} /path/to/imagefile.raw\n```\n\n```python\nfrom ntfsfind import ntfsfind\n\n# imagefile_path: str\n# search_query: str\n# volume_num: Optional[int] = None\n# file_type: Literal['raw', 'e01', 'vhd', 'vhdx', 'vmdk'] = 'raw'\n# multiprocess: bool = False\n#\n# -> List[str]\n\nrecords = ntfsfind(\n    imagefile_path='./path/to/your/imagefile.raw',\n    search_query='.*\\.evtx',\n    volume_num=2,\n    file_type='raw',\n    multiprocess=False\n)\n\nfor record in records:\n    print(record)\n```\n\n\n### Query\nThis tool allows you to search for file, directory, and ADS with regular expression queries.  \nPaths are separated by forward slashes (Unix/Linux-style) rather than backslashes (Windows-style).\n\n\ne.g.\n```\nOriginal Path: C:\\$MFT\nQuery: '/\\$MFT'\n\n# find Eventlogs\nQuery: '.*\\.evtx'\n\n# find Alternate Data Streams\nQuery: '.*:.*'\n```\n\n\n### Example\nThis tool can directly extract and search for $MFT information from image files (RAW, E01, VHD, VHDX, VMDK) containing recorded NTFS volumes as follows.\n\n```.bash\n$ ntfsfind '.*\\.evtx' /path/to/imagefile.raw\nWindows/System32/winevt/Logs/Setup.evtx\nWindows/System32/winevt/Logs/Microsoft-Windows-All-User-Install-Agent%4Admin.evtx\nLogs/Windows PowerShell.evtx\nLogs/Microsoft-Windows-Winlogon%4Operational.evtx\nLogs/Microsoft-Windows-WinINet-Config%4ProxyConfigChanged.evtx\nLogs/Microsoft-Windows-Windows Firewall With Advanced Security%4ConnectionSecurity.evtx\nLogs/Microsoft-Windows-UserPnp%4ActionCenter.evtx\nLogs/Microsoft-Windows-TerminalServices-RemoteConnectionManager%4Admin.evtx\nLogs/Microsoft-Windows-TerminalServices-LocalSessionManager%4Admin.evtx\nLogs/Microsoft-Windows-SMBServer%4Security.evtx\nLogs/Microsoft-Windows-SMBServer%4Connectivity.evtx\nLogs/Microsoft-Windows-SMBServer%4Audit.evtx\nLogs/Microsoft-Windows-SmbClient%4Security.evtx\nLogs/Microsoft-Windows-SMBClient%4Operational.evtx\nLogs/Microsoft-Windows-Shell-Core%4ActionCenter.evtx\nLogs/Microsoft-Windows-SettingSync%4Operational.evtx\n...\n\n```\n\n\n#### When use with [ntfsdump](https://github.com/sumeshi/ntfsdump)\nWhen combined with ntfsdump, the retrieved files can be directly dumped from the image file.\n\n```.bash\n$ ntfsfind '.*\\.evtx' /path/to/imagefile.raw | ntfsdump /path/to/your/imagefile\n```\n\nntfsfind and ntfsdump are compatible if they share the same major and minor versions. For instance, they can be used together if both are version 2.5.x.\n\nhttps://github.com/sumeshi/ntfsdump\n\n\n### Options\n```\n--help, -h:\n    Display the help message and exit.\n\n--version, -v:\n    Show the program's version number and exit.\n\n--volume-num, -n:\n    Specify the NTFS volume number (default is autodetect).\n\n--type, -t:\n    Set the image file format (default is raw(dd-format)).\n    Supported formats include raw, e01, vhd, vhdx, and vmdk.\n\n--ignore-case, -i:\n    Enable case-insensitive search.\n\n--multiprocess, -m:\n    Enable multiprocessing for the operation.\n```\n\n## Execution Environment\nYou can run ntfsfind 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 ntfsfind 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 ntfsfind\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 ./ntfsfind\n$ ./ntfsfind {{options...}}\n```\n\n```bat\n> ntfsfind .exe {{options...}}\n```\n\n## NTFS File Prerequisites\n\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## Contributing\n\nThe source code for ntfsfind is hosted at GitHub, and you may download, fork, and review it from this repository(https://github.com/sumeshi/ntfsfind).  \nPlease report issues and feature requests. :sushi: :sushi: :sushi:\n\n\n## License\n\nntfsfind is released under the [LGPLv3+](https://github.com/sumeshi/ntfsfind/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- [pymft-rs](https://github.com/omerbenamram/pymft-rs)\n- [Nuitka](https://github.com/Nuitka/Nuitka)\n",
    "bugtrack_url": null,
    "license": "LGPLv3+",
    "summary": "An efficient tool for search files, directories, and alternate data streams directly from NTFS image files.",
    "version": "2.5.0",
    "project_urls": {
        "Homepage": "https://github.com/sumeshi/ntfsfind",
        "Repository": "https://github.com/sumeshi/ntfsfind"
    },
    "split_keywords": [
        "security",
        "forensics",
        "dfir",
        "windows",
        "ntfs"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "47ab305dbf66eac83972426b75ab13cad450aafd7bd8461e3940e83d2aabc028",
                "md5": "53732e9f468f31f1077443240c8cbe49",
                "sha256": "677338b99354ea2d6fdcf1a4b7cb9f865ecc4f5c7aa48d6f14bd01b981794de4"
            },
            "downloads": -1,
            "filename": "ntfsfind-2.5.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "53732e9f468f31f1077443240c8cbe49",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11,<4.0",
            "size": 19951,
            "upload_time": "2023-11-24T20:22:09",
            "upload_time_iso_8601": "2023-11-24T20:22:09.375458Z",
            "url": "https://files.pythonhosted.org/packages/47/ab/305dbf66eac83972426b75ab13cad450aafd7bd8461e3940e83d2aabc028/ntfsfind-2.5.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "63d8b7387c84e183b9b4d75a66a54433e4365f2eed30f2b24cec97fbda425e11",
                "md5": "4b6897ffee9e7fe7429289c684260171",
                "sha256": "d2ac8ea90c42bc76336dbfdc6f99691e9f28b9cd0634f9da2176d57208e530d3"
            },
            "downloads": -1,
            "filename": "ntfsfind-2.5.0.tar.gz",
            "has_sig": false,
            "md5_digest": "4b6897ffee9e7fe7429289c684260171",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11,<4.0",
            "size": 18382,
            "upload_time": "2023-11-24T20:27:41",
            "upload_time_iso_8601": "2023-11-24T20:27:41.228283Z",
            "url": "https://files.pythonhosted.org/packages/63/d8/b7387c84e183b9b4d75a66a54433e4365f2eed30f2b24cec97fbda425e11/ntfsfind-2.5.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-11-24 20:27:41",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "sumeshi",
    "github_project": "ntfsfind",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "ntfsfind"
}
        
Elapsed time: 0.21142s