ext2py 0.1.0__tar.gz

ext2py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santiago Ciciliani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ext2py-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: ext2py
+Version: 0.1.0
+Summary: Pure-Python, read-only ext2/ext3/ext4 filesystem reader and browsing shell, no root or kernel drivers needed
+Author-email: Santiago Ciciliani <santiago.ciciliani@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sciciliani/ext2py
+Project-URL: Repository, https://github.com/sciciliani/ext2py
+Project-URL: Issues, https://github.com/sciciliani/ext2py/issues
+Project-URL: Changelog, https://github.com/sciciliani/ext2py/blob/main/CHANGELOG.md
+Keywords: ext2,ext3,ext4,filesystem,disk-image,shell,forensics,linux,macos,read-only
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: System :: Recovery Tools
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# ext2py
+
+**Browse ext2 / ext3 / ext4 Linux filesystems from Python on macOS, Linux or Windows: no kernel drivers, no FUSE, no root for disk images.**
+
+`ext2py` is a pure-Python, zero-dependency, **read-only** ext2/3/4 parser. It ships with
+an interactive shell to `cd`, `ls` and download files out of Linux disk images,
+partitions and devices.
+
+[![PyPI](https://img.shields.io/pypi/v/ext2py.svg)](https://pypi.org/project/ext2py/)
+[![Python](https://img.shields.io/pypi/pyversions/ext2py.svg)](https://pypi.org/project/ext2py/)
+[![CI](https://github.com/sciciliani/ext2py/actions/workflows/ci.yml/badge.svg)](https://github.com/sciciliani/ext2py/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> ⚠️ Early alpha. ext2py never writes to the source image or device.
+
+## Install
+
+```bash
+pip install ext2py
+```
+
+## Interactive shell
+
+```console
+$ ext2py shell disk.img
+ext2py shell: disk.img (ext4, read-only). Type 'help' for commands, 'exit' to quit.
+ext2py:/$ cd home/me
+ext2py:/home/me$ ls -l
+-rw-r--r-- 1 1000 1000 16 Nov 14  2023 notes.txt
+ext2py:/home/me$ get notes.txt
+/home/me/notes.txt -> /Users/you/notes.txt
+1 item(s) copied
+```
+
+Commands: `ls [-lah]`, `ll`, `cd`, `pwd`, `tree`, `find [-name GLOB]`, `cat`, `stat`,
+`readlink`, `info`, `get PATH [LOCAL]` (recursive for directories), and the local-side
+`lcd`, `lpwd`, `lls`. Tab completion works on paths inside the image.
+
+## One-shot commands
+
+```bash
+ext2py info  disk.img                   # superblock summary
+ext2py parts disk.img                   # partition table (MBR / GPT)
+ext2py ls    disk.img /home -l          # list a directory
+ext2py cat   disk.img /etc/hostname     # print a file
+ext2py stat  disk.img /etc/passwd       # inode details
+ext2py get   disk.img /home/me ./out    # copy files out
+```
+
+Whole-disk images are handled automatically when they contain a single ext partition;
+otherwise use `--partition N` (see `ext2py parts`) or `--offset BYTES`.
+
+Physical disks on macOS: find the disk with `diskutil list`, then point at the raw
+device (`sudo ext2py shell /dev/rdisk4`). Reading a device needs read permission on
+it, which is the only reason `sudo` is involved. Image files need no privileges.
+
+## Python API
+
+```python
+from ext2py import ExtFS, open_fs
+
+with ExtFS("partition.img") as fs:          # or open_fs("disk.img") for partitioned disks
+    print(fs.listdir("/etc"))
+    data = fs.read_file("/etc/os-release")
+    st = fs.stat("/etc/passwd")               # Inode: mode, uid, gid, size, mtime, ...
+    for top, dirs, files in fs.walk("/home"):
+        ...
+    fs.extract("/home/me", "./out")           # like cp -R
+```
+
+## Features
+
+- [x] ext2, ext3 and ext4 (the journal is ignored; reads the on-disk state)
+- [x] Direct, indirect, double- and triple-indirect block maps; sparse files
+- [x] ext4 extent trees, uninitialized extents, inline data, 64bit, flex_bg, meta_bg
+- [x] Hashed (htree) directories, fast and slow symlinks
+- [x] Partitioned images (MBR / GPT)
+- [ ] Encrypted directories (names are shown raw, contents are not decrypted)
+- [ ] Extended attributes outside the inode, MBR logical partitions
+
+## Development
+
+```bash
+git clone https://github.com/sciciliani/ext2py && cd ext2py
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+The tests build ext2/ext4 images in pure Python (`tests/imagebuilder.py`), so no
+`mke2fs` is required.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ext2py-0.1.0/README.md

@@ -0,0 +1,95 @@
+# ext2py
+
+**Browse ext2 / ext3 / ext4 Linux filesystems from Python on macOS, Linux or Windows: no kernel drivers, no FUSE, no root for disk images.**
+
+`ext2py` is a pure-Python, zero-dependency, **read-only** ext2/3/4 parser. It ships with
+an interactive shell to `cd`, `ls` and download files out of Linux disk images,
+partitions and devices.
+
+[![PyPI](https://img.shields.io/pypi/v/ext2py.svg)](https://pypi.org/project/ext2py/)
+[![Python](https://img.shields.io/pypi/pyversions/ext2py.svg)](https://pypi.org/project/ext2py/)
+[![CI](https://github.com/sciciliani/ext2py/actions/workflows/ci.yml/badge.svg)](https://github.com/sciciliani/ext2py/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> ⚠️ Early alpha. ext2py never writes to the source image or device.
+
+## Install
+
+```bash
+pip install ext2py
+```
+
+## Interactive shell
+
+```console
+$ ext2py shell disk.img
+ext2py shell: disk.img (ext4, read-only). Type 'help' for commands, 'exit' to quit.
+ext2py:/$ cd home/me
+ext2py:/home/me$ ls -l
+-rw-r--r-- 1 1000 1000 16 Nov 14  2023 notes.txt
+ext2py:/home/me$ get notes.txt
+/home/me/notes.txt -> /Users/you/notes.txt
+1 item(s) copied
+```
+
+Commands: `ls [-lah]`, `ll`, `cd`, `pwd`, `tree`, `find [-name GLOB]`, `cat`, `stat`,
+`readlink`, `info`, `get PATH [LOCAL]` (recursive for directories), and the local-side
+`lcd`, `lpwd`, `lls`. Tab completion works on paths inside the image.
+
+## One-shot commands
+
+```bash
+ext2py info  disk.img                   # superblock summary
+ext2py parts disk.img                   # partition table (MBR / GPT)
+ext2py ls    disk.img /home -l          # list a directory
+ext2py cat   disk.img /etc/hostname     # print a file
+ext2py stat  disk.img /etc/passwd       # inode details
+ext2py get   disk.img /home/me ./out    # copy files out
+```
+
+Whole-disk images are handled automatically when they contain a single ext partition;
+otherwise use `--partition N` (see `ext2py parts`) or `--offset BYTES`.
+
+Physical disks on macOS: find the disk with `diskutil list`, then point at the raw
+device (`sudo ext2py shell /dev/rdisk4`). Reading a device needs read permission on
+it, which is the only reason `sudo` is involved. Image files need no privileges.
+
+## Python API
+
+```python
+from ext2py import ExtFS, open_fs
+
+with ExtFS("partition.img") as fs:          # or open_fs("disk.img") for partitioned disks
+    print(fs.listdir("/etc"))
+    data = fs.read_file("/etc/os-release")
+    st = fs.stat("/etc/passwd")               # Inode: mode, uid, gid, size, mtime, ...
+    for top, dirs, files in fs.walk("/home"):
+        ...
+    fs.extract("/home/me", "./out")           # like cp -R
+```
+
+## Features
+
+- [x] ext2, ext3 and ext4 (the journal is ignored; reads the on-disk state)
+- [x] Direct, indirect, double- and triple-indirect block maps; sparse files
+- [x] ext4 extent trees, uninitialized extents, inline data, 64bit, flex_bg, meta_bg
+- [x] Hashed (htree) directories, fast and slow symlinks
+- [x] Partitioned images (MBR / GPT)
+- [ ] Encrypted directories (names are shown raw, contents are not decrypted)
+- [ ] Extended attributes outside the inode, MBR logical partitions
+
+## Development
+
+```bash
+git clone https://github.com/sciciliani/ext2py && cd ext2py
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+The tests build ext2/ext4 images in pure Python (`tests/imagebuilder.py`), so no
+`mke2fs` is required.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ext2py-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ext2py"
+dynamic = ["version"]
+description = "Pure-Python, read-only ext2/ext3/ext4 filesystem reader and browsing shell, no root or kernel drivers needed"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Santiago Ciciliani", email="santiago.ciciliani@gmail.com" }
+]
+keywords = [
+  "ext2", "ext3", "ext4", "filesystem", "disk-image", "shell", "forensics", "linux", "macos", "read-only",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: System :: Filesystems",
+  "Topic :: System :: Recovery Tools",
+  "Topic :: Utilities",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build", "twine"]
+
+[project.scripts]
+ext2py = "ext2py.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/sciciliani/ext2py"
+Repository = "https://github.com/sciciliani/ext2py"
+Issues = "https://github.com/sciciliani/ext2py/issues"
+Changelog = "https://github.com/sciciliani/ext2py/blob/main/CHANGELOG.md"
+
+[tool.setuptools.dynamic]
+version = { attr = "ext2py.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ext2py = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ext2py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ext2py-0.1.0/src/ext2py/__init__.py

@@ -0,0 +1,11 @@
+"""ext2py - read-only ext2/ext3/ext4 filesystem reader in pure Python."""
+
+__version__ = "0.1.0"
+
+from ext2py.partitions import Partition, find_partitions, open_fs
+from ext2py.reader import DirEntry, ExtError, ExtFS, Inode, Superblock
+
+__all__ = [
+    "__version__", "ExtFS", "ExtError", "Inode", "DirEntry", "Superblock",
+    "Partition", "find_partitions", "open_fs",
+]

ext2py-0.1.0/src/ext2py/__main__.py

@@ -0,0 +1,3 @@
+from ext2py.cli import main
+
+raise SystemExit(main())

ext2py-0.1.0/src/ext2py/cli.py

@@ -0,0 +1,115 @@
+"""Command-line entry point for `ext2py` (also `python -m ext2py`)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+import sys
+from typing import List, Optional
+
+from ext2py import __version__
+from ext2py.partitions import find_partitions, open_fs
+from ext2py.reader import ExtError, ExtFS
+from ext2py.shell import ExtShell, format_info, format_stat, human_size
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ext2py",
+        description="Read-only ext2/ext3/ext4 filesystem browser. Never writes to the image.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    image = argparse.ArgumentParser(add_help=False)
+    image.add_argument("image", help="filesystem image, disk image or device (e.g. /dev/rdisk4)")
+    where = image.add_mutually_exclusive_group()
+    where.add_argument("-p", "--partition", type=int, metavar="N",
+                       help="use partition N of a partitioned disk (see 'parts')")
+    where.add_argument("--offset", type=int, metavar="BYTES",
+                       help="byte offset of the filesystem within the image")
+
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.add_parser("shell", parents=[image], help="interactive shell: cd, ls, cat, get ...")
+    sub.add_parser("info", parents=[image], help="show filesystem information")
+    sub.add_parser("parts", help="list partitions of a disk image").add_argument("image")
+    p = sub.add_parser("ls", parents=[image], help="list a directory")
+    p.add_argument("path", nargs="?", default="/")
+    p.add_argument("-l", action="store_true", help="long listing")
+    p.add_argument("-a", action="store_true", help="include hidden entries")
+    p.add_argument("-H", "--human", action="store_true", help="human-readable sizes")
+    p = sub.add_parser("cat", parents=[image], help="print a file to stdout")
+    p.add_argument("path")
+    p = sub.add_parser("stat", parents=[image], help="show inode details")
+    p.add_argument("path")
+    p = sub.add_parser("get", parents=[image], help="copy a file or directory tree out")
+    p.add_argument("path")
+    p.add_argument("dest", nargs="?", default=".")
+    return parser
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.command == "parts":
+        with open(args.image, "rb", buffering=0) as f:
+            parts = find_partitions(f)
+        if not parts:
+            print("no partition table found")
+            return 0
+        for part in parts:
+            print(f"{part.number:>3}  offset={part.offset:<14} size={human_size(part.size):<8} "
+                  f"type={part.type}{'  (linux)' if part.is_linux else ''}  {part.name}")
+        return 0
+
+    with open_fs(args.image, partition=args.partition, offset=args.offset) as fs:
+        if args.command == "shell":
+            ExtShell(fs, label=os.path.basename(args.image)).cmdloop()
+        elif args.command == "info":
+            print("\n".join(format_info(fs)))
+        elif args.command == "ls":
+            flags = "".join(f for f, on in (("l", args.l), ("a", args.a), ("h", args.human)) if on)
+            ExtShell(fs).do_ls(shlex.join(([f"-{flags}"] if flags else []) + [args.path]))
+        elif args.command == "cat":
+            out = sys.stdout.buffer
+            for chunk in fs.iter_read(args.path):
+                out.write(chunk)
+            out.flush()
+        elif args.command == "stat":
+            print("\n".join(format_stat(fs, args.path)))
+        elif args.command == "get":
+            return _get(fs, args.path, args.dest)
+    return 0
+
+
+def _get(fs: ExtFS, path: str, dest: str) -> int:
+    errors = []
+    n = fs.extract(path, dest, on_error=lambda s, e: errors.append((s, e)))
+    for s, e in errors:
+        print(f"ext2py: {s}: {e}", file=sys.stderr)
+    print(f"{n} item(s) copied" + (f", {len(errors)} error(s)" if errors else ""), file=sys.stderr)
+    return 1 if errors else 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 0
+    try:
+        return run(args)
+    except BrokenPipeError:
+        sys.stderr.close()   # e.g. `ext2py cat img /big | head`
+        return 0
+    except KeyboardInterrupt:
+        return 130
+    except (OSError, ExtError) as exc:
+        if isinstance(exc, OSError) and exc.strerror:
+            msg = f"{exc.filename}: {exc.strerror}" if exc.filename else exc.strerror
+        else:
+            msg = str(exc)
+        print(f"ext2py: {msg}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ext2py-0.1.0/src/ext2py/partitions.py

@@ -0,0 +1,120 @@
+"""Minimal MBR / GPT partition table parsing, to find ext filesystems on whole disks."""
+
+from __future__ import annotations
+
+import os
+import struct
+import uuid
+from dataclasses import dataclass
+from typing import BinaryIO, List, Optional, Union
+
+from ext2py.reader import EXT_MAGIC, SUPERBLOCK_OFFSET, ExtError, ExtFS, Source
+
+LINUX_FS_GUID = uuid.UUID("0FC63DAF-8483-4772-8E79-3D69D8477DE4")
+_MBR_EXTENDED = (0x05, 0x0F, 0x85)
+_MBR_GPT_PROTECTIVE = 0xEE
+
+
+@dataclass
+class Partition:
+    number: int       # 1-based, as in /dev/sdaN or diskNsN
+    offset: int       # bytes
+    size: int         # bytes
+    type: str         # MBR type byte (hex) or GPT type GUID
+    name: str = ""
+
+    @property
+    def is_linux(self) -> bool:
+        return self.type in ("0x83", str(LINUX_FS_GUID))
+
+
+def _gpt(src: Source, sector: int) -> Optional[List[Partition]]:
+    hdr = src.pread(sector, 92)
+    if hdr[:8] != b"EFI PART":
+        return None
+    entries_lba, count, entry_size = struct.unpack_from("<QII", hdr, 72)
+    if entry_size < 128 or count > 1024:
+        return None
+    table = src.pread(entries_lba * sector, count * entry_size)
+    parts = []
+    for i in range(count):
+        e = table[i * entry_size:(i + 1) * entry_size]
+        type_guid = uuid.UUID(bytes_le=e[:16])
+        if type_guid.int == 0:
+            continue
+        first, last = struct.unpack_from("<QQ", e, 32)
+        name = e[56:128].decode("utf-16-le", "replace").split("\0", 1)[0]
+        parts.append(Partition(i + 1, first * sector, (last - first + 1) * sector, str(type_guid), name))
+    return parts
+
+
+def find_partitions(f: BinaryIO) -> List[Partition]:
+    """Return the partitions on a disk image or device (empty if none found).
+
+    Logical partitions inside MBR extended partitions are not listed.
+    """
+    src = Source(f)
+    try:
+        mbr = src.pread(0, 512)
+    except ExtError:
+        return []
+    for sector in (512, 4096):
+        try:
+            parts = _gpt(src, sector)
+        except ExtError:
+            parts = None
+        if parts is not None:
+            return parts
+    if mbr[510:512] != b"\x55\xaa":
+        return []
+    parts = []
+    for i in range(4):
+        _status, ptype, start, count = struct.unpack_from("<B3xB3xII", mbr, 446 + 16 * i)
+        if ptype == 0 or ptype in _MBR_EXTENDED or ptype == _MBR_GPT_PROTECTIVE or count == 0:
+            continue
+        parts.append(Partition(i + 1, start * 512, count * 512, f"0x{ptype:02x}"))
+    return parts
+
+
+def _has_ext_magic(f: BinaryIO, offset: int) -> bool:
+    try:
+        sb = Source(f, offset).pread(SUPERBLOCK_OFFSET, 64)
+    except ExtError:
+        return False
+    return struct.unpack_from("<H", sb, 56)[0] == EXT_MAGIC
+
+
+def open_fs(
+    path: Union[str, "os.PathLike[str]"],
+    partition: Optional[int] = None,
+    offset: Optional[int] = None,
+) -> ExtFS:
+    """Open an ext filesystem from a bare filesystem image or a partitioned disk.
+
+    With neither ``partition`` nor ``offset``, a bare filesystem is tried
+    first, then the partition table is searched for exactly one ext partition.
+    """
+    f = open(path, "rb", buffering=0)
+    try:
+        if offset is None:
+            if partition is not None:
+                parts = {p.number: p for p in find_partitions(f)}
+                if partition not in parts:
+                    raise ExtError(f"no partition {partition} (found: {sorted(parts) or 'none'})")
+                offset = parts[partition].offset
+            elif _has_ext_magic(f, 0):
+                offset = 0
+            else:
+                found = [p for p in find_partitions(f) if _has_ext_magic(f, p.offset)]
+                if not found:
+                    raise ExtError("no ext2/3/4 filesystem found (not a bare image, no ext partition)")
+                if len(found) > 1:
+                    nums = ", ".join(str(p.number) for p in found)
+                    raise ExtError(f"several ext partitions found ({nums}); pick one with --partition")
+                offset = found[0].offset
+        fs = ExtFS(f, offset)
+    except BaseException:
+        f.close()
+        raise
+    fs._owns_file = True
+    return fs