nasl_guide.tex

大国补丁后的nessus2.2.8的源代码

is in fact :
\begin{verbatim}
 script_function(english:english_text, [francais:french_text, 
                                        deutsch:german_text,
					...]);
\end{verbatim}


In addition to these functions, the function \verb+script_dependencies()+ may be
called. It tells nessusd to launch the current script after some other script.
This is useful when you want to use the results that another script must
store in the KB. The syntax is :
\begin{verbatim}
script_dependencies(filename1 [,filename2, ..., filenameN]);
\end{verbatim}

where \verb+filename+ is the name of the script to be launched after, 
as it is stored on disk.


\subsubsection{The attack section}

The attack section may contain anything you think is useful for an attack. Once
your attack is done, you can report a problem using the
\verb+security_warning()+, \verb+security_hole()+ and \verb+security_info()+ 
functions which work the same way. \verb+security_info()+ must be used when
the attack was a succes but is not an important security problem.
\verb+security_warning()+ must be used when the attack was a success
but is not a great security problem. That is, it will not allow instant access
to an attacker. These two functions have the following syntaxes :
\begin{verbatim}
security_info(<port> [, protocol:<proto>]);
security_warning(<port> [, protocol:<proto>]);
security_hole(<port> [, protocol:<proto>]);

security_info(port:<port>, data:<data> [, protocol:<proto>]);
security_warning(port:<port>, data:<data> [, protocol:<proto>]);
security_hole(port:<port>, data:<data> [, protocol:<proto>]);
\end{verbatim}

In the first case, the data displayed by the client is the script
description, as entered with \verb+script_description()+. It is handy, because
of the multilingual support. 

In the second case the client will display the \verb+data+ argument. This
is handy if you must display information caught on the fly, such as a version
number.

\subsubsection{CVE compatibility}

CVE is an attempt to settle a common denominator to all the security-related
products. See \verb+http://cve.mitre.org+ for more details.

Nessus is fully CVE-compatible. If you write a script that tests
for a CVE-defined security problem, then call the \verb+script_cve_id()+
function in the description section of your plugin.
\verb+script_cve_id()+ is defined as : 
\begin{verbatim}
	script_cve_id(string);
\end{verbatim}

Example :
\begin{verbatim}
	script_cve_id("CVE-1999-0991");
\end{verbatim}

It is important to make a separate call to this function, rather than
just writing the CVE id in the report, so that the Nessus clients may
make an active use of it.


\subsubsection{An example}

In addition to security tests, NASL can be used to do some maintenance.
Here is a script example that will ensure that each host is running
ssh, and tell the user which hosts are not running it :
\begin{verbatim}
#
# Check for ssh
#
if(description)
{
 script_name(english:"Ensure the presence of ssh");
 script_description(english:"This script makes sure that ssh is running");
 script_summary(english:"connects on remote tcp port 22");
 script_category(ACT_GATHER_INFO);
 script_family(english:"Administration toolbox");
 script_copyright(english:"This script was written by Joe U.");
 script_dependencies("find_service.nes");
 exit(0);
}

#
# First, ssh may run on another port. 
# That's why we rely on the plugin 'find_service'
#


port = get_kb_item("Services/ssh");
if(!port)port = 22;

# declare that ssh is not installed yet
ok = 0;
if(get_port_state(port))
{
 soc = open_sock_tcp(port);
 if(soc)
 {
  # Check that ssh is not tcpwrapped. And that it's really
  # SSH
  data = recv(socket:soc, length:200);
  if("SSH" >< data)ok = 1;
 }
 close(soc);
}

#
# Only warn the user that SSH is NOT installed
#  
if(!ok)
{
  report = "SSH is not running on this host !";
  security_warning(port:22, data:report);
}
\end{verbatim}


\subsection{Tuning your script}

During a test, nessusd will launch more than 600 scripts. If all of them were badly written, then a test would take even more time than it currently does. That's why you must absolutely make whatever you can to make your script go as fast as possible. 

\subsubsection{Asking nessusd to execute the script only if it is necessary}

The best way to optimize your script is to tell nessusd when to \textbf{not} launch it. For instance, let's imagine that your script attempts to connect to the remote TCP port 123. If nessusd knows that this port is closed, then it's no use to start your script, since it will not do anything. The functions \verb+script_require_ports()+, \verb+script_require_keys()+ and \verb+script_exclude_keys()+ are designed for this purpose. They must be called in the description section of the script.

\begin{itemize}
\item \verb+script_require_ports(<port1>, <port2>, ...)+ : will make \verb+nessusd+ execute your script if and only if at least one of the ports is open. \verb+<port>+ can be either a numeric value (ie: 80) or a symbolic value, as defined in the knowledge base (ie: "Services/www").\\
Example : \verb+script_require_ports(80, "Services/www")+\\
Note that if the state of a port is unknown (if, for instance, no portscan was made), then the script will be executed.



