pwncat.platform.linux module¶
The Linux platform provides Linux shell support ontop of any channel. The Linux platform expects the channel to expose a shell whose stdio is connected directly to the channel IO. At a minimum stdin and stdout must be connected.
Because of the way this platform interacts with the shell directly,
it is not able to manage multiple active processes. Only as single
Popen can be running at a time. It is imperative that you call
Popen.wait
or wait for Popen.poll
to return non-Null prior
to calling any other pwncat methods.
- class pwncat.platform.linux.Linux(session, channel: pwncat.channel.Channel, *args, **kwargs)¶
Bases:
pwncat.platform.Platform
Concrete platform class abstracting interaction with a GNU/Linux remote host. See the base class (
pwncat.platform.Platform
) for more information on the implemented methods and interface definition.- PATH_TYPE¶
alias of
pwncat.platform.linux.LinuxPath
- PROMPTS = {'dash': '\'$(command printf "(remote) $(whoami)@$(hostname):$PWD\\$ ")\'', 'default': '\'$(command printf "\\[\\033[01;31m\\](remote)\\[\\033[0m\\] \\[\\033[01;33m\\]$(whoami)@$(hostname)\\[\\033[0m\\]:\\[\\033[1;36m\\]$PWD\\[\\033[0m\\]\\$ ")\'', 'sh': '\'$(command printf "(remote) $(whoami)@$(hostname):$PWD\\$ ")\'', 'zsh': "'%B%F{red}(remote) %B%F{yellow}%n@%M%B%F{reset}:%B%F{cyan}$PWD%B%(#.%b%F{white}#.%b%F{white}$)%b%F{reset} '"}¶
- Popen(args, bufsize=- 1, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, encoding=None, text=None, errors=None, env=None, bootstrap_input=None, send_command=None, **other_popen_kwargs) pwncat.subprocess.Popen ¶
Execute a process on the remote host with an interface similar to that of the python standard
subprocess.Popen
. The returned object behaves much like a standardPopen
object and conforms to the interface defined bypwncat.subprocess.Popen
. For an explanation of arguments, seepwncat.subprocess.Popen
.
- abspath(path: str) str ¶
Attempt to resolve a path to an absolute path
- chdir(path: Union[str, pwncat.platform.Path])¶
Change directories to the given path. This method returns the current working directory prior to the change.
- Parameters
path (Union[str, pwncat.platform.Path]) – a relative or absolute path to change to
- Returns
current working directory prior to the change
- Raises
FileNotFoundError: the specified path doesn’t exist NotADirectoryError: the specified path is not a directory
- chmod(path: str, mode: int, link: bool = False)¶
Update the file permissions
- chown(path: str, uid: int, gid: int)¶
Change ownership of a file
- compile(sources: List[Union[str, BinaryIO]], output: Optional[str] = None, suffix: Optional[str] = None, cflags: Optional[List[str]] = None, ldflags: Optional[List[str]] = None) str ¶
Attempt to compile the given C source files into a binary suitable for the remote host. If a compiler exists on the remote host, prefer compilation locally. If no compiler exists on the remote remote host, check the cross global config variable for the path to a local compiler capable of generating binaries for the remote host. If the binary is compiled locally, it is automatically uploaded to the remote host. The path to the new binary on the victim is returned.
- Parameters
sources (List[Union[str, io.IOBase]]) – list of source file paths or IO streams used as source files
output (str) – base name of the output file. If not specified, a name is randomly generated.
suffix (str) – a suffix to add to the output name.
cflags (List[str]) – a list of flags to pass to the compiler
ldflags (List[str]) – a list of flags to pass to the linker
- Returns
str
- Raises
NotImplementedError – this platform does not support c compilation
PlatformError – no local or cross compiler detected or compilation failed
- disable_history()¶
Disable shell history
- exit()¶
Exit this session
- get_host_hash() str ¶
Retrieve a string which uniquely identifies this victim host. On Unix-like platforms, this retrieves the hostname and MAC addresses of any available network interfaces and computes a hash, which should be unique regardless of connection method.
- Returns
a unique string (normally a hash) identifying this host
- Return type
str
- get_pty()¶
Spawn a PTY in the current shell. If a PTY is already running then this method does nothing.
- getenv(name: str)¶
Get the value of an environment variable.
- Parameters
name (str) – the name of the environment variable
- Return type
str
- getuid()¶
Retrieve the current cached uid
- property interactive: bool¶
Indicates whether the remote victim shell is currently in a state suitable for user-interactivity. Setting this property to True will ensure that a suitable shell prompt is set, echoing is one, etc.
- link_to(source: str, target: str)¶
Create a filesystem hard link.
- listdir(path=None) Generator[str, None, None] ¶
List the contents of a directory. If
path
is None, then the contents of the current directory is listed. The list is not guaranteed to be sorted in any way.- Parameters
path (str or Path-like) – the directory to list
- Raises
FileNotFoundError – When the requested directory is not a directory, does not exist, or you do not have execute permissions.
- lstat(path: str) os.stat_result ¶
Perform the equivalent of the lstat syscall
- mkdir(path: str, mode: int = 511, parents: bool = False)¶
Create a new directory
- name = 'linux'¶
Name of this platform (e.g. “linux”)
- open(path: Union[str, pwncat.platform.Path], mode: str = 'r', buffering: int = - 1, encoding: str = 'utf-8', errors: Optional[str] = None, newline: Optional[str] = None)¶
Open a remote file for reading or writing. Normally, only one of read or write modes are allowed for a remote file, but this may change with future platforms. It is recommended to only use one mode when opening remote files. This method attempts to replicate the built-in
open
function and returns a file-like object. The b mode is honored and if not present, a TextIOWrapper is used to wrap the file object to ensure text data is returned.- Parameters
path (Union[str, pwncat.platform.Path]) – path to the file
mode (str) – the open-mode (see built-in
open
)
- Returns
a file-like object
- readlink(path: str)¶
Attempt to read the target of a link
- refresh_uid()¶
Retrieve the current user ID
- rename(source: str, target: str)¶
Rename a file from the source to the target. This should replace the target if it exists.
- rmdir(target: str)¶
Remove the specified directory. It must be empty.
- setenv(name: str, value: str, export: bool = False)¶
Set an environment variable in the shell.
- Parameters
name (a string representing a valid shell variable name) – the name of the environment variable
value (str) – the value of the variable
export (bool) – whether to export the new value
- stat(path: str) os.stat_result ¶
Perform the equivalent of the stat syscall on the remote host
- su(user: str, password: Optional[str] = None)¶
Attempt to switch users in the running shell. This normally executes a new sub-shell as the requested user. On unix-like systems, this is simply a wrapper for the
su
command. Implementations may differ on other systems. If a password isn’t provided, the database will be consulted for a matching username and password.- Parameters
user (str) – the name of the new user
password (str) – the password for the new user
- Raises
PermissionError: the provided password was incorrect
- sudo(command: Union[str, List[str]], user: Optional[str] = None, group: Optional[str] = None, password: Optional[str] = None, as_is: bool = False, **popen_kwargs)¶
Run the specified command as the specified user and group. On unix-like systems the normally translates to the
sudo
command. The command is executed using theself.popen
method. All arguments not documented here are passed directly toself.popen
. The process is executed and if a password is required, it is sent from the database. If a password is not available, the process is killed and a PermissionError is raised. If the password is incorrect, a PermissionError is also raised.- Parameters
command (str) – either an argument array or command line string
user (str) – the name of a user to execute as or None
group (str) – the group to execute as or None
password (str) – the password for the current user
as_is (bool) – indicates to not add
sudo
to the command line**popen_kwargs – arguments passed to the
Popen
method
- symlink_to(source: str, target: str)¶
Create a symbolic link to source from target
- tempfile(length: Optional[int] = None, suffix: Optional[str] = None, directory: Optional[str] = None, **kwargs)¶
Create a temporary file on the remote host and open it with the specified mode. Creating a new temporary file with a mode other than “w” is mostly useless, however
mode
can be used to specify a binary or text-mode file. The length argument is useful if you know the length of file you are about to read. This alleviates some situations which could be complicated on some platforms by not knowing the intended file length prior to opening. Optionally, a suffix can be added to the random file name. A file-like object is returned. The temporary file is not removed by pwncat itself. Unless explicitly removed, it will continue to exist until the remote operating system cleans up temporary files (possible at the next reboot).- Parameters
mode (str) – the open-mode for the new file-like object
length (int) – the intended length for the new file random name component
suffix (str) – a suffix for the filename
directory (str or Path-like) – a directory where the temporary file will be placed
- Returns
a file-like object
- touch(path: str)¶
Update a file modification time and possibly create it
- umask(mask: Optional[int] = None)¶
Set or retrieve the current umask value
- unlink(target: str)¶
Remove a link to a file (similar to rm)
- whoami()¶
Get the name of the current user
- class pwncat.platform.linux.LinuxPath(*args)¶
Bases:
pathlib.PurePosixPath
Special cases for Linux remote paths
- readable()¶
Test if a file is readable
- writable()¶
- class pwncat.platform.linux.LinuxReader(popen, on_close=None, name: Optional[str] = None)¶
Bases:
io.BufferedIOBase
A file-like object which wraps a Popen object to enable reading a remote file.
- close()¶
Close the file and stop the process
- detach()¶
Detach the underlying process and return the Popen object
- read(size: int = - 1)¶
Read data from the file
- read1(size: int = - 1)¶
Read data w/ 1 call to underlying buffer
- readable()¶
Return whether object was opened for reading.
If False, read() will raise OSError.
- readinto(b)¶
Read data w/ 1 call to underlying buffer
- readinto1(b)¶
Read data w/ 1 call to underlying buffer
- writable()¶
Return whether object was opened for writing.
If False, write() will raise OSError.
- class pwncat.platform.linux.LinuxWriter(popen, on_close=None, name: Optional[str] = None)¶
Bases:
io.BufferedIOBase
A wrapper around an active Popen object which is writing to a file. Remote files are not seekable, and cannot be simultaneous read/write.
- CONTROL_CODES = [0, 1, 2, 3, 4, 5, 6, 7, 12, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 127]¶
- close()¶
Close the file and stop the process
- detach()¶
Detach the underlying process and return the Popen object
- readable()¶
Return whether object was opened for reading.
If False, read() will raise OSError.
- writable()¶
Return whether object was opened for writing.
If False, write() will raise OSError.
- write(b)¶
Write data to the underlying Popen stdin. This translates any control-sequences into escaped control sequences, because it assumes you are trying to write to a file and not control the terminal.
- class pwncat.platform.linux.PopenLinux(platform: pwncat.platform.Platform, args, stdout, stdin, text, encoding, errors, bufsize, start_delim: bytes, end_delim: bytes, code_delim: bytes)¶
Bases:
pwncat.subprocess.Popen
Linux-specific Popen wrapper class.
- args: List[str]¶
The args argument as it was passed to Popen – a sequence of program arguments or else a single string.
- communicate(input=None, timeout=None)¶
Interact with process: Send data to stdin. Read data from stdout and stderr, until end-of-file is reached. Wait for the process to terminate and set the
returncode
attribute. The optionalinput
argument should be data to be sent to the child process, or None, if no data should be sent to the child. If streams were opened in text mode,input
must be a string. Otherwise, it must bebytes
.
- detach()¶
- kill()¶
Kills the child
- pid: int¶
The process ID of the child process.
- poll()¶
Check if the child process has terminated. Set and return
returncode
attribute. Otherwise, returns None.
- returncode: int¶
The child return code, set by poll() and wait() (and indirectly by communicate()). A None value indicates that the process hasn’t terminated yet.
- stderr: IO¶
If the stderr argument was PIPE, this attribute is a readable stream object as returned by open(). Reading from the stream provides error output from the child process. If the encoding or errors arguments were specified or the universal_newlines argument was True, the stream is a text stream, otherwise it is a byte stream. If the stderr argument was not PIPE, this attribute is None.
- stdin: IO¶
If the stdin argument was PIPE, this attribute is a writeable stream object as returned by open(). If the encoding or errors arguments were specified or the universal_newlines argument was True, the stream is a text stream, otherwise it is a byte stream. If the stdin argument was not PIPE, this attribute is None.
- stdout: IO¶
If the stdout argument was PIPE, this attribute is a readable stream object as returned by open(). Reading from the stream provides output from the child process. If the encoding or errors arguments were specified or the universal_newlines argument was True, the stream is a text stream, otherwise it is a byte stream. If the stdout argument was not PIPE, this attribute is None.
- terminate()¶
Stop the child.
- wait(timeout: Optional[float] = None)¶
Wait for child process to terminate. Set and return
returncode
attribute.If the process does not terminate after
timeout
seconds, raise aTimeoutExpired
exception. It is safe to catch this exception and retry the wait.