ext2py 0.1.0__py3-none-any.whl

ext2py/shell.py

@@ -0,0 +1,380 @@
+"""Interactive, read-only shell for browsing an ext filesystem (``ext2py shell``)."""
+
+from __future__ import annotations
+
+import cmd
+import fnmatch
+import os
+import posixpath
+import shlex
+import sys
+import time
+from typing import List, Optional, TextIO
+
+from ext2py.reader import DirEntry, ExtError, ExtFS
+
+
+def human_size(n: int) -> str:
+    for unit in ("B", "K", "M", "G", "T"):
+        if n < 1024 or unit == "T":
+            return f"{n}{unit}" if unit == "B" else f"{n:.1f}{unit}"
+        n /= 1024
+    return str(n)
+
+
+def format_time(ts: float) -> str:
+    t = time.localtime(ts)
+    if abs(time.time() - ts) > 180 * 86400:
+        return time.strftime("%b %d  %Y", t)
+    return time.strftime("%b %d %H:%M", t)
+
+
+def long_listing(fs: ExtFS, entries: List[tuple], human: bool = False) -> List[str]:
+    """Format ``(name, inode)`` pairs like ``ls -l``."""
+    rows = []
+    for name, inode in entries:
+        size = human_size(inode.size) if human else str(inode.size)
+        if inode.is_symlink:
+            try:
+                name = f"{name} -> {fs._readlink(inode).decode('utf-8', 'replace')}"
+            except (OSError, ExtError):
+                pass
+        rows.append((inode.filemode, str(inode.links_count), str(inode.uid), str(inode.gid),
+                     size, format_time(inode.mtime), name))
+    if not rows:
+        return []
+    widths = [max(len(r[i]) for r in rows) for i in range(4)]
+    size_w = max(len(r[4]) for r in rows)
+    return [
+        f"{r[0]} {r[1]:>{widths[1]}} {r[2]:<{widths[2]}} {r[3]:<{widths[3]}} "
+        f"{r[4]:>{size_w}} {r[5]} {r[6]}"
+        for r in rows
+    ]
+
+
+class ExtShell(cmd.Cmd):
+    """``cd`` / ``ls`` / ``get`` around a read-only :class:`ExtFS`."""
+
+    doc_header = "Commands (type help <command>):"
+
+    def __init__(self, fs: ExtFS, label: str = "", stdin: Optional[TextIO] = None,
+                 stdout: Optional[TextIO] = None):
+        super().__init__(stdin=stdin, stdout=stdout)
+        if stdin is not None:
+            self.use_rawinput = False
+        self.fs = fs
+        self.label = label
+        self.cwd = "/"
+        self.local_dir = os.getcwd()
+        self.intro = (
+            f"ext2py shell: {label} ({fs.sb.fs_type}, read-only). "
+            "Type 'help' for commands, 'exit' to quit."
+        )
+        if fs.needs_recovery:
+            self.intro += ("\nwarning: the journal needs recovery; the most recent "
+                           "writes may be missing or inconsistent.")
+
+    # -- plumbing ---------------------------------------------------------- #
+
+    @property
+    def prompt(self) -> str:  # type: ignore[override]
+        return f"ext2py:{self.cwd}$ "
+
+    def print(self, *args) -> None:
+        print(*args, file=self.stdout)
+
+    def error(self, msg: str) -> None:
+        print(f"error: {msg}", file=self.stdout)
+
+    def resolve(self, arg: str) -> str:
+        """Lexically resolve ``arg`` against the current directory (like ``cd`` in a shell)."""
+        path = posixpath.normpath(posixpath.join(self.cwd, arg or "."))
+        return "/" + path.lstrip("/")
+
+    def local_path(self, arg: str) -> str:
+        return os.path.normpath(os.path.join(self.local_dir, os.path.expanduser(arg)))
+
+    def args(self, line: str) -> List[str]:
+        return shlex.split(line)
+
+    def onecmd(self, line: str) -> bool:
+        try:
+            return bool(super().onecmd(line))
+        except KeyboardInterrupt:
+            self.print("^C")
+        except ValueError as exc:   # shlex: unbalanced quotes
+            self.error(str(exc))
+        except (OSError, ExtError) as exc:
+            self.error(exc.strerror if isinstance(exc, OSError) and exc.strerror else str(exc))
+        return False
+
+    def emptyline(self) -> bool:
+        return False
+
+    def default(self, line: str) -> bool:
+        self.error(f"unknown command: {line.split()[0]} (try 'help')")
+        return False
+
+    def preloop(self) -> None:
+        try:
+            import readline
+        except ImportError:
+            return
+        readline.set_completer_delims(" \t\n")
+        if "libedit" in (readline.__doc__ or "") and sys.version_info < (3, 13):
+            readline.parse_and_bind("bind ^I rl_complete")
+
+    # -- completion -------------------------------------------------------- #
+
+    def _complete_remote(self, text: str, dirs_only: bool = False) -> List[str]:
+        head, _, tail = text.rpartition("/")
+        base = self.resolve(head + "/" if head or text.startswith("/") else ".")
+        try:
+            entries = self.fs.scandir(base)
+        except (OSError, ExtError):
+            return []
+        out = []
+        for e in entries:
+            if not e.name.startswith(tail):
+                continue
+            is_dir = self._entry_is_dir(base, e)
+            if dirs_only and not is_dir:
+                continue
+            prefix = head + "/" if head or text.startswith("/") else ""
+            out.append(prefix + e.name + ("/" if is_dir else ""))
+        return out
+
+    def _entry_is_dir(self, base: str, e: DirEntry) -> bool:
+        try:
+            return self.fs.isdir(posixpath.join(base, e.name))
+        except (OSError, ExtError):
+            return False
+
+    def _complete_paths(self, text, line, begidx, endidx):
+        return self._complete_remote(text)
+
+    def complete_cd(self, text, line, begidx, endidx):
+        return self._complete_remote(text, dirs_only=True)
+
+    complete_ls = complete_ll = complete_cat = complete_stat = _complete_paths
+    complete_get = complete_find = complete_tree = complete_readlink = _complete_paths
+
+    def complete_lcd(self, text, line, begidx, endidx):
+        base = self.local_path(os.path.dirname(text) or ".")
+        try:
+            names = os.listdir(base)
+        except OSError:
+            return []
+        head = os.path.dirname(text)
+        return [os.path.join(head, n) + "/" for n in names
+                if n.startswith(os.path.basename(text)) and os.path.isdir(os.path.join(base, n))]
+
+    # -- navigation -------------------------------------------------------- #
+
+    def do_pwd(self, line: str) -> None:
+        """pwd: print the current directory inside the filesystem."""
+        self.print(self.cwd)
+
+    def do_cd(self, line: str) -> None:
+        """cd [DIR]: change directory inside the filesystem (default: /)."""
+        args = self.args(line)
+        path = self.resolve(args[0] if args else "/")
+        if not self.fs.stat(path).is_dir:
+            raise NotADirectoryError(20, "Not a directory")
+        self.cwd = path
+
+    def do_ls(self, line: str) -> None:
+        """ls [-l] [-a] [-h] [PATH...]: list directory contents."""
+        flags, paths = set(), []
+        for a in self.args(line):
+            if a.startswith("-") and len(a) > 1:
+                flags.update(a[1:])
+            else:
+                paths.append(a)
+        unknown = flags - set("lah")
+        if unknown:
+            return self.error(f"ls: unknown option -{''.join(sorted(unknown))}")
+        paths = paths or ["."]
+        for i, p in enumerate(paths):
+            path = self.resolve(p)
+            inode = self.fs.stat(path)
+            if len(paths) > 1 and inode.is_dir:
+                self.print(("\n" if i else "") + f"{p}:")
+            if not inode.is_dir:
+                self._print_listing([(p, self.fs.lstat(path))], flags)
+                continue
+            entries = sorted(self.fs._dir_entries(inode.ino), key=lambda e: e.name)
+            if "a" not in flags:
+                entries = [e for e in entries if not e.name.startswith(".")]
+            items = []
+            for e in entries:
+                try:
+                    items.append((e.name, self.fs.inode(e.inode)))
+                except ExtError as exc:
+                    self.error(f"{e.name}: {exc}")
+            self._print_listing(items, flags)
+
+    def _print_listing(self, items: List[tuple], flags: set) -> None:
+        if "l" in flags:
+            for row in long_listing(self.fs, items, human="h" in flags):
+                self.print(row)
+        else:
+            for name, inode in items:
+                suffix = "/" if inode.is_dir else "@" if inode.is_symlink else ""
+                self.print(name + suffix)
+
+    def do_ll(self, line: str) -> None:
+        """ll [PATH...]: shorthand for ls -lh."""
+        self.do_ls("-lh " + line)
+
+    def do_tree(self, line: str) -> None:
+        """tree [PATH]: show the directory tree."""
+        args = self.args(line)
+        root = self.resolve(args[0] if args else ".")
+        self.print(root)
+        self._tree(root, "")
+
+    def _tree(self, path: str, indent: str) -> None:
+        entries = sorted(self.fs.scandir(path), key=lambda e: e.name)
+        for i, e in enumerate(entries):
+            last = i == len(entries) - 1
+            child = posixpath.join(path, e.name)
+            inode = self.fs.inode(e.inode)
+            self.print(f"{indent}{'└── ' if last else '├── '}{e.name}{'/' if inode.is_dir else ''}")
+            if inode.is_dir:
+                self._tree(child, indent + ("    " if last else "│   "))
+
+    def do_find(self, line: str) -> None:
+        """find [PATH] [-name PATTERN]: list files recursively, optionally matching a glob."""
+        args = self.args(line)
+        pattern = None
+        if "-name" in args:
+            i = args.index("-name")
+            if i + 1 >= len(args):
+                return self.error("find: -name needs a pattern")
+            pattern = args[i + 1]
+            del args[i:i + 2]
+        root = self.resolve(args[0] if args else ".")
+        for top, dirs, files in self.fs.walk(root):
+            for name in dirs + files:
+                if pattern is None or fnmatch.fnmatch(name, pattern):
+                    self.print(posixpath.join(top, name))
+
+    # -- inspection -------------------------------------------------------- #
+
+    def do_cat(self, line: str) -> None:
+        """cat FILE...: print file contents."""
+        out = getattr(self.stdout, "buffer", None)
+        for p in self.args(line):
+            for chunk in self.fs.iter_read(self.resolve(p)):
+                if out is not None:
+                    out.write(chunk)
+                else:
+                    self.stdout.write(chunk.decode("utf-8", "replace"))
+            if out is not None:
+                out.flush()
+
+    def do_stat(self, line: str) -> None:
+        """stat PATH...: show inode details (does not follow a final symlink)."""
+        for p in self.args(line):
+            for row in format_stat(self.fs, self.resolve(p)):
+                self.print(row)
+
+    def do_readlink(self, line: str) -> None:
+        """readlink PATH: print a symlink's target."""
+        for p in self.args(line):
+            self.print(self.fs.readlink(self.resolve(p)))
+
+    def do_info(self, line: str) -> None:
+        """info: show filesystem (superblock) information."""
+        for row in format_info(self.fs):
+            self.print(row)
+
+    # -- local side and downloads ----------------------------------------- #
+
+    def do_lpwd(self, line: str) -> None:
+        """lpwd: print the local download directory."""
+        self.print(self.local_dir)
+
+    def do_lcd(self, line: str) -> None:
+        """lcd [DIR]: change the local download directory (default: home)."""
+        args = self.args(line)
+        path = self.local_path(args[0] if args else "~")
+        if not os.path.isdir(path):
+            raise NotADirectoryError(20, f"Not a local directory: {path}")
+        self.local_dir = path
+
+    def do_lls(self, line: str) -> None:
+        """lls [DIR]: list the local download directory."""
+        args = self.args(line)
+        for name in sorted(os.listdir(self.local_path(args[0] if args else "."))):
+            self.print(name)
+
+    def do_get(self, line: str) -> None:
+        """get PATH [LOCAL]: download a file or directory (recursively) to the local side.
+
+        LOCAL defaults to the local directory (see lcd / lpwd)."""
+        args = self.args(line)
+        if not args or len(args) > 2:
+            return self.error("usage: get PATH [LOCAL]")
+        src = self.resolve(args[0])
+        dest = self.local_path(args[1] if len(args) > 1 else ".")
+        errors = []
+        n = self.fs.extract(
+            src, dest,
+            on_file=lambda s, d: self.print(f"{s} -> {d}"),
+            on_error=lambda s, e: errors.append((s, e)),
+        )
+        for s, e in errors:
+            self.error(f"{s}: {e}")
+        self.print(f"{n} item(s) copied" + (f", {len(errors)} error(s)" if errors else ""))
+
+    # -- exit -------------------------------------------------------------- #
+
+    def do_exit(self, line: str) -> bool:
+        """exit: leave the shell."""
+        return True
+
+    do_quit = do_exit
+
+    def do_EOF(self, line: str) -> bool:
+        self.print()
+        return True
+
+
+def format_stat(fs: ExtFS, path: str) -> List[str]:
+    inode = fs.lstat(path)
+    kind = ("directory" if inode.is_dir else "symlink" if inode.is_symlink
+            else "regular file" if inode.is_file else "special file")
+    rows = [
+        f"  File: {path}" + (f" -> {fs.readlink(path)}" if inode.is_symlink else ""),
+        f"  Type: {kind}",
+        f"  Size: {inode.size}  Blocks: {inode.blocks}  Inode: {inode.ino}  Links: {inode.links_count}",
+        f"  Mode: ({inode.mode & 0o7777:04o}/{inode.filemode})  Uid: {inode.uid}  Gid: {inode.gid}",
+        f"Access: {time.ctime(inode.atime)}",
+        f"Modify: {time.ctime(inode.mtime)}",
+        f"Change: {time.ctime(inode.ctime)}",
+    ]
+    if inode.crtime is not None:
+        rows.append(f" Birth: {time.ctime(inode.crtime)}")
+    rows.append(f" Flags: 0x{inode.flags:08x}")
+    return rows
+
+
+def format_info(fs: ExtFS) -> List[str]:
+    sb = fs.sb
+    return [
+        f"Filesystem:     {sb.fs_type}",
+        f"Volume name:    {sb.volume_name or '<none>'}",
+        f"UUID:           {sb.uuid_str}",
+        f"Last mounted:   {sb.last_mounted or '<not available>'}",
+        f"Block size:     {sb.block_size}",
+        f"Blocks:         {sb.blocks_count} ({human_size(sb.blocks_count * sb.block_size)})",
+        f"Free blocks:    {sb.free_blocks_count} ({human_size(sb.free_blocks_count * sb.block_size)})",
+        f"Inodes:         {sb.inodes_count} (free: {sb.free_inodes_count})",
+        f"Inode size:     {sb.inode_size}",
+        f"Block groups:   {sb.group_count}",
+        f"Features:       {' '.join(sb.incompat_names()) or '<none>'}",
+        f"Last written:   {time.ctime(sb.wtime) if sb.wtime else '<never>'}",
+        f"Needs recovery: {'yes' if fs.needs_recovery else 'no'}",
+    ]