\item \verb+script_require_keys(<key1>, <key2>, ...)+ : will make \verb+nessusd+ execute your script if and only if \textit{all the keys} given in argument are defined in the knowledge base. \\
Example : \verb+script_require_keys("ftp/anonymous", "ftp/writeable_dir")+ will only execute the script if the remote FTP server offers an anonymous access and if there is a writeable directory in it.

\item \verb+script_exclude_keys(<key1>, <key2>, ...)+ : will make \verb+nessusd+ \textit{not} execute your script if at least one of the keys given in argument is set in the knowledge base.
\end{itemize}

\subsubsection{Be smart enough to use the result of the other scripts}

Be sure to read the appendix regarding the knowledge base to make sure that your script is as lazy as possible - that is, it must not do something that another script has already done. For instance, rather that directly opening a socket
on a given tcp port (using \verb+open_sock_tcp()+), make sure that this port is open using \verb+get_port_state()+. The less your script will do, the faster things will go on.

\subsection{So you want to share your new script ?}

If you plan to share your script then you should obey to these rules :
\begin{itemize}
\item \textit{Your script must never interact with the user}. NASL scripts are
executed on the server side. Therefore, all the output will not be seen by
the user. 

\item \textit{Your script must test one vulnerability}. If you know how to test
multiple vulnerabilities, then write several scripts. So that you stay
consistent with all the Nessus scripts

\item \textit{Your script should belong to an existing family}. If you plan
to share your script, then avoid to create a family like \textit{Joe's Power Tools}
but try to stay consistent

\item \textit{Look up in CVE to see if there is a definition of your script}.
If you take care of CVE compatibility, then the Nessus maintainer will not
have to do it by himself, and this will save his time
 
\item \textit{Send it to the Nessus maintainer}. That is, me :) If you plan to share
your script, then make it available to everyone, not only your friends or a newsgroup
you hang on. Send it and see it being included in the Nessus distribution.
Once your script has been included in the distribution, it will be given
a unique ID.
\end{itemize}

\newpage
\section{Conclusion}


I hope you enjoyed this overview of NASL. Basically, the language should not
evolve for a while, so it's safe to learn how to use it and to practice it.

You will see bugs in the NASL interpretor. That is for sure. I do not know how you program, so it is very
likely that you will manage to make it crash. Please, do not keep the bugs for you. Share them, and send them
to me.


I hope you enjoyed reading this guide. 



\begin{verbatim}

				   -- Renaud Deraison
				   <[e-mail]>
\end{verbatim}

\newpage
\appendix
\section{The knowledge base}


The knowledge base is a set of keys which contains the results of the other
plugins. Using the functions \verb+script_dependencies()+, \verb+get_kb_item()+ and \verb+set_kb_item()+, then you can make your scripts and upcoming scripts avoid to do something that has already been done.

Here is a sum up of the keys that are set by the plugins : \\


KB items may have several values. For instance, imagine that
the remote host is running two FTP servers : one on port 21 and one
on port 2100. Then, the key \verb+Services/ftp+, which is the symbolic
name of the FTP server port is equal to 21 \textbf{and} 2100. If that is 
the case, then the script will be executed twice : the first time, 
\verb+get_kb_item("Services/ftp")+ will return 21, the second time
it will return 2100. \textit{This behavior is automatic} and your
script should not take care of this - that is, it should consider
that a given key always has only \textbf{one} value. Even if that is not
the case in real life, because \verb+nessusd+ is in charge of this.


Not all these keys are useful. I have never used several of them. But putting
too much elements in the KB is better than the opposite...



\begin{itemize}
\item \verb+Host/OS+\\
\textbf{Defined in} : \verb+queso.nasl+ and \verb+nmap_wrapper.nasl+\\
\textbf{Type} : string\\
\textbf{Meaning} : Remote operating system type

\item \verb+Host/dead+\\
\textbf{Defined in} : \verb+ping_host.nasl+ and all the DoS plugins 
\textbf{Type} : boolean\\
\textbf{Meaning} : The remote host is dead. If you set this item, then nessusd
will interrupt the test of the host.

\item \verb+Services/www+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a web server is running. Returns 0 if no web
server has been found.


\item \verb+Services/auth+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which an identd server is running. Returns 0 if no
such server has been found

\item \verb+Services/echo+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which 'echo' is running. Returns 0 if no
such service has been found


\item \verb+Services/finger+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a finger server is running. Returns 0 if no
such server has been found

\item \verb+Services/ftp+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which an ftp server is running. Returns 0 if no
such server has been found

\item \verb+Services/smtp+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which an SMTP server is running. Returns 0 if no
such server has been found

