[Openvas-commits] r1143 - trunk/openvas-compendium
scm-commit@wald.intevation.org
scm-commit at wald.intevation.org
Mon Aug 18 14:59:22 CEST 2008
Author: mwiegand
Date: 2008-08-18 14:59:21 +0200 (Mon, 18 Aug 2008)
New Revision: 1143
Modified:
trunk/openvas-compendium/ChangeLog
trunk/openvas-compendium/openvas-compendium.tex
Log:
* openvas-compendium.tex: Expanded NASL documentation.
Modified: trunk/openvas-compendium/ChangeLog
===================================================================
--- trunk/openvas-compendium/ChangeLog 2008-08-18 08:50:49 UTC (rev 1142)
+++ trunk/openvas-compendium/ChangeLog 2008-08-18 12:59:21 UTC (rev 1143)
@@ -1,5 +1,9 @@
2008-08-18 Michael Wiegand <michael.wiegand at intevation.de>
+ * openvas-compendium.tex: Expanded NASL documentation.
+
+2008-08-18 Michael Wiegand <michael.wiegand at intevation.de>
+
* openvas-compendium.tex: Started section about NASL structure, migrated
section about NASL testing and debugging.
Modified: trunk/openvas-compendium/openvas-compendium.tex
===================================================================
--- trunk/openvas-compendium/openvas-compendium.tex 2008-08-18 08:50:49 UTC (rev 1142)
+++ trunk/openvas-compendium/openvas-compendium.tex 2008-08-18 12:59:21 UTC (rev 1143)
@@ -2159,6 +2159,9 @@
parser which extended the range of built-in functions and operators. This
improved version is generally refered to as NASL2.
+If not indicated otherwise, this compendium describes NASL2 as it is
+implemented in OpenVAS.
+
The NASL syntax was inspired by C. Users with experience in C or related
programming languages should be able to pick up the basics of NASL development
in a relatively short amount of time.
@@ -2217,11 +2220,114 @@
description, please refer to the section \ref{sec:NASL-desc} of the NASL API
documentation.
+\section{Basic NASL Syntax}
+
+\subsection{Comments}
+
+Comments in NASL start with the \verb|#| character. If a \verb|#| character is
+encountered, the remaining line is ignored by the NASL interpreter.
+
+Example:
+\begin{verbatim}
+ # This is a comment.
+ a = b + c; # This is a comment as well.
+\end{verbatim}
+
+\subsection{Variables and Declarations}
+
+Variables are implicitly declared in NASL; this means that it is not necessary
+to declare any variables before use. You can however use the \verb|local_var|
+keyword to declare a variable as local to a certain function and avoid
+collisions with external variables. By default, NASL considers a variable to be
+local to the context in which it was declared; if you want to declare a
+variable as global, you can use the \verb|global_var| keyword.
+
+In contrast to C (and other languages), variable types do not have to be
+declared in advance; the NASL interpreter will use the appropriate type the
+first time the variable is assigned. Memory allocation is automatically handled
+by the interpreter as well.
+
+\subsection{Data Types}
+
+\begin{itemize}
+ \item Integers
+ \item Strings
+ \item Arrays
+ \item Booleans
+\end{itemize}
+
+
+\subsection{Numbers and Strings}
+
+\subsection{Function Arguments}
+
+\subsection{Loops}
+
+\begin{itemize}
+ \item for
+ \item foreach
+ \item while
+ \item repeat .. until
+ \item break
+ \item continue
+ \item return
+\end{itemize}
+
+
+\subsection{User-defined Functions}
+
+\subsection{Operators}
+
+\begin{itemize}
+ \item =
+ \item $\left[ \right] $
+ \item +
+ \item -
+ \item *
+ \item /
+ \item \%
+ \item **
+ \item ++
+ \item +=
+ \item -=
+ \item *=
+ \item /=
+ \item \%=
+ \item <<=
+ \item >>=
+ \item >>>=
+ \item ><
+ \item >!<
+ \item =~
+ \item !~
+ \item ==
+ \item !=
+ \item >
+ \item >=
+ \item <
+ \item <=
+ \item !
+ \item &&
+ \item ||
+ \item ~
+ \item &
+ \item |
+ \item ^
+ \item <<
+ \item >>
+ \item >>>
+\end{itemize}
+
+\subsubsection{Operator Precedence}
+
\section{NASL API Documentation}
+\subsection{Pre-defined Constants}
+
\subsection{Built-In Functions}
-NASL1:
+\subsubsection{Socket Manipulation}
+
\begin{itemize}
\item \verb!open_sock_tcp()!
\item \verb!open_sock_udp()!
@@ -2232,13 +2338,51 @@
\item \begin{verbatim}recv()\end{verbatim}
\item \begin{verbatim}recv_line()\end{verbatim}
\item \verb!send()!
+\end{itemize}
+
+\subsubsection{Network Operations}
+
+\begin{itemize}
+ \item \verb!start_denial()!
+ \item \verb!end_denial()!
+ \item \verb!get_port_transport()!
+ \item \verb!get_source_port()!
+ \item \verb!get_tcp_port_state()!
+ \item \verb!get_udp_port_state()!
+ \item \verb!islocalhost()!
+ \item \verb!islocalnet()!
+ \item \verb!join_multicast_group()!
+ \item \verb!leave_multicast_group()!
+ \item \verb!scanner_add_port()!
+ \item \verb!scanner_get_port()!
+ \item \verb!this_host_name()!
+\end{itemize}
+
+\subsubsection{FTP Operations}
+
+\begin{itemize}
\item \verb!ftp_log_in()!
\item \verb!ftp_get_pasv_port()!
+\end{itemize}
+
+\subsubsection{HTTP Operations}
+
+\begin{itemize}
\item \verb!is_cgi_installed()!
\item \verb!http_get()!
\item \verb!http_head()!
\item \verb!http_post()!
\item \verb!cgibin()!
+ \item \verb!http_delete()!
+ \item \verb!http_close_socket()!
+ \item \verb!http_open_socket()!
+ \item \verb!http_recv_headers()!
+ \item \verb!http_put()!
+\end{itemize}
+
+\subsubsection{Packet Manipulation}
+
+\begin{itemize}
\item \verb!forge_ip_packet()!
\item \verb!get_ip_element()!
\item \verb!set_ip_elements()!
@@ -2255,6 +2399,13 @@
\item \verb!get_icmp_element()!
\item \verb!set_icmp_elements()!
\item \verb!forge_igmp_packet()!
+ \item \verb!dump_tcp_packet()!
+ \item \verb!dump_udp_packet()!
+\end{itemize}
+
+\subsubsection{Utilities}
+
+\begin{itemize}
\item \verb!this_host()!
\item \verb!get_host_name()!
\item \verb!get_host_ip()!
@@ -2263,6 +2414,11 @@
\item \verb!telnet_init()!
\item \verb!tcp_ping()!
\item \verb!getrpcport()!
+\end{itemize}
+
+\subsubsection{String Manipulation}
+
+\begin{itemize}
\item \verb!ereg()!
\item \verb!ereg_replace()!
\item \verb!egrep()!
@@ -2271,9 +2427,83 @@
\item \verb!strlen()!
\item \verb!raw_string()!
\item \verb!tolower()!
+ \item \verb!chomp()!
+ \item \verb!display()!
+ \item \verb!eregmatch()!
+ \item \verb!hex()!
+ \item \verb!hexstr()!
+ \item \verb!insstr()!
+ \item \verb!int()!
+ \item \verb!match()!
+ \item \verb!ord()!
+ \item \verb!str_replace()!
+ \item \verb!strcat()!
+ \item \verb!stridx()!
+ \item \verb!strstr()!
+ \item \verb!split()!
+ \item \verb!substr()!
+ \item \verb!toupper()!
+\end{itemize}
+
+\subsubsection{Knowledge Base}
+
+\begin{itemize}
\item \verb!get_kb_item()!
\item \verb!set_kb_item()!
+ \item \verb!get_kb_list()!
+ \item \verb!replace_kb_item()!
+ \item \verb!replace_or_set_kb_item()!
+\end{itemize}
+
+\subsubsection{Plugin Description}
+
+\begin{itemize}
\item \verb!script_id()!
+ \item \verb!script_oid()!
+\compendiumauthor{Tim Brown}
+
+This function is intended to replace \verb!script_id!, the current method of
+uniquely
+identifying NASL scripts. The logic behind this is that \verb!script_id! has
+only a single
+global namespace. With plans by several organisations to develop and contribute
+plugin feeds it was deemed necessary to introduce a new namespace that could be
+shared between each organisation.
+
+The current proposed implementation of this function is as follows. Any plugin
+that
+contains a \verb!script_id! call will automatically be given an OID from the
+namespace
+allocated for legacy plugins. Moreover \verb!script_oid! can only be used on
+plugins
+that do not have a \verb!script_id! set. The OID namespace for legacy plugins
+has the
+prefix "1.3.6.1.4.1.25623.1.0". The OpenVAS OID namespace is currently
+administered
+by Tim Brown.
+
+Both the client and server as well as the libraries on which they depend are
+being
+updated to support this functionality. You can detect if it is supported by
+checking
+OPENVAS\_NASL\_LEVEL is greater than 2206.
+
+\verb!script_oid! should be called like so:
+
+\begin{verbatim}
+ ...
+ if(description)
+ {
+ if (OPENVAS_NASL_LEVEL >= 2206)
+ {
+ script_oid("1.3.6.1.4.1.25623.1.0.90010");
+ }
+ else
+ {
+ script_id(90010);
+ }
+ ...
+\end{verbatim}
\item \verb!script_version()!
\item \verb!script_name()!
\item \verb!script_description()!
@@ -2282,22 +2512,10 @@
\item \verb!script_copyright()!
\item \verb!script_family()!
\item \verb!script_dependencies()!
- \item \verb!security_warning()!
- \item \verb!security_hole()!
- \item \verb!security_info()!
\item \verb!script_cve_id()!
\item \verb!script_require_ports()!
\item \verb!script_require_keys()!
\item \verb!script_exclude_keys()!
-\end{itemize}
-
-NASL2:
-\begin{itemize}
- \item \verb!get_kb_list()!
- \item \verb!make_list()!
- \item \verb!make_array()!
- \item \verb!replace_kb_item()!
- \item \verb!replace_or_set_kb_item()!
\item \verb!scanner_status()!
\item \verb!script_get_preference()!
\item \verb!script_add_preference()!
@@ -2307,43 +2525,20 @@
\item \verb!script_get_preference_file_location()!
\item \verb!script_require_udp_ports()!
\item \verb!script_timeout()!
- \item \verb!get_preference()!
- \item \verb!start_denial()!
- \item \verb!end_denial()!
- \item \verb!get_port_transport()!
- \item \verb!get_source_port()!
- \item \verb!get_tcp_port_state()!
- \item \verb!get_udp_port_state()!
- \item \verb!islocalhost()!
- \item \verb!islocalnet()!
- \item \verb!join_multicast_group()!
- \item \verb!leave_multicast_group()!
- \item \verb!scanner_add_port()!
- \item \verb!scanner_get_port()!
- \item \verb!this_host_name()!
- \item \verb!chomp()!
- \item \verb!display()!
- \item \verb!eregmatch()!
- \item \verb!hex()!
- \item \verb!hexstr()!
- \item \verb!insstr()!
- \item \verb!int()!
- \item \verb!match()!
- \item \verb!ord()!
- \item \verb!str_replace()!
- \item \verb!strcat()!
- \item \verb!stridx()!
- \item \verb!strstr()!
- \item \verb!split()!
- \item \verb!substr()!
- \item \verb!toupper()!
- \item \verb!http_delete()!
- \item \verb!http_close_socket()!
- \item \verb!http_open_socket()!
- \item \verb!http_recv_headers()!
- \item \verb!http_put()!
- \item \verb!dump_tcp_packet()!
- \item \verb!dump_udp_packet()!
+\end{itemize}
+
+\subsubsection{Report Functions}
+
+\begin{itemize}
+ \item \verb!security_warning()!
+ \item \verb!security_hole()!
+ \item \verb!security_info()!
+ \item \verb!security_note()!
+\end{itemize}
+
+\subsubsection{Crypto Functions}
+
+\begin{itemize}
\item \verb!HMAC_DSS()!
\item \verb!HMAC_MD2()!
\item \verb!HMAC_MD4()!
@@ -2357,6 +2552,11 @@
\item \verb!RIPEMD160()!
\item \verb!SHA()!
\item \verb!SHA1()!
+\end{itemize}
+
+\subsubsection{Miscellaneous Functions}
+
+\begin{itemize}
\item \verb!cvsdate2unixtime()!
\item \verb!defined_func()!
\item \verb!dump_ctxt()!
@@ -2371,6 +2571,16 @@
\item \verb!safe_checks()!
\item \verb!sleep()!
\item \verb!type_of()!
+ \item \verb!usleep()!
+ \item \verb!unixtime()!
+ \item \verb!make_list()!
+ \item \verb!make_array()!
+ \item \verb!get_preference()!
+\end{itemize}
+
+\subsubsection{``Unsafe'' Functions}
+
+\begin{itemize}
\item \verb!find_in_path()!
\item \verb!file_close()!
\item \verb!file_open()!
@@ -2385,44 +2595,106 @@
\item \verb!pread()!
\end{itemize}
-\subsection{script\_oid()}
+\subsection{Functions from the NASL Library}
-\compendiumauthor{Tim Brown}
+Apart from the built-in functions provided by NASL itself it is also possible
+to use functions defined in ``include'' files. As a convention, these files
+have the extension ``.inc'' and reside in the plugin directory. Before you
+start writing functions for your own NASL scripts, you might want to check if
+the functionality is already available in the NASL Library. If you find
+yourself implementing a function that could be useful in other plugins as well,
+please consider adding it to the library.
-This function is intended to replace \verb!script_id!, the current method of uniquely
-identifying NASL scripts. The logic behind this is that \verb!script_id! has only a single
-global namespace. With plans by several organisations to develop and contribute
-plugin feeds it was deemed necessary to introduce a new namespace that could be
-shared between each organisation.
+Quite a number of functions have been added to the NASL library already; the
+following list contains the names and declared functions of the files currently
+in the library. Keep in mind that this information is subject to change as
+plugins are added or updated.
-The current proposed implementation of this function is as follows. Any plugin that
-contains a \verb!script_id! call will automatically be given an OID from the namespace
-allocated for legacy plugins. Moreover \verb!script_oid! can only be used on plugins
-that do not have a \verb!script_id! set. The OID namespace for legacy plugins has the
-prefix "1.3.6.1.4.1.25623.1.0". The OpenVAS OID namespace is currently administered
-by Tim Brown.
+\begin{description}
+ \item[backport.inc] get\_backport\_banner(), get\_php\_version()
+ \item[debian\_package.inc] deb\_check(), deb\_str\_cmp(), deb\_ver\_cmp()
+ \item[default\_account.inc] check\_account(), \_check\_telnet(), recv\_until()
+ \item[dump.inc] dump(), hexdump(), isprint (), line2string ()
+ \item[ftp\_func.inc] ftp\_authenticate(), ftp\_close(), ftp\_pasv(),
+ftp\_recv\_data(), ftp\_recv\_line(), ftp\_recv\_listing(), ftp\_send\_cmd(),
+get\_ftp\_banner()
+ \item[global\_settings.inc] debug\_print(), log\_print()
+ \item[http\_func.inc] can\_host\_asp(), can\_host\_php(), cgi\_dirs(),
+check\_win\_dir\_trav(), do\_check\_win\_dir\_trav(), get\_http\_banner(),
+get\_http\_port(), headers\_split(), hex2dec(), \_\_hex\_value(), http\_40x(),
+http\_is\_dead(), http\_recv(), http\_recv\_body(), http\_recv\_headers2(),
+http\_recv\_length(), http\_send\_recv(), php\_ver\_match()
+ \item[http\_keepalive.inc] check\_win\_dir\_trav\_ka(), enable\_keepalive(),
+get\_http\_page(), http\_keepalive\_check\_connection(),
+http\_keepalive\_enabled(), http\_keepalive\_recv\_body(),
+http\_keepalive\_send\_recv(), is\_cgi\_installed\_ka(), on\_exit()
+ \item[imap\_func.inc] get\_imap\_banner ()
+ \item[misc\_func.inc] add\_port\_in\_list(), base64(), base64\_code(),
+base64\_decode(), cvsdate2unixtime(), dec2hex(), get\_mysql\_version(),
+get\_rpc\_port(), get\_service\_banner\_line(), get\_unknown\_banner(),
+hex2raw(), known\_service(), pow2(), rand\_str(), register\_service(),
+replace\_or\_set\_kb\_item(), report\_service(), service\_is\_unknown(),
+set\_mysql\_version(), set\_unknown\_banner()
+ \item[netop.inc] ip\_dot2raw(), ip\_raw2dot(), netop\_banner\_items(),
+netop\_check\_and\_add\_banner(), netop\_each\_found(), netop\_kb\_derive(),
+netop\_log\_detected(), netop\_product\_ident(), netop\_spacepad(),
+netop\_zeropad()
+ \item[network\_func.inc] htonl(), htons(), ip\_checksum(), is\_private\_addr(),
+ms\_since\_midnight(), ntohl(), test\_udp\_port()
+ \item[nfs\_func.inc] cwd(), mount(), open(), padsz(), read(), readdir(),
+rpclong(), rpcpad(), str2long(), umount()
+ \item[nntp\_func.inc] nntp\_article(), nntp\_auth(), nntp\_connect(),
+nntp\_make\_id(), nntp\_post()
+ \item[pingpong.inc] udp\_ping\_pong()
+ \item[pkg-lib-deb.inc] isdpkgvuln()
+ \item[pop3\_func.inc] get\_pop3\_banner ()
+ \item[qpkg.inc] qpkg\_check(), qpkg\_cmp(), qpkg\_ver\_cmp()
+ \item[revisions-lib.inc] isdigit(), revcomp()
+ \item[slackware.inc] slack\_elt\_cmp(), slack\_ver\_cmp(), slackware\_check()
+ \item[slad\_ssh.inc] slad\_ssh\_login ()
+ \item[smbcl\_func.inc] bin\_dword(), bin\_word(), fileread(), GetPEFileVersion
+(), GetPEProductVersion (), get\_windir(), is\_domain(), PEVersion(),
+smbclientavail(), smbgetdir(), smbgetfile(), smbversion()
+ \item[smb\_hotfixes.inc] hotfix\_check\_dhcpserver\_installed(),
+hotfix\_check\_domain\_controler(), hotfix\_check\_excel\_version(),
+hotfix\_check\_exchange\_installed(), hotfix\_check\_iis\_installed(),
+hotfix\_check\_nt\_server(), hotfix\_check\_office\_version(),
+hotfix\_check\_outlook\_version(), hotfix\_check\_powerpoint\_version(),
+hotfix\_check\_sp(), hotfix\_check\_wins\_installed(),
+hotfix\_check\_word\_version(), hotfix\_check\_works\_installed(),
+hotfix\_data\_access\_version(), hotfix\_get\_commonfilesdir(),
+hotfix\_get\_programfilesdir(), hotfix\_get\_systemroot(), hotfix\_missing()
+ \item[smtp\_func.inc] get\_smtp\_banner(), smtp\_close(), smtp\_from\_header(),
+smtp\_open(), smtp\_recv\_banner(), smtp\_recv\_line(), smtp\_send\_port(),
+smtp\_send\_socket(), smtp\_to\_header()
+ \item[ssh\_func.inc] base64decode(), check\_pattern(), crypt(), decrypt(),
+derive\_keys(), dh\_gen\_key(), dh\_valid\_key(), get\_data\_size(),
+get\_ssh\_banner(), get\_ssh\_error(), get\_ssh\_server\_version(),
+get\_ssh\_supported\_authentication(), getstring(), init(), is\_sshd\_bugged(),
+kb\_ssh\_login(), kb\_ssh\_passphrase(), kb\_ssh\_password(),
+kb\_ssh\_privatekey(), kb\_ssh\_publickey(), kb\_ssh\_transport(),
+kex\_packet(), load\_array\_from\_kb(), load\_data\_from\_kb(),
+load\_intarray\_from\_kb(), load\_int\_from\_kb(), mac\_compute(), ntol(),
+packet\_payload(), putbignum(), putstring(), raw\_int32(), raw\_int8(),
+recv\_ssh\_packet(), register\_array\_in\_kb(), register\_data\_in\_kb(),
+register\_intarray\_in\_kb(), register\_int\_in\_kb(),
+reuse\_connection\_init(), send\_ssh\_packet(), set\_ssh\_error(),
+ssh\_close\_channel(), ssh\_close\_connection(), ssh\_cmd(), ssh\_cmd\_error(),
+ssh\_dss\_verify(), ssh\_exchange\_identification(), ssh\_hex2raw(),
+ssh\_kex2(), ssh\_login(), ssh\_login\_or\_reuse\_connection(),
+ssh\_open\_channel(), ssh\_recv(), ssh\_reuse\_connection(), ssh\_rsa\_verify(),
+ssh\_userauth2(), update\_window\_size()
+ \item[telnet\_func.inc] get\_telnet\_banner(), set\_telnet\_banner()
+ \item[tftp.inc] tftp\_get(), tftp\_put()
+ \item[ubuntu.inc] deb\_str\_cmp(), ubuntu\_check(), ubuntu\_ver\_cmp()
+ \item[uddi.inc] create\_uddi\_xml ()
+ \item[version\_func.inc] find\_bin(), get\_bin\_version(),
+get\_string\_version(), version\_is\_equal(), version\_is\_greater(),
+version\_is\_greater\_equal(), version\_is\_less(), version\_is\_less\_equal(),
+version\_test()
+\end{description}
-Both the client and server as well as the libraries on which they depend are being
-updated to support this functionality. You can detect if it is supported by checking
-OPENVAS\_NASL\_LEVEL is greater than 2206.
-\verb!script_oid! should be called like so:
-
-\begin{verbatim}
- ...
- if(description)
- {
- if (OPENVAS_NASL_LEVEL >= 2206)
- {
- script_oid("1.3.6.1.4.1.25623.1.0.90010");
- }
- else
- {
- script_id(90010);
- }
- ...
-\end{verbatim}
-
\subsection{Knowledge Base}
\label{sec:NASL-KB}
More information about the Openvas-commits
mailing list