ext2py-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+ext2py/__init__.py,sha256=_FijcqrFGHtrwilC2PqT27RKPDTFQmVHUHydWMwB7Wo,372
+ext2py/__main__.py,sha256=rCpxNVxxM_DN11PqB6c2XBWECcdK3_COdyFjhMZUQKE,54
+ext2py/cli.py,sha256=TznMfVcXl2Cq3bdp_1Mf5ICusUv21zGSG1RvfpJmhXs,4689
+ext2py/partitions.py,sha256=Ff5AH6o2MNHV_-Uz1qSv96F1Bq1Cz1Ed7raWdDb37dI,4143
+ext2py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ext2py/reader.py,sha256=Tpx9-RmtsZsvgukprSyRN0-X2P2DvgbVGN5sn9KZsOg,30380
+ext2py/shell.py,sha256=XhlStQnmoYHvkcPgP8qhNEsY-vrA0DsZxK4oSX8YbFU,14583
+ext2py-0.1.0.dist-info/licenses/LICENSE,sha256=Kn4QoRBSiTQ3mbTE9nI3yRUXGAYATn19XVnVEzL9ybA,1075
+ext2py-0.1.0.dist-info/METADATA,sha256=HPbO2SgYi-tt3P2oojuAIyQ8gl5RXhiGMLW9kdrUgUQ,4821
+ext2py-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ext2py-0.1.0.dist-info/entry_points.txt,sha256=RTFc6CHQP1trbvF2TIrpQyH-9WlCPtaB_n0wt0sP64w,43
+ext2py-0.1.0.dist-info/top_level.txt,sha256=byf7DwC3q56XkogUSGhtBURO_3tw6bx5wagy0m21mm4,7
+ext2py-0.1.0.dist-info/RECORD,,

ext2py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ext2py-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ext2py = ext2py.cli:main

ext2py-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+ext2py