\item \verb+Services/ssh+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which an SSH server is running. Returns 0 if no
such server has been found

\item \verb+Services/http_proxy+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which an HTTP proxy is running. Returns 0 if no
such server has been found

\item \verb+Services/imap+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which an imap server is running. Returns 0 if no
such server has been found

\item \verb+Services/pop1+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a POP-1 server is running. Returns 0 if no
such server has been found

\item \verb+Services/pop2+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a POP-2 server is running. Returns 0 if no
such server has been found


\item \verb+Services/pop3+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a POP-3 server is running. Returns 0 if no
such server has been found

\item \verb+Services/nntp+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which an NNTP server is running. Returns 0 if no
such server has been found

\item \verb+Services/linuxconf+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a linuxconf server is running. Returns 0 if no
such server has been found


\item \verb+Services/swat+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a SWAT server is running. Returns 0 if no
such server has been found

\item \verb+Services/wild_shell+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a shell is open to the world (usually
a bad thing). Returns 0 if no such server has been found

\item \verb+Services/telnet+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a telnet server is running. Returns 0 if no
such server has been found

\item \verb+Services/realserver+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a RealServer server is running. Returns 0 if no
such server has been found

\item \verb+Services/netbus+\\
\textbf{Defined in} : \verb+find_service.nes+
\textbf{Type} : port number\\
\textbf{Meaning} : port on which a NetBus server is running (usually not
a good thing). Returns 0 if no such server has been found


\item \verb+bind/version+\\
\textbf{Defined in} : \verb+bind_version.nasl+
\textbf{Type} : string\\
\textbf{Meaning} : version of the remote BIND daemon


\item \verb+rpc/bootparamd+\\
\textbf{Defined in} : \verb+bootparamd.nasl+
\textbf{Type} : string\\
\textbf{Meaning} : The bootparam RPC service is running

\item \verb+Windows compatible+\\
\textbf{Defined in} : \verb+ca_unicenter_file_transfer_service.nasl+,
\verb+ca_unicenter_transport_service.nasl+, \verb+mssqlserver_detect.nasl+ and
\verb+windows_detect.nasl+
\textbf{Type} : boolean value\\
\textbf{Meaning} : The remote host appears to be running a Windows-compatible
operating system (this test is only done regarding the number of the
opened-ports)


\item \verb+finger/search.**@host+\\
\textbf{Defined in} : \verb+cfinger_search.nasl+
\textbf{Type} : boolean value\\
\textbf{Meaning} : The finger daemon dumps the list of users
if the query \verb+.**+ is made

\item \verb+finger/0@host+\\
\textbf{Defined in} : \verb+finger_0.nasl+
\textbf{Type} : boolean value\\
\textbf{Meaning} : The finger daemon dumps a list of users
if the query \verb+0+ is made

\item \verb+finger/.@host+\\
\textbf{Defined in} : \verb+finger_dot.nasl+
\textbf{Type} : boolean value\\
\textbf{Meaning} : The finger daemon dumps a list of users
if the query \verb+.+ is made

\item \verb+finger/user@host1@host2+\\
\textbf{Defined in} : \verb+finger_0.nasl+
\textbf{Type} : boolean value\\
\textbf{Meaning} : The finger daemon is vulnerable to a redirection attack

\item \verb+www/frontpage+\\
\textbf{Defined in} : \verb+frontpage.nasl+
\textbf{Type} : boolean value\\
\textbf{Meaning} : The remote web server is running frontpage extensions

\item \verb+ftp/anonymous+\\
\textbf{Defined in} : \verb+ftp_anonymous.nasl+
\textbf{Type} : boolean value\\
\textbf{Meaning} : The remote FTP server accepts anonymous logins


\item \verb+ftp/root_via_cwd+\\
\textbf{Defined in} : \verb+ftp_cwd_root.nasl+
\textbf{Type} : boolean value\\
\textbf{Meaning} : It is possible to gain root on the remote
FTP server using the \verb+CWD ~+ bug (see CVE-1999-0082)

\item \verb+ftp/microsoft+\\
\textbf{Defined in} : \verb+ftp_overflow.nasl+
\textbf{Type} : boolean value\\
\textbf{Meaning} : The remote server is a Microsoft FTP server, which
closes the connection whenever a too long argument is issued.

\item \verb+ftp/false_ftp+\\
\textbf{Defined in} : \verb+ftp_overflow.nasl+
\textbf{Type} : boolean value\\
\textbf{Meaning} : the remote FTP server is either protected
by tcp wrappers or the FTP port is open but closes the connection

\end{itemize}



\section{The 'nasl' utility}

The \textit{libnasl} package now comes with its own standalone interpretor
\verb+nasl+. Do 'man nasl' for more details





\end{document}