[Openvas-commits] r1352 - trunk/openvas-compendium

scm-commit@wald.intevation.org scm-commit at wald.intevation.org
Tue Sep 16 16:15:29 CEST 2008


Author: mwiegand
Date: 2008-09-16 16:15:28 +0200 (Tue, 16 Sep 2008)
New Revision: 1352

Modified:
   trunk/openvas-compendium/ChangeLog
   trunk/openvas-compendium/openvas-compendium.tex
Log:
* openvas-compendium.tex: Adapted OTP documentation from specification.


Modified: trunk/openvas-compendium/ChangeLog
===================================================================
--- trunk/openvas-compendium/ChangeLog	2008-09-16 10:04:36 UTC (rev 1351)
+++ trunk/openvas-compendium/ChangeLog	2008-09-16 14:15:28 UTC (rev 1352)
@@ -1,3 +1,7 @@
+2008-09-16  Michael Wiegand <michael.wiegand at intevation.de>
+
+	* openvas-compendium.tex: Adapted OTP documentation from specification.
+
 2008-09-10  Tim Brown <timb at nth-dimension.org.uk>
 
 	* openvas-compendium.tex: Added details about automatically updating.

Modified: trunk/openvas-compendium/openvas-compendium.tex
===================================================================
--- trunk/openvas-compendium/openvas-compendium.tex	2008-09-16 10:04:36 UTC (rev 1351)
+++ trunk/openvas-compendium/openvas-compendium.tex	2008-09-16 14:15:28 UTC (rev 1352)
@@ -843,7 +843,9 @@
 \xname{automatically-updating-an-nvt-feed}
 \subsection{Automatically Updating an NVT Feed}
 
-\item Create a script called "openvas-update" and save it somewhere such as "/usr/local/bin":
+\begin{itemize}
+\item Create a script called "openvas-update" and save it somewhere such as
+"/usr/local/bin":
 \begin{verbatim}
 	#!/bin/sh
 
@@ -865,6 +867,7 @@
 \begin{verbatim}
 	25 4 * * *	root	/usr/local/bin/openvas-update
 \end{verbatim}
+\end{itemize}
 
 \xname{managing-nvt-signatures}
 \section{Managing NVT signatures}
@@ -3891,7 +3894,667 @@
 
 \xname{openvas-transfer-protocol}
 \chapter{OpenVAS Transfer Protocol (OTP)}
+The client and the server module in an OpenVAS installation communicate through
+the OpenVAS Transfer Protocol (OTP). Earlier versions of OpenVAS have used the
+Nessus Transport Protocol (NTP) inherited from Nessus, but in order to address
+shortcomings of NTP and to facilitate further improvements in the OpenVAS
+modules it became necessary to make changes to the protocol. Since NTP was
+specified by the Nessus project and changes to NTP by the Nessus project are to
+be expected, a decision was made to switch to a new protocol to avoid
+collisions with future protocol specifications by the Nessus project and to
+avoid confusion with other well-established protocols. The initial
+specification of OTP is very close to the NTP implementation in the last
+versions available under the GNU General Public License (GPL).
 
