From c7c83ca5397471357921a8e32f23bb7003aff9b4 Mon Sep 17 00:00:00 2001 From: David McDonald Date: Thu, 27 Feb 2025 21:22:38 -0600 Subject: [PATCH] Development: Add stub files With the plugin module __path__ variable updated at runtime, and plugin imports based on this updated path within their own module definitions, static type checkers and language servers cannot resolve these imports to provide support for autocompletion, type-checking, etc. This commit: - Adds the required stub files to make development easier when working on plugins - Removes the stubs directory from the .gitignore file - Adds a [tool.pyright] section to tell pyright where to look for stubs Development: Additional stub updates --- .gitignore | 1 - pyproject.toml | 3 + stubs/volatility3/__init__.pyi | 14 ++ stubs/volatility3/plugins/__init__.pyi | 27 ++++ stubs/volatility3/plugins/linux/__init__.pyi | 85 ++++++++++ stubs/volatility3/plugins/mac/__init__.pyi | 51 ++++++ .../volatility3/plugins/windows/__init__.pyi | 153 ++++++++++++++++++ volatility3/py.typed | 0 8 files changed, 333 insertions(+), 1 deletion(-) create mode 100644 stubs/volatility3/__init__.pyi create mode 100644 stubs/volatility3/plugins/__init__.pyi create mode 100644 stubs/volatility3/plugins/linux/__init__.pyi create mode 100644 stubs/volatility3/plugins/mac/__init__.pyi create mode 100644 stubs/volatility3/plugins/windows/__init__.pyi create mode 100644 volatility3/py.typed diff --git a/.gitignore b/.gitignore index c132736a9c..da06318669 100644 --- a/.gitignore +++ b/.gitignore @@ -13,7 +13,6 @@ workspace.xml # Manually generated files .mypy_cache -stubs volatility3/symbols/linux* volatility3/symbols/windows* volatility3/symbols/mac* diff --git a/pyproject.toml b/pyproject.toml index 742b4f7712..687c6506dd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -76,6 +76,9 @@ include = ["volatility3*"] mypy_path = "./stubs" show_traceback = true +[tool.pyright] +stubPath = "./stubs" + [tool.ruff] line-length = 88 target-version = "py38" diff --git a/stubs/volatility3/__init__.pyi b/stubs/volatility3/__init__.pyi new file mode 100644 index 0000000000..1f76940292 --- /dev/null +++ b/stubs/volatility3/__init__.pyi @@ -0,0 +1,14 @@ +from importlib import abc +from typing import Any, Callable + +class classproperty(property): + def __init__(self, func: Callable[[_S], _T]) -> None: ... + def __get__(self, obj: Any, type: _S | None = None) -> _T: ... + +class WarningFindSpec(abc.MetaPathFinder): + @staticmethod + def find_spec( + fullname: str, path: list[str] | None, target: None = None, **kwargs + ) -> None: ... + +warning_find_spec: list[abc.MetaPathFinder] diff --git a/stubs/volatility3/plugins/__init__.pyi b/stubs/volatility3/plugins/__init__.pyi new file mode 100644 index 0000000000..98870ce5b5 --- /dev/null +++ b/stubs/volatility3/plugins/__init__.pyi @@ -0,0 +1,27 @@ +from volatility3.framework.plugins import ( + banners, + configwriter, + isfinfo, + layerwriter, + linux, + mac, + regexscan, + timeliner, + vmscan, + windows, + yarascan, +) + +__all__ = [ + "banners", + "configwriter", + "isfinfo", + "layerwriter", + "linux", + "mac", + "regexscan", + "timeliner", + "vmscan", + "windows", + "yarascan", +] diff --git a/stubs/volatility3/plugins/linux/__init__.pyi b/stubs/volatility3/plugins/linux/__init__.pyi new file mode 100644 index 0000000000..475db98f25 --- /dev/null +++ b/stubs/volatility3/plugins/linux/__init__.pyi @@ -0,0 +1,85 @@ +from volatility3.framework.plugins.linux import ( + bash, + boottime, + capabilities, + check_afinfo, + check_creds, + check_idt, + check_modules, + check_syscall, + ebpf, + elfs, + envars, + hidden_modules, + iomem, + ip, + kallsyms, + keyboard_notifiers, + kmsg, + kthreads, + library_list, + lsmod, + lsof, + malfind, + modxview, + mountinfo, + netfilter, + pagecache, + pidhashtable, + proc, + psaux, + pscallstack, + pslist, + psscan, + pstree, + ptrace, + sockstat, + tracing, + tty_check, + vmaregexscan, + vmayarascan, + vmcoreinfo, +) + +__all__ = [ + "bash", + "boottime", + "capabilities", + "check_afinfo", + "check_creds", + "check_idt", + "check_modules", + "check_syscall", + "ebpf", + "elfs", + "envars", + "hidden_modules", + "iomem", + "ip", + "kallsyms", + "keyboard_notifiers", + "kmsg", + "kthreads", + "library_list", + "lsmod", + "lsof", + "malfind", + "modxview", + "mountinfo", + "netfilter", + "pagecache", + "pidhashtable", + "proc", + "psaux", + "pscallstack", + "pslist", + "psscan", + "pstree", + "ptrace", + "sockstat", + "tracing", + "tty_check", + "vmaregexscan", + "vmayarascan", + "vmcoreinfo", +] diff --git a/stubs/volatility3/plugins/mac/__init__.pyi b/stubs/volatility3/plugins/mac/__init__.pyi new file mode 100644 index 0000000000..4745f51633 --- /dev/null +++ b/stubs/volatility3/plugins/mac/__init__.pyi @@ -0,0 +1,51 @@ +from volatility3.framework.plugins.mac import ( + bash, + check_syscall, + check_sysctl, + check_trap_table, + dmesg, + ifconfig, + kauth_listeners, + kauth_scopes, + kevents, + list_files, + lsmod, + lsof, + malfind, + mount, + netstat, + proc_maps, + psaux, + pslist, + pstree, + socket_filters, + timers, + trustedbsd, + vfsevents, +) + +__all__ = [ + "bash", + "check_syscall", + "check_sysctl", + "check_trap_table", + "dmesg", + "ifconfig", + "kauth_listeners", + "kauth_scopes", + "kevents", + "list_files", + "lsmod", + "lsof", + "malfind", + "mount", + "netstat", + "proc_maps", + "psaux", + "pslist", + "pstree", + "socket_filters", + "timers", + "trustedbsd", + "vfsevents", +] diff --git a/stubs/volatility3/plugins/windows/__init__.pyi b/stubs/volatility3/plugins/windows/__init__.pyi new file mode 100644 index 0000000000..90ef5c7f0a --- /dev/null +++ b/stubs/volatility3/plugins/windows/__init__.pyi @@ -0,0 +1,153 @@ +from volatility3.framework.plugins.windows import ( + amcache, + bigpools, + cachedump, + callbacks, + cmdline, + cmdscan, + consoles, + crashinfo, + debugregisters, + devicetree, + direct_system_calls, + dlllist, + driverirp, + drivermodule, + driverscan, + dumpfiles, + envars, + filescan, + getservicesids, + getsids, + handles, + hashdump, + hollowprocesses, + iat, + indirect_system_calls, + info, + joblinks, + kpcrs, + ldrmodules, + lsadump, + malfind, + mbrscan, + memmap, + mftscan, + modscan, + modules, + mutantscan, + netscan, + netstat, + orphan_kernel_threads, + pe_symbols, + pedump, + poolscanner, + privileges, + processghosting, + pslist, + psscan, + pstree, + psxview, + registry, + scheduled_tasks, + sessions, + shimcachemem, + skeleton_key_check, + ssdt, + strings, + suspended_threads, + suspicious_threads, + svcdiff, + svclist, + svcscan, + symlinkscan, + thrdscan, + threads, + timers, + truecrypt, + unhooked_system_calls, + unloadedmodules, + vadinfo, + vadregexscan, + vadwalk, + vadyarascan, + verinfo, + virtmap, +) + +__all__ = [ + "amcache", + "bigpools", + "cachedump", + "callbacks", + "cmdline", + "cmdscan", + "consoles", + "crashinfo", + "debugregisters", + "devicetree", + "direct_system_calls", + "dlllist", + "driverirp", + "drivermodule", + "driverscan", + "dumpfiles", + "envars", + "filescan", + "getservicesids", + "getsids", + "handles", + "hashdump", + "hollowprocesses", + "iat", + "indirect_system_calls", + "info", + "joblinks", + "kpcrs", + "ldrmodules", + "lsadump", + "malfind", + "mbrscan", + "memmap", + "mftscan", + "modscan", + "modules", + "mutantscan", + "netscan", + "netstat", + "orphan_kernel_threads", + "pe_symbols", + "pedump", + "poolscanner", + "privileges", + "processghosting", + "pslist", + "psscan", + "pstree", + "psxview", + "registry", + "scheduled_tasks", + "sessions", + "shimcachemem", + "skeleton_key_check", + "ssdt", + "strings", + "suspended_threads", + "suspicious_threads", + "svcdiff", + "svclist", + "svcscan", + "symlinkscan", + "thrdscan", + "threads", + "timers", + "truecrypt", + "unhooked_system_calls", + "unloadedmodules", + "vadinfo", + "vadregexscan", + "vadwalk", + "vadyarascan", + "verinfo", + "virtmap", +] diff --git a/volatility3/py.typed b/volatility3/py.typed new file mode 100644 index 0000000000..e69de29bb2