:py:mod:`dissect.target.tools.shell` ==================================== .. py:module:: dissect.target.tools.shell Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: dissect.target.tools.shell.AnsiColors dissect.target.tools.shell.ExtendedCmd dissect.target.tools.shell.TargetCmd dissect.target.tools.shell.TargetHubCli dissect.target.tools.shell.TargetCli dissect.target.tools.shell.RegistryCli Functions ~~~~~~~~~ .. autoapisummary:: :nosignatures: dissect.target.tools.shell.readline_escape dissect.target.tools.shell.arg_str_to_arg_list dissect.target.tools.shell.extend_args dissect.target.tools.shell.build_pipe dissect.target.tools.shell.build_pipe_stdout dissect.target.tools.shell.open_shell dissect.target.tools.shell.target_shell dissect.target.tools.shell.python_shell dissect.target.tools.shell.create_cli dissect.target.tools.shell.run_cli dissect.target.tools.shell.main Attributes ~~~~~~~~~~ .. autoapisummary:: dissect.target.tools.shell.log dissect.target.tools.shell.readline dissect.target.tools.shell.ANSI_COLORS .. py:data:: log .. py:data:: readline :value: None .. py:function:: readline_escape(s: str | dict[str, str]) -> str | dict[str, str] Escape a string or values in dictionary for readline prompt. Used to embed terminal-specific escape sequences in prompts. .. rubric:: References - https://wiki.hackzine.org/development/misc/readline-color-prompt.html - http://stackoverflow.com/a/9468954/148845 - RL_PROMPT_START_IGNORE = "" - RL_PROMPT_END_IGNORE = "" .. py:class:: AnsiColors Bases: :py:obj:`dissect.target.helpers.utils.StrEnum` ANSI color escape sequences. .. py:attribute:: RESET :value: '\x1b[0m' .. py:attribute:: RED :value: '\x1b[31m' .. py:attribute:: GREEN :value: '\x1b[32m' .. py:attribute:: YELLOW :value: '\x1b[33m' .. py:attribute:: BLUE :value: '\x1b[34m' .. py:attribute:: MAGENTA :value: '\x1b[35m' .. py:attribute:: CYAN :value: '\x1b[36m' .. py:attribute:: WHITE :value: '\x1b[37m' .. py:attribute:: BOLD_RED :value: '\x1b[1;31m' .. py:attribute:: BOLD_GREEN :value: '\x1b[1;32m' .. py:attribute:: BOLD_YELLOW :value: '\x1b[1;33m' .. py:attribute:: BOLD_BLUE :value: '\x1b[1;34m' .. py:attribute:: BOLD_MAGENTA :value: '\x1b[1;35m' .. py:attribute:: BOLD_CYAN :value: '\x1b[1;36m' .. py:attribute:: BOLD_WHITE :value: '\x1b[1;37m' .. py:method:: as_dict() -> dict[str, str] :classmethod: Return ANSI color escape sequences as a dictionary. .. py:data:: ANSI_COLORS .. py:class:: ExtendedCmd(cyber: bool = False) Bases: :py:obj:`cmd.Cmd` Subclassed cmd.Cmd to provide some additional features. Add new simple commands by implementing: do_(self, line) Add new complex commands by implementing: cmd_(self, args, stdout) Simple commands are plain cmd.Cmd commands. Output is generally presented using print(). Complex command allow @arg decorators for argparse argument parsing. Additionally, complex commands allow their output to be piped to external commands. Complex commands should therefor always write to the stdout handle that is passed as argument. .. py:attribute:: CMD_PREFIX :value: 'cmd_' .. py:attribute:: DEFAULT_RUNCOMMANDS_FILE :value: None .. py:attribute:: debug :value: False .. py:attribute:: cyber :value: False .. py:method:: __getattr__(attr: str) -> Any .. py:method:: preloop() -> None Hook method executed once when the cmdloop() method is called. .. py:method:: check_compatible(target: dissect.target.target.Target) -> bool :staticmethod: .. py:method:: register_aliases() -> None .. py:method:: get_names() -> list[str] .. py:method:: default(line: str) -> bool Called on an input line when the command prefix is not recognized. If this method is not overridden, it prints an error message and returns. .. py:method:: emptyline() -> None This function forces Python's cmd.Cmd module to behave like a regular shell. When entering an empty command, the cmd module will by default repeat the previous command. By defining an empty ``emptyline`` function we make sure no command is executed instead. .. rubric:: References - https://stackoverflow.com/a/16479030 - https://github.com/python/cpython/blob/3.12/Lib/cmd.py#L10 .. py:method:: do_man(line: str) -> bool alias for help .. py:method:: complete_man(*args: list[str]) -> list[str] .. py:method:: do_unalias(line: str) -> bool delete runtime alias .. py:method:: do_alias(line: str) -> bool create a runtime alias .. py:method:: do_clear(line: str) -> bool clear the terminal screen .. py:method:: do_cls(line: str) -> bool alias for clear .. py:method:: do_exit(line: str) -> bool exit shell .. py:method:: do_cyber(line: str) -> bool cyber .. py:method:: do_debug(line: str) -> bool toggle debug mode .. py:class:: TargetCmd(target: dissect.target.target.Target) Bases: :py:obj:`ExtendedCmd` Subclassed cmd.Cmd to provide some additional features. Add new simple commands by implementing: do_(self, line) Add new complex commands by implementing: cmd_(self, args, stdout) Simple commands are plain cmd.Cmd commands. Output is generally presented using print(). Complex command allow @arg decorators for argparse argument parsing. Additionally, complex commands allow their output to be piped to external commands. Complex commands should therefor always write to the stdout handle that is passed as argument. .. py:attribute:: DEFAULT_HISTFILE :value: '~/.dissect_history' .. py:attribute:: DEFAULT_HISTFILESIZE :value: 10000 .. py:attribute:: DEFAULT_HISTDIR :value: None .. py:attribute:: DEFAULT_HISTDIRFMT :value: '.dissect_history_{uid}_{target}' .. py:attribute:: DEFAULT_RUNCOMMANDS_FILE :value: '~/.targetrc' .. py:attribute:: CONFIG_KEY_RUNCOMMANDS_FILE :value: 'TARGETRCFILE' .. py:attribute:: target .. py:attribute:: histfilesize .. py:attribute:: histdir .. py:attribute:: prompt_ps1 :value: '{BOLD_GREEN}{base}{RESET}:{BOLD_BLUE}{cwd}{RESET}$ ' .. py:method:: preloop() -> None Hook method executed once when the cmdloop() method is called. .. py:method:: postloop() -> None Hook method executed once when the cmdloop() method is about to return. .. py:method:: do_python(line: str) -> bool drop into a Python shell .. py:class:: TargetHubCli(targets: list[dissect.target.target.Target], cli: TargetCmd) Bases: :py:obj:`cmd.Cmd` Hub Cli for interacting with multiple targets. .. py:attribute:: prompt :value: 'dissect> ' .. py:attribute:: doc_header :value: Multiline-String .. raw:: html
Show Value .. code-block:: python """Target Hub ========== List and enter targets by using 'list' and 'enter'. Documented commands (type help ):""" .. raw:: html
.. py:attribute:: targets .. py:method:: default(line: str) -> bool Called on an input line when the command prefix is not recognized. If this method is not overridden, it prints an error message and returns. .. py:method:: emptyline() -> None Called when an empty line is entered in response to the prompt. If this method is not overridden, it repeats the last nonempty command entered. .. py:method:: do_exit(line: str) -> bool exit shell .. py:method:: do_list(line: str) -> bool list the loaded targets .. py:method:: do_enter(line: str) -> bool enter a target by number or name .. py:method:: complete_enter(text: str, line: str, begidx: int, endidx: int) -> list[str] .. py:method:: do_python(line: str) -> bool drop into a Python shell .. py:class:: TargetCli(target: dissect.target.target.Target) Bases: :py:obj:`TargetCmd` CLI for interacting with a target and browsing the filesystem. .. py:attribute:: prompt_base .. py:attribute:: cwd .. py:property:: prompt :type: str .. py:method:: completedefault(text: str, line: str, begidx: int, endidx: int) -> list[str] Method called to complete an input line when no command-specific complete_*() method is available. By default, it returns an empty list. .. py:method:: resolve_path(path: str) -> dissect.target.helpers.fsutil.TargetPath .. py:method:: resolve_glob_path(path: str) -> collections.abc.Iterator[dissect.target.helpers.fsutil.TargetPath] .. py:method:: check_file(path: str) -> dissect.target.helpers.fsutil.TargetPath | None .. py:method:: check_dir(path: str) -> dissect.target.helpers.fsutil.TargetPath | None .. py:method:: check_path(path: str) -> dissect.target.helpers.fsutil.TargetPath | None .. py:method:: chdir(path: str) -> None Change directory to the given path. .. py:method:: do_cd(line: str) -> bool change directory .. py:method:: do_pwd(line: str) -> bool print current directory .. py:method:: do_disks(line: str) -> bool print target disks .. py:method:: do_volumes(line: str) -> bool print target volumes .. py:method:: do_filesystems(line: str) -> bool print target filesystems .. py:method:: do_mounts(line: str) -> bool print target mounts .. py:method:: do_info(line: str) -> bool print target information .. py:method:: do_reload(line: str) -> bool reload the target .. py:method:: cmd_ls(args: argparse.Namespace, stdout: TextIO) -> bool list directory contents .. py:method:: cmd_ll(args: argparse.Namespace, stdout: TextIO) -> bool alias for ls -la .. py:method:: cmd_tree(args: argparse.Namespace, stdout: TextIO) -> bool alias for ls -R .. py:method:: cmd_find(args: argparse.Namespace, stdout: TextIO) -> bool search for files in a directory hierarchy .. py:method:: cmd_stat(args: argparse.Namespace, stdout: TextIO) -> bool display file status .. py:method:: cmd_attr(args: argparse.Namespace, stdout: TextIO) -> bool display file attributes .. py:method:: cmd_file(args: argparse.Namespace, stdout: TextIO) -> bool determine file type .. py:method:: cmd_save(args: argparse.Namespace, stdout: TextIO) -> bool save a common file or directory to the host filesystem .. py:method:: cmd_cat(args: argparse.Namespace, stdout: TextIO) -> bool print file content .. py:method:: cmd_zcat(args: argparse.Namespace, stdout: TextIO) -> bool print file content from compressed files .. py:method:: cmd_hexdump(args: argparse.Namespace, stdout: TextIO) -> bool print a hexdump of file(s) .. py:method:: cmd_hash(args: argparse.Namespace, stdout: TextIO) -> bool print the MD5, SHA1 and SHA256 hashes of a file .. py:method:: cmd_md5sum(args: argparse.Namespace, stdout: TextIO) -> bool print the MD5 checksum of a file provided by a path .. py:method:: cmd_sha1sum(args: argparse.Namespace, stdout: TextIO) -> bool print the SHA1 checksum of a file provided by a path .. py:method:: cmd_sha256sum(args: argparse.Namespace, stdout: TextIO) -> bool print the SHA256 checksum of a file provided by a path .. py:method:: cmd_less(args: argparse.Namespace, stdout: TextIO) -> bool open the first 10 MB of a file with less .. py:method:: cmd_zless(args: argparse.Namespace, stdout: TextIO) -> bool open the first 10 MB of a compressed file with zless .. py:method:: cmd_readlink(args: argparse.Namespace, stdout: TextIO) -> bool print resolved symbolic links or canonical file names .. py:method:: cmd_registry(args: argparse.Namespace, stdout: TextIO) -> bool drop into a registry shell .. py:method:: cmd_enter(args: argparse.Namespace, stdout: TextIO) -> bool load one or more files as sub-targets and drop into a sub-shell .. py:class:: RegistryCli(target: dissect.target.target.Target, registry: dissect.target.helpers.regutil.RegfHive | None = None) Bases: :py:obj:`TargetCmd` CLI for browsing the registry. .. py:attribute:: DEFAULT_RUNCOMMANDS_FILE :value: '~/.targetrc.registry' .. py:attribute:: CONFIG_KEY_RUNCOMMANDS_FILE :value: 'TARGETRCFILE_REGISTRY' .. py:attribute:: prompt_base .. py:attribute:: registry .. py:attribute:: cwd :value: None .. py:method:: check_compatible(target: dissect.target.target.Target) -> bool :staticmethod: .. py:property:: prompt :type: str .. py:method:: completedefault(text: str, line: str, begidx: int, endidx: int) -> list[str] Method called to complete an input line when no command-specific complete_*() method is available. By default, it returns an empty list. .. py:method:: resolve_key(path: str) -> dissect.target.helpers.regutil.RegistryKey .. py:method:: check_key(path: str) -> dissect.target.helpers.regutil.RegistryKey .. py:method:: check_value(path: str) -> dissect.target.helpers.regutil.RegistryValue .. py:method:: chdir(path: str) -> None .. py:method:: scandir(path: str, color: bool = False) -> list[tuple[dissect.target.helpers.regutil.RegistryKey | dissect.target.helpers.regutil.RegistryValue, str]] .. py:method:: do_cd(line: str) -> bool change subkey .. py:method:: do_up(line: str) -> bool go up a subkey .. py:method:: do_pwd(line: str) -> bool print current path .. py:method:: do_recommend(line: str) -> bool recommend a key .. py:method:: cmd_ls(args: argparse.Namespace, stdout: TextIO) -> bool .. py:method:: cmd_cat(args: argparse.Namespace, stdout: TextIO) -> bool .. py:method:: cmd_hexdump(args: argparse.Namespace, stdout: TextIO) -> bool .. py:function:: arg_str_to_arg_list(args: str) -> list[str] Convert a commandline string to a list of command line arguments. .. py:function:: extend_args(args: argparse.Namespace, func: collections.abc.Callable) -> argparse.Namespace Extend the arguments of the given ``func`` with the provided ``argparse.Namespace``. .. py:function:: build_pipe(pipe_parts: list[str], pipe_stdout: int = subprocess.PIPE) -> collections.abc.Iterator[tuple[TextIO, BinaryIO]] Generator context manager that chains piped subprocessess and returns a tuple (chain input stream, chain output stream). On context exit the generator will close the input stream and wait for the subprocessess to finish. .. py:function:: build_pipe_stdout(pipe_parts: list[str]) -> collections.abc.Iterator[TextIO] Generator context manager that chains piped subprocessess, with a chain's outgoing stream configured to be parent's stdout. Generator returns a chain's input stream from `build_pipe` generator. .. py:function:: open_shell(targets: list[dissect.target.target.Target], python: bool = False, registry: bool = False, commands: list[str] | None = None) -> None Helper method for starting a regular, Python or registry shell for one or multiple targets. .. py:function:: target_shell(targets: list[dissect.target.target.Target], cli_cls: type[TargetCmd], commands: list[str] | None = None) -> None Helper method for starting a :class:`TargetCli` or :class:`TargetHubCli` for one or multiple targets. .. py:function:: python_shell(targets: list[dissect.target.target.Target], commands: list[str] | None = None) -> None Helper method for starting a (I)Python shell with multiple targets. .. py:function:: create_cli(targets: list[dissect.target.target.Target], cli_cls: type[TargetCmd]) -> cmd.Cmd | None Helper method for instatiating the appropriate CLI. .. py:function:: run_cli(cli: cmd.Cmd) -> None Helper method for running a cmd.Cmd cli. Loops cli.cmdloop(), skipping KeyboardInterrupts. This is done so that ctrl+c doesn't exit the shell but only resets the current line. .. py:function:: main() -> int