+\xname{general-aspects-of-otp}
+\section{General Aspects of OTP}
+
+The OpenVAS Transfer Protocol is text-based, human readable and
+line-oriented. Each line consists of fields separated by `` <|> ''. The first
+fields indicates whether it is a command send by client or by server (``CLIENT''
+vs. ``SERVER'').
+
+\xname{otp-initialization-and-features}
+\section{Protocol Initialization and Protocol Features}
+
+The client start the protocol with a initializer of the protocol version
+followed by parameters switching on various features. Available protocol
+features are:
+\begin{itemize}
+ \item md5\_caching (server will use the MD5 caching feature)
+\end{itemize}
+
+Syntax:
+\begin{verbatim}
+< OTP/1.0 >< protocol_feature1 protocol_feature2 ... >
+User : user_name
+Password : user_password
+\end{verbatim}
+
+\xname{otp-commands}
+\section{Protocol Commands}
+
+\xname{otp-attached\_file}
+\subsection{ATTACHED\_FILE}
+
+\paragraph{Description:}
+This command corresponds to the plugin preferences type "file". It follows
+the command PREFERENCES to upload the specified files from client to
+server.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> ATTACHED_FILE
+name: file_name
+content: octet/stream
+bytes: file_length
+file_content
+\end{verbatim}
+
+where
+\begin{description}
+ \item[file\_name] The path and name of the file. It is a identifier
+to reference the file in the plugin preferences.
+ \item[file\_length] the number of bytes that will follow after the newline
+ \item[file\_content] the actual file as byte stream.
+\end{description}
+
+\xname{otp-complete_list}
+\subsection{COMPLETE\_LIST}
+
+\paragraph{Description:}
+This command can be used by the client in case the protocol feature
+"md5\_caching" was selected by the client.
+
+It usually follows the PLUGINS\_MD5 commands of the server in case the server
+side md5sum is not equal to the md5sum of the client side cached NVTs.
+Alternatively, the client can use the command SEND\_PLUGINS\_MD5.
+
+The server will answer with command PLUGIN\_LIST.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> COMPLETE_LIST <|> CLIENT
+\end{verbatim}
+
+\xname{otp-error}
+\subsection{ERROR}
+
+\paragraph{Description:}
+In case of problems the server sends an error message with this command. In case
+of unrecoverable problems, the server will then close connection with BYE
+command.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> ERROR <|> error description <|> SERVER
+\end{verbatim}
+
+\xname{otp-finished}
+\subsection{FINISHED}
+
+\paragraph{Description:}
+The server will send this information each time when a scan of a single host is
+finished.
+This will only be done if requested by the client via setting the preferences
+option "ntp\_opt\_show\_end".
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> FINISHED <|> host <|> SERVER
+\end{verbatim}
+
+\xname{otp-go-on}
+\subsection{GO ON}
+
+\paragraph{Description:}
+This command can be used by the client in case the protocol feature
+"md5\_caching" was selected by the client. It usually follows the PLUGINS\_MD5
+commands of the server in case the server side md5sum is equal to the md5sum of
+the client side cached NVTs. The server will answer with command PREFERENCES and
+communication will continue as it would have been without md5\_caching feature.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> GO ON <|> CLIENT
+\end{verbatim}
+
+\xname{otp-hole}
+\subsection{HOLE}
+
+\paragraph{Description:}
+With this command the server reports a identified problem of class
+"security hole". The "general" version is applied if no port relates to the
+hole.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> HOLE <|> host <|> service_name (port_number/protocol_type) <|>
+description <|> oid <|> SERVER
+
+SERVER <|> HOLE <|> host <|> general <|> description <|> oid <|> SERVER
+\end{verbatim}
+
+where
+\begin{description}
+ \item[host] the target system
+ \item[service\_name] the name of the service (like in /etc/services)
+ \item[port\_number] the port number the problem relates to.
+ \item[protocol\_type] "tcp" or "udp".
+ \item[description] the problem description where newlines have been replaced by
+semicolons.
+ \item[oid] the OID of the NVT that identified the problem.
+\end{description}
+
+\xname{otp-info}
+\subsection{INFO}
+
+\paragraph{Description:}
+With this command the server reports a identified problem of class "security
+info". The "general" version is applied if no port relates to the info.
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> INFO <|> host <|> service_name (port_number/protocol_type) <|>
+description <|> oid <|> SERVER
+
+SERVER <|> INFO <|> host <|> general <|> description <|> oid <|> SERVER
+\end{verbatim}
+
+    where
+\begin{description}
+ \item[host] the target system
+ \item[service\_name] the name of the service (like in /etc/services)
+ \item[port\_number] the port number the problem relates to.
+ \item[protocol\_type] "tcp" or "udp".
+ \item[description] the problem description where newlines have been replaced by
+semicolons.
+ \item[oid] the OID of the NVT that identified the problem.
+\end{description}
+
+\xname{otp-long_attack}
+\subsection{LONG\_ATTACK}
+
+\paragraph{Description:}
+With this command the client requests the server to attack target system(s)
+"hosts". "hosts" is one or many (comma-separated) IP or FQDN.
+
+"length" is the number of bytes of "hosts". In case this does not match, the
+server will close connection.
+
+Before the client sends LONG\_ATTACK, the commands PREFERENCES and RULES should
+be applied.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> LONG_ATTACK
+length
+hosts
+\end{verbatim}
+
+\xname{otp-note}
+\subsection{NOTE}
+
+\paragraph{Description:}
+With this command the server reports a identified problem of class "security
+note". The "general" version is applied if no port relates to the note.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> NOTE <|> host <|> service_name (port_number/protocol_type) <|>
+description <|> oid <|> SERVER
+
+SERVER <|> NOTE <|> host <|> general <|> description <|> oid <|> SERVER
+\end{verbatim}
+
+where
+\begin{description}
+ \item[host] the target system
+ \item[service\_name] the name of the service (like in /etc/services)
+ \item[port\_number] the port number the problem relates to.
+ \item[protocol\_type] "tcp" or "udp".
+ \item[description] the problem description where newlines have been replaced by
+semicolons.
+ \item[oid] the OID of the NVT that identified the problem.
+\end{description}
+
+\xname{otp-openvas_version}
+\subsection{OPENVAS\_VERSION}
+
+\paragraph{Description:}
+With this command the client asks the server to send its version.
+
+The server will answer as shown in the syntax.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> OPENVAS_VERSION <|> CLIENT
+
+SERVER <|> OPENVAS_VERSION <|> version <|> SERVER
+\end{verbatim}
+
+\xname{otp-plugin_dependencies}
+\subsection{PLUGINS\_DEPENDENCIES}
+
+\paragraph{Description:}
+The PLUGINS\_DEPENDENCIES messages are send after the RULES messages.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> PLUGINS_DEPENDENCIES
+plugin_1_name <|> dependency1 <|> dependency2 <|> ... <|>
+plugin_2_name <|> dependency1 <|> dependency2 <|> ... <|>
+...
+<|> SERVER
+\end{verbatim}
+
+\xname{otp-plugins_md5}
+\subsection{PLUGINS\_MD5}
+
+\paragraph{Description:}
+Attention: This command occurs in two ways.
+
+\begin{enumerate}
+ \item This command replaces PLUGIN\_LIST command in case the protocol feature
+"md5\_caching" was selected by the client. "md5sum" is the MD5 sum over all
+NVTs.
+ \item This command follows the SEND\_PLUGINS\_MD5 command of the client and
+delivers the md5sums for each NVT.
+\end{enumerate}
+
+\paragraph{Syntax:}
+\begin{enumerate}
+ \item
+\begin{verbatim}
+SERVER <|> PLUGINS_MD5 <|> md5sum <|> SERVER
+\end{verbatim}
+ \item
+\begin{verbatim}
+SERVER <|> PLUGINS_MD5
+nvt_name1 <|> md5sum1
+nvt_name2 <|> md5sum2
+...
+<|> SERVER
+\end{verbatim}
+\end{enumerate}
+
+\xname{otp-plugin_info}
+\subsection{PLUGIN\_INFO}
+
+\paragraph{Description:}
+This command is issued by the client to request information of the NVT specified
+by its oid.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> PLUGIN_INFO <|> oid <|> CLIENT
+\end{verbatim}
+
+The server answers with this line (analogous to PLUGIN\_LIST command):
+
+\begin{verbatim}
+oid <|> name <|> category <|> copyright <|> description <|> summary <|>
+family <|> plugin_version <|> cve_id <|> bugtraq_id <|> xrefs
+\end{verbatim}
+
+In case no plugin with OID=oid is found, the server will not answer at
+all.
+
+\xname{otp-plugin_list}
+\subsection{PLUGIN\_LIST}
+
+\paragraph{Description:}
+With this command the server sends detailed information about the available
+NVTs.
+
+The server will send PREFERENCES and RULES right after this command.
+
+The client might request individual NVT information via PLUGIN\_INFO command.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> PLUGIN_LIST <|>
+oid <|> name <|> category <|> copyright <|> description <|> summary <|> family
+<|> plugin_version <|> cve_id <|> bugtraq_id <|> xrefs
+oid <|> name <|> category <|> copyright <|> description <|> summary <|> family
+<|> plugin_version <|> cve_id <|> bugtraq_id <|> xrefs
+<|> SERVER
+\end{verbatim}
+
+\xname{otp-port}
+\subsection{PORT}
+
+\paragraph{Description:}
+With this command the server reports on open port "port\_number" on target
+system "host".
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> PORT <|> host <|> port_number <|> SERVER
+\end{verbatim}
+
+\xname{otp-preferences}
+\subsection{PREFERENCES}
+
+\paragraph{Description:}
+With this command the values for the preferences are
+communicated. The server uses the commands to inform
+about defaults, the client uses the command to send
+the user selections. The server answers with PREFERENCES\_ERROR.
+
+Note that besides some general preferences, the syntax definition
+describes also per-NVT preferences and its special way of applying these.
+
+\paragraph{Available preferences:}
+
+\begin{description}
+ \item [ntp\_save\_sessions] If set to "yes", the server will support
+server-side saving of scan sessions and these commands will be available
+SESSIONS\_LIST, SESSION\_DELETE and SESSION\_RESTORE.
+ \item [save\_session] If set to yes, the server will save the scan as a
+session.
+ \item [save\_empty\_sessions] Only considered if save\_session is set to "yes".
+If set to "yes" even emtpy scans will be saved a session.
+ \item [max\_threads] 
+ \item [test\_file] 
+ \item [ping\_hosts] 
+ \item [reverse\_lookup] 
+ \item [outside\_firewall] 
+ \item [host\_expansion] 
+ \item [port\_range] 
+ \item [max\_hosts] 
+ \item [save\_knowledge\_base] Activates KB saving when set to "yes"
+ \item [only\_test\_hosts\_whose\_kb\_we\_have] Only scans host for which the KB
+is filled when set to "yes"
+ \item [only\_test\_hosts\_whose\_kb\_we\_dont\_have] Only scans host for which
+the KB is empty when set to "yes"
+ \item [kb\_restore] Restore the KB contents for tested hosts when when set to
+"yes".
+ \item [kb\_dont\_replay\_scanners] Don't run scanners in case in case
+kb\_restore is set to "yes" and there is contents in the KB when set to "yes".
+ \item [kb\_dont\_replay\_info\_gathering] Don't run gatherers in case in case
+kb\_restore is set to "yes" and there is contents in the KB when set to "yes".
+ \item [kb\_dont\_replay\_attacks] Don't run attack scripts in case in case
+kb\_restore is set to "yes" and there is contents in the KB when set to "yes".
+ \item [kb\_dont\_replay\_denials] Don't run DoS attack scripts in case in case
+kb\_restore is set to "yes" and there is contents in the KB when set to "yes".
+ \item [kb\_max\_age] This sets the maximum age (in seconds) of a KB until it
+gets disregarded.
+ \item[timeout.<nvt\_id> = <timeout>] Set the timeout <timeout> for NVT
+<nvt\_id>. Timeout of "-1" means no specific timeout.
+\end{description}
+
+Only sent by CLIENT:
+\begin{description}
+ \item [plugin\_set] empty means all NVTs
+ \item [ntp\_opt\_show\_end] Tell server to send FINISHED messages
+ \item [ntp\_keep\_communication\_alive] Tell server to keep the connection even
+after a scan was finished.
+ \item [ntp\_short\_status] Tell server send shorter STATUS message in order to
+save bandwidth.
+\end{description}
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> PREFERENCES <|>
+pref_name <|> value
+pref_name <|> value
+pref_name <|> value
+...
+<|> SERVER
+
+CLIENT <|> PREFERENCES <|>
+pref_name <|> value
+pref_name <|> value
+pref_name <|> value
+...
+<|> CLIENT
+\end{verbatim}
+
+
+For preference of individual NVTs these lines can occur inside the list:
+
+\begin{verbatim}
+nvt_name[pref_type]:pref_name <|> value
+\end{verbatim}
+
+where
+\begin{description}
+ \item [nvt\_name] This references the NVT for which the preferences are set
+ \item [pref\_type] Defines the variable type of the preference which ultimately
+determines the widget type in the client GUI.
+ \item [pref\_name] This references the Preference and at the same time is used
+as the visible string for the user in the GUI.
+ \item [value] The default value for this preference when sent by SERVER, the
+user selected value if send by CLIENT
+\end{description}
+
+and pref\_type is one of these:
+\begin{description}
+ \item [checkbox] value is "yes" or "no"
+ \item [entry] value is a text string
+ \item [password] value is a text string but should not be shown in GUI or in
+cleartext in local files
+ \item [radio] value is a list of semicolon-separated options when sent by
+SERVER and only the user-selected option name when sent by CLIENT
+ \item [file] value is "<none>" when sent by SERVER and a file path when sent by
+CLIENT. The client has to submit the file under the very same path name using
+the command ATTACHED\_FILE.
+\end{description}
+
+\xname{otp-preferences_errors}
+\subsection{PREFERENCES\_ERRORS}
+
+\paragraph{Description:}
+With this command the server reports problems with the parameters set by the
+client. It follows immediately the PREFERENCES command of the client.
+
+Each "pref\_name" occuring in this list was not accepted by the server. The
+server will apply "default\_value" instead.
+
+In case no "pref\_name" is reported with this command, all preferences where
+accepted.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> PREFERENCES_ERRORS
+pref_name <|> default_value
+pref_name <|> default_value
+pref_name <|> default_value
+...
+<|> SERVER
+\end{verbatim}
+
+\xname{otp-rules}
+\subsection{RULES}
+
+\paragraph{Description:}
+Rules define restrictions for target systems.
+Client-side rules self-restrict target host patterns,
+server-side rules are just for information to the client.
+These rule sets are independent of each other.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> RULES <|>
+rule_1;
+rule_2;
+rule_3;
+...
+<|> SERVER
+
+CLIENT <|> RULES <|>
+rule_1;
+rule_2;
+rule_3;
+...
+<|> CLIENT
+\end{verbatim}
+
+\xname{otp-send_plugins_md5}
+\subsection{SEND\_PLUGINS\_MD5}
+
+\paragraph{Description:}
+This command can be used by the client in case the protocol feature
+"md5\_caching" was selected by the client.
+
+It usually follows the PLUGINS\_MD5 commands of the server in case the server
+side md5sum is not equal to the md5sum of the client side cached NVTs.
+Alternatively, the client can use the command COMPLETE\_LIST.
+
+The server will answer with command PLUGINS\_MD5.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> SEND_PLUGINS_MD5 <|> CLIENT
+\end{verbatim}
+
+\xname{otp-sessions_list}
+\subsection{SESSIONS\_LIST}
+
+\paragraph{Description:}
+The CLIENT request with this command the list of sessions stored on the server
+side for the logged in user.
+
+The SERVER will answer with the same command and provide the list of sessions.
+The session names are derived from time stamps. The hosts are the targets
+applied for the respective session. The hosts are just there to help identify
+the sessions. It is cut after 4000 bytes of length.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> SESSIONS_LIST <|> CLIENT
+
+SERVER <|> SESSIONS_LIST
+session_name1 hosts1
+session_name2 hosts2
+...
+<|> SERVER
+\end{verbatim}
+
+\xname{otp-session_delete}
+\subsection{SESSION\_DELETE}
+
+\paragraph{Description:}
+With this command the client deletes the session identified with "session\_name"
+from the server-side storage. The server will not answer in case of success,
+else it will answer with an ERROR command.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> SESSION_DELETE <|> session_name <|> CLIENT
+\end{verbatim}
+
+
+\xname{otp-session_restore}
+\subsection{SESSION\_RESTORE}
+
+\paragraph{Description:}
+With this command the client tells the server to pick up again the session
+identified with "session\_name". The server will act as if a LONG\_ATTACK
+command has issued and will send all results that were collected so far for this
+session immediately (and naturally rapidly) and then continue the scan where it
+stopped.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> SESSION_RESTORE <|> session_name <|> CLIENT
+\end{verbatim}
+
+\xname{otp-status}
+\subsection{STATUS}
+
+\paragraph{Description:}
+With this command, the server informs the client about the progress of the scan
+for target system "host". "attack\_state" is either "portscan" or "attack" (or
+just "p" and "a" in case the client has set preferences option
+"ntp\_short\_status"). "current" is the currently processed port and "max" the
+last port number to be tested.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+SERVER <|> STATUS <|> host <|> attack_state <|> current/max <|> SERVER
+\end{verbatim}
+
+In case the client has set "ntp\_short\_status":
+\begin{verbatim}
+SERVER <|> STATUS <|> attack_state:host:current:max <|> SERVER
+\end{verbatim}
+
+\xname{otp-stop_attack}
+\subsection{STOP\_ATTACK}
+
+\paragraph{Description:}
+With this command, the client tells the server to stop scanning target "host".
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> STOP_ATTACK <|> host <|> CLIENT
+\end{verbatim}
+
+\xname{otp-stop_whole_test}
+\subsection{STOP\_WHOLE\_TEST}
+
+\paragraph{Description:}
+With this command the client tells to stop the currently running test.
+
+\paragraph{Syntax:}
+
+\begin{verbatim}
+CLIENT <|> STOP_WHOLE_TEST <|> CLIENT
+\end{verbatim}
+
+\xname{otp-time}
+\subsection{TIME}
+
+\paragraph{Description:}
+The TIME messages are sent by the server to inform about the duration of
+scanning a host and of the whole scan.
+
+\paragraph{Syntax:}
+
+After completion of scanning a target host the server sends:
+\begin{verbatim}
+SERVER <|> TIME <|> HOST_START <|> host <|> time_string <|> SERVER
+SERVER <|> TIME <|> HOST_END <|> host <|> time_string <|> SERVER
+\end{verbatim}
+
+or, in case STOP\_ATTACK was issued by the client:
+\begin{verbatim}
+SERVER <|> TIME <|> HOST_START <|> host <|> time_string <|> SERVER
+SERVER <|> TIME <|> HOST_INTERRUPTED <|> host <|> time_string <|> SERVER
+\end{verbatim}
+
+After completion of the whole scan the server sends:
+\begin{verbatim}
+SERVER <|> TIME <|> SCAN_START <|> time_string <|> SERVER
+SERVER <|> TIME <|> SCAN_END <|> time_string  <|> SERVER
+\end{verbatim}
+
+where time\_string is of the form "Wed Jun 30 21:49:08 1993".
+
 \clearpage
 
 \xname{document-license}



More information about the Openvas-commits mailing list