From a58d5f4e5ebc69e8580d2ac197a8be1ba6bf9440 Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Sun, 27 Nov 2005 23:15:30 +0000 Subject: [PATCH] payload docs git-svn-id: file:///home/svn/incoming/trunk@3141 4d416f70-5f16-0410-b530-b9f4589650da --- .../devguide/dev_guide_payload_hierarchy.png | Bin 0 -> 5420 bytes .../devguide/developers_guide.tex | 355 +++++++++++++++++- 2 files changed, 352 insertions(+), 3 deletions(-) create mode 100755 dev/documentation/devguide/dev_guide_payload_hierarchy.png diff --git a/dev/documentation/devguide/dev_guide_payload_hierarchy.png b/dev/documentation/devguide/dev_guide_payload_hierarchy.png new file mode 100755 index 0000000000000000000000000000000000000000..524098f6640b5b203a48a95161590b0789346519 GIT binary patch literal 5420 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 tzoGmwP& + { + 'Payload' => "\xcc\xcc\xcc", + 'Offsets' => ... + } + } +\end{verbatim} + + \subsubsection{Stage} + +\par +A stage payload is an implementation of a connection-independent +task like spawning a command shell or running an arbitrary command. +Stage payloads are combined with various framework stagers to +produce a set of connection-oriented multi-stage payloads. This is +done automatically by the framework by associating stage payloads +with stagers that have a compatible staging convention. The staging +convention describes the manner in which connection information is +passed from the stager to the stage in terms of what register might +hold a file descriptor, for instance. Stages and stagers are also +matched up by their symbol lookup convention if necessary so that +stages can assume that certain locations in memory will hold +routines that may be useful. + +\par +Stage payloads convey their raw payload contents in relation to the +\texttt{Stage} module information hash element. The sub-hash +elements are similar to the single-style payloads in that it has +both a \texttt{Payload} and an \texttt{Offsets} element. + +\par +Stage payloads are meaningless unless there is a compatible stager. + + \subsubsection{Stager} + +\par +A stager payload is an implementation of a payload that establishes +some communication channel with the attacker to read in or otherwise +obtain a second stage payload to execute. For example, a stager +might connection back to the attacker on a defined port and read in +code to execute. + +\par +Stagers convey their raw payload contents in relation to the +\texttt{Stager} module information hash element. The sub-hash +elements are similar to single-style payloads in that it has both a +\texttt{Payload} and an \texttt{Offsets} element. + +\par +Furthermore, staged payloads have some extra accessor methods that +single payloads do not. For instance, the stager's payload and +offsets can be obtained through the \texttt{payload} and +\texttt{offsets} accessors. The stage's payload and offsets can be +obtained through the \texttt{stage\_payload} and +\texttt{stage\_offsets} accessors. + + \subsection{Handlers} + +\par +Handles are one of the critical components of a payload. They are +responsible for handling the attacker's half of establishing a +connection that might be created by the payload being transmitted +via an exploit. The different handlers will be discussed in detail +later in this subsection. + +\par +Handlers themselves act as mixins that get merged into an actual +payload module class. The framework interacts with handlers through +a well-defined interface. Prior to initiating an exploit, the +framework will call into the payload handler's +\texttt{setup\_handler} and \texttt{start\_handler} methods that +will lead to the initialization of the handler in preparation for a +payload connection. When a connection arrives, the handler calls +the \texttt{handle\_connection} method on the payload instance. This +method is intended to be overridden as necessary by the payload to +do custom tasks. For instance, staged payloads will initiate the +transfer of the second stage over the established connection and +then call the default implementation which leads to the creation of +a session for the connection. + +\par +When an exploit has finished, the framework will call into the +payload handlers \texttt{stop\_handler} and +\texttt{cleanup\_handler} methods to stop it from listening for +future connections. + + \subsubsection{Bind TCP} + +\par +The bind TCP handler is provided through +\texttt{Msf::Handler::BindTcp}. It will attempt to establish a +connection to a target machine on a given port (specified in +\texttt{LPORT}). If a connection is established, a call is made +into \texttt{handle\_connection} passing along the socket associated +with the connection. + + \subsubsection{Find port} + +\par +The find port handler is provided by the +\texttt{Msf::Handler::FindPort} class. When an exploit calls the +\texttt{handler} method with a socket connection, the find port +handler will attempt to see if the socket has now been re-purposed +for use by the payload. The find port handler is meant to be used +for payloads that search for a socket by comparing peer port names +relative to the target machine. + + \subsubsection{Find tag} + +\par +The find port handler is provided by the +\texttt{Msf::Handler::FindTag} class. When an exploit calls the +\texttt{handler} method with a socket connection, the find port +handler will attempt to see if the socket has now been re-purposed +for use by the payload. The find tag handler is meant to be used +for find socket style payloads that search for a socket based on the +presence of a tag on the wire. + + \subsubsection{None} + +\par +If a payload does not establish a connection of any sort, the +\texttt{Msf::Handler::None} handler is used. + + \subsubsection{Reverse TCP} + +\par +The reverse TCP handler is provided by the +\texttt{Msf::Handler::ReverseTcp} class. It will listen on a port +for incoming connections and will make a call into +\texttt{handle\_connection} with the client sockets as they do. + \section{Recon} \par