#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass article
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize a4paper
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title

The NASL2 reference manual
\layout Date

2002-02-06
\layout Author


\begin_inset LatexCommand \url[Michel Arboi]{<arboi@alussinan.org>}

\end_inset 


\layout Abstract

This is the NASL2 reference manual.
 It describes the language syntax and the internal functions.
\layout Abstract

If you want tips on how to write a security test in NASL, read 
\emph on 
The Nessus Attack Scripting Language Reference Guide
\emph default 
 by 
\begin_inset LatexCommand \url[Renaud Deraison]{<deraison@nessus.org>}

\end_inset 

.
\layout Standard


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\layout Standard


\begin_inset LatexCommand \printindex{}

\end_inset 


\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
newpage
\end_inset 


\layout Section

Introduction
\layout Subsection

History
\layout Standard

Please read 
\emph on 
The Nessus Attack Scripting Language Reference Guide
\emph default 
.
\newline 
Here is what the man page says:
\layout Quotation

NASL comes from a private project called 
\begin_inset Quotes eld
\end_inset 

pkt_forge
\begin_inset Quotes erd
\end_inset 

, which was written in late 1998 by Renaud Deraison and which was an interactive
 shell to forge and send raw IP packets (this pre-dates Perl's Net::RawIP
 by a couple of weeks).
 It was then extended to do a wide range of net­ work-related operations
 and integrated into Nessus as 
\begin_inset Quotes eld
\end_inset 

NASL
\begin_inset Quotes erd
\end_inset 

.
\layout Quotation

The parser was completely hand-written and a pain to work with.
 In Mid-2002, Michel Arboi wrote a bison parser for NASL, and he and Renaud
 Deraison re-wrote NASL from scratch.
 Although the 
\begin_inset Quotes eld
\end_inset 

new
\begin_inset Quotes erd
\end_inset 

 NASL was nearly working as early as August 2002, Michel's lazyness made
 us wait for early 2003 to have it working completely.
 
\layout Subsection

Differences between NASL1 and NASL2
\layout Itemize

NASL2 uses a real Bison parser.
 It is stricter and can handle complex expressions.
\layout Itemize

NASL2 has more built-in functions (although most of them could be back ported
 to NASL1).
\layout Itemize

NASL2 has more built-in operators.
\layout Itemize

NASL2 is much quicker (about sixteen times).
\layout Itemize

Most NASL2 scripts cannot run under NASL1.
\layout Itemize

And a few NASL1 scripts cannot run under NASL2 (but fixing them is easy).
\layout Itemize

NASL2 user-defined functions can handle array.
\layout Subsection

Copyright
\layout Standard

This document is (C) Michel Arboi.
 Permission is granted to reproduce this document as long as you do not
 modify it (and leave this copyright in place, of course).
\layout Subsection

Comments
\layout Standard

Please send comments to 
\begin_inset LatexCommand \url[Michel Arboi]{<arboi@alussinan.org>}

\end_inset 

.
 
\newline 
I checked the spelling of this document with an American dictionary, however
 the grammar may be incorrect.
\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
newpage
\end_inset 


\layout Section

The NASL2 grammar
\layout Subsection

Preliminary remarks
\layout Itemize

A comment
\begin_inset LatexCommand \index{comment}

\end_inset 

 starts with a 
\series bold 
#
\begin_inset LatexCommand \index{\#}

\end_inset 


\series default 
 and finishes at the end of the current line.
 It is ignored by the lexical analyzer.
\layout Itemize

You may insert 
\begin_inset Quotes eld
\end_inset 

blanks
\begin_inset LatexCommand \index{blanks}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 anywhere between two lexical tokens.
\newline 
A blank may be a sequence of white space, horizontal or vertical tabulation,
 line feed, form feed or carriage return characters; or a comment.
\layout Itemize

Token are parsed by a lexical analyzer and returned to the parser.
\begin_deeper 
\layout Itemize

As the lexical analyzer returns the longer token it finds, expressions like
 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{a+++++b}
\end_inset 

 without any white space are erroneous because they will be interpreted
 as 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{a++~++~+~b}
\end_inset 

 i.e.
 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{(a++~++)~+~b}
\end_inset 

 just like in ANSI C
\begin_inset Foot
collapsed true

\layout Standard

They used to work in K&R C.
\end_inset 

.
 You have to insert spaces: 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{a++~+~++b}
\end_inset 


\layout Itemize

You cannot insert spaces in the middle of multiple character tokens.
 e.g.
 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{x~=~a~+~+;}
\end_inset 

 will not parse.
 Write 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{x~=~a~++;}
\end_inset 


\end_deeper 
\layout Subsection

Syntax
\layout List
\labelwidthstring 00.00.0000

decl_list instr_decl 
\newline 
instr_decl instr_decl_list
\layout List
\labelwidthstring 00.00.0000

instr_decl instr
\newline 
func_decl;
\layout List
\labelwidthstring 00.00.0000

func_decl 
\series bold 
function\SpecialChar ~

\series default 
identifier\SpecialChar ~

\series bold 
(\SpecialChar ~

\series default 
arg_decl\SpecialChar ~

\series bold 
)\SpecialChar ~

\series default 
block 
\layout List
\labelwidthstring 00.00.0000

arg_decl /*nothing*/
\newline 
arg_decl_1
\layout List
\labelwidthstring 00.00.0000

arg_decl_1 identifier
\newline 
identifier\SpecialChar ~

\series bold 
,\SpecialChar ~

\series default 
arg_decl_1
\layout List
\labelwidthstring 00.00.0000

block 
\series bold 
{
\series default 
\SpecialChar ~
instr_list
\series bold 
\SpecialChar ~
}
\newline 
{\SpecialChar ~
}
\layout List
\labelwidthstring 00.00.0000

instr_list instr
\newline 
instr instr_list
\layout List
\labelwidthstring 00.00.0000

instr simple_instr\SpecialChar ~
 
\series bold 
;
\series default 

\newline 
block
\newline 
if_block
\newline 
loop
\layout List
\labelwidthstring 00.00.0000

simple_instr aff
\newline 
post_pre_incr
\newline 
rep
\newline 
func_call
\newline 
ret
\newline 
inc
\newline 
loc
\newline 
glob
\series bold 

\newline 
break
\series default 

\newline 
/*nothing*/
\layout List
\labelwidthstring 00.00.0000

ret 
\series bold 
return
\series default 
\SpecialChar ~
expr
\series bold 

\newline 
return
\layout List
\labelwidthstring 00.00.0000

if_block 
\series bold 
if\SpecialChar ~
(\SpecialChar ~

\series default 
expr\SpecialChar ~

\series bold 
)
\series default 
 instr
\series bold 

\newline 
if\SpecialChar ~
(\SpecialChar ~

\series default 
expr\SpecialChar ~

\series bold 
)
\series default 
 instr 
\series bold 
else
\series default 
 instr
\layout List
\labelwidthstring 00.00.0000

loop for_loop 
\newline 
while_loop
\newline 
repeat_loop
\newline 
foreach_loop
\layout List
\labelwidthstring 00.00.0000

for_loop 
\series bold 
for\SpecialChar ~
(\SpecialChar ~

\series default 
aff_func\SpecialChar ~

\series bold 
;\SpecialChar ~

\series default 
expr\SpecialChar ~

\series bold 
;\SpecialChar ~

\series default 
aff_func\SpecialChar ~

\series bold 
)\SpecialChar ~

\series default 
instr
\layout List
\labelwidthstring 00.00.0000

while_loop 
\series bold 
while\SpecialChar ~
(\SpecialChar ~

\series default 
expr\SpecialChar ~

\series bold 
)\SpecialChar ~

\series default 
instr
\layout List
\labelwidthstring 00.00.0000

repeat_loop 
\series bold 
repeat
\series default 
\SpecialChar ~
instr
\series bold 
\SpecialChar ~
until
\series default 
\SpecialChar ~
expr
\series bold 
\SpecialChar ~
;
\layout List
\labelwidthstring 00.00.0000

foreach_loop 
\series bold 
foreach\SpecialChar ~

\series default 
identifier
\series bold 
\SpecialChar ~
(
\series default 
\SpecialChar ~
array
\series bold 
\SpecialChar ~
)\SpecialChar ~

\series default 
 instr
\layout List
\labelwidthstring 00.00.0000

array expr
\layout List
\labelwidthstring 00.00.0000

aff_func aff
\newline 
post_pre_incr
\newline 
func_call
\newline 
/*nothing */
\layout List
\labelwidthstring 00.00.0000

rep func_call
\series bold 
\SpecialChar ~
x
\series default 
\SpecialChar ~
expr
\layout List
\labelwidthstring 00.00.0000

string 
\noun on 
string1
\noun default 

\newline 

\noun on 
string2
\layout List
\labelwidthstring 00.00.0000

inc 
\series bold 
include (
\series default 
 string 
\series bold 
)
\series default 
 
\layout List
\labelwidthstring 00.00.0000

func_call identifier
\series bold 
\SpecialChar ~
(
\series default 
\SpecialChar ~
arg_list
\series bold 
\SpecialChar ~
)
\series default 
 
\layout List
\labelwidthstring 00.00.0000

arg_list arg_list_1 
\newline 
/*nothing*/
\layout List
\labelwidthstring 00.00.0000

arg_list_1 arg
\newline 
arg
\series bold 
\SpecialChar ~
,
\series default 
\SpecialChar ~
arg_list_1
\layout List
\labelwidthstring 00.00.0000

arg expr
\newline 
identifier
\series bold 
\SpecialChar ~
:
\series default 
\SpecialChar ~
expr
\layout List
\labelwidthstring 00.00.0000

aff lvalue\SpecialChar ~

\series bold 
=
\series default 
\SpecialChar ~
expr 
\newline 
lvalue
\series bold 
\SpecialChar ~
+=
\series default 
\SpecialChar ~
expr 
\newline 
lvalue\SpecialChar ~

\series bold 
-=\SpecialChar ~

\series default 
expr 
\newline 
lvalue\SpecialChar ~

\series bold 
*=\SpecialChar ~

\series default 
expr 
\newline 
lvalue\SpecialChar ~

\series bold 
/=\SpecialChar ~

\series default 
expr 
\newline 
lvalue\SpecialChar ~

\series bold 
%=\SpecialChar ~

\series default 
expr 
\newline 
lvalue\SpecialChar ~

\series bold 
>>=\SpecialChar ~

\series default 
expr
\newline 
lvalue
\series bold 
\SpecialChar ~
>>>=
\series default 
\SpecialChar ~
expr
\newline 
lvalue
\series bold 
\SpecialChar ~
<<=
\series default 
\SpecialChar ~
expr
\layout List
\labelwidthstring 00.00.0000

lvalue identifier
\newline 
array_elem 
\layout List
\labelwidthstring 00.00.0000

identifier 
\noun on 
identifier
\noun default 
 
\newline 

\series bold 
x
\layout List
\labelwidthstring 00.00.0000

array_elem identifier
\series bold 
\SpecialChar ~
[
\series default 
\SpecialChar ~
array_index
\series bold 
\SpecialChar ~
]
\layout List
\labelwidthstring 00.00.0000

array_index expr 
\layout List
\labelwidthstring 00.00.0000

post_pre_incr 
\series bold 
++\SpecialChar ~

\series default 
lvalue 
\series bold 

\newline 
--
\series default 
\SpecialChar ~
lvalue 
\newline 
lvalue\SpecialChar ~

\series bold 
++
\series default 
 
\newline 
lvalue\SpecialChar ~

\series bold 
--
\layout List
\labelwidthstring 00.00.0000

expr 
\series bold 
(
\series default 
\SpecialChar ~
expr\SpecialChar ~

\series bold 
)
\series default 
 
\newline 
logic_expr
\newline 
arith_expr
\newline 
bit_expr
\newline 
post_pre_incr
\newline 
compar
\noun on 

\newline 
integer
\newline 
string2
\newline 
string1
\noun default 

\newline 
var
\newline 
aff
\newline 
ipaddr
\layout List
\labelwidthstring 00.00.0000

logic_expr expr\SpecialChar ~

\series bold 
and\SpecialChar ~

\series default 
expr
\series bold 

\newline 
!\SpecialChar ~

\series default 
expr
\newline 
expr
\series bold 
\SpecialChar ~
or\SpecialChar ~

\series default 
expr
\layout List
\labelwidthstring 00.00.0000

arith_expr expr\SpecialChar ~

\series bold 
+\SpecialChar ~

\series default 
expr
\newline 
expr\SpecialChar ~

\series bold 
-
\series default 
\SpecialChar ~
expr
\series bold 

\newline 
-
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
*
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
/
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
%
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
**
\series default 
\SpecialChar ~
expr
\layout List
\labelwidthstring 00.00.0000

bit_expr 
\series bold 
~
\series default 
\SpecialChar ~
expr
\newline 
expr\SpecialChar ~

\series bold 
&\SpecialChar ~

\series default 
expr
\newline 
expr\SpecialChar ~

\series bold 
^\SpecialChar ~

\series default 
expr
\newline 
expr\SpecialChar ~

\series bold 
|
\series default 
\SpecialChar ~
expr
\newline 
expr\SpecialChar ~

\series bold 
>>\SpecialChar ~

\series default 
expr
\newline 
expr\SpecialChar ~

\series bold 
>>>\SpecialChar ~

\series default 
expr
\newline 
expr\SpecialChar ~

\series bold 
<<
\series default 
expr
\layout List
\labelwidthstring 00.00.0000

compar expr
\series bold 
\SpecialChar ~
><
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
>!<
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
=~
\series default 
\SpecialChar ~
string
\newline 
expr\SpecialChar ~

\series bold 
!~\SpecialChar ~

\series default 
string
\newline 
expr
\series bold 
\SpecialChar ~
<
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
>
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
==
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
!=
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
>=
\series default 
\SpecialChar ~
expr
\newline 
expr
\series bold 
\SpecialChar ~
<=
\series default 
\SpecialChar ~
expr
\layout List
\labelwidthstring 00.00.0000

var identifier 
\newline 
array_elem 
\newline 
func_call
\layout List
\labelwidthstring 00.00.0000

ipaddr 
\noun on 
integer
\series bold 
\noun default 
\SpecialChar ~
.
\series default 
\noun on 
\SpecialChar ~
integer\SpecialChar ~

\series bold 
\noun default 
.\SpecialChar ~

\series default 
\noun on 
integer
\series bold 
\noun default 
\SpecialChar ~
.
\series default 
\noun on 
\SpecialChar ~
integer
\noun default 
 
\layout List
\labelwidthstring 00.00.0000

loc 
\series bold 
local_var
\series default 
 arg_decl 
\layout List
\labelwidthstring 00.00.0000

glob 
\series bold 
global_var
\series default 
 arg_decl
\layout List
\labelwidthstring 00.00.0000


\noun on 
integer
\noun default 
 is any sequence of decimal digit (preceded by an optional minus sign),
 or 
\series bold 
0
\series default 
 followed by a sequence of octal digits, or 
\series bold 
0x
\series default 
 followed by a sequence of hexadecimal digits.
\layout List
\labelwidthstring 00.00.0000


\noun on 
string1
\noun default 
 is a string between simple quotes.
\layout List
\labelwidthstring 00.00.0000


\noun on 
string2
\noun default 
 is a string between double quotes.
\layout Subsection

Types
\layout Standard

NASL2 handles the following data types:
\layout Enumerate


\series bold 
integers
\series default 

\begin_inset LatexCommand \index{integers}

\end_inset 


\newline 
Any sequence of digits with an optional minus sign is an integer.
 NASL2 uses the C syntax: octal numbers can be enter by starting with 
\series bold 
0
\series default 
 and hexadecimal with 
\series bold 
0x
\series default 
 (i.e.
 0x10 = 020 = 16)
\layout Enumerate


\series bold 
strings
\series default 

\begin_inset LatexCommand \index{strings}

\end_inset 

, which can exist in two flavors: 
\begin_inset Quotes eld
\end_inset 

pure
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

impure
\begin_inset Quotes erd
\end_inset 


\begin_inset Foot
collapsed true

\layout Standard

This is an heritage from NASL1, it would have been too complex to break
 it.
 The 
\series bold 
string
\series default 
 function interprets escape sequences in 
\begin_inset Quotes eld
\end_inset 

impure
\begin_inset Quotes erd
\end_inset 

 strings and returns a 
\begin_inset Quotes eld
\end_inset 

pure
\begin_inset Quotes erd
\end_inset 

 string; it just copy 
\begin_inset Quotes eld
\end_inset 

pure
\begin_inset Quotes erd
\end_inset 

 strings without changing them.
 Note that 
\series bold 
display
\series default 
 calls 
\series bold 
string
\series default 
 before printing its argument on the standard output.
\end_inset 

.
\begin_deeper 
\layout Enumerate


\begin_inset Quotes eld
\end_inset 

Impure
\begin_inset Quotes erd
\end_inset 

 strings
\begin_inset LatexCommand \index{impure strings}

\end_inset 

 are entered between double quotes and are 
\bar under 
not
\bar default 
 converted: backslashes remain backslashes.
 
\begin_inset Quotes eld
\end_inset 

Impure
\begin_inset Quotes erd
\end_inset 

 strings are transformed into 
\begin_inset Quotes eld
\end_inset 

pure
\begin_inset Quotes erd
\end_inset 

 string by the internal 
\series bold 
string
\series default 
 function.
\layout Enumerate


\begin_inset Quotes eld
\end_inset 

Pure
\begin_inset Quotes erd
\end_inset 

 strings
\begin_inset LatexCommand \index{pure strings}

\end_inset 

 are returned by 
\series bold 
string
\series default 
 or are entered between simple quotes.
 In this case, a few escape sequences are transformed
\begin_inset Foot
collapsed true

\layout Standard

Much less than in C, but I don't think we need the octal representation,
 wide chars, etc.
 Note that the way the parser is written, we could not accept 
\series bold 

\backslash 
0
\layout Standard

So...
 
\series bold 

\backslash 
n
\series default 
 is the newline character, 
\series bold 

\backslash 
t
\series default 
 the horizontal tabulation, 
\series bold 

\backslash 
v 
\series default 
the vertical tabulation, 
\series bold 

\backslash 
r
\series default 
 line feed, 
\series bold 

\backslash 
f
\series default 
 form feed, 
\series bold 

\backslash 
'
\series default 
 the single quote, 
\series bold 

\backslash 

\series default 
 
\series bold 

\begin_inset Quotes erd
\end_inset 


\series default 
 the double quote (just in case), and 
\series bold 

\backslash 
x42
\series default 
 is 
\begin_inset Quotes eld
\end_inset 

B
\begin_inset Quotes erd
\end_inset 

, because its ASCII code is 0x42 (66 in hex).
 Do not enter 
\series bold 

\backslash 
x00
\series default 
 unless you really want to break the parser.
 
\end_inset 

.
\end_deeper 
\layout Enumerate


\series bold 
arrays
\series default 

\begin_inset LatexCommand \index{arrays}

\end_inset 

, which can be indexed with integers
\begin_inset Foot
collapsed true

\layout Standard

Elements are numbered from 0, just like in C.
 Negative indexes are not supported (yet) and big values are not recommended
 as they woul eat memory.
 If you want such indexes, you should convert them into strings, so that
 they get hashed.
 I admit that this is neither clean nor efficient.
\end_inset 

 or strings
\begin_inset Foot
collapsed true

\layout Standard

Like the Perl hashes.
 Hashes have a big inconvenient: they destroy the order of the data their
 store.
\end_inset 

.
\layout Enumerate

And the 
\series bold 
NULL
\begin_inset LatexCommand \index{NULL}

\end_inset 


\series default 
 value, which is what you get if you read an initialized variable, or what
 internal functions returns in case of severe error.
\newline 
Read the warning below!
\layout Enumerate


\series bold 
Booleans
\begin_inset LatexCommand \index{Booleans}

\end_inset 


\series default 
 are not a standalone type.
 The comparison operators return 
\series bold 
0
\series default 
 for FALSE
\begin_inset LatexCommand \index{FALSE}

\end_inset 

 and 
\series bold 
1
\series default 
 for TRUE
\begin_inset LatexCommand \index{TRUE}

\end_inset 

.
 Any other value is converted :
\begin_deeper 
\layout Itemize

The undefined or null value is FALSE
\begin_inset LatexCommand \index{FALSE}

\end_inset 

.
\layout Itemize

Integers are TRUE
\begin_inset LatexCommand \index{TRUE}

\end_inset 

 if not null; 
\series bold 
0
\series default 
 is FALSE
\begin_inset LatexCommand \index{FALSE}

\end_inset 

.
\layout Itemize

Strings are TRUE
\begin_inset LatexCommand \index{TRUE}

\end_inset 

 if not empty.
 So 
\series bold 
"0"
\series default 
 is TRUE (it is false in Perl or in NASL1).
\layout Itemize

Although it does not really make sense, arrays are always TRUE
\begin_inset LatexCommand \index{TRUE}

\end_inset 

, whether they are empty or not.
\end_deeper 
\layout Standard

All built-in or user-defined functions can handle or return all those types
 (even arrays!).
\layout Paragraph

Warnings about the NULL value
\begin_inset LatexCommand \index{NULL}

\end_inset 


\begin_inset LatexCommand \label{par:Warning-about-NULL}

\end_inset 


\layout Subparagraph

NULL and the array operator
\layout Standard

Reading an array element from a NULL value will immediately convert it into
 an array.
 An empty array of course, but no more an undefined variable.
 Changing this means big modifications in the NASL interpretor.
 For example:
\layout LyX-Code

v = NULL;
\layout LyX-Code

# isnull(v)=TRUE and typeof(v)="undef"
\layout LyX-Code

x = v[2];
\layout LyX-Code

# isnull(x)=TRUE and typeof(x)="undef"
\layout LyX-Code

# But isnull(v)=FALSE and typeof(v)="array"
\layout Subparagraph

NULL and isnull
\layout Standard

If you want to check if a variable is undefined, you have to used 
\series bold 
isnull(var)
\series default 
.
 Testing the equality with the 
\series bold 
NULL
\series default 
 constant (
\series bold 
var\SpecialChar ~
==
\series default 
\SpecialChar ~

\series bold 
NULL
\series default 
) is not a good idea, as 
\series bold 
NULL
\series default 
 will be converted to 
\series bold 
0
\series default 
 or the empty string 
\series bold 

\begin_inset Quotes eld
\end_inset 


\begin_inset Quotes erd
\end_inset 


\series default 
 according to the type of the variable.
 This is necessary to ensure that variables are 
\begin_inset Quotes eld
\end_inset 

automatically initialized
\begin_inset Quotes erd
\end_inset 

 - changing this would probably break some existing scripts.
\layout LyX-Code

\layout Subsection

Operators
\layout Subsubsection

General operators
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{=}
\end_inset 


\begin_inset LatexCommand \index{=}

\end_inset 


\series default 
 is the affectation operator.
\begin_deeper 
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{x=42;}
\end_inset 

 puts 42 into the variable 
\series bold 
x
\series default 
.
 The previous value is forgotten.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{x=y;}
\end_inset 

 copies the value of variable 
\series bold 
y
\series default 
 into x.
 If 
\series bold 
y
\series default 
 was undefined, 
\series bold 
x
\series default 
 becomes undefined too.
\end_deeper 
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{[]}
\end_inset 


\begin_inset LatexCommand \index{[]}

\end_inset 

 is the array index operator.
\begin_deeper 
\layout Itemize

A variable cannot be atomic
\begin_inset Foot
collapsed true

\layout Standard

i.e.
 a 
\begin_inset Quotes eld
\end_inset 

string
\begin_inset Quotes erd
\end_inset 

 or an 
\begin_inset Quotes eld
\end_inset 

integer
\begin_inset Quotes erd
\end_inset 

, or even 
\begin_inset Quotes eld
\end_inset 

null
\begin_inset Quotes erd
\end_inset 

.
\end_inset 

 and an array at the same time.
 If you changed the type, the previous value(s) is (are) lost.
\layout Itemize

However, this operator can be used to extract a character from a string:
 if 
\series bold 
s\SpecialChar ~
=\SpecialChar ~
"abcde"
\series default 
, then 
\series bold 
s[2]\SpecialChar ~
= "c"
\series default 
.
\newline 
In NASL1, this could be used to 
\emph on 
change
\emph default 
 the character too: you could write 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{s[2]~=~"C";}
\end_inset 

 and 
\series bold 
s
\series default 
 became 
\series bold 
"abCde"
\series default 
.
 This is no longer true; you have to use the 
\series bold 
insstr
\series default 
 function and write something like 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{s~=~insstr(s,~"C",~2,~2);}
\end_inset 

 See 
\series bold 
insstr
\series default 
 
\begin_inset LatexCommand \vpageref{ite:insstr}

\end_inset 

.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{y[1]~=~42;}
\end_inset 

 makes an array out of 
\series bold 
y
\series default 
 and puts 42 in the second element.
 If 
\series bold 
y
\series default 
 was not an array, it's first undefined.
\end_deeper 
\layout Subsubsection

Arithmetics operators
\layout Standard

Be aware that there is no strict rule on the integer size in NASL2.
 The interpretor implements them with the native 
\begin_inset Quotes eld
\end_inset 

int
\begin_inset Quotes erd
\end_inset 

 C type, which is 32 bit long on most systems, and maybe 64 bit long on
 a few one
\begin_inset Foot
collapsed false

\layout Standard

Yes, no more 16 bit systems! Who wants to port NASL2 to MS/DOS?
\end_inset 

.
 There is no overflow or underflow protection.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{+}
\end_inset 


\begin_inset LatexCommand \index{+}

\end_inset 

 is the addition.
 
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{-}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'55}}

\end_inset 

 is the subtraction.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{*}
\end_inset 


\begin_inset LatexCommand \index{*}

\end_inset 

 is the multiplication.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{/}
\end_inset 


\begin_inset LatexCommand \index{/}

\end_inset 

 is the integer division.
 Please note that:
\begin_deeper 
\layout Itemize

NASL2 does not support floating point operations.
\layout Itemize

Division by zero will return 0 instead of crashing the interpretor.
 How nice of us!
\end_deeper 
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
%}
\end_inset 


\begin_inset LatexCommand \index{\%}

\end_inset 

 is the modulo.
 Once again, if the 2
\begin_inset Formula $^{\textrm{nd}}$
\end_inset 

 operand is null, the interpretor will return 0 instead of crashing on SIGFPE.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{**}
\end_inset 


\begin_inset LatexCommand \index{**}

\end_inset 

 is the power function
\begin_inset Foot
collapsed true

\layout Standard


\series bold 
**
\series default 
 is Fortran syntax.
 Maybe some of you will regret the Basic syntax, but 
\emph on 
^
\emph default 
 is already used by the exclusive-or (xor) operator (C syntax).
\end_inset 

.
\layout Subsubsection

Nice C operators
\layout Standard

NASL2 imported some nice operators from C:
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{++}
\end_inset 


\begin_inset LatexCommand \index{++}

\end_inset 

 is the pre-incrementation
\begin_inset LatexCommand \index{pre-incrementation}

\end_inset 

 (++x) or post-incrementation
\begin_inset LatexCommand \index{post-incrementation}

\end_inset 

 (x++).
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{++x}
\end_inset 

 adds 1 to 
\series bold 
x
\series default 
 and returns the result; 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{x++}
\end_inset 

 adds 1 to x but returns the previous value.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{--}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'55}\symbol{'55}}

\end_inset 

 is the pre-decrementation
\begin_inset LatexCommand \index{pre-decrementation}

\end_inset 

 (--x) or post-decrementation
\begin_inset LatexCommand \index{post-decrementation}

\end_inset 

 (x--).
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{+=}
\end_inset 


\begin_inset LatexCommand \index{+=}

\end_inset 


\series default 
 
\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{-=}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'55}=}

\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{*=}
\end_inset 


\begin_inset LatexCommand \index{*=}

\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{/=}
\end_inset 


\begin_inset LatexCommand \index{/=}

\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
%=}
\end_inset 


\begin_inset LatexCommand \index{\%=}

\end_inset 


\series default 
 have the same meaning as in C
\newline 
e.g.
 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{x~+=~y;}
\end_inset 

 is equivalent to 
\begin_inset ERT
status Collapsed

\layout Standard
x~=~x~+~y;
\end_inset 

but 
\series bold 
x
\series default 
 is evaluated only once.
 This is important in expressions like 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{a[i++]~*=~2;}
\end_inset 

 where the index 
\begin_inset Quotes eld
\end_inset 

i
\begin_inset Quotes erd
\end_inset 

 is incremented only once.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'74}
\backslash 
symbol{'74}=}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'74}\symbol{'74}=}

\end_inset 


\series default 
 and
\series bold 
 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'76}
\backslash 
symbol{'76}=}
\end_inset 

 
\begin_inset LatexCommand \index{\symbol{'76}\symbol{'76}=}

\end_inset 


\series default 
 also exist; we added 
\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'76}
\backslash 
symbol{'76}
\backslash 
symbol{'76}=}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'76}\symbol{'76}\symbol{'76}=}

\end_inset 


\series default 
 
\layout Subsubsection

String operators
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{+}
\end_inset 


\begin_inset LatexCommand \index{+}

\end_inset 

 is the string concatenation
\begin_inset LatexCommand \index{string concatenation}

\end_inset 

.
 However, you should better use the 
\series bold 
string
\series default 
 function.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{-}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'55}}

\end_inset 

 is the 
\begin_inset Quotes eld
\end_inset 

string subtraction
\begin_inset LatexCommand \index{string subtraction}

\end_inset 


\begin_inset Quotes erd
\end_inset 

.
 It removes the first instance of a string inside another.
 
\newline 
For example 
\series bold 
'abcd' \SpecialChar ~
- \SpecialChar ~
'bc'
\series default 
 will give 
\series bold 
'ad'
\series default 
.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{[]}
\end_inset 


\begin_inset LatexCommand \index{[]}

\end_inset 

 extracts one character from the string, as explained before.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{><}
\end_inset 


\begin_inset LatexCommand \index{><}

\end_inset 


\series default 
 is the 
\begin_inset Quotes eld
\end_inset 

string match
\begin_inset LatexCommand \index{string match}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 operator.
 It looks for substrings inside a string.
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{'ab'~><~'xabcdz'}
\end_inset 

 is TRUE; 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{'ab'~><~'xxx'}
\end_inset 

 is FALSE.
\layout Itemize


\series bold 

\begin_inset ERT
status Open

\layout Standard

\backslash 
texttt{>!<}
\end_inset 


\begin_inset LatexCommand \index{>!<}

\end_inset 


\series default 
 is the 
\begin_inset Quotes eld
\end_inset 

string don't match
\begin_inset LatexCommand \index{string don't match}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 operator.
 It looks for substrings inside a string and returns the opposite as the
 previous operator.
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{'ab'~>!<~'xabcdz'}
\end_inset 

 is FALSE; 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{'ab'~>!<~'xxx'}
\end_inset 

 is TRUE.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{=
\backslash 
~ }
\end_inset 


\begin_inset LatexCommand \index{=\symbol{'176}}

\end_inset 


\series default 
 is the 
\begin_inset Quotes eld
\end_inset 

regex match
\begin_inset LatexCommand \index{regex match}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 operator.
 It is similar to a call to the internal function 
\series bold 
ereg
\series default 
 but is quicker because the regular expression is compiled only once when
 the script is parsed
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{s~=
\backslash 
~ ~"[ab]*x+"}
\end_inset 

 is equivalent to 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{ereg(string:s,~pattern:"[ab]*x+",~icase:1)}
\end_inset 


\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{!
\backslash 
~ }
\end_inset 


\begin_inset LatexCommand \index{\symbol{'41}\symbol{'176}}

\end_inset 


\series default 
 is the 
\begin_inset Quotes eld
\end_inset 

regex don't match
\begin_inset Quotes erd
\end_inset 

 operator.
 It gives the opposite result of the previous one
\begin_inset Foot
collapsed true

\layout Standard

In fact, there is a pathological case where both operator returns 
\series bold 
NULL
\series default 
: when the pattern could not be compiled.
 You will get an error when the pattern is parsed, then every time you try
 to execute the line.
\end_inset 

.
\layout Subsubsection

Compare operators
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{==}
\end_inset 


\begin_inset LatexCommand \index{==}

\end_inset 


\series default 
 is TRUE if both arguments are equals
\begin_inset LatexCommand \index{equals}

\end_inset 

, FALSE otherwise.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{!=}
\end_inset 


\begin_inset LatexCommand \index{=}

\end_inset 


\series default 
 is TRUE if both arguments are different
\begin_inset LatexCommand \index{different}

\end_inset 

, TRUE otherwise.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{62}}
\end_inset 


\begin_inset LatexCommand \index{>}

\end_inset 


\series default 
 is the 
\begin_inset Quotes eld
\end_inset 

greater than
\begin_inset LatexCommand \index{greater than}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 operator.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{62}=}
\end_inset 


\begin_inset LatexCommand \index{>=}

\end_inset 


\series default 
 is the 
\begin_inset Quotes eld
\end_inset 

greater than or equal
\begin_inset LatexCommand \index{greater than or equal}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 operator.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{60}}
\end_inset 


\begin_inset LatexCommand \index{<}

\end_inset 


\series default 
 is the 
\begin_inset Quotes eld
\end_inset 

lesser than
\begin_inset LatexCommand \index{lesser than}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 operator.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{60}=}
\end_inset 


\begin_inset LatexCommand \index{<=}

\end_inset 


\series default 
 is the 
\begin_inset Quotes eld
\end_inset 

lesser than or equal
\begin_inset LatexCommand \index{lesser than or equal}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 operator.
\layout Subsubsection

Logical operators
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{!}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'41}}

\end_inset 

 is the logical 
\begin_inset Quotes eld
\end_inset 

not
\begin_inset Quotes erd
\end_inset 

.
 TRUE if its argument is FALSE, FALSE otherwise.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
&
\backslash 
&}
\end_inset 


\begin_inset LatexCommand \index{\&\&}

\end_inset 

 is the logical 
\begin_inset Quotes eld
\end_inset 

and
\begin_inset Quotes erd
\end_inset 

.
 Note that if the first argument is FALSE, the second is not evaluated.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{||}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'174}\symbol{'174}}

\end_inset 

 is the logical 
\begin_inset Quotes eld
\end_inset 

or
\begin_inset Quotes erd
\end_inset 

.
 If the first argument is TRUE, the second is not evaluated.
\layout Subsubsection

Bit fields operators
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
~ }
\end_inset 


\begin_inset LatexCommand \index{\symbol{'176}}

\end_inset 

 is the arithmetic 
\begin_inset Quotes eld
\end_inset 

not
\begin_inset LatexCommand \index{arithmetic not}

\end_inset 


\begin_inset Quotes erd
\end_inset 

, the 1-complement
\begin_inset LatexCommand \index{1-complement}

\end_inset 


\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
&}
\end_inset 


\begin_inset LatexCommand \index{\&}

\end_inset 

 is the arithmetic 
\begin_inset Quotes eld
\end_inset 

and
\begin_inset LatexCommand \index{arithmetic and}

\end_inset 


\begin_inset Quotes erd
\end_inset 

.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{|}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'174}}

\end_inset 

 is the arithmetic 
\begin_inset Quotes eld
\end_inset 

or
\begin_inset LatexCommand \index{arithemtic or}

\end_inset 


\begin_inset Quotes erd
\end_inset 

.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
^}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'136}}

\end_inset 

 is the arithmetic 
\begin_inset Quotes eld
\end_inset 

xor
\begin_inset LatexCommand \index{arithmetic xor}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 (exclusive or).
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'74}
\backslash 
symbol{'74}}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'74}\symbol{'74}}

\end_inset 


\series default 
 is the logical bit shift to the left
\begin_inset LatexCommand \index{logical bit shift to the left}

\end_inset 

.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'76}
\backslash 
symbol{'76}}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'76}\symbol{'76}}

\end_inset 


\series default 
 is the arithmetic
\begin_inset LatexCommand \index{arithmetic shift to the right}

\end_inset 

 / signed shift to the right
\begin_inset LatexCommand \index{signed shift to the right}

\end_inset 


\begin_inset Foot
collapsed true

\layout Standard

The sign bit, if any, is propagated.
\end_inset 

.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'76}
\backslash 
symbol{'76}
\backslash 
symbol{'76}}
\end_inset 


\begin_inset LatexCommand \index{\symbol{'76}\symbol{'76}\symbol{'76}}

\end_inset 


\series default 
 is the logical
\begin_inset LatexCommand \index{logical shift to the right}

\end_inset 

 / unsigned shift to the right
\begin_inset LatexCommand \index{unsigned shift to the right}

\end_inset 


\begin_inset Foot
collapsed true

\layout Standard

The sign bit is pushed to the right and replaced with zero.
\end_inset 

.
\layout Standard

In all shift operators, the count is on the right.
 i.e.
 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{x
\backslash 
symbol{62}
\backslash 
symbol{62}2}
\end_inset 

 is equivalent to 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{x/4}
\end_inset 

 and 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{x
\backslash 
symbol{60}
\backslash 
symbol{60}2}
\end_inset 

 is 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{x*4}
\end_inset 


\layout Subsubsection

Special behavior
\layout Itemize


\series bold 
break
\series default 
 can (but should not) be used to exit from a function or the script.
\layout Itemize

In case its arguments have different types, + now tries very hard to do
 something smart, i.e.
 a string concatenation, then an integer addition.
 It prints a warning, though, because such automatic conversion is dangerous.
\begin_deeper 
\layout Itemize

If one of its argument is undefined, + returns the other one.
\layout Itemize

If one of its argument is a 
\begin_inset Quotes eld
\end_inset 

pure string
\begin_inset Quotes erd
\end_inset 

, the other argument is converted to a string, if necessary, and the result
 is a 
\begin_inset Quotes eld
\end_inset 

pure string
\begin_inset Quotes erd
\end_inset 

.
 
\begin_inset Quotes eld
\end_inset 

Impure string
\begin_inset Quotes erd
\end_inset 

 are converted to pure string 
\emph on 
without escape sequence interpretation
\emph default 
.
 i.e.
 
\series bold 
"AB
\backslash 
n"+'de'
\series default 
 gives 
\series bold 
'AB
\backslash 

\backslash 
nde'
\series default 
, i.e.
 
\begin_inset Quotes eld
\end_inset 

AB
\begin_inset Quotes erd
\end_inset 

, a backslash, then 
\begin_inset Quotes eld
\end_inset 

nde
\begin_inset Quotes erd
\end_inset 

.
\layout Itemize

If one of its argument is an 
\begin_inset Quotes eld
\end_inset 

impure string
\begin_inset Quotes erd
\end_inset 

, the second argument is converted to string if necessary and the result
 is an 
\begin_inset Quotes eld
\end_inset 

impure string
\begin_inset Quotes erd
\end_inset 

.
 i.e.
 
\series bold 
"ABC"+2
\series default 
 gives 
\series bold 
"ABC2".
\layout Itemize

If one of its argument is an integer, the other is converted to integer
 and the result is an integer.
\layout Itemize

In any other case, NULL is returned.
\end_deeper 
\layout Itemize

The 
\begin_inset Quotes eld
\end_inset 

magical strings
\begin_inset Quotes erd
\end_inset 

 from NASL1 have been removed.
 In NASL1, adding a string to an integer might give an integer if the string
 contained only digits.
\layout Itemize

The minus operator follows the same type conversion rules as plus.
\layout Itemize

Using unitialized variables is 
\series bold 
bad
\series default 
.
 However, to ensure that old scripts still work, the 
\series bold 
NULL
\series default 
 undefined value will be into 
\series bold 
0
\series default 
 or 
\series bold 

\begin_inset Quotes eld
\end_inset 


\begin_inset Quotes erd
\end_inset 


\series default 
 according to the context (integer or string).
 That's why you have to use 
\series bold 
isnull
\series default 
 to test if a variable is undefined.
 See 
\begin_inset Quotes eld
\end_inset 

warnings about the NULL value
\begin_inset Quotes erd
\end_inset 

 in 
\begin_inset LatexCommand \ref{par:Warning-about-NULL}

\end_inset 

.
\layout Subsection

Precedence
\layout Standard

From the higher priority to the lower:
\layout Standard


\begin_inset  Tabular
<lyxtabular version="3" rows="15" columns="2">
<features>
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Operators
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Associativity
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{++}
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'55}
\backslash 
symbol{'55}}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

None
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{**}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Right
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{126}}
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{-}
\end_inset 

(unary minus)
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Left
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{!}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Left
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{*}
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{/}
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
%}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Left
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{+ -}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Left
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'74}
\backslash 
symbol{'74}}
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'76}
\backslash 
symbol{'76}}
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'76}
\backslash 
symbol{'76}
\backslash 
symbol{'76}} 
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Left
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'46}}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Left
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
^}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Left
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{|}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Left
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{ 
\backslash 
symbol{60} 
\backslash 
symbol{60}= }
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{ 
\backslash 
symbol{62} 
\backslash 
symbol{62}= }
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{ == != }
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{ 
\backslash 
symbol{60} 
\backslash 
symbol{62} }
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{ =
\backslash 
symbol{126} 
\backslash 
texttt{!
\backslash 
symbol{126}} }
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{ 
\backslash 
symbol{62}!
\backslash 
symbol{60} 
\backslash 
symbol{62}
\backslash 
symbol{60}}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

None
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'46}
\backslash 
symbol{'46}}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Left
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{||}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Left
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{= += -= *= /= 
\backslash 
%=}
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'74}
\backslash 
symbol{'74}=}
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'76}
\backslash 
symbol{'76}=}
\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{
\backslash 
symbol{'76}
\backslash 
symbol{'76}
\backslash 
symbol{'76}=}
\end_inset 


\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Right
\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\layout Subsection

Loops and control flow
\layout Subsubsection

Operators
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{for}
\end_inset 


\begin_inset LatexCommand \index{for}

\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{(expr1; cond; expr2) block;}
\end_inset 

 is similar to the C operator and
\series bold 
 
\series default 
is equivalent to 
\newline 

\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{expr1; while(cond) block; expr2;}
\end_inset 


\newline 

\series default 
A classical construction to count from 1 to 10 is:
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{for(i=1;i<=10;i++) display(i,'
\backslash 
{
\backslash 
symbol{92}n');}
\end_inset 


\layout Itemize


\begin_inset ERT
status Open

\layout Standard

\backslash 
texttt{foreach}
\end_inset 

 
\begin_inset LatexCommand \index{foreach}

\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{var (array) block;}
\end_inset 

 iterates all elements in an array.
 Note that 
\emph on 
var
\emph default 
 iterates through the 
\emph on 
values
\emph default 
 stored in the array, not the 
\emph on 
indexes
\emph default 
.
 If you want that, just use: 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{foreach var (keys(array)) block;}
\end_inset 


\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{while}
\end_inset 


\begin_inset LatexCommand \index{while}

\end_inset 


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{(cond) block;}
\end_inset 

 executes the block as long as the condition is TRUE.
 If the condition is FALSE, the block is never executed.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{repeat}
\end_inset 


\begin_inset LatexCommand \index{repeat}

\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{block; until}
\end_inset 


\begin_inset LatexCommand \index{until}

\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{(cond);}
\end_inset 

 executes the blocks as long as the condition is TRUE.
 The block is executed at least once.
\layout Itemize


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{break}
\end_inset 


\begin_inset LatexCommand \index{break}

\end_inset 

 breaks the current loop and jumps at its exit.
\newline 
If you are not inside a loop, the behavior is undefined
\begin_inset Foot
collapsed true

\layout Standard

Currently, it exits from the current function or the script.
 But you should not rely upon this behavior.
\end_inset 

.
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{return}
\end_inset 


\begin_inset LatexCommand \index{return}

\end_inset 


\series default 
 returns a value from the current function.
\layout Subsubsection

Special behavior
\layout Subsection

Declarations
\layout Subsubsection

Variable declarations
\layout Standard

NASL1 had only global variables.
 NASL2 uses global and local variables.
 Local variables are created in a function and stop existing as soon as
 the function returns.
 When the interpretor looks for a variable, it first searches in the current
 function context, then in the calling context (if any), etc., until it reaches
 the top level context that contains the global variables.
\layout Standard

Normally, you do not need to declare a variable: either it exists, because
 you already used it in this context, or because a calling function used
 it, or it will be created in the current context.
 However, this may be dangerous in some cases:
\layout Enumerate

if you want to write into a 
\emph on 
global
\emph default 
 variable from within a function and cannot be sure that the variable was
 created first in the top level context, or created as a local variable
 in a calling function context.
\layout Enumerate

if you want to be sure that you are creating a brand new 
\emph on 
local
\emph default 
 variable and not overwriting a global variable with the same name.
\layout Standard

So you can explicitly declare a variable:
\layout Itemize


\series bold 

\begin_inset ERT
status Open

\layout Standard

\backslash 
texttt{local
\backslash 
_var var;}
\end_inset 


\begin_inset LatexCommand \index{local\_var}

\end_inset 


\series default 
 
\layout Itemize


\series bold 

\begin_inset ERT
status Open

\layout Standard

\backslash 
texttt{global
\backslash 
_var var;}
\end_inset 


\begin_inset LatexCommand \index{global\_var}

\end_inset 


\series default 
 
\layout Standard

If the variable already exists in the specified context, you will get an
 error message, but this will work!
\layout Subsubsection

Function declarations
\layout Itemize


\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{function}
\end_inset 


\begin_inset LatexCommand \index{function}

\end_inset 

 
\begin_inset ERT
status Collapsed

\layout Standard
name (argname1, argname2) { block; }
\end_inset 


\layout Standard

Note that the argument list may be empty, but if it is not, user-defined
 function parameters must be named.
\layout Subsection

An example
\layout LyX-Code

function fact(x)
\layout LyX-Code

{
\layout LyX-Code

  local_var i, f;
\layout LyX-Code

  f = 1;
\layout LyX-Code

  for (i = 1; i <= n; i ++) f *= i;
\layout LyX-Code

  return f;
\layout LyX-Code

}
\layout LyX-Code

display("3 ! = ", fact(x: 3), "
\backslash 
n");
\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
newpage
\end_inset 


\layout Section

The NASL2 library
\layout Subsection

Predefined constants
\layout Standard

These constants are actually variables, i.e.
 you can modify their value in a script.
 If you really want to shoot you in the foot, that is...
\layout Itemize

Booleans constants
\begin_deeper 
\layout Itemize


\series bold 
FALSE
\begin_inset LatexCommand \index{FALSE}

\end_inset 


\series default 
 = 0
\layout Itemize


\series bold 
TRUE
\begin_inset LatexCommand \index{TRUE}

\end_inset 


\series default 
 = 1
\end_deeper 
\layout Itemize

Plugin categories
\begin_inset LatexCommand \label{ite:ACT_xxx}

\end_inset 


\begin_deeper 
\layout Itemize


\series bold 
ACT_INIT
\begin_inset LatexCommand \index{ACT\_INIT}

\end_inset 


\series default 
: the plugin just sets a few KB items (kinds of global variables for all
 plugins).
\layout Itemize


\series bold 
ACT_SCANNER
\begin_inset LatexCommand \index{ACT\_SCANNER}

\end_inset 


\series default 
: the plugin is a port scanner or something like it (e.g.
 ping).
\layout Itemize


\series bold 
ACT_SETTINGS
\begin_inset LatexCommand \index{ACT\_SETTINGS}

\end_inset 


\series default 
: just like ACT_INIT, but run after the scanners, once we are sure that
 the host is alive (for performance).
\layout Itemize


\series bold 
ACT_GATHER_INFO
\begin_inset LatexCommand \index{ACT\_GATHER\_INFO}

\end_inset 


\series default 
: the plugin identifies services, gather data, parses banners, etc.
\layout Itemize


\series bold 
ACT_ATTACK
\begin_inset LatexCommand \index{ACT\_ATTACK}

\end_inset 


\series default 
: the plugin launches a soft attack, e.g.
 a web directory traversal.
\layout Itemize


\series bold 
ACT_MIXED_ATTACK
\begin_inset LatexCommand \index{ACT\_MIXED\_ATTACK}

\end_inset 


\series default 
: the plugin launches an attach that might have dangerous side effects (crashing
 the service most of the time).
\layout Itemize


\series bold 
ACT_DESTRUCTIVE_ATTACK
\begin_inset LatexCommand \index{ACT\_DESTRUCTIVE\_ATTACK}

\end_inset 


\series default 
: the plugin tries to destroy data
\begin_inset Foot
collapsed true

\layout Standard

By the way, there is only 
\emph on 
one
\emph default 
 plugin that really tries to destroy data.
 This is 
\emph on 
http_methods.nasl
\end_inset 

 or launch some dangerous attack (e.g.
 testing a buffer overflow is likely to crash a vulnerable service).
\layout Itemize


\series bold 
ACT_DENIAL
\begin_inset LatexCommand \index{ACT\_DENIAL}

\end_inset 


\series default 
: the plugin tries to crash a service.
\layout Itemize


\series bold 
ACT_KILL_HOST
\begin_inset LatexCommand \index{ACT\_KILL\_HOST}

\end_inset 


\series default 
: the plugin tries to crash the target host or disable it (e.g.
 saturate the CPU, kill some vital service...).
\end_deeper 
\layout Itemize

Network constants
\begin_deeper 
\layout Itemize

Nessus 
\begin_inset Quotes eld
\end_inset 

encapsulation
\begin_inset Quotes erd
\end_inset 


\begin_inset LatexCommand \label{ite:ENCAPS}

\end_inset 


\begin_deeper 
\layout Itemize


\series bold 
ENCAPS_IP
\series default 

\begin_inset LatexCommand \index{ENCAPS\_IP}

\end_inset 

 = 1; this is the 
\begin_inset Quotes eld
\end_inset 

transport
\begin_inset Quotes erd
\end_inset 

 value for a pure TCP socket.
\layout Itemize


\series bold 
ENCAPS_SSLv23
\series default 

\begin_inset LatexCommand \index{ENCAPS\_SSLv23}

\end_inset 

 = 2; this is the 
\begin_inset Quotes eld
\end_inset 

transport
\begin_inset Quotes erd
\end_inset 

 value for a SSL connection in compatibility mode.
 Note that the 
\series bold 
find_service
\begin_inset LatexCommand \index{find\_service}

\end_inset 


\series default 
 plugin will never declare a port with this 
\begin_inset Quotes eld
\end_inset 

encapsulation
\begin_inset Quotes erd
\end_inset 

, but you may use it in a script.
\layout Itemize


\series bold 
ENCAPS_SSLv2
\begin_inset LatexCommand \index{ENCAPS\_SSLv2}

\end_inset 

 
\series default 
= 3.
 The old SSL version which only supports server side certificates.
\layout Itemize


\series bold 
ENCAPS_SSLv3
\begin_inset LatexCommand \index{ENCAPS\_SSLv3}

\end_inset 


\series default 
 = 4.
 The new SSL version: it supports server and client side certificates, more
 ciphers, and fixes a few security holes.
\layout Itemize


\series bold 
ENCAPS_TLSv1
\begin_inset LatexCommand \index{ENCAPS\_TLSv1}

\end_inset 


\series default 
 = 5; TLSv1 is defined RFC 2246.
 Some people call it 
\begin_inset Quotes eld
\end_inset 

SSL v3.1
\begin_inset Quotes erd
\end_inset 

.
\end_deeper 
\layout Itemize

Sockets options
\begin_inset LatexCommand \label{ite:Sockets-options}

\end_inset 


\begin_deeper 
\layout Itemize


\series bold 
MSG_OOB
\series default 

\begin_inset LatexCommand \index{MSG\_OOB}

\end_inset 

, a socket option used to send 
\begin_inset Quotes eld
\end_inset 

out of band data
\begin_inset Quotes erd
\end_inset 

.
\end_deeper 
\layout Itemize

Raw sockets
\begin_deeper 
\layout Itemize


\series bold 
IPPROTO_ICMP
\begin_inset LatexCommand \index{IPPROTO\_ICMP}

\end_inset 


\series default 
 as defined in the system C include files.
\layout Itemize


\series bold 
IPPROTO_IGMP
\begin_inset LatexCommand \index{IPPROTO\_IGMP}

\end_inset 


\layout Itemize


\series bold 
IPPROTO_IP
\begin_inset LatexCommand \index{IPPROTO\_IP}

\end_inset 


\layout Itemize


\series bold 
IPPROTO_TCP
\begin_inset LatexCommand \index{IPPROTO\_TCP}

\end_inset 


\layout Itemize


\series bold 
IPPROTO_UDP
\begin_inset LatexCommand \index{IPPROTO\_UDP}

\end_inset 


\layout Itemize


\series bold 
pcap_timeout
\begin_inset LatexCommand \index{pcap\_timeout}

\end_inset 


\series default 
 = 5
\layout Itemize


\series bold 
TH_ACK
\begin_inset LatexCommand \index{TH\_ACK}

\end_inset 


\series default 
 = 0x10.
 This TCP flag indicates that the packet contains a valid acknowledgment.
\layout Itemize


\series bold 
TH_FIN
\begin_inset LatexCommand \index{TH\_FIN}

\end_inset 


\series default 
 = 0x01.
 This TCP flag indicates that the packet negociates the end of the session.
\layout Itemize


\series bold 
TH_PUSH
\begin_inset LatexCommand \index{TH\_PUSH}

\end_inset 


\series default 
 = 0x08.
\layout Itemize


\series bold 
TH_RST
\begin_inset LatexCommand \index{TH\_RST}

\end_inset 


\series default 
 = 0x04.
 This TCP flag indicates that the connection was refused or 
\begin_inset Quotes eld
\end_inset 

reset by peer
\begin_inset Quotes erd
\end_inset 

.
\layout Itemize


\series bold 
TH_SYN
\begin_inset LatexCommand \index{TH\_SYN}

\end_inset 


\series default 
 = 0x02.
 This belong to the initial handshake (connection opening).
\layout Itemize


\series bold 
TH_URG
\begin_inset LatexCommand \index{TH\_URG}

\end_inset 


\series default 
 = 0x20.
 This TCP flag indicates that the packet contains urgent data.
\end_deeper 
\end_deeper 
\layout Itemize

Miscellaneous constants 
\begin_deeper 
\layout Itemize


\series bold 
NULL
\series default 

\begin_inset LatexCommand \index{NULL}

\end_inset 

 is the undefined value.
\end_deeper 
\layout Subsection

Built-in functions 
\layout Standard

Internal built-in functions can have unnamed and named arguments.
 Some use both types.
\layout Subsubsection

Knowledge base functions
\layout Standard

This KB is used for inter-plugin communication.
\layout Itemize


\series bold 
set_kb_item
\begin_inset LatexCommand \index{set\_kb\_item}

\end_inset 


\series default 
 creates a new entry in the KB.
\newline 
It takes two named string arguments: 
\series bold 
name
\series default 
 and 
\series bold 
value
\series default 
.
\newline 
Entering an item several times creates a list.
\layout Itemize


\series bold 
get_kb_item
\begin_inset LatexCommand \index{get\_kb\_item}

\end_inset 


\series default 
 retrieves an entry from the KB.
\newline 
It takes one unnamed string argument (the 
\series bold 
name
\series default 
 of the KB item).
\newline 
If the item is a list, the plugin will fork and each child process will
 use a different value.
 Nessus remebers which child got which value: reading the same item a second
 time will not fork again!
\newline 
You should not call this function when some connections are open if you
 do not want to see several processes fighting to read or write on the same
 socket.
\layout Itemize


\series bold 
get_kb_list
\begin_inset LatexCommand \index{get\_kb\_list}

\end_inset 

 
\series default 
retrieves multiple entrie from the KB.
 It takes one unnamed string argument which may either designate a literal
 KB entry name, or a mask.
 The returned value is a 
\begin_inset Quotes eld
\end_inset 

hash
\begin_inset Quotes erd
\end_inset 

, i.e.
 an array with potentially duplicated indexes; because of this, you need
 to convert it with 
\series bold 
make_list
\series default 
() or use 
\series bold 
foreach
\series default 
 to access each element (the 
\series bold 
make_array
\series default 
 function allows you to create such hashes).
\layout LyX-Code

# Retrieves the list of all the web servers
\layout LyX-Code

webservers = get_kb_list("Services/www");
\layout LyX-Code

# Retrieves the list of all the services
\layout LyX-Code

services = get_kb_list("Services/*");
\layout LyX-Code

# Retrieves the whole KB
\layout LyX-Code

services = get_kb_list("*");
\layout Subsubsection

Report functions
\layout Standard

Those functions send back information to the Nessus daemon.
\layout Itemize


\series bold 
scanner_status
\begin_inset LatexCommand \index{scanner\_status}

\end_inset 


\series default 
 reports the port scan progress (if the plugin is a port scanner!).
\newline 
It takes two named integer arguments: 
\begin_deeper 
\layout Itemize


\series bold 
current
\series default 
, the number of ports already scanned,
\layout Itemize


\series bold 
total
\series default 
, the full number of ports to be scanned.
\end_deeper 
\layout Itemize


\series bold 
security_note
\begin_inset LatexCommand \index{security\_note}

\end_inset 


\series default 
 reports a miscellaneous information.
\newline 
It either takes an unnamed integer argument (the port number), or a some
 of those named arguments:
\begin_deeper 
\layout Itemize


\series bold 
data
\series default 
 is the text report (the 
\begin_inset Quotes eld
\end_inset 

description
\begin_inset Quotes erd
\end_inset 

 by default).
\layout Itemize


\series bold 
port
\series default 
 is the TCP or UDP port number of the service (or nothing if the bug concerns
 the whole machine, e.g.
 the IP stack configuration).
\layout Itemize


\series bold 
proto
\series default 
 (or 
\series bold 
protocol
\series default 
) is the protocol (
\series bold 
"tcp"
\series default 
 by default; 
\series bold 
"udp"
\series default 
 is the other value).
\end_deeper 
\layout Itemize


\series bold 
security_hole
\begin_inset LatexCommand \index{security\_hole}

\end_inset 


\series default 
 reports a severe flaw.
\newline 
It either takes an unnamed integer argument (the port number), or a some
 of those named arguments:
\begin_deeper 
\layout Itemize


\series bold 
data
\series default 
 is the text report (the 
\begin_inset Quotes eld
\end_inset 

description
\begin_inset Quotes erd
\end_inset 

 by default).
\layout Itemize


\series bold 
port
\series default 
 is the TCP or UDP port number of the vulnerable service (or nothing if
 the bug concerns the whole machine, e.g.
 the IP stack configuration).
\layout Itemize


\series bold 
proto
\series default 
 (or 
\series bold 
protocol
\series default 
) is the protocol (
\series bold 
"tcp"
\series default 
 by default; 
\series bold 
"udp"
\series default 
 is the other value).
\end_deeper 
\layout Itemize


\series bold 
security_warning
\begin_inset LatexCommand \index{security\_warning}

\end_inset 


\series default 
 reports a mild flaw.
\newline 
It either takes an unnamed integer argument (the port number), or a some
 of those named arguments:
\begin_deeper 
\layout Itemize


\series bold 
data
\series default 
 is the text report (the 
\begin_inset Quotes eld
\end_inset 

description
\begin_inset Quotes erd
\end_inset 

 by default).
\layout Itemize


\series bold 
port
\series default 
 is the TCP or UDP port number of the vulnerable service (or nothing if
 the bug concerns the whole machine, e.g.
 the IP stack configuration).
\layout Itemize


\series bold 
proto
\series default 
 (or 
\series bold 
protocol
\series default 
) is the protocol (
\series bold 
"tcp"
\series default 
 by default; 
\series bold 
"udp"
\series default 
 is the other value).
\end_deeper 
\layout Subsubsection

Description functions
\layout Standard

All those functions but 
\series bold 
script_get_preference 
\series default 
are only used in the 
\begin_inset Quotes eld
\end_inset 

description part
\begin_inset Quotes erd
\end_inset 

 of the plugin, i.e.
 the block that is run when the 
\series bold 
description
\series default 
 variable is 
\series bold 
1
\series default 
.
 They only make sense in the Nessus environment and have no effect when
 the plugin is run with the standalone 
\series bold 
nasl
\series default 
 interpretor.
\layout Itemize


\series bold 
script_add_preference
\begin_inset LatexCommand \index{script\_add\_preference}

\end_inset 


\series default 
 adds an option to the plugin.
 
\newline 
It takes tree named arguments:
\begin_deeper 
\layout Itemize


\series bold 
name
\series default 
 is the option name.
 As it is displayed 
\begin_inset Quotes eld
\end_inset 

as is
\begin_inset Quotes erd
\end_inset 

 in the GUI, it usually ends with 
\begin_inset Quotes eld
\end_inset 

:
\begin_inset Quotes erd
\end_inset 

.
\layout Itemize


\series bold 
type
\series default 
 is the option type.
 It may be:
\begin_deeper 
\layout Itemize


\series bold 
checkbox
\layout Itemize


\series bold 
entry
\layout Itemize


\series bold 
password
\layout Itemize


\series bold 
radio
\end_deeper 
\layout Itemize


\series bold 
value
\series default 
 is the default value (
\begin_inset Quotes eld
\end_inset 

yes
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

no
\begin_inset Quotes erd
\end_inset 

 for checkboxes, a text string for 
\begin_inset Quotes eld
\end_inset 

entries
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

passwords
\begin_inset Quotes erd
\end_inset 

) except for 
\begin_inset Quotes eld
\end_inset 

radios
\begin_inset Quotes erd
\end_inset 

, where it is the list of options (separate the items with 
\begin_inset Quotes eld
\end_inset 

;
\begin_inset Quotes erd
\end_inset 

).
 e.g.
\newline 

\series bold 
script_add_preference(name:"Reverse\SpecialChar ~
traversal", type:"radio", value:"none;Basic;L
ong \SpecialChar ~
URL");
\end_deeper 
\layout Itemize


\series bold 
script_bugtraq_id
\begin_inset LatexCommand \index{script\_bugtraq\_id}

\end_inset 


\series default 
 sets the SecurityFocus 
\begin_inset Quotes eld
\end_inset 

bid
\begin_inset Quotes erd
\end_inset 

.
\newline 
It takes one or several unnamed integer arguments.
\layout Itemize


\series bold 
script_category
\begin_inset LatexCommand \index{script\_category}

\end_inset 


\series default 
 sets the 
\begin_inset Quotes eld
\end_inset 

category
\begin_inset Quotes erd
\end_inset 

 of the plugin.
 
\newline 
Usually, its unnamed integer argument is one of those pre-defined constants
\begin_inset Foot
collapsed true

\layout Standard

Using an integer is definitely not a good idea, as new values may be inserted
 
\bar under 
before
\bar default 
 the one you used.
 Actually, those values are not constants but initialized variables; changing
 their values in your script is a good way to shoot you in the foot.
\end_inset 

 explained 
\begin_inset LatexCommand \vpageref{ite:ACT_xxx}

\end_inset 

:
\begin_deeper 
\layout Itemize


\series bold 
ACT_INIT
\begin_inset LatexCommand \index{ACT\_INIT}

\end_inset 


\layout Itemize


\series bold 
ACT_SCANNER
\begin_inset LatexCommand \index{ACT\_SCANNER}

\end_inset 


\layout Itemize


\series bold 
ACT_SETTINGS
\begin_inset LatexCommand \index{ACT\_SETTINGS}

\end_inset 


\layout Itemize


\series bold 
ACT_GATHER_INFO
\begin_inset LatexCommand \index{ACT\_GATHER\_INFO}

\end_inset 


\layout Itemize


\series bold 
ACT_ATTACK
\begin_inset LatexCommand \index{ACT\_ATTACK}

\end_inset 


\layout Itemize


\series bold 
ACT_MIXED_ATTACK
\begin_inset LatexCommand \index{ACT\_MIXED\_ATTACK}

\end_inset 


\layout Itemize


\series bold 
ACT_DESTRUCTIVE_ATTACK
\begin_inset LatexCommand \index{ACT\_DESTRUCTIVE\_ATTACK}

\end_inset 


\layout Itemize


\series bold 
ACT_DENIAL
\begin_inset LatexCommand \index{ACT\_DENIAL}

\end_inset 


\layout Itemize


\series bold 
ACT_KILL_HOST
\begin_inset LatexCommand \index{ACT\_KILL\_HOST}

\end_inset 


\end_deeper 
\layout Itemize


\series bold 
script_copyright
\begin_inset LatexCommand \index{script\_copyright}

\end_inset 


\series default 
 sets the copyright string of the plugin (usually the author's name).
 
\newline 
It takes an unnamed string argument, or one or several named
\begin_inset Foot
collapsed false

\layout Standard

If you want to use a full sentence like 
\begin_inset Quotes eld
\end_inset 

this plugin was written by Foo Bar
\begin_inset Quotes erd
\end_inset 

 which would be translated in French, 
\begin_inset Quotes eld
\end_inset 

ce plugin a été écrit par Foo Bar
\begin_inset Quotes erd
\end_inset 

.
\end_inset 

 arguments: 
\series bold 
english
\series default 
, 
\series bold 
francais
\series default 
, 
\series bold 
deutsch
\series default 
, 
\series bold 
portuguese
\series default 
.
\layout Itemize


\series bold 
script_cve_id
\begin_inset LatexCommand \index{script\_cve\_id}

\end_inset 


\series default 
 sets the CVE IDs of the flaws tested by the script.
 
\newline 
It takes any number of unnamed string arguments.
 They usually looks like 
\begin_inset Quotes eld
\end_inset 

CVE-2002-042
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

CAN-2003-666
\begin_inset Quotes erd
\end_inset 

.
\layout Itemize


\series bold 
script_dependencie
\begin_inset LatexCommand \index{script\_dependencie}

\end_inset 


\series default 
 sets the lists of scripts that should be run before this one (if 
\begin_inset Quotes eld
\end_inset 

optimize mode
\begin_inset Quotes erd
\end_inset 

 is on).
\newline 
It takes any number of unnamed string arguments.
\layout Itemize


\series bold 
script_dependencies
\begin_inset LatexCommand \index{script\_dependencies}

\end_inset 


\series default 
 is the same function as 
\series bold 
script_dependencie
\series default 
 (too many typos?).
\layout Itemize


\series bold 
script_description
\begin_inset LatexCommand \index{script\_description}

\end_inset 


\series default 
 sets the 
\begin_inset Quotes eld
\end_inset 

description
\begin_inset Quotes erd
\end_inset 

 of the plugin.
 
\newline 
It takes an unnamed string argument, or one or several named arguments:
 
\series bold 
english
\series default 
, 
\series bold 
francais
\series default 
, 
\series bold 
deutsch
\series default 
, 
\series bold 
portuguese
\series default 
.
 If the argument is unnamed, the default language is 
\series bold 
english
\series default 
.

\series bold 
 
\layout Itemize


\series bold 
script_exclude_keys
\begin_inset LatexCommand \index{script\_exclude\_keys}

\end_inset 


\series default 
 sets the list of 
\begin_inset Quotes eld
\end_inset 

KB items
\begin_inset Quotes erd
\end_inset 

 that must 
\emph on 
not
\emph default 
 be set to run this script in 
\begin_inset Quotes eld
\end_inset 

optimize mode
\begin_inset Quotes erd
\end_inset 

.
\newline 
It takes any number of unnamed string arguments.
\layout Itemize


\series bold 
script_family
\begin_inset LatexCommand \index{script\_family}

\end_inset 


\series default 
 sets the 
\begin_inset Quotes eld
\end_inset 

family
\begin_inset Quotes erd
\end_inset 

 of the plugin.
\newline 
It takes an unnamed string argument, or one or several named arguments:
 
\series bold 
english
\series default 
, 
\series bold 
francais
\series default 
, 
\series bold 
deutsch
\series default 
, 
\series bold 
portuguese
\series default 
.
 If the argument is unnamed, the default language is 
\series bold 
english
\series default 
.

\series bold 
 
\series default 

\newline 
There is no standardized family, but you should avoid inventing too many
 new ones.
 Here is a list:
\newline 

\begin_inset  Tabular
<lyxtabular version="3" rows="24" columns="2">
<features>
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

english
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

francais
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Backdoors
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Backdoors
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
CGI abuses
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Abus de CGI
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
CISCO
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

CISCO
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Denial of Service
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Déni de service
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Finger abuses
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Abus de finger
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Firewalls
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Firewalls
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
FTP
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
FTP
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Gain a shell remotely
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Obtenir un shell à distance
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Gain root remotely
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Passer root à distance
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

General
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
General
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Misc.
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Divers
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Netware
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

NIS
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Ports scanners
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Port scanners
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Remote file access
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Accès aux fichiers distants
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

RPC
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

RPC
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Settings
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Configuration
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
SMTP problems
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Problèmes SMTP
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

SNMP
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

SNMP
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Untested
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Untested
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Useless services
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard


\family roman 
\series medium 
\shape up 
\size normal 
\emph off 
\bar no 
\noun off 
\color none
Services inutiles
\end_inset 
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Windows
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

Windows
\end_inset 
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\layout Standard

Windows : User management
\end_inset 
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\layout Standard

\end_inset 
</cell>
</row>
</lyxtabular>

\end_inset 


\layout Itemize


\series bold 
script_get_preference
\begin_inset LatexCommand \index{script\_get\_preference}

\end_inset 


\series default 
 reads an option.
 It takes an unnamed string argument.
\newline 
Note that it might returns an empty string if you are running the script
 from the standalone NASL interpretor.
\layout Itemize


\series bold 
script_id
\begin_inset LatexCommand \index{script\_id}

\end_inset 


\series default 
 sets the script number
\begin_inset Foot
collapsed false

\layout Standard

Which should you use? Well, there is only one rule: two scripts must have
 two different IDs.
 Ff your script is integrated into the Nessus distribution, the maintainer
 will choose an unaffected number.
\end_inset 

.
 It takes an unnamed integer argument.
\layout Itemize


\series bold 
script_name
\begin_inset LatexCommand \index{script\_name}

\end_inset 


\series default 
 sets the 
\begin_inset Quotes eld
\end_inset 

name
\begin_inset Quotes erd
\end_inset 

 of the plugin.
\newline 
It takes an unnamed string argument, or one or several named arguments:
 
\series bold 
english
\series default 
, 
\series bold 
francais
\series default 
, 
\series bold 
deutsch
\series default 
, 
\series bold 
portuguese
\series default 
.
 If the argument is unnamed, the default language is 
\series bold 
english
\series default 
.

\series bold 
 
\layout Itemize


\series bold 
script_require_keys
\begin_inset LatexCommand \index{script\_require\_keys}

\end_inset 


\series default 
 sets the list of 
\begin_inset Quotes eld
\end_inset 

KB items
\begin_inset Quotes erd
\end_inset 

 that must be set to run this script in 
\begin_inset Quotes eld
\end_inset 

optimize mode
\begin_inset Quotes erd
\end_inset 

.
\newline 
It takes any number of unnamed string arguments.
\layout Itemize


\series bold 
script_require_ports
\begin_inset LatexCommand \index{script\_require\_ports}

\end_inset 


\series default 
 sets the list of TCP ports that must be open to run this script in 
\begin_inset Quotes eld
\end_inset 

optimize mode
\begin_inset Quotes erd
\end_inset 

.
\newline 
It takes any number of unnamed integer or string arguments.
 e.g.
 
\series bold 
23
\series default 
 or 
\series bold 
"Services/telnet"
\series default 
.
\layout Itemize


\series bold 
script_require_udp_ports
\begin_inset LatexCommand \index{script\_require\_udp\_ports}

\end_inset 


\series default 
 sets the list of UDP ports that must be open to run this script in 
\begin_inset Quotes eld
\end_inset 

optimize mode
\begin_inset Quotes erd
\end_inset 

.
\newline 
It takes any number of unnamed integer arguments
\begin_inset Foot
collapsed false

\layout Standard


\series bold 
find_service.nes
\series default 
 identifies TCP services and has no equivalent for UDP.
 So do not expect something like 
\begin_inset Quotes eld
\end_inset 

Services/DNS
\begin_inset Quotes erd
\end_inset 

 to returns a value different from 53.
\end_inset 

.
\layout Itemize


\series bold 
script_summary
\begin_inset LatexCommand \index{script\_summary}

\end_inset 


\series default 
 sets the 
\begin_inset Quotes eld
\end_inset 

short description
\begin_inset Quotes erd
\end_inset 

 of the plugin.
 
\newline 
It takes an unnamed string argument, or one or several named arguments:
 
\series bold 
english
\series default 
, 
\series bold 
francais
\series default 
, 
\series bold 
deutsch
\series default 
, 
\series bold 
portuguese
\series default 
.
 If the argument is unnamed, the default language is 
\series bold 
english
\series default 
.

\series bold 
 
\newline 

\series default 
Each of its arguments should be a single line of text.
\layout Itemize


\series bold 
script_timeout
\begin_inset LatexCommand \index{script\_timeout}

\end_inset 


\series default 
 sets the default timeout of the plugin.
 
\newline 
It takes an unnamed integer argument.
 If it is 
\series bold 
(-1)
\series default 
, the timeout is infinite.
\layout Itemize


\series bold 
script_version
\begin_inset LatexCommand \index{script\_version}

\end_inset 


\series default 
 sets the 
\begin_inset Quotes eld
\end_inset 

version
\begin_inset Quotes erd
\end_inset 

 of the plugin.
 
\newline 
It takes an unnamed string argument
\begin_inset Foot
collapsed false

\layout Standard

Usually, it is set to 
\begin_inset Quotes eld
\end_inset 

$Revision
\begin_inset Quotes erd
\end_inset 

 which is updated by CVS
\end_inset 

.
\layout Subsubsection

Network functions
\layout Standard

Note: the 
\begin_inset Quotes eld
\end_inset 

socket
\begin_inset Quotes erd
\end_inset 

 data type used by those functions is in fact an integer.
 However, you should not touch it and it may be turned into an opaque data
 type some day.
 In case of error, all those functions returns a value that can be interpreted
 as FALSE (most of the time NULL).
\layout Itemize


\series bold 
close
\begin_inset LatexCommand \index{close}

\end_inset 


\series default 
 closes the socket given in its only unnamed argument.
\layout Itemize


\series bold 
end_denial
\begin_inset LatexCommand \index{end\_denial}

\end_inset 


\series default 
 takes no argument and returns TRUE if the target host is still alive and
 FALSE if it is dead.
 You must have called 
\series bold 
start_denial
\series default 
 before your test.
\layout Itemize


\series bold 
ftp_get_pasv_port
\begin_inset LatexCommand \index{ftp\_get\_pasv\_port}

\end_inset 


\series default 
 sends the 
\begin_inset Quotes eld
\end_inset 


\series bold 
PASV
\series default 

\begin_inset LatexCommand \index{PASV}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 command on the open socket, parses the returned data and returns the chosen
 
\begin_inset Quotes eld
\end_inset 

passive
\begin_inset Quotes erd
\end_inset 

 port.
\newline 
It takes one named argument: 
\series bold 
socket
\series default 
.
 
\layout Itemize


\series bold 
get_host_name
\begin_inset LatexCommand \index{get\_host\_name}

\end_inset 


\series default 
 takes no argument and returns the target host name.
\layout Itemize


\series bold 
get_host_ip
\begin_inset LatexCommand \index{get\_host\_ip}

\end_inset 


\series default 
 takes no arguments and returns the target IP address.
\layout Itemize


\series bold 
get_host_open_port
\series default 

\begin_inset LatexCommand \index{get\_host\_open\_port}

\end_inset 

 takes no argument and returns an open TCP port on the target host.
\newline 
This function is used by tests that need to speak to the TCP/IP stack but
 not to a specific service.
\layout Itemize


\series bold 
get_port_transport
\begin_inset LatexCommand \index{get\_port\_transport}

\end_inset 


\series default 
 takes an unnamed integer (socket) argument and returns its 
\begin_inset Quotes eld
\end_inset 

encapsulation
\begin_inset Quotes erd
\end_inset 

 (see page 
\begin_inset LatexCommand \pageref{ite:transport}

\end_inset 

).
\layout Itemize


\series bold 
get_port_state
\series default 

\begin_inset LatexCommand \index{get\_port\_state}

\end_inset 

 takes an unnamed integer (TCP port number) and returns TRUE if it is open
 and FALSE otherwise.
\newline 
As some TCP ports may be in an unknown state because they were not scanned,
 the behavior of this function may be modified by the 
\begin_inset Quotes eld
\end_inset 

consider unscanned ports as closed
\begin_inset Quotes erd
\end_inset 

 global option.
 When this option is reset (the default), 
\series bold 
get_port_state
\series default 
 will return TRUE on unknown ports; when it is set, 
\series bold 
get_port_state
\series default 
 will return FALSE.
\layout Itemize


\series bold 
get_tcp_port_state
\begin_inset LatexCommand \index{get\_tcp\_port\_state}

\end_inset 


\series default 
 is a synonym for 
\series bold 
get_port_state
\series default 
.
\layout Itemize


\series bold 
get_udp_port_state
\series default 

\begin_inset LatexCommand \index{get\_udp\_port\_state}

\end_inset 

 returns TRUE if the UDP port is open, FALSE otherwise (see 
\series bold 
get_port_state
\series default 
 for comments).
 Note that UDP port scanning may be unreliable.
\layout Itemize


\series bold 
islocalhost
\series default 
 takes no argument and returns TRUE if the target host is the same as the
 attacking host, FALSE otherwise.
\layout Itemize


\series bold 
islocalnet
\series default 
 takes no argument and returns TRUE if the target host is on the same network
 as the attacking host, FALSE otherwise.
\layout Itemize


\series bold 
open_priv_sock_tcp
\begin_inset LatexCommand \index{open\_priv\_sock\_tcp}

\end_inset 


\series default 
 opens a 
\begin_inset Quotes eld
\end_inset 

privileged
\begin_inset Quotes erd
\end_inset 

 TCP socket to the target host.
\newline 
It takes two named integer arguments:
\begin_deeper 
\layout Itemize


\series bold 
dport
\series default 
 is the destination port,
\layout Itemize


\series bold 
sport
\series default 
 is the source port, which may be inferior to 1024.
\end_deeper 
\layout Itemize


\series bold 
open_priv_sock_udp
\begin_inset LatexCommand \index{open\_priv\_sock\_tcp}

\end_inset 


\series default 
 opens a 
\begin_inset Quotes eld
\end_inset 

privileged
\begin_inset Quotes erd
\end_inset 

 UDP socket to the target host.
\newline 
It takes two named integer arguments:
\begin_deeper 
\layout Itemize


\series bold 
dport
\series default 
 is the destination port,
\layout Itemize


\series bold 
sport
\series default 
 is the source port, which may be inferior to 1024.
\end_deeper 
\layout Itemize


\series bold 
open_sock_tcp
\series default 

\begin_inset LatexCommand \index{open\_sock\_tcp}

\end_inset 

 opens a TCP socket to the target host
\begin_inset Foot
collapsed false

\layout Standard

In NASL, there is no way you can open connections to some specific host.
 This way, a NASL script cannot be trojaned.
\end_inset 

.
\newline 
It takes an unnamed integer argument (the port number) and two optional
 named integer arguments:
\begin_deeper 
\layout Itemize


\series bold 
timeout
\series default 
, if you want to change it from the default,
\layout Itemize


\series bold 
transport
\series default 
, to force Nessus a specific 
\begin_inset Quotes eld
\end_inset 

transport
\begin_inset Quotes erd
\end_inset 

.
 Its main use is to disable Nessus 
\begin_inset Quotes eld
\end_inset 

auto SSL discovery
\begin_inset LatexCommand \index{auto SSL discovery}

\end_inset 


\begin_inset Quotes erd
\end_inset 

 feature on dynamic ports (e.g.
 FTP data connections).
\newline 
The possible values for 
\series bold 
transport
\series default 
 were explained in §
\begin_inset LatexCommand \vref{ite:ENCAPS}

\end_inset 

.
 They are:
\begin_inset LatexCommand \label{ite:transport}

\end_inset 


\begin_deeper 
\layout Itemize


\series bold 
ENCAPS_IP
\layout Itemize


\series bold 
ENCAPS_SSLv23
\layout Itemize


\series bold 
ENCAPS_SSLv2
\layout Itemize


\series bold 
ENCAPS_SSLv3
\layout Itemize


\series bold 
ENCAPS_TLSv1
\end_deeper 
\end_deeper 
\layout Itemize


\series bold 
open_sock_udp
\begin_inset LatexCommand \index{open\_sock\_udp}

\end_inset 


\series default 
 opens a UDP socket to the target host.
\newline 
It takes an unnamed integer argument, the port number.
\layout Itemize


\series bold 
recv
\begin_inset LatexCommand \index{recv}

\end_inset 


\series default 
 receives data from a TCP or UDP socket.
\newline 
For a UDP socket, if it cannot read data, NASL will suppose that the last
 sent datagram was lost and will sent it again a couple of time.
\newline 
It takes at least two named arguments:
\begin_deeper 
\layout Itemize


\series bold 
socket 
\series default 
which was returned by 
\series bold 
open_sock_tcp
\series default 
, for example,
\layout Itemize

and 
\series bold 
length
\series default 
, the number of bytes that you want to read at most.
\newline 

\series bold 
recv
\series default 
 may return before 
\series bold 
length
\series default 
 bytes have been read: as soon as at least one byte has been received, the
 timeout is lowered to 1 second.
 If no data is received during that time, the function returns the already
 read data; otherwise, if the full initial timeout has not been reached,
 a 1 second timeout is re-armed and the script tries to receive more data
 from the socket.
 This special feature was implemented to get a good compromise between reliabili
ty and speed when Nessus talks to unknown or complex protocols.
 Two other optional named integer arguments can twist this behavior:
\layout Itemize


\series bold 
min
\series default 
 is the minimum number of data that must be read in case the 
\begin_inset Quotes eld
\end_inset 

magic read function
\begin_inset Quotes erd
\end_inset 

 is activated and the timeout is lowered.
 By default this is 
\series bold 
0
\series default 
.
\layout Itemize


\series bold 
timeout
\series default 
 can be changed from the default.

\series bold 
 
\end_deeper 
\layout Itemize


\series bold 
recv_line
\series default 

\begin_inset LatexCommand \index{recv\_line}

\end_inset 

 receives data from 
\series bold 
socket
\series default 
 and stops as soon as a 
\emph on 
line feed
\emph default 
 character has been read, 
\series bold 
length
\series default 
 bytes have been read or the default timeout has been triggered.
\layout Itemize


\series bold 
send
\begin_inset LatexCommand \index{send}

\end_inset 


\series default 
 sends data on a socket.
\newline 
Its named arguments are:
\begin_deeper 
\layout Itemize


\series bold 
socket
\series default 
,
\layout Itemize


\series bold 
data
\series default 
, the data block.
 A string is expected here (pure or impure, this does not matter).
\layout Itemize


\series bold 
length
\series default 
 is optional and will be the full 
\series bold 
data
\series default 
 length if not set,
\layout Itemize


\series bold 
option
\series default 
 is the flags for the send() system call.
 You should not use a raw numeric value here; the only interesting constant
 is 
\series bold 
MSG_OOB
\series default 
.
 See §
\begin_inset LatexCommand \vref{ite:Sockets-options}

\end_inset 

.
\end_deeper 
\layout Itemize


\series bold 
scanner_add_port
\begin_inset LatexCommand \index{scanner\_add\_port}

\end_inset 


\series default 
 declares an open port to nessusd.
\newline 
It takes two named arguments and returns no value:
\begin_deeper 
\layout Itemize


\series bold 
port
\series default 
 is the port number,
\layout Itemize


\series bold 
proto
\series default 
 is 
\series bold 
"tcp"
\series default 
 or 
\series bold 
"udp"
\series default 
.
\end_deeper 
\layout Itemize


\series bold 
scanner_get_port
\begin_inset LatexCommand \index{scanner\_get\_port}

\end_inset 


\series default 
 walks through the list of open ports.
 It takes one unnamed integer argument, an index, and returns a port number
 or 
\series bold 
0
\series default 
 when the end of the list if reached.
 A good way to use it is:
\layout LyX-Code

i = 0;
\layout LyX-Code

while (port = scanner_get_port(i++))
\layout LyX-Code

{
\layout LyX-Code

  do_something_with_port;
\layout LyX-Code

}
\layout Itemize


\series bold 
tcp_ping
\series default 

\begin_inset LatexCommand \index{tcp\_ping}

\end_inset 

 launches a 
\begin_inset Quotes eld
\end_inset 

TCP ping
\begin_inset Quotes erd
\end_inset 

 against the target host, i.e.
 tries to open a TCP connection and sees if anything comes back (SYNACK
 or RST).
 The named integer argument 
\series bold 
port
\series default 
 is not compulsory: if it is not set, 
\series bold 
tcp_ping
\series default 
 will use an internal list of common ports
\begin_inset Foot
collapsed false

\layout Standard

22 (SSH), 25 (SMTP), 53 (DNS), 110 (POP3), 113 (IDENT), 443 (HTTPS), 993
 (IMAPS), 8080 (alt HTTP), 65534.
\end_inset 

.
\layout Itemize


\series bold 
telnet_init
\series default 
 performs a telnet negotiation on an open socket 
\begin_inset LatexCommand \cite{RFC854}

\end_inset 

.
 This function takes one unnamed argument (the open socket) and returns
 the data read (more or less the telnet dialog plus the banner).
\layout Itemize


\series bold 
this_host
\begin_inset LatexCommand \index{this\_host}

\end_inset 


\series default 
 takes no argument and returns the IP address of the current (attacking)
 machine.
\layout Itemize


\series bold 
this_host_name
\begin_inset LatexCommand \index{this\_host\_name}

\end_inset 


\series default 
 takes no argument and returns the host name of the current (attacking)
 machine.
\layout Itemize


\series bold 
ftp_log_in
\begin_inset LatexCommand \index{ftp\_log\_in}

\end_inset 


\series default 
 performs a FTP identification / authentication on an open socket.
 It returns TRUE if it could login successfully, FALSE otherwise (e.g.
 wrong password, or any network problem).
 It takes three named arguments:
\begin_deeper 
\layout Itemize


\series bold 
user
\series default 
 is the user name (it has 
\emph on 
no
\emph default 
 default value like 
\begin_inset Quotes eld
\end_inset 

anonymous
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

ftp
\begin_inset Quotes erd
\end_inset 

),
\layout Itemize


\series bold 
pass
\series default 
 is the password (again, no default value like the user e-mail address),
\layout Itemize

and 
\series bold 
socket
\series default 
.
\end_deeper 
\layout Itemize


\series bold 
start_denial
\begin_inset LatexCommand \index{start\_denial}

\end_inset 


\series default 
 initializes some internal data structure for 
\series bold 
end_denial
\series default 
.
 It takes no argument and returns no value.
\layout Subsubsection

String manipulation functions
\layout Itemize


\series bold 
chomp
\series default 

\begin_inset LatexCommand \index{chomp}

\end_inset 

 takes an unnamed string argument and removes any spaces at the end of it.
 
\begin_inset Quotes eld
\end_inset 

Space
\begin_inset Quotes erd
\end_inset 

 means white space, vertical or horizontal tabulation, carriage return or
 line feed.
\layout Itemize


\series bold 
crap
\series default 

\begin_inset LatexCommand \index{crap}

\end_inset 

 returns a buffer of required length.
 This function is mainly used in buffer overflow tests.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
length
\series default 
, the size of the wanted buffer,
\layout Itemize


\series bold 
data
\series default 
, the pattern that will be repeated to fill the buffer.
 By default 
\series bold 
'X'
\series default 
.
\end_deeper 
\layout Itemize


\series bold 
display
\begin_inset LatexCommand \index{display}

\end_inset 


\series default 
 takes an unlimited number of arguments, calls 
\series bold 
string
\series default 
 on them, then displays them.
 
\newline 
It returns the number of output characters.
\newline 
Unprintable characters are replaced with 
\begin_inset Quotes eld
\end_inset 


\series bold 
.
\series default 

\begin_inset Quotes erd
\end_inset 

.
\layout Itemize


\series bold 
egrep
\series default 

\begin_inset LatexCommand \index{egrep"}

\end_inset 

 looks for a pattern in a string, line by line and returns the concatenation
 of all lines that match.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
icase
\series default 
,
\layout Itemize


\series bold 
pattern
\series default 
,
\layout Itemize


\series bold 
string
\series default 
.
\end_deeper 
\layout Itemize


\series bold 
ereg
\series default 

\begin_inset LatexCommand \index{ereg}

\end_inset 

 matches a string against a regular expression.
 It returns the first found pattern.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
string
\series default 
,
\layout Itemize


\series bold 
pattern
\series default 
 (standard extended POSIX regex, no PCRE for the moment!),
\layout Itemize

and 
\series bold 
icase
\series default 
, which is FALSE by default, and can be set to TRUE for case insensitive
 search.
\end_deeper 
\layout Itemize


\series bold 
ereg_replace
\series default 

\begin_inset LatexCommand \index{ereg\_replace}

\end_inset 

 searches and replaces all the occurrences of a pattern inside a string.
 It returns the modified string, or the original string if the pattern did
 not match.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
string
\series default 
, the original string,
\layout Itemize


\series bold 
pattern
\series default 
, the pattern that should be matched,
\layout Itemize


\series bold 
replace
\series default 
, the replacement, which may contain escape sequences like 
\backslash 

\series bold 
1 
\series default 
to reference found sub-patterns.
 The index is the number of the opening parenthesis, as usual
\begin_inset Foot
collapsed false

\layout Standard

For example, 
\layout Standard


\begin_inset ERT
status Open

\layout Standard

\backslash 
texttt{ereg
\backslash 
_replace(string:'ZABCABD',pattern:'A([ABC]+)D',replace:'
\backslash 
symbol{92}
\backslash 
symbol{92}1') }
\end_inset 


\layout Standard

will return 
\series bold 
'ZBCAB'
\series default 
.
 
\end_inset 

,
\layout Itemize


\series bold 
icase
\series default 
, the case insensitive flag.
\end_deeper 
\layout Itemize


\series bold 
eregmatch
\series default 

\begin_inset LatexCommand \index{eregmatch}

\end_inset 

 searches for a pattern into a string and returns NULL if it did not match
 or an array of all found sub-patterns.
 There is at least one returned pattern, which is the part of the string
 that matched the whole pattern.
 For those used to Perl, the elements of the returned array are equivalent
 to 
\series bold 
$0
\series default 
, 
\series bold 
$1
\series default 
, 
\series bold 
$2
\series default 
...
\begin_inset Foot
collapsed false

\layout Standard

For example,
\layout Standard


\begin_inset ERT
status Open

\layout Standard

\backslash 
texttt{v = eregmatch(string:'XYZ IADAOZOOH',pattern:'([AEIOU]+).*(Z.*H)'); }
\end_inset 


\layout Standard

will set 
\series bold 
v[0]=I'ADA OZOOH'
\series default 
 
\series bold 
v[1]='IA'
\series default 
 
\layout Standard

and 
\series bold 
v[2]='ZOOH'
\series default 
.
\end_inset 

.
 Its argument are
\begin_deeper 
\layout Itemize


\series bold 
icase
\series default 
,
\layout Itemize


\series bold 
pattern
\series default 
,
\layout Itemize


\series bold 
string
\series default 
.
\end_deeper 
\layout Standard

Note that all the regex functions work the same way.
 If you want to match from the beginning / end of your string (or your line,
 in the case of 
\series bold 
egrep
\series default 
), you'll have to use 
\series bold 
^
\series default 
 or 
\series bold 
$
\series default 
.
 If you want to eliminate what's before or after a pattern with 
\series bold 
ereg_replace
\series default 
, you'll have to play with something like 
\series bold 
^.* 
\series default 
or 
\series bold 
.*$ 
\series default 
and 
\series bold 

\backslash 
1
\series default 
.
 
\newline 
You should read your (POSIX) system manual for details on regular expressions.
\layout Itemize


\series bold 
hex
\begin_inset LatexCommand \index{hex}

\end_inset 


\series default 
 converts its unnamed integer argument into the hexadecimal representation.
 It returns a string.
\layout Itemize


\series bold 
hexstr
\begin_inset LatexCommand \index{hexstr}

\end_inset 


\series default 
 takes one unnamed string argument and returns a string made of the hexadecimal
 representation of the ASCII codes of each input character.
 For example, 
\series bold 
hexstr('aA
\backslash 
n')
\series default 
 returns 
\series bold 
'61410a'
\series default 
.
\layout Itemize


\series bold 

\begin_inset LatexCommand \label{ite:insstr}

\end_inset 

insstr
\series default 

\begin_inset LatexCommand \index{insstr}

\end_inset 

 takes three or four unnamed arguments: a first string, a second string,
 a start index and an optional end index .
 Indexes starts at 0.
\newline 
The function replaces the declared slice in the first string by the second
 string, and returns the result.
 For example,
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{insstr('abcdefgh', 'xyz', 3, 5)}
\end_inset 

 
\newline 
returns 
\series bold 
'abcxyzgh'
\series default 
.
\layout Itemize


\series bold 
int
\begin_inset LatexCommand \index{int}

\end_inset 


\series default 
 converts its unnamed argument into an integer.
 If the argument is not a string, it returns 
\series bold 
0
\series default 
.
\layout Itemize


\series bold 
match
\series default 

\begin_inset LatexCommand \index{match"}

\end_inset 

 matches a string against a simple shell-like pattern and returns TRUE or
 FALSE.
 This function is less powerful than 
\series bold 
ereg
\series default 
 but it is quicker and its interface is simple.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
icase
\series default 
 if the match should be case insensitive.
\layout Itemize


\series bold 
string
\series default 
 is the input string.
\layout Itemize


\series bold 
pattern
\series default 
 is the searched pattern.
 The only wildcards are * (for any string, even empty) and 
\series bold 
?
\series default 
 (for any character).
\end_deeper 
\layout Itemize


\series bold 
ord
\series default 

\begin_inset LatexCommand \index{ord}

\end_inset 

 takes one unnamed string argument and returns the (integer) ASCII code
 of the first character of the string.
\layout Itemize


\series bold 
raw_string
\begin_inset LatexCommand \index{raw\_string}

\end_inset 


\series default 
 takes any number of unnamed arguments and returns a 
\begin_inset Quotes eld
\end_inset 

pure
\begin_inset Quotes erd
\end_inset 

 string resulting from these operations:
\begin_deeper 
\layout Itemize


\begin_inset Quotes eld
\end_inset 

Impure
\begin_inset Quotes erd
\end_inset 

 strings are parsed and escaped sequences are interpreted
\begin_inset Foot
collapsed false

\layout Standard

In NASL1, only the first character of the string was kept.
\end_inset 

.
\layout Itemize

Each integer is converted to the corresponding ASCII character
\begin_inset Foot
collapsed false

\layout Standard

And that's where you can enter a null character into a string in NASL!
\end_inset 

.
\layout Itemize

Undefined variables are skipped
\begin_inset Foot
collapsed false

\layout Standard

Old versions of Nessus 1.3 were badly designed and 
\series bold 
string
\series default 
 stopped processing its arguments at the first undefined value.
 Other functions may suffer from this bug; do not hesitate to tell.
\end_inset 

.
\layout Itemize

Arrays are converted to some ASCII representation
\begin_inset Foot
collapsed false

\layout Standard

Which is not necessarily a good idea.
 Maybe we should expand them; the problem is hash elements are not ordered.
\end_inset 

.
\layout Itemize


\begin_inset Quotes eld
\end_inset 

Pure
\begin_inset Quotes erd
\end_inset 

 strings are left as they were
\layout Itemize

And last but not least, the processing stops as soon as RAW_STR_LEN
\begin_inset LatexCommand \index{Raw string maximum length}

\end_inset 

 = 32768 have been entered.
 
\series bold 
string
\series default 
 does not have such a limitation.
\end_deeper 
\layout Itemize


\series bold 
str_replace
\begin_inset LatexCommand \index{str\_replace}

\end_inset 


\series default 
 replaces any occurence of a substring inside a bigger string and returns
 the modified string.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
string
\series default 
 is the original string.
\layout Itemize


\series bold 
find
\series default 
 is the sub-string that is looked for.
\layout Itemize


\series bold 
replace
\series default 
 is the replacement sub-string.
\layout Itemize


\series bold 
count
\series default 
 is optional; if set, 
\series bold 
str_replace
\series default 
 stops after this number of occurences have been replaced and leave the
 rest of the string as it is.
\end_deeper 
\layout Itemize


\series bold 
string
\begin_inset LatexCommand \index{string}

\end_inset 


\series default 
 takes any number of unnamed arguments and returns a 
\begin_inset Quotes eld
\end_inset 

pure
\begin_inset Quotes erd
\end_inset 

 string
\begin_inset Foot
collapsed false

\layout Standard

Note that its size is unlimited
\end_inset 

 resulting from these operations:
\begin_deeper 
\layout Itemize


\begin_inset Quotes eld
\end_inset 

Impure
\begin_inset Quotes erd
\end_inset 

 strings are parsed and escaped sequences are interpreted.
\layout Itemize

Integer are converted to their ASCII representation (in decimal base).
 That's where it is different from 
\series bold 
raw_string
\series default 
.
\layout Itemize

Undefined variables are skipped
\begin_inset Foot
collapsed false

\layout Standard

Old versions of Nessus 1.3 were badly designed and 
\series bold 
string
\series default 
 stopped processing its arguments at the first undefined value.
 Other functions may suffer from this bug; do not hesitate to tell.
\end_inset 

.
\layout Itemize

Arrays are converted to some ASCII representation.
\layout Itemize


\begin_inset Quotes eld
\end_inset 

Pure
\begin_inset Quotes erd
\end_inset 

 strings are left as they were.
\end_deeper 
\layout Itemize


\series bold 
strcat
\begin_inset LatexCommand \index{strcat}

\end_inset 


\series default 
 takes any number of unnamed arguments and returns a 
\begin_inset Quotes eld
\end_inset 

pure
\begin_inset Quotes erd
\end_inset 

 string resulting from these operations:
\begin_deeper 
\layout Itemize

Integer are converted to their ASCII representation (in decimal base).
 
\layout Itemize

Undefined variables are skipped.
\layout Itemize

Arrays are converted to some ASCII representation
\begin_inset Foot
collapsed true

\layout Standard

Which is not necessarily a good idea.
 Maybe we should expand them; the problem is hash elements are not ordered.
\end_inset 

.
\layout Itemize


\begin_inset Quotes eld
\end_inset 

Pure
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

impure
\begin_inset Quotes erd
\end_inset 

 strings are left as they were.
\end_deeper 
\layout Itemize


\series bold 
stridx
\begin_inset LatexCommand \index{stridx}

\end_inset 


\series default 
 takes two or three unnamed arguments, looks for a substring inside a string
 (starting from the optional position) and returns its index (or -1 if not
 found or in case of error).
\begin_deeper 
\layout Itemize

The first argument is the string (the haystack).
\layout Itemize

The second is the substring that is looked for (the needle)
\layout Itemize

The optional third argument is the starting position (by default 
\series bold 
0
\series default 
)
\layout Itemize

Note that the return value is not 
\series bold 
NULL
\series default 
 if the substring was not found but 
\series bold 
-1
\series default 
.
\end_deeper 
\layout Itemize


\series bold 
strstr
\begin_inset LatexCommand \index{strstr}

\end_inset 


\series default 
 takes two unnamed string arguments and searches the first occurrence of
 arg2 into arg1.
 It returns NULL if nothing was found, or the piece of arg2 from the first
 matching character till the end.
 For example 
\series bold 
strstr('zabadz', 'ad')
\series default 
 returns 
\series bold 
'adz'
\series default 
.
\layout Itemize


\series bold 
split
\series default 

\begin_inset LatexCommand \index{split"}

\end_inset 

 splits a string into an array of 
\begin_inset Quotes eld
\end_inset 

lines
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

sub strings
\begin_inset Quotes erd
\end_inset 

.
 It takes an unnamed parameter (the input string) and an optional 
\series bold 
sep
\series default 
 string argument; it returns the array.
 
\newline 
If 
\series bold 
sep
\series default 
 is not set, 
\series bold 
split
\series default 
 cuts the input strings into lines.
 A line is supposed to end with the single character 
\series bold 
LF
\series default 
 or the sequence 
\series bold 
CR LF
\series default 
.
\newline 
Note that the separator (whatever it is) will be included in the sub-strings
 or lines.
\layout Itemize


\series bold 
strlen
\series default 

\begin_inset LatexCommand \index{strlen"}

\end_inset 

 returns the length of the unnamed string argument.
 If the argument is not a string, you get an undefined result
\begin_inset Foot
collapsed false

\layout Standard

Most of the time, the 
\begin_inset Quotes eld
\end_inset 

internal size
\begin_inset Quotes erd
\end_inset 

 of the data, which might be 0 even if it is not true!
\end_inset 

.
\layout Itemize


\series bold 
substr
\series default 

\begin_inset LatexCommand \index{substr"}

\end_inset 

 takes two or three unnamed arguments: a string, a start index (counting
 from 0) and an optional end index (by default, the end).
 It returns the desired substring.
 
\newline 
For example, 
\series bold 
substr('abcde', 2)
\series default 
 returns 
\series bold 
'cde'
\series default 
 and 
\series bold 
substr('abcde', 1, 3)
\series default 
 returns 
\series bold 
'bcd'
\series default 
.
\layout Itemize


\series bold 
tolower
\series default 

\begin_inset LatexCommand \index{tolower}

\end_inset 

 converts its unnamed string argument to lower case.
\layout Itemize


\series bold 
toupper
\series default 

\begin_inset LatexCommand \index{toupper}

\end_inset 

 converts its unnamed string argument to upper case.
\layout Subsubsection

HTTP functions
\layout Itemize


\series bold 
cgibin
\begin_inset LatexCommand \index{cgibin}

\end_inset 


\series default 
 takes no argument and returns the cgi-bin path elements.
 In fact the NASL interpretor forks and each process gets one value.
 This function should be considered as 
\emph on 
deprecated
\series bold 
\emph default 
 
\series default 
and 
\series bold 
cgi_dirs()
\series default 
 should be used instead.
\layout Itemize


\series bold 
http_delete
\begin_inset LatexCommand \index{http\_delete}

\end_inset 


\series default 
 formats an HTTP DELETE request for the server on the port.
 It will automatically handle the HTTP version and the basic or cookie based
 authentication.
 The arguments are 
\series bold 
port
\series default 
 and 
\series bold 
item
\series default 
 (the URL).
 
\series bold 
data
\series default 
 is not compulsory and probably useless in this function.
 It returns a string (the formatted request).
\layout Itemize


\series bold 
http_get
\begin_inset LatexCommand \index{http\_get}

\end_inset 


\series default 
 formats an HTTP GET request for the server on the port.
 It will automatically handle the HTTP version and the basic or cookie based
 authentication.
 The arguments are 
\series bold 
port
\series default 
 and 
\series bold 
item
\series default 
 (the URL).
 
\series bold 
data
\series default 
 is not compulsory and probably useless in this function.
 It returns a string (the formatted request).
\layout Itemize


\series bold 
http_close_socket
\begin_inset LatexCommand \index{http\_close\_socket}

\end_inset 


\series default 
 closes a socket.
 Currently, it is identical to 
\series bold 
close
\series default 
 but this may change in the future.
\layout Itemize


\series bold 
http_head
\begin_inset LatexCommand \index{http\_head}

\end_inset 


\series default 
 formats an HTTP HEAD request for the server on the port.
 It will automatically handle the HTTP version and the basic or cookie based
 authentication.
 The arguments are 
\series bold 
port
\series default 
 and 
\series bold 
item
\series default 
 (the URL).
 
\series bold 
data
\series default 
 is not compulsory and probably useless in this function.
 It returns a string (the formatted request).
\layout Itemize


\series bold 
http_open_socket
\series default 

\begin_inset LatexCommand \index{http\_open\_socket}

\end_inset 

 opens a socket to the given port.
 Currently, this functions is identical to 
\series bold 
open_sock_tcp
\series default 
 but this may change in the future.
\layout Itemize


\series bold 
http_recv_headers
\series default 

\begin_inset LatexCommand \index{http_recv_headers"}

\end_inset 

 reads all HTTP headers on the given socket (unnamed integer argument).
 It stops at the first blank line and returns a string made of all headers,
 starting with the HTTP answer code.
\layout Itemize


\series bold 
http_post
\begin_inset LatexCommand \index{http\_post}

\end_inset 


\series default 
 formats an HTTP POST request for the server on the port.
 It will automatically handle the HTTP version and the basic or cookie based
 authentication.
 The arguments are 
\series bold 
port
\series default 
, 
\series bold 
item
\series default 
 (the URL) and 
\series bold 
data
\series default 
.
 It returns a string (the formatted request).
\layout Itemize


\series bold 
http_put
\begin_inset LatexCommand \index{http\_put}

\end_inset 


\series default 
 formats an HTTP PUT request for the server on the port.
 It will automatically handle the HTTP version and the basic or cookie based
 authentication.
 The arguments are 
\series bold 
port
\series default 
, 
\series bold 
item
\series default 
 (the URL) and 
\series bold 
data
\series default 
.
 It returns a string (the formatted request).
\layout Itemize


\series bold 
is_cgi_installed
\begin_inset LatexCommand \index{is\_cgi\_installed}

\end_inset 


\series default 
 tests if a CGI is found.
 If the path is relative (does not start with a slash), the CGI is search
 into the cgi-bin path.
 This functions returns the port of the web server where it was found (it
 will fork if there are several web servers); this magical behavior allows
 you to write very short plugins.
 For example: 
\newline 

\begin_inset ERT
status Open

\layout Standard

\backslash 
texttt{if (port = cgi
\backslash 
_installed("vuln.cgi")) security
\backslash 
_warning(port);}
\end_inset 


\newline 
The arguments are:
\begin_deeper 
\layout Itemize


\series bold 
item
\series default 
, for the CGI path,
\layout Itemize

and 
\series bold 
port
\series default 
; by default, the function will look on all found web servers (i.e.
 read the KB entry 
\series bold 
Services/www
\series default 
).
\end_deeper 
\layout Subsubsection

Raw IP functions
\layout Standard

All those functions work on blocks of data which are implemented as 
\begin_inset Quotes eld
\end_inset 

pure strings
\begin_inset Quotes erd
\end_inset 

.
 This means that you could change them with the string manipulation functions,
 but this is probably not very easy.
\layout Itemize


\series bold 
dump_ip_packet
\series default 

\begin_inset LatexCommand \index{dump\_ip\_packet}

\end_inset 

 dumps IP datagrams.
 It takes any number of unnamed (string) arguments and does not return anything.
\layout Itemize


\series bold 
dump_tcp_packet
\begin_inset LatexCommand \index{dump\_tcp\_packet}

\end_inset 


\series default 
 dumps the TCP parts of datagrams.
 It takes any number of unnamed arguments.
\layout Itemize


\series bold 
dump_udp_packet
\begin_inset LatexCommand \index{dump\_udp\_packet}

\end_inset 


\series default 
 dumps the UDP parts of datagrams.
 It takes any number of unnamed arguments.
\layout Itemize


\series bold 
forge_icmp_packet
\series default 

\begin_inset LatexCommand \index{forge\_icmp\_packet}

\end_inset 

 fills an IP datagram with ICMP data.
 Note that the 
\series bold 
ip_p
\series default 
 field is not updated.
 It returns the modified IP datagram.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
data
\series default 
 is the payload.
\layout Itemize


\series bold 
icmp_cksum
\series default 
 is the checksum, computed by default.
\layout Itemize


\series bold 
icmp_code
\series default 
 is the ICMP code.
\layout Itemize


\series bold 
icmp_id
\series default 
 is the ICMP ID.
\layout Itemize


\series bold 
icmp_seq
\series default 
 is the ICMP sequence number.
\layout Itemize


\series bold 
icmp_type
\series default 
 is the ICMP type.
\layout Itemize


\series bold 
ip
\series default 
 is the IP datagram that is updated.
\layout Itemize


\series bold 
update_ip_len
\series default 
 is a flag (TRUE by default).
 If set, NASL will recompute the size field of the IP datagram.
\end_deeper 
\layout Itemize


\series bold 
forge_igmp_packet
\series default 

\begin_inset LatexCommand \index{forge\_igmp\_packet}

\end_inset 

 fills an IP datagram with IGMP data.
 Note that the 
\series bold 
ip_p
\series default 
 field is not updated.
 It returns the modified IP datagram.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
code
\series default 
 
\layout Itemize


\series bold 
data
\layout Itemize


\series bold 
group
\layout Itemize


\series bold 
ip
\series default 
 is the IP datagram that is updated.
 Note that the IGMP checksum is automatically computed.
\layout Itemize


\series bold 
type
\layout Itemize


\series bold 
update_ip_len
\series default 
 is a flag (TRUE by default).
 If set, NASL will recompute the size field of the IP datagram.
\end_deeper 
\layout Itemize


\series bold 
forge_ip_packet
\begin_inset LatexCommand \index{forge\_ip\_packet}

\end_inset 


\series default 
 returns an IP datagram inside the block of data.
 The named argument are:
\begin_deeper 
\layout Itemize


\series bold 
data
\series default 
 is the payload.
\layout Itemize


\series bold 
ip_hl
\series default 
 is the IP header length in 32 bits words.
 
\series bold 
5 
\series default 
by default.
\layout Itemize


\series bold 
ip_id
\series default 
 is the datagram ID; by default, it is random.
\layout Itemize


\series bold 
ip_len
\series default 
 is the length of the datagram.
 By default, it is 
\series bold 
20
\series default 
 plus the length of the 
\series bold 
data 
\series default 
field.
\layout Itemize


\series bold 
ip_off
\series default 
 is the fragment offset in 64 bits words.
 By default, 
\series bold 
0
\series default 
.
\layout Itemize


\series bold 
ip_p
\series default 
 is the IP protocol.
 
\series bold 
0 
\series default 
by default.
\layout Itemize


\series bold 
ip_src
\series default 
 is the source address in ASCII.
 NASL will convert it into an integer in network order.
\newline 
Note that the function accepts an 
\series bold 
ip_dst
\series default 
 argument but ignore it!
\layout Itemize


\series bold 
ip_sum
\series default 
 is the packet header checksum.
 It will be computed by default.
\layout Itemize


\series bold 
ip_tos
\series default 
 is the 
\begin_inset Quotes eld
\end_inset 

type of service
\begin_inset Quotes erd
\end_inset 

 field.
 
\series bold 
0 
\series default 
by default
\layout Itemize


\series bold 
ip_ttl
\series default 
 is the 
\begin_inset Quotes eld
\end_inset 

Time To Live
\begin_inset Quotes erd
\end_inset 

.
 
\series bold 
64
\series default 
 by default.
\layout Itemize


\series bold 
ip_v
\series default 
 is the IP version.
 
\series bold 
4
\series default 
 by default.
\end_deeper 
\layout Itemize


\series bold 
forge_tcp_packet
\series default 

\begin_inset LatexCommand \index{forge\_tcp\_packet}

\end_inset 

 fills an IP datagram with TCP data.
 Note that the 
\series bold 
ip_p
\series default 
 field is not updated.
 It returns the modified IP datagram.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
data
\series default 
 is the TCP data payload.
\layout Itemize


\series bold 
ip
\series default 
 is the IP datagram to be filled.
\layout Itemize


\series bold 
th_ack
\series default 
 is the acknowledge number.
 NASL will convert it into network order if necessary.
\layout Itemize


\series bold 
th_dport
\series default 
 is the destination port.
 NASL will convert it into network order if necessary.
\layout Itemize


\series bold 
th_flags
\series default 
 are the TCP flags.
\layout Itemize


\series bold 
th_off
\series default 
 is the size of the TCP header in 32 bits words.
 By default, 
\series bold 
5.
\layout Itemize


\series bold 
th_seq
\series default 
 is the TCP sequence number.
 NASL will convert it into network order if necessary.
\layout Itemize


\series bold 
th_sport
\series default 
 is the source port.
 NASL will convert it into network order if necessary.
\layout Itemize


\series bold 
th_sum
\series default 
 is the TCP checksum.
 By default, the right value is computed.
\layout Itemize


\series bold 
th_urp
\series default 
 is the urgent pointer.
 
\series bold 
0
\series default 
 by default.
\layout Itemize


\series bold 
th_win
\series default 
 is the TCP window size.
 NASL will convert it into network order if necessary.
 
\series bold 
0
\series default 
 by default.
\layout Itemize


\series bold 
th_x2
\series default 
 is a reserved field and should probably be left unchanged.
\layout Itemize


\series bold 
update_ip_len
\series default 
 is a flag (TRUE by default).
 If set, NASL will recompute the size field of the IP datagram.
\end_deeper 
\layout Itemize


\series bold 
forge_udp_packet
\series default 

\begin_inset LatexCommand \index{forge_udp_packet"}

\end_inset 

 fills an IP datagram with UDP data.
 Note that the 
\series bold 
ip_p
\series default 
 field is not updated.
 It returns the modified IP datagram.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
data
\series default 
 is the payload.
\layout Itemize


\series bold 
ip
\series default 
 is the old datagram.
\layout Itemize


\series bold 
uh_dport
\series default 
 is the destination port.
 NASL will convert it into network order if necessary.
\layout Itemize


\series bold 
uh_sport
\series default 
 is the source port.
 NASL will convert it into network order if necessary.
\layout Itemize


\series bold 
uh_sum
\series default 
 is the UDP checksum.
 Although it is not compulsary, the right value is computed by default.
\layout Itemize


\series bold 
uh_ulen
\series default 
 is the data length.
 By default it is set to the length the 
\series bold 
data
\series default 
 argument plus the size of the UDP header.
\layout Itemize


\series bold 
update_ip_len
\series default 
 is a flag (TRUE by default).
 If set, NASL will recompute the size field of the IP datagram.
\end_deeper 
\layout Itemize


\series bold 
get_icmp_element
\series default 

\begin_inset LatexCommand \index{get\_icmp\_element}

\end_inset 

 returns an ICMP element from a IP datagram.
 It returns a data block or an integer, according to the type of the element.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
element
\series default 
 is the name of the TCP field (see 
\series bold 
forge_tcp_packet
\series default 
).
\layout Itemize


\series bold 
icmp 
\series default 
is the IP datagram (
\emph on 
not
\emph default 
 the ICMP part only).
\end_deeper 
\layout Itemize


\series bold 
get_ip_element
\series default 

\begin_inset LatexCommand \index{get\_ip\_element}

\end_inset 

 extracts a field from a datagram.
 It returns an integer or a string, depending on the type of the element.
 It takes two named string arguments:
\begin_deeper 
\layout Itemize


\series bold 
element
\series default 
 is the name of the field, e.g.
 
\series bold 
"ip_len"
\series default 
 ou 
\series bold 
"ip_src"
\series default 
.
\newline 
Note that 
\series bold 
"ip_dst"
\series default 
 works here!
\layout Itemize


\series bold 
ip
\series default 
 is the datagram or fragment.
\end_deeper 
\layout Itemize


\series bold 
get_tcp_element
\series default 

\begin_inset LatexCommand \index{get\_tcp\_element}

\end_inset 

 returns a TCP element from a IP datagram.
 It returns a data block or an integer, according to the type of the element.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
element
\series default 
 is the name of the TCP field (see 
\series bold 
forge_tcp_packet
\series default 
).
\layout Itemize


\series bold 
tcp 
\series default 
is the IP datagram (
\emph on 
not
\emph default 
 the TCP part only).
\end_deeper 
\layout Itemize


\series bold 
get_udp_element
\series default 

\begin_inset LatexCommand \index{get\_udp\_element}

\end_inset 

 returns an UDP element from a IP datagram.
 It returns a data block or an integer, according to the type of the element.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
element
\series default 
 is the name of the UDP field (see 
\series bold 
forge_udp_packet
\series default 
).
\layout Itemize


\series bold 
udp 
\series default 
is the IP datagram (
\emph on 
not
\emph default 
 the UDP part only).
\end_deeper 
\layout Itemize


\series bold 
insert_ip_options
\series default 

\begin_inset LatexCommand \index{insert\_ip\_options}

\end_inset 

 adds an IP option to the datagram and returns the modified datagram.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
code
\series default 
 is the number of the option.
\layout Itemize


\series bold 
length
\series default 
 is the length of the option data.
\layout Itemize


\series bold 
ip 
\series default 
is the old datagram.
\layout Itemize


\series bold 
value
\series default 
 is the option data.
\end_deeper 
\layout Itemize


\series bold 
pcap_next
\series default 

\begin_inset LatexCommand \index{pcap\_next}

\end_inset 

 listens to one packet and returns it.
 Its arguments are:
\begin_deeper 
\layout Itemize


\series bold 
interface
\series default 
 is the network interface name.
 By default, NASL will try to find the best one.
\layout Itemize


\series bold 
pcap_filter
\series default 
 is the BPF filter.
 By default, it listens to everything.
\layout Itemize


\series bold 
timeout
\series default 
 is 
\series bold 
5 
\series default 
seconds by default.
\end_deeper 
\layout Itemize


\series bold 
set_ip_elements
\begin_inset LatexCommand \index{set\_ip\_elements}

\end_inset 


\series default 
 modifies the fields of a datagram.
 The named argument 
\series bold 
ip
\series default 
 is the datagram; the other arguments are the same as 
\series bold 
forge_ip_packet
\series default 
.
 Once again, 
\series bold 
ip_dst
\series default 
 is ignored.
 It returns the new datagram.
\layout Itemize


\series bold 
set_tcp_elements
\begin_inset LatexCommand \index{set\_tcp\_elements}

\end_inset 


\series default 
 modifies the TCP fields of a datagram.
 The named argument 
\series bold 
tcp
\series default 
 is the IP datagram; the other arguments are the same as 
\series bold 
forge_tcp_packet
\series default 
.
 It returns the new IP datagram.
\layout Itemize


\series bold 
set_udp_elements
\begin_inset LatexCommand \index{set\_udp\_elements}

\end_inset 


\series default 
 modifies the UDP fields of a datagram.
 The named argument 
\series bold 
udp
\series default 
 is the IP datagram; the other arguments are the same as 
\series bold 
forge_udp_packet
\series default 
.
 It returns the new IP datagram.
\layout Itemize


\series bold 
send_packet
\series default 

\begin_inset LatexCommand \index{send\_packet}

\end_inset 

 sends a list of packets (passed as unnamed arguments) and listens to the
 answers.
 It returns a block made of all the sniffed 
\begin_inset Quotes eld
\end_inset 

answers
\begin_inset Quotes erd
\end_inset 

.
\begin_deeper 
\layout Itemize


\series bold 
length
\series default 
 is the length of each packet by default.
\layout Itemize


\series bold 
pcap_active
\series default 
 is TRUE by default.
 Otherwise, NASL does not listen for the answers.
\layout Itemize


\series bold 
pcap_filter
\series default 
 is the BPF filter.
 By default it is 
\series bold 
"ip and (src host 
\series default 
target
\series bold 
 and dst host 
\series default 
nessus_host
\series bold 
)"
\series default 
.
\layout Itemize


\series bold 
pcap_timeout
\series default 
 is 
\series bold 
5
\series default 
 by default.
\end_deeper 
\layout Subsubsection

Cryptographic functions
\layout Standard

They are only implemented if Nessus is linked with OpenSSL.
\layout Itemize


\series bold 
HMAC_DSS
\begin_inset LatexCommand \index{HMAC\_DSS}

\end_inset 

 
\series default 
takes two named string arguments (
\series bold 
data
\series default 
 and 
\series bold 
key
\series default 
) and returns the HMAC as a string.
\layout Itemize


\series bold 
HMAC_MD2
\begin_inset LatexCommand \index{HMAC\_MD2}

\end_inset 

 
\series default 
takes two named string arguments (
\series bold 
data
\series default 
 and 
\series bold 
key
\series default 
) and returns the HMAC as a string.
\layout Itemize


\series bold 
HMAC_MD4
\begin_inset LatexCommand \index{HMAC\_MD4}

\end_inset 

 
\series default 
takes two named string arguments (
\series bold 
data
\series default 
 and 
\series bold 
key
\series default 
) and returns the HMAC as a string.
\layout Itemize


\series bold 
HMAC_MD5
\begin_inset LatexCommand \index{HMAC\_MD5}

\end_inset 

 
\series default 
takes two named string arguments (
\series bold 
data
\series default 
 and 
\series bold 
key
\series default 
) and returns the HMAC as a string.
\layout Itemize


\series bold 
HMAC_RIPEMD160
\begin_inset LatexCommand \index{HMAC\_RIPEMD160}

\end_inset 

 
\series default 
takes two named string arguments (
\series bold 
data
\series default 
 and 
\series bold 
key
\series default 
) and returns the HMAC as a string.
\layout Itemize


\series bold 
HMAC_SHA
\begin_inset LatexCommand \index{HMAC\_SHA}

\end_inset 

 
\series default 
takes two named string arguments (
\series bold 
data
\series default 
 and 
\series bold 
key
\series default 
) and returns the HMAC as a string.
\layout Itemize


\series bold 
HMAC_SHA1
\begin_inset LatexCommand \index{HMAC\_SHA1}

\end_inset 

 
\series default 
takes two named string arguments (
\series bold 
data
\series default 
 and 
\series bold 
key
\series default 
) and returns the HMAC as a string.
\layout Itemize


\series bold 
MD2
\begin_inset LatexCommand \index{MD2}

\end_inset 


\series default 
 takes an unnamed string argument and returns the hash as a string.
\layout Itemize


\series bold 
MD4
\begin_inset LatexCommand \index{MD4}

\end_inset 


\series default 
 takes an unnamed string argument and returns the hash as a string.
\layout Itemize


\series bold 
MD5
\begin_inset LatexCommand \index{MD5}

\end_inset 


\series default 
 takes an unnamed string argument and returns the hash as a string.
\layout Itemize


\series bold 
RIPEMD160
\begin_inset LatexCommand \index{RIPEMD160}

\end_inset 


\series default 
 takes an unnamed string argument and returns the hash as a string.
\layout Itemize


\series bold 
SHA
\begin_inset LatexCommand \index{SHA}

\end_inset 


\series default 
 takes an unnamed string argument and returns the hash as a string.
\layout Itemize


\series bold 
SHA1
\begin_inset LatexCommand \index{SHA1}

\end_inset 


\series default 
 takes an unnamed string argument and returns the hash as a string.
\layout Subsubsection

Miscellaneous functions
\layout Itemize


\series bold 
defined_func
\begin_inset LatexCommand \index{defined\_func}

\end_inset 


\series default 
 takes one unnamed string argument and returns TRUE if a function with this
 named is defined.
 Whether it is a user or a built-in function does not matter.
\layout Itemize


\series bold 
dump_ctxt
\begin_inset LatexCommand \index{dump\_ctxt}

\end_inset 


\series default 
 is a debugging function which is not very useful for end users.
 It does not take any argument.
\layout Itemize


\series bold 
isnull
\begin_inset LatexCommand \index{isnull}

\end_inset 


\series default 
 takes one unnamed argument and returns TRUE if it is not initialized, and
 FALSE otherwise.
\newline 
Remember that most of the time, (
\series bold 
x\SpecialChar ~
==\SpecialChar ~
NULL
\series default 
) will not give the same result as 
\series bold 
isnull(x)
\layout Itemize


\series bold 
make_array
\series default 

\begin_inset LatexCommand \index{make\_array}

\end_inset 

 takes any 
\emph on 
even
\emph default 
 number of unnamed arguments and returns an array made from them.
 Contrary to 
\series bold 
make_list
\series default 
, only 
\begin_inset Quotes eld
\end_inset 

atomic
\begin_inset Quotes erd
\end_inset 

 values are accepted.
 The first argument in each pair is the key (either an integer or a character
 string), the second is the value.
 For example, 
\series bold 
v=make_array(1,'one', 'Two', 2);
\series default 
 is equivalent to 
\series bold 
v[1]='one';\SpecialChar ~
v['Two']=2;
\newline 
make_array
\series default 
 can return arrays with duplicated keys, that have to be converted with
 
\series bold 
make_list
\series default 
 or walked through with 
\series bold 
foreach
\layout Itemize


\series bold 
make_list
\begin_inset LatexCommand \index{make\_list}

\end_inset 


\series default 
 takes any number of unnamed arguments of any types and returns an array
 made from them.
 If an argument is an array, it is split into its elements (i.e.
 make_list does not create a multi-dimensional array); the 
\begin_inset Quotes eld
\end_inset 

integer indexed
\begin_inset Quotes erd
\end_inset 

 elements will be re-indexed but the order will be kept.
\newline 
e.g., this:
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{v = make
\backslash 
_list(0,-1,'two'); w = make
\backslash 
_list('A', v); }
\end_inset 


\newline 
is equivalent to:
\newline 

\series bold 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{v[0] = 0; v[1] = -1; v[2] = 'two';}
\end_inset 


\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{w[0] = 'A'; w[1] = 0; w[2] = -1; w[3] = 'two';}
\end_inset 


\layout Itemize


\series bold 
max_index
\begin_inset LatexCommand \index{max\_index}

\end_inset 


\series default 
 takes one unnamed array argument and returns the bigger integer index used
 
\bar under 
plus 1
\bar default 
.
\newline 
e.g., to add an element at the end of any array, you may write 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{w[max
\backslash 
_index(w)] = value;}
\end_inset 


\layout Itemize


\series bold 
safe_checks
\begin_inset LatexCommand \index{safe\_checks}

\end_inset 


\series default 
 takes no argument and returns the boolean value of the 
\begin_inset Quotes eld
\end_inset 

safe checks
\begin_inset Quotes erd
\end_inset 

 option.
\newline 
Dangerous plugins which may crash the remote service are expected to change
 their behavior when 
\begin_inset Quotes eld
\end_inset 

safe checks
\begin_inset Quotes erd
\end_inset 

 is on.
 Usually, they just identify the service version (e.g.
 from the banner) and check if it is known as vulnerable.
 
\newline 
In 
\begin_inset Quotes eld
\end_inset 

safe checks
\begin_inset Quotes erd
\end_inset 

 mode, plugins from the most dangerous 
\begin_inset Quotes eld
\end_inset 

categories
\begin_inset Quotes erd
\end_inset 

 (ACT_DESTRUCTIVE_ATTACK, ACK_DENIAL and ACT_KILL_HOST) are not launched.
 So you do not need to test the value of 
\series bold 
safe_checks
\series default 
 in those scripts.
\newline 
You shouldn't either write code like 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
texttt{if (safe
\backslash 
_checks()) exit(0);}
\end_inset 

.
 If you do not want to run your test in this mode (e.g.
 because you do not know how to parse the banner), you should move your
 plugin to one of those 
\begin_inset Quotes eld
\end_inset 

dangerous
\begin_inset Quotes erd
\end_inset 

 categories, probably 
\series bold 
ACT_DESTRUCTIVE_ATTACK
\series default 
.
\layout Itemize


\series bold 
sleep
\begin_inset LatexCommand \index{sleep}

\end_inset 


\series default 
 takes one unnamed integer argument and waits for this number of seconds.
\layout Itemize


\series bold 
type_of
\begin_inset LatexCommand \index{type\_of}

\end_inset 


\series default 
 returns the type of the argument.
 The return value is a string:
\begin_deeper 
\layout Itemize


\series bold 
"undef"
\series default 
 if the variable / argument is not initialized.
\layout Itemize


\series bold 
"int"
\series default 
 if it is an integer.
\layout Itemize


\series bold 
"string"
\series default 
 it if is an 
\begin_inset Quotes eld
\end_inset 

impure string
\begin_inset Quotes erd
\end_inset 

.
\layout Itemize


\series bold 
"data"
\series default 
 if it is a 
\begin_inset Quotes eld
\end_inset 

pure string
\begin_inset Quotes erd
\end_inset 

.
\layout Itemize


\series bold 
"unknown"
\series default 
 if the type is unknown, which means that you have found a bug in the interpreto
r!
\end_deeper 
\layout Itemize


\series bold 
usleep
\begin_inset LatexCommand \index{usleep}

\end_inset 


\series default 
 takes one unnamed integer argument and waits for this number of microseconds.
\layout Subsection

NASL library
\layout Standard

It is implemented through 
\begin_inset Quotes eld
\end_inset 

include files
\begin_inset Quotes erd
\end_inset 

.
 Some of the functions are not very interesting because they were not designed
 to be called directly: they are used by other functions in the 
\begin_inset Quotes eld
\end_inset 

.inc
\begin_inset Quotes erd
\end_inset 

 file.
\layout Subsubsection

dump.inc
\layout Itemize


\series bold 
dump
\series default 

\begin_inset LatexCommand \index{dump}

\end_inset 

(ddata, dtitle)
\newline 
prints the optional title and dumps the data block to the standard output.
 This function is useful for debugging only.
\layout Itemize


\series bold 
hexdump
\series default 

\begin_inset LatexCommand \index{hexdump}

\end_inset 

(ddata)
\newline 
dumps a data block into hexadecimal and returns the results (as a string).
\layout Subsubsection

ftp_func.inc
\layout Itemize


\series bold 
ftpclose
\series default 

\begin_inset LatexCommand \index{ftpclose}

\end_inset 

(socket)
\newline 
cleanly closes a FTP connection: sends 
\begin_inset Quotes eld
\end_inset 

QUIT
\begin_inset Quotes erd
\end_inset 

, waits for the answer and then closes the socket.
 This functions does not return any value.
\layout Itemize


\series bold 
get_ftp_banner
\series default 

\begin_inset LatexCommand \index{get\_ftp\_banner}

\end_inset 

(port)
\newline 
returns the FTP banner that was stored in the KB under 
\series bold 

\begin_inset Quotes eld
\end_inset 

ftp/banner/
\series default 
port_number
\begin_inset Quotes erd
\end_inset 

.
 If the KB item is not present, the function connects to the FTP server,
 reads the banner, stores it into the KB and returns it.
\layout Itemize


\series bold 
ftp_recv_line
\series default 

\begin_inset LatexCommand \index{ftp\_recv\_line}

\end_inset 

(socket)
\newline 
reads a line on the socket until the 4
\begin_inset Formula $^{\textrm{th}}$
\end_inset 

character is different from 
\begin_inset Quotes eld
\end_inset 

-
\begin_inset Quotes erd
\end_inset 

.
 Useful to skip a long login banner.
\layout Subsubsection

http_func.inc
\layout Itemize


\series bold 
check_win_dir_trav
\series default 

\begin_inset LatexCommand \index{check\_win\_dir\_trav}

\end_inset 

(port, url, quickcheck)
\newline 
connects to port and sends a HTTP GET request to the given 
\series bold 
url
\series default 
.
 You are supposed to try to access AUTOEXEC.BAT, BOOT.INI or WIN.INI
\newline 
If 
\series bold 
quickcheck
\series default 
 is TRUE, the function returns TRUE if it gets a 200 (OK) answer.
 
\newline 
If 
\series bold 
quickcheck
\series default 
 is FALSE, it looks for pattern in the answer; it will returns TRUE if it
 can find 
\begin_inset Quotes eld
\end_inset 

ECHO
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

SET
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

export
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

mode
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

MODE
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

doskey
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

DOSKEY
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

[boot\SpecialChar ~
loader]
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

[fonts]
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

[extensions]
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

[mci\SpecialChar ~
extensions]
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

[files]
\begin_inset Quotes erd
\end_inset 

, 
\begin_inset Quotes eld
\end_inset 

[Mail]
\begin_inset Quotes erd
\end_inset 

, or 
\begin_inset Quotes eld
\end_inset 

[operating \SpecialChar ~
systems]
\begin_inset Quotes erd
\end_inset 

.
 
\newline 
You are supposed to set 
\series bold 
quickcheck
\series default 
 if the server answers with clean 404 codes to requests to unknown pages,
 i.e.
 if 
\begin_inset Quotes eld
\end_inset 


\series bold 
www/no404/
\series default 
port
\begin_inset Quotes erd
\end_inset 

 is not set in the KB.
\layout Itemize


\series bold 
get_cgi_path
\series default 

\begin_inset LatexCommand \index{get\_cgi\_path}

\end_inset 

(port) 
\newline 
returns the list of directories where the CGI might be installed.
 The list is a string where the items are separated with 
\begin_inset Quotes eld
\end_inset 

:
\begin_inset Quotes erd
\end_inset 

.
\newline 
WARNING: this function is not a good idea and may disappear in the future.
\layout Itemize


\series bold 
get_http_banner
\series default 

\begin_inset LatexCommand \index{get\_http\_banner}

\end_inset 

(port)
\newline 
returns the HTTP banner that was stored in the KB under 
\series bold 

\begin_inset Quotes eld
\end_inset 

www/banner/
\series default 
port_number
\begin_inset Quotes erd
\end_inset 

.
 If the KB item is void, the function connects to the HTTP server, sends
 a GET request, and stores the result into the KB.
\layout Itemize


\series bold 
get_http_port
\series default 

\begin_inset LatexCommand \index{get\_http\_port}

\end_inset 

(default)
\newline 
reads the KB item 
\series bold 

\begin_inset Quotes eld
\end_inset 

Services/www
\series default 

\begin_inset Quotes erd
\end_inset 

, verifies that the port is open, that there is an HTTP server behind it,
 and returns it.
 Note that the function will fork if there are several web servers on the
 target machine.
 
\newline 
If the KB item is void, the 
\series bold 
default
\series default 
 port is tested.
\newline 
If no HTTP port is found, 
\emph on 
the script exits
\emph default 
.
\layout Itemize


\series bold 
http_is_dead
\series default 

\begin_inset LatexCommand \index{http\_is\_dead}

\end_inset 

(port, retry)
\newline 
tries very hard to test if the web server is still alive even if there is
 a transparent or reverse proxy on the way.
 It sends a HTTP GET request for a random page (
\series bold 
/NessusTest
\series default 
<rand>
\series bold 
.html
\series default 
) and waits for the answer.
 The optional argument 
\series bold 
retry
\series default 
 is the number of times it should wait (one second) and retry to open the
 socket to the remote service if this failed in the first time (by default,
 there is no retry).
\newline 
It returns TRUE if
\begin_deeper 
\layout Itemize

the connection was refused, or 
\layout Itemize

no valid HTTP answer was received, or
\layout Itemize

a 502 (bad gateway) or 503 (service unavailable) was received.
\end_deeper 
\layout Itemize


\series bold 
http_recv_body
\series default 

\begin_inset LatexCommand \index{http\_recv\_body}

\end_inset 

(socket, headers, length)
\newline 
reads N bytes from the 
\series bold 
socket
\series default 
.
 N is defined like this:
\begin_deeper 
\layout Itemize

If the 
\series bold 
header
\series default 
 field is not defined, the function first calls 
\series bold 
http_recv_headers
\series default 
; the 
\begin_inset Quotes eld
\end_inset 

Content-Length
\begin_inset Quotes erd
\end_inset 

 field is extracted from the headers.
 
\newline 
Note that the headers will not be returned, only the HTTP 
\begin_inset Quotes eld
\end_inset 

body
\begin_inset Quotes erd
\end_inset 

.
\layout Itemize

Then, if 
\series bold 
length
\series default 
 is set 
\begin_deeper 
\layout Itemize

if content_length could be extracted from the headers, N\SpecialChar ~
=\SpecialChar ~
max(length,\SpecialChar ~
content_leng
th)
\layout Itemize

otherwise, N\SpecialChar ~
=\SpecialChar ~
length
\end_deeper 
\layout Itemize

else if content_length could be extracted from the headers, N\SpecialChar ~
=\SpecialChar ~
content_length,
\layout Itemize

else N defaults to 8192 bytes.
\end_deeper 
\layout Itemize


\series bold 
http_recv
\series default 

\begin_inset LatexCommand \index{http\_recv}

\end_inset 

(socket, code)
\newline 
reads the HTTP headers and data from the socket and returns all this.
\newline 
This function is efficient because it just reads the right number of bytes
 without waiting for a network timeout.
 The code argument is optional.
 If you read the HTTP code (with 
\series bold 
recv_line
\series default 
), you have to put it into this argument
\begin_inset Foot
collapsed true

\layout Standard

In fact, 
\series bold 
http_recv
\series default 
 only needs to know that the code was read, because 
\series bold 
http_recv_header
\series default 
 may not work in this case.
 
\series bold 
http_recv
\series default 
 uses its own loop to read the remaining headers before the body.
\end_inset 

.
\layout Itemize


\series bold 
http_recv_length
\series default 

\begin_inset LatexCommand \index{http\_recv\_length}

\end_inset 

(socket, bodylength)
\newline 
reads the HTTP headers, then calls 
\series bold 
http_recv_body
\series default 
 with length=bodylength, and returns the concatenated headers and body.
\layout Itemize


\series bold 
locate_cgi
\series default 

\begin_inset LatexCommand \index{locate\_cgi}

\end_inset 

(port, item)
\newline 
looks for a given CGI on a web server.
 It returns its path if it could be found, or NULL otherwise.
\newline 
WARNING: the implementation is wrong, so this function may disappear in
 the future.
\layout Itemize


\series bold 
php_ver_match
\series default 

\begin_inset LatexCommand \index{php\_ver\_match}

\end_inset 

(banner, pattern)
\newline 
the function returns TRUE if the regex pattern matches a 
\begin_inset Quotes eld
\end_inset 

Server:
\begin_inset Quotes erd
\end_inset 

 ou 
\begin_inset Quotes eld
\end_inset 

X-Powered-by:
\begin_inset Quotes erd
\end_inset 

 line in the banner.
 A way to use this function is, for example:
\layout LyX-Code

if (php_ver_match(banner:banner,
\layout LyX-Code

     pattern:".*PHP/((3.*)|(4
\backslash 
.0.*)|(4
\backslash 
.1
\backslash 
.[01].*))"))
\layout LyX-Code

 security_hole(port); 
\layout Itemize


\series bold 
cgi_dirs
\begin_inset LatexCommand \index{cgi\_dirs}

\end_inset 

()
\newline 

\series default 
returns an array containing all the directories that may have CGIs in it
 (by default /cgi-bin and /scripts).
 Several scripts try to augment this list (in particular 
\emph on 
webmirror.nasl
\emph default 
).
 
\layout LyX-Code

\layout Subsubsection

http_keepalive.inc
\layout Standard

Nessus 2.0.1 and newer support HTTP keep-alive connections, which avoid to
 re-open a socket for each request.
 This saves bandwidth and CPU cycles (especially on hosts using SSL).
 At this time, only the requests made from within the same plugin can be
 kept alive, however sharing one socket among multiple plugins could be
 done in the future.
 To work properly, this file must be included after 
\series bold 
http_func.inc
\series default 
.
 
\layout Itemize


\series bold 
http_keepalive_send_recv
\begin_inset LatexCommand \index{http\_keepalive\_send\_recv}

\end_inset 


\series default 
(port, req)
\newline 
sends the request 
\series bold 
req
\series default 
 to the remote web server listening on port 
\series bold 
port 
\series default 
and returns the result of the request, or NULL if the connection could not
 be established.
 Internally, this function will automatically determine if the remote host
 supports Keep-Alive connections and will restore the connection if it was
 cut.
 
\series bold 
req
\series default 
 is a full HTTP request, as returned by 
\series bold 
http_get()
\series default 
.
\newline 
It is not recommanded to send potentially destructive attacks on top of
 a kept-alive connection.
\layout Itemize


\series bold 
is_cgi_installed_ka
\begin_inset LatexCommand \index{is\_cgi\_installed\_ka}

\end_inset 

(
\series default 
port, item)
\newline 
acts the same way as 
\series bold 
is_cgi_installed()
\series default 
 but on top of a kept-alive connection.
\layout Itemize


\series bold 
check_win_dir_traversal_ka
\begin_inset LatexCommand \index{check\_win\_dir\_traversal\_ka}

\end_inset 


\series default 
(port, url, quickcheck)
\newline 
acts the same way as 
\series bold 
check_win_dir_traversal()
\series default 
 but on top ofa kept-alive connection.
\layout Subsubsection

misc_func.inc
\layout Itemize


\series bold 
register_service
\series default 

\begin_inset LatexCommand \index{register\_service}

\end_inset 

(port, proto)
\newline 

\begin_inset Quotes eld
\end_inset 

registers
\begin_inset Quotes erd
\end_inset 

 a service.
 Used values for the proto arguments are: 
\series bold 
aos
\series default 
, 
\series bold 
bugbear
\series default 
, 
\series bold 
DCE/
\series default 
guid, 
\series bold 
dns
\series default 
, 
\series bold 
lpd
\series default 
, 
\series bold 
uucp
\series default 
, 
\series bold 
irc
\series default 
, 
\series bold 
daytime
\series default 
, 
\series bold 
ftp
\series default 
, 
\series bold 
smtp
\series default 
, 
\series bold 
nntp
\series default 
, 
\series bold 
ssh
\series default 
, 
\series bold 
auth
\series default 
, 
\series bold 
finger
\series default 
, 
\series bold 
www
\series default 
, 
\series bold 
mldonkey-telnet
\series default 
, 
\series bold 
nessus
\series default 
, 
\series bold 
QMTP
\series default 
, 
\series bold 
radmin
\series default 
, 
\series bold 
RPC/
\series default 
name, 
\series bold 
portmapper
\series default 
, 
\series bold 
rsh
\series default 
, 
\series bold 
x11
\series default 
, 
\series bold 
xtel
\series default 
, 
\series bold 
xtelw
\series default 
.
 
\newline 
In practice, this function defines two items in the KB:
\begin_deeper 
\layout Itemize


\series bold 
Known/tcp/
\series default 
port = proto
\layout Itemize


\series bold 
Services/
\series default 
proto = port
\newline 
This may create a list if several servers are known on differents ports.
\end_deeper 
\layout Itemize


\series bold 
known_service
\series default 

\begin_inset LatexCommand \index{known\_service}

\end_inset 

(port)
\newline 
returns TRUE if the service is known on the port, FALSE otherwise.
 Note that if the service was 
\begin_inset Quotes eld
\end_inset 

registered
\begin_inset Quotes erd
\end_inset 

 several times, 
\series bold 
known_service
\series default 
 may fork.
 So the right way to use this function is to exit if it returns TRUE.
 For example:
\layout LyX-Code

port = get_kb_item("Services/unknown");
\layout LyX-Code

# This was set by find_service.nes but another plugin
\layout LyX-Code

# may have identified the service.
 So:
\layout LyX-Code

if (known_service(port: port)) exit(0);
\layout Itemize


\series bold 
get_unknown_banner
\series default 

\begin_inset LatexCommand \index{get\_unknown\_banner}

\end_inset 

(port, dontfetch)
\newline 
reads 
\series bold 
unknown/banner/
\series default 
port from the KB.
 If a value is found, it is returned.
 If no value is found and 
\series bold 
dontfetch
\series default 
 is set, the function returns NULL.
 Otherwise the function connects to the port, tries to read a banner, stores
 it in the KB and returns it.
\layout Itemize


\series bold 
set_unknown_banner
\series default 

\begin_inset LatexCommand \index{set\_unknown\_banner}

\end_inset 

(port, banner)
\newline 
sets 
\series bold 
unknown/banner/
\series default 
port to 
\series bold 
banner
\series default 
 in the KB.
\layout Itemize


\series bold 
get_service_banner
\series default 
_line
\begin_inset LatexCommand \index{get\_service\_banner\_line}

\end_inset 

(service, port)
\newline 
reads 
\series bold 
Services/
\series default 
service from the KB.
 If no value is found, uses the 
\series bold 
port
\series default 
 parameter.
 It then reads service
\series bold 
/banner/
\series default 
port from the KB; if it exists, it is returned.
 If not, the function connects to the port, reads one line and returns it,
 
\emph on 
but does not store it in the KB.
\emph default 

\newline 
Note that this function may fork.
\layout Itemize


\series bold 
get_rpc_port
\series default 

\begin_inset LatexCommand \index{get\_rpc\_port}

\end_inset 

(program, protocol)
\newline 
calls the portmapper and gets the port where the service specified by the
 parameters is located.
 
\series bold 
program
\series default 
 is a RPC number and 
\series bold 
protocol
\series default 
 may be IPPROTO_TCP or IPPROTO_UDP.
 If the portmapper could not be reached or the service is down, the function
 returns 
\series bold 
0
\series default 
.
\layout Subsubsection

nfs_func.inc
\layout Standard

NFS read and write functions are not defined yet.
 You can only mount a NFS share and inspect its contents.
\layout Itemize


\series bold 
mount
\begin_inset LatexCommand \index{mount}

\end_inset 


\series default 
(soc, share)
\newline 
attempts to mount 
\series bold 
share 
\series default 
(defined in 
\series bold 
NFS/exportlist
\series default 
 in the KB).
 
\series bold 
soc 
\series default 
is a UDP socket opened to the remote mount daemon (mountd, rpc program#100005).
 This function returns NULL in case of failure, or a file handle (fid) in
 case of success.
\layout Itemize


\series bold 
umount
\begin_inset LatexCommand \index{umount}

\end_inset 


\series default 
(soc, share)
\newline 
unmounts 
\series bold 
share
\series default 
 - basically, this tells the remote mount daemon that we will stop using
 its services.
 
\series bold 
soc
\series default 
 is a UDP socket opened to the remote mount daemon.
\layout Itemize


\series bold 
readdir
\begin_inset LatexCommand \index{readdir}

\end_inset 


\series default 
(soc, fid)
\newline 
returns the content of the directory pointed by 
\series bold 
fid
\series default 
.
 
\series bold 
soc
\series default 
 is a UDP socket opened to the remote NFS daemon (nfsd, rpc program #100003).
 This function returns an array.
\layout Itemize


\series bold 
cwd
\begin_inset LatexCommand \index{cwd}

\end_inset 


\series default 
(soc, fid, dir)
\newline 
changes directories.
 
\series bold 
soc
\series default 
 is a UDP socket opened to the remote NFS daemon, 
\series bold 
fid 
\series default 
is the current working directory and 
\series bold 
dir
\series default 
 is the name of the directory we would like to change it.
 This function returns NULL on failure, or a handle (fid) to the directory
 we changed to.
\layout Subsubsection

smb_nt.inc
\layout Standard

The SMB library provides a way to interact with Windows hosts using SMB,
 either on top of port 139 or on top of port 445.
 Since Microsoft protocol is barely documented, most if not all of these
 functions have been coded by packet analysis.
 Therefore, the name of the functions may vary compared to what you would
 find in Microsoft-Land.
\layout Standard

The functions described here are both low-level and high-level.
 This a description of the SMB protocol (and DCE/RPC over SMB) is beyond
 the scope of this manual, we suggest you refer to the books listed in the
 bibliography if needed.
 The functions are defined in this guide in the order they are usually used
 :
\layout Paragraph

Setting up an SMB session
\layout Itemize


\series bold 
smb_session_request
\series default 

\begin_inset LatexCommand \index{smb\_session\_request}

\end_inset 

(soc, remote)
\newline 
pre-establishes a SMB session with the remote host.
 
\series bold 
soc
\series default 
 is a socket opened to port 139 or 445 if the remote host supports it.
 You must open the connect to the port pointed by the KB item 
\series bold 
SMB/transport
\series default 
, which is defined in the plugin 
\emph on 
cifs445.nasl.

\emph default 
 
\series bold 
remote 
\series default 
is the netbios name of the remote host (as stored in the KB item 
\series bold 
SMB/name
\series default 
, created in the plugin 
\emph on 
netbios_name_get.nasl
\emph default 
).

\emph on 
 
\emph default 
If the name is not defined you can try to use 
\series bold 
*SMBSERVER
\series default 
 which is recognized by most SMB hosts.
 If the connection takes place on top of port 445, this function immediately
 returns as it is unnecessary in this case.
\layout Itemize


\series bold 
smb_neg_prot
\begin_inset LatexCommand \index{smb\_neg\_prot}

\end_inset 


\series default 
(soc)
\newline 
negociates the protocol we will use to log into the remote host.
 This function asks for NTLMv1 authentication if possible, and returns a
 buffer suitable to be used with 
\series bold 
smb_session_setup()
\series default 
, which contains the authentication protocols the remote host supports.
 
\series bold 
soc
\series default 
 must be the socket opened to the remote SMB server, and a call to 
\series bold 
smb_session_request()
\series default 
 has to be made before this function is called.
\layout Itemize


\series bold 
smb_session_setup
\series default 

\begin_inset LatexCommand \index{smb\_session\_setup}

\end_inset 

(soc, login, password, domain, prot)
\newline 
setups the SMB session to the remote host.
 It logs as 
\series bold 
login
\series default 
 with the password 
\series bold 
password
\series default 
, in the domain 
\series bold 
domain 
\series default 
(which can be NULL, in which case the function will log locally).
 This function returns a buffer suitable to use with the function 
\series bold 
session_extract_uid()
\series default 
, or NULL if the authentication failed.
 Internally, the function will use either clear-text or NTLMv1 authentication,
 depending on what the remote host supports and the options set by the user.
 
\series bold 
prot 
\series default 
is the buffer returned by the function 
\series bold 
smb_neg_prot()
\series default 
.

\series bold 
 soc
\series default 
 must be the socket opened to the remote SMB server, and a call to 
\series bold 
smb_neg_prot()
\series default 
 must have been made prior to calling this function.
 
\series bold 
smb_session_setup()
\series default 
 returns a buffer suitable to be used with 
\series bold 
session_extract_uid()
\series default 
.
\layout Itemize


\series bold 
session_extract_uid
\series default 

\begin_inset LatexCommand \index{session\_extract\_uid}

\end_inset 

(reply)
\newline 
extracts the user id from 
\series bold 
reply
\series default 
.
 It is used each time a new SMB call is made.
 It returns 0 if 
\series bold 
smb_session_setup()
\series default 
 failed.
\layout Paragraph

Connecting and reading from the remote shares
\layout Standard

Each SMB host exports shares - virtual directories accessible from accross
 the network, usually containing files.
 The list of shares exported by a given host is written in 
\series bold 
SMB/shares
\series default 
, which is written to by 
\emph on 
smb_enum_shares.nasl
\series bold 
.
 
\layout Itemize


\series bold 
smb_tconx
\series default 

\begin_inset LatexCommand \index{smb\_tconx}

\end_inset 

(soc, name, uid, share)
\newline 
connects to 
\series bold 
share
\series default 
 (ie: 
\begin_inset Quotes eld
\end_inset 

IPC$
\begin_inset Quotes erd
\end_inset 

) on top of the socket 
\series bold 
soc
\series default 
 connected to the smb host whose name is 
\series bold 
name.

\series default 
 The option 
\series bold 
uid
\series default 
 comes from the call to 
\series bold 
session_extract_uid()
\series default 
.
 This function returns a buffer suitable to be used with 
\series bold 
tconx_extract_tid()
\series default 
.
\layout Itemize


\series bold 
tconx_extract_tid
\series default 

\begin_inset LatexCommand \index{tconx\_extract\_tid}

\end_inset 

(reply)
\newline 
extracts the tree id from 
\series bold 
reply
\series default 
, which is a buffer returned by a call to 
\series bold 
smb_tconx()
\series default 
.
 It returns 0 if the call to 
\series bold 
smb_tconx()
\series default 
 failed.
\layout Itemize


\series bold 
OpenAndX
\begin_inset LatexCommand \index{OpenAndX}

\end_inset 


\series default 
(socket, uid, tid, file)
\newline 
opens 
\series bold 
file
\series default 
 on the share pointed by 
\series bold 
tid
\series default 
, and returns a file id (fid) or NULL if the call failed (ie: file does
 not exist or can not be read).
\layout Itemize


\series bold 
ReadAndX
\begin_inset LatexCommand \index{ReadAndX}

\end_inset 


\series default 
(socket, uid, tid, count, off)
\newline 
reads 
\series bold 
count
\series default 
 bytes starting at offset 
\series bold 
off
\series default 
 in the file 
\series bold 
fid 
\series default 
and returns the content (or NULL if the call failed)
\layout Itemize


\series bold 
smb_get_file_size
\begin_inset LatexCommand \index{smb\_get\_file\_size}

\end_inset 


\series default 
(socket, uid, tid, fid)
\newline 
returns the size of the file pointed by 
\series bold 
fid.
\layout Paragraph

Accessing the remote registry
\layout Itemize


\series bold 
smbntcreatex
\series default 

\begin_inset LatexCommand \index{smbntcreatex}

\end_inset 

(soc, uid, tid) 
\newline 
this function creates a connection to the remote 
\backslash 
winreg named pipe.
 It should be rewritten to support a fourth argument (pipename) but it is
 not the case at this time.
 
\series bold 
soc
\series default 
 is a socket connected to the remote SMB host, 
\series bold 
uid 
\series default 
is our user id (obtained via 
\series bold 
smb_session_setup()
\series default 
 and 
\series bold 
session_extract_uid()
\series default 
) and 
\series bold 
tid
\series default 
 is pointing to the special share IPC$.
 This function returns a buffer suitable to be used with 
\series bold 
smbntcreatex_extract_pipe()
\series default 
 or NULL if the called failed (ie: there is no 
\backslash 
winreg named pipe).
\layout Itemize


\series bold 
smbntcreatex_extract_pipe
\series default 

\begin_inset LatexCommand \index{smbntcreatex\_extract\_pipe}

\end_inset 

(reply) 
\newline 
extracts the pipe id from the buffer returned by 
\series bold 
smbntcreatex()
\series default 
.
 It returns 0 if the call failed.
\layout Itemize


\series bold 
pipe_accessible_registry
\series default 
(soc, uid, tid, pipe) 
\newline 
what this function does is quite unclear.
 It should be called before continuing to explore the registry, just after
 
\series bold 
smbntcreatex()
\series default 
.
 
\series bold 
pipe
\series default 
 is the integer returned by 
\series bold 
smbntcreatex_extract_pipe()
\series default 
.
\layout Itemize


\series bold 
registry_access_step_1
\series default 
(soc, uid, tid, pipe) 
\newline 
this function should be renamed registry_open_hklm (and will probably be).
 It opens HIVE_KEY_LOCAL_MACHINE and returns a buffer suitable to use with
 
\series bold 
registry_get_key()
\series default 
 and 
\series bold 
registry_get_key_security()
\series default 
.
\layout Itemize


\series bold 
registry_get_key
\series default 

\begin_inset LatexCommand \index{registry\_get\_key}

\end_inset 

(soc, uid, tid, pipe, key, reply) 
\newline 
opens the registry key 
\begin_inset Quotes eld
\end_inset 


\series bold 
key
\series default 

\begin_inset Quotes erd
\end_inset 

 (as in 
\begin_inset Quotes eld
\end_inset 

SOFTWARE
\backslash 
Microsoft
\backslash 
Windows NT
\begin_inset Quotes erd
\end_inset 

) and returns a buffer suitable to use with 
\series bold 
registry_get_item_dword()
\series default 
, 
\series bold 
registry_get_item_sz()
\series default 
, or 
\series bold 
registry_get_key_security()
\series default 
.
 
\series bold 
reply
\series default 
 is the buffer returned by 
\series bold 
registry_access_step_1()
\series default 
.
 This function returns NULL if the key does not exist or is not accessible.
\layout Itemize


\series bold 
registry_get_item_sz
\series default 

\begin_inset LatexCommand \index{registry\_get\_item\_sz}

\end_inset 

(soc, uid, tid, pipe, item, reply) 
\newline 
returns the content of 
\series bold 
item
\series default 
 in the currently opened key (designated by 
\series bold 
reply
\series default 
, which is a buffer returned by 
\series bold 
registry_get_key()
\series default 
).
 It returns a buffer which needs to be decoded with 
\series bold 
registry_decode_sz()
\series default 
.
 
\series bold 
item
\series default 
 must be a string key value.
 If 
\series bold 
reply
\series default 
 is the reply to a call to 
\series bold 
registry_get_key
\series default 
(key:
\begin_inset Quotes erd
\end_inset 

SOFTWARE
\backslash 
Microsoft
\backslash 
Windows NT
\begin_inset Quotes erd
\end_inset 

), 
\series bold 
item
\series default 
 could be equal to 
\begin_inset Quotes eld
\end_inset 

CurrentVersion
\begin_inset Quotes erd
\end_inset 

.
\layout Itemize


\series bold 
registry_decode_sz
\begin_inset LatexCommand \index{registry\_decode\_sz}

\end_inset 


\series default 
(data)
\newline 
decodes the value returned by 
\series bold 
registry_get_item_sz()
\series default 
 and returns a string containing the value, or NULL if the call to 
\series bold 
registry_get_item_sz() 
\series default 
failed.
\layout Itemize


\series bold 
registry_get_item_dword
\begin_inset LatexCommand \index{registry\_get\_item\_dword}

\end_inset 


\series default 
(soc, uid, tid, pipe, item, reply)
\newline 
returns the content of 
\series bold 
item
\series default 
 in the currently opened key (designated by 
\series bold 
reply
\series default 
, which is a buffer returned by 
\series bold 
registry_get_key()
\series default 
).
 It returns a buffer which needs to be decoded with 
\series bold 
registry_decode_dword()
\series default 
.
 
\series bold 
item 
\series default 
must be an integer key value.
 
\layout Itemize


\series bold 
registry_decode_dword
\begin_inset LatexCommand \index{registry\_decode\_dword}

\end_inset 


\series default 
(data)
\newline 
decodes the value returned by 
\series bold 
registry_get_item_dword()
\series default 
 and returns an integer containing the value, or NULL if the call to 
\series bold 
registry_get_item_dword()
\series default 
 failed.
\layout Itemize


\series bold 
registry_get_key_security
\begin_inset LatexCommand \index{registry\_get\_key\_security}

\end_inset 


\series default 
(soc, uid, tid, pipe, reply)
\newline 
obtains the ACLs associated to the key opened with 
\series bold 
registry_get_key()
\series default 
.
 
\series bold 
reply 
\series default 
is the buffer returned by 
\series bold 
registry_get_key()
\series default 
.
 It returns a security descriptor
\begin_inset LatexCommand \index{security descriptor}

\end_inset 

 which contains the ACLs and which has to be parsed manually.
 The function 
\series bold 
registry_key_writeable_by_non_admin
\series default 
() is a great example of usage for this.
\layout Itemize


\series bold 
registry_key_writeable_by_non_admin
\begin_inset LatexCommand \index{registry\_key\_writeable\_by\_non\_admin}

\end_inset 


\series default 
(security_descriptor)
\newline 
decodes the buffer returned by 
\series bold 
registry_get_key_security()
\series default 
 and returns TRUE if a user other than the owner of the key or a member
 of the administrator group can write to the key.
\layout Paragraph

SAM access
\layout Itemize

OpenPipeToSamr(soc, uid, tid) 
\layout Itemize

SamrConnect2(soc, tid, uid, pipe, name) 
\layout Itemize

_SamrEnumDomains(soc, uid, tid, pipe, samrhdl) 
\layout Itemize

SamrDom2Sid(soc, tid, uid, pipe, samrhdl, dom) 
\layout Itemize

SamrOpenDomain(soc, tid, uid, pipe, samrhdl, sid) 
\layout Itemize

SamrOpenBuiltin(soc, tid, uid, pipe, samrhdl) 
\layout Itemize

SamrLookupNames(soc, uid, tid, pipe, name, domhdl) 
\layout Itemize

SamrOpenUser(soc, uid, tid, pipe, samrhdl, rid) 
\layout Itemize

SamrQueryUserGroups(soc, uid, tid, pipe, usrhdl) 
\layout Itemize

SamrQueryUserInfo(soc, uid, tid, pipe, usrhdl) 
\layout Itemize

SamrQueryUserAliases(soc, uid, tid, pipe, usrhdl, sid, rid) 
\layout Subsubsection

smtp_func.inc
\layout Itemize


\series bold 
smtp_send_socket
\series default 

\begin_inset LatexCommand \index{smtp\_send\_socket}

\end_inset 

(socket, from, to, body) 
\newline 
sends a SMTP message on an open socket and returns TRUE if the message for
 accepted for delivery, or FALSE if some problem occured.
\layout Itemize


\series bold 
smtp_send_port
\series default 

\begin_inset LatexCommand \index{smtp\_send\_port}

\end_inset 

(port, from, to, body) 
\newline 
opens a socket to 
\series bold 
port
\series default 
, sends a SMTP message, and closes the socket.
 It returns TRUE if the message for accepted for delivery, or FALSE if some
 problem occured.
\layout Itemize


\series bold 
smtp_from_header
\series default 

\begin_inset LatexCommand \index{smtp\_from\_header}

\end_inset 

() 
\newline 
returns the default 
\begin_inset Quotes eld
\end_inset 

From
\begin_inset Quotes erd
\end_inset 

 address.
 If the KB item 
\series bold 
SMTP/headers/from
\series default 
 is not set, the default address is 
\begin_inset Quotes eld
\end_inset 

nessus@example.com
\begin_inset Quotes erd
\end_inset 

.
\layout Itemize


\series bold 
smtp_to_header
\series default 

\begin_inset LatexCommand \index{smtp\_to\_header}

\end_inset 

() 
\newline 
returns the default 
\begin_inset Quotes eld
\end_inset 

To
\begin_inset Quotes erd
\end_inset 

 adress.
 If the KB item 
\series bold 
SMTP/headers/to
\series default 
 is not set, the default address is 
\begin_inset Quotes eld
\end_inset 

postmaster@[1.2.3.4]
\begin_inset Quotes erd
\end_inset 

 (where 1.2.3.4 is the target host IP).
\layout Itemize


\series bold 
get_smtp_banner
\series default 

\begin_inset LatexCommand \index{get\_smtp\_banner}

\end_inset 

(port) 
\newline 
reads the KB item 
\series bold 
smtp/banner/
\series default 
port and returns it, or if it is not set, connects to the port, reads the
 SMTP banner, stores it into the KB and returns it.
\layout Itemize


\series bold 
smtp_recv_banner
\series default 

\begin_inset LatexCommand \index{smtp\_recv\_banner}

\end_inset 

(socket) 
\newline 
reads lines from the socket and returns the first line that does not started
 with 
\begin_inset Quotes eld
\end_inset 

220-
\begin_inset Quotes erd
\end_inset 

.
\layout Subsubsection

telnet.inc
\layout Itemize


\series bold 
get_telnet_banner
\series default 

\begin_inset LatexCommand \index{get\_telnet\_banner}

\end_inset 

(port) 
\newline 
reads 
\series bold 
telnet/banner/
\series default 
port from the KB and returns it.
 If no value is found, connects to the port, grabs the telnet banner, stores
 it into the KB and returns it.
\layout Itemize


\series bold 
set_telnet_banner
\series default 

\begin_inset LatexCommand \index{set\_telnet\_banner}

\end_inset 

(port, banner) 
\newline 
writes 
\series bold 
banner
\series default 
 into the KB item 
\series bold 
telnet/banner/
\series default 
port
\layout Subsubsection

uddi.inc
\layout Itemize


\series bold 
create_uddi_xml
\series default 

\begin_inset LatexCommand \index{create\_uddi\_xml}

\end_inset 

(ktype,path,key,name) 
\newline 
formats a UDDI XML query, whatever this means.
\newline 

\emph on 
Can anybody write something about this?
\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
newpage
\end_inset 


\layout Section

Hacking your way inside the interpretor
\layout Subsection

How it works
\layout Subsubsection

The parser
\layout Paragraph

The lexical analyzer
\layout Standard

It is written directly in C because flex cannot generate C reentrant code
\begin_inset Foot
collapsed true

\layout Standard

It is able to generate reeentrant C++ code but we do not want to link Nessus
 with C++.
\end_inset 

.
 That's why it is rather crude.
 Anyway, I was surprised to see that according to cachegrind, we do not
 lose much time in it.
 
\newline 
The lexer entry point is the 
\begin_inset Quotes eld
\end_inset 

mylex
\begin_inset Quotes erd
\end_inset 

 function in 
\series bold 
nasl_grammar.y
\series default 
.
 The parser calls it; you are not supposed to do it.
 I mention it because that's where you can add 
\begin_inset Quotes eld
\end_inset 

tokens
\begin_inset Quotes erd
\end_inset 

.
\layout Paragraph

The syntactic analyzer
\layout Standard

It is written in Bison and you 
\emph on 
cannot
\emph default 
 compile it with Yacc, because we use the 
\series bold 
%pure_parser
\series default 
 instruction.
 This generates a reentrant parser, allowing us to handle 
\begin_inset Quotes eld
\end_inset 

includes
\begin_inset Quotes erd
\end_inset 

 very simply
\begin_inset Foot
collapsed true

\layout Standard

OK, a good preprocessor could do it.
 But the fact that 
\begin_inset ERT
status Open

\layout Standard

\backslash 
texttt{include("file.inc");}
\end_inset 

 is a simple instruction allows some interesting things, e.g.
\newline 

\begin_inset ERT
status Open

\layout Standard

\backslash 
texttt{if (!defined
\backslash 
_func("gizmo") include("gizmo
\backslash 
_compat.inc");}
\end_inset 

.
\end_inset 

.
 While reading the source, the parser builds a 
\begin_inset Quotes eld
\end_inset 

syntax tree
\begin_inset Quotes erd
\end_inset 

.
\layout Paragraph

The syntax tree
\layout Standard

You can find a description of the 
\begin_inset Quotes eld
\end_inset 

cell type
\begin_inset Quotes erd
\end_inset 

 in 
\series bold 
nasl_tree.h
\series default 
.
 The only used data type is the 
\series bold 
tree_cell
\series default 
 structure.
 Each cell maybe linked to children cells: from 0 (if it is a leaf) to 4
 (if I remember correctly, only the 
\begin_inset Quotes eld
\end_inset 

for
\begin_inset Quotes erd
\end_inset 

 instruction uses this).
\newline 
For example, this code:
\layout LyX-Code

x = y * 2;
\layout LyX-Code

f(arg1: x);
\layout Standard

will become this tree:
\layout LyX-Code

NODE_INSTR_L
\layout LyX-Code

1: NODE_AFF
\layout LyX-Code

   1: NODE_VAR Val="x"
\layout LyX-Code

   2: EXPR_MULT
\layout LyX-Code

      1: NODE_VAR Val="y"
\layout LyX-Code

      2: CONST_INT Val=2
\layout LyX-Code

2: NODE_INSTR_L
\layout LyX-Code

   1: NODE_FUN_CALL Val="f"
\layout LyX-Code

      1: NODE_ARG Val="arg1"
\layout LyX-Code

         1: NODE_VAR Val="x" 
\layout Subsubsection

The interpretor
\layout Quote

To iterate is human, to recurse is divine.
\layout Standard

The entry point is 
\series bold 
nasl_exec
\series default 
.
 This function takes two arguments (a 
\begin_inset Quotes eld
\end_inset 

lexical context
\begin_inset Quotes erd
\end_inset 

 and a 
\begin_inset Quotes eld
\end_inset 

tree cell
\begin_inset Quotes erd
\end_inset 

) and returns the result another 
\begin_inset Quotes eld
\end_inset 

tree cell
\begin_inset Quotes erd
\end_inset 

, the result of the evaluation of the a 
\begin_inset Quotes eld
\end_inset 

tree cell
\begin_inset Quotes erd
\end_inset 

 in the 
\begin_inset Quotes eld
\end_inset 

context
\begin_inset Quotes erd
\end_inset 

.
 To perform its job, 
\series bold 
nasl_exec
\series default 
 calls itself again and again.
 
\layout Subsubsection

Memory management
\layout Standard

Memory copy is expensive
\begin_inset Foot
collapsed true

\layout Standard

If you do not believe me, run a slow plugin like webmirror.nasl with cachegrind
 and look at the result.
\end_inset 

, memory allocation too.
 So I tried to avoid unnecessary duplications of 
\begin_inset Quotes eld
\end_inset 

cells
\begin_inset Quotes erd
\end_inset 

.
 That's why I implemented a poor man's garbage collector: each 
\begin_inset Quotes eld
\end_inset 

cell
\begin_inset Quotes erd
\end_inset 

 has a reference count.
 
\series bold 
ref_cell
\series default 
 increments it, and 
\series bold 
deref_cell
\series default 
 decrements it.
 Once it reaches 0, the cell is freed
\begin_inset Foot
collapsed true

\layout Standard

And if it becomes negative, the interpretor aborts because this is a serious
 bug! In fact, the reference count becomes negative when the cell is 
\begin_inset Quotes eld
\end_inset 

referenced
\begin_inset Quotes erd
\end_inset 

 too many times (integer roll over).
\end_inset 

.
\newline 
To use, do not try to be smart, just follow a couple of simple rules:
\layout Itemize


\series bold 
nasl_exec
\series default 
 never tries to free its input argument.
\layout Itemize


\series bold 
nasl_exec
\series default 
 returns a value that is 
\begin_inset Quotes eld
\end_inset 

referenced
\begin_inset Quotes erd
\end_inset 

 (i.e.
 ref_count > 0).
 Once you have finished playing with it, you have to 
\begin_inset Quotes eld
\end_inset 

dereference
\begin_inset Quotes erd
\end_inset 

 it.
\layout Itemize

Internal functions should return 
\begin_inset Quotes eld
\end_inset 

referenced
\begin_inset Quotes erd
\end_inset 

 cells.
\layout Subsubsection

Internal functions interfaces
\layout Standard

Every internal function uses the same interface: it reads a 
\begin_inset Quotes eld
\end_inset 

lexical context
\begin_inset Quotes erd
\end_inset 

 on input and returns a 
\begin_inset Quotes eld
\end_inset 

cell
\begin_inset Quotes erd
\end_inset 

.
 The interface is described in details in the next paragraph.
\newline 
The function name and NASL arguments are declared in 
\series bold 
nasl_init.c
\layout Subsection

Adding new internal functions
\layout Subsubsection

Interface
\layout Standard

Every internal function has the same interface:
\layout Itemize

it takes one input argument, a 
\begin_inset Quotes eld
\end_inset 

lexical context
\begin_inset Quotes erd
\end_inset 

.
 The NASL arguments are variables in the context, either 
\begin_inset Quotes eld
\end_inset 

named
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

numbered
\begin_inset Quotes erd
\end_inset 

.
 The context is chained to the calling context.
\layout Itemize

and it returns a 
\begin_inset Quotes eld
\end_inset 

tree cell
\begin_inset Quotes erd
\end_inset 

.
 The returned cell should be 
\begin_inset Quotes eld
\end_inset 

referenced
\begin_inset Quotes erd
\end_inset 

 once; you shouldn't have to do anything as all the cell allocation functions
 set 
\begin_inset Quotes eld
\end_inset 

ref_count
\begin_inset Quotes erd
\end_inset 

 to 1.
\begin_deeper 
\layout Itemize

If you do not want to return a value, returns 
\series bold 
FAKE_CELL
\series default 
.
\layout Itemize

If you want to return a serious error, returns 
\series bold 
NULL
\series default 
.
\end_deeper 
\layout Standard

A simple example:
\layout LyX-Code

tree_cell*
\layout LyX-Code

my_test_function(lex_ctxt* lexic)
\layout LyX-Code

{
\layout LyX-Code

  fprintf(stderr, "My test function was called
\backslash 
n");
\layout LyX-Code

  /* let's look at the context */
\layout LyX-Code

  dump_ctxt(lexic);
\layout LyX-Code

  /* And return nothing (in NASL) */
\layout LyX-Code

  return FAKE_CELL;
\layout LyX-Code

}
\layout Subsubsection

Reading arguments
\layout Standard

The arguments are stored as 
\begin_inset Quotes eld
\end_inset 

named
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

numbered
\begin_inset Quotes erd
\end_inset 

 variables in the context.
 This NASL code:
\layout LyX-Code

f(1, "TWO", a: 33, z: "three");
\layout Standard

will create four variables in the context, two 
\begin_inset Quotes eld
\end_inset 

numbered
\begin_inset Quotes erd
\end_inset 

 and two 
\begin_inset Quotes eld
\end_inset 

named
\begin_inset Quotes erd
\end_inset 

:
\layout Itemize

0   -> 1
\layout Itemize

1  -> "TWO"
\layout Itemize

a -> 33
\layout Itemize

z -> "three"
\layout Standard

To read those arguments, you can use one of those functions:
\layout Itemize

char* 
\series bold 
get_str_var_by_num
\series default 
 (lex_ctxt* lexic, int num)
\newline 
reads the variable and converts it to a string if necessary.
 Do not free the result and do not call the function twice in a row on a
 non-string variable
\begin_inset Foot
collapsed true

\layout Standard

i.e.
 integer or array
\end_inset 

 without copying the result somewhere, as the function returns a pointer
 to a static buffer in this case.
\newline 
If the variable is not initialized or cannot be converted to character,
 NULL is returned.
\layout Itemize

int 
\series bold 
get_int_var_by_num
\series default 
(lex_ctxt* lexic, int num, int default_value)
\newline 
reads the variable and converts it to an integer if necessary.
 
\newline 
If the variable is not initialized or cannot be converted, the default value
 is returned.
\layout Itemize

char* 
\series bold 
get_str_local_var_by_num
\series default 
(lex_ctxt* lexic, const char* name)
\layout Itemize

int 
\series bold 
get_int_local_var_by_num
\series default 
(lex_ctxt* lexic, int num, int default_value)
\layout Itemize

int get_local_var_size_by_name
\layout Itemize

int get_var_size_by_num
\layout Subsubsection

Returning a value
\layout Standard

Returning void is easy: just returns 
\series bold 
FAKE_CELL
\series default 
 (which is currently defined as 
\begin_inset Quotes eld
\end_inset 


\series bold 
(void*)1
\series default 

\begin_inset Quotes erd
\end_inset 

, but this might change).
 To return a value, you have to allocate a cell, reference it once (this
 is automatically done by all the alloc_*cell functions) and put data into
 it.
 Examples:
\layout LyX-Code

tree_cell    *retc;
\layout LyX-Code

char         *p;
\layout LyX-Code

/* return 42 */
\layout LyX-Code

retc = alloc_typed_cell(CONST_INT);
\layout LyX-Code

retc->x.i_val = 42;
\layout LyX-Code

return retc;
\layout LyX-Code

/* return "abcd" */
\layout LyX-Code

retc = alloc_typed_cell(CONST_DATA);
\layout LyX-Code

retc->x.size = 4;
\layout LyX-Code

retc->x.str_val = p = emalloc(5);
\layout LyX-Code

strcpy(p, "abcd");
\layout LyX-Code

return retc;
\layout Subsubsection

Adding your function in nasl_init.c
\layout Standard

Your function is not yet known to the NASL interpretor.
 You have to add it into 
\series bold 
nasl_init.c
\layout Subsubsection

Cave at
\layout Standard

You should be careful not to open security holes with your new C functions.
 Here are examples of potentially dangerous system calls:
\layout List
\labelwidthstring 00.00.0000

open as it allows to read protected files if the argument is not properly
 checked (the Nessus daemon runs as root).
\layout List
\labelwidthstring 00.00.0000

unlink as it allows to delete protected files.
\layout List
\labelwidthstring 00.00.0000

fork as a malicious user may implement a fork bomb.
 More, it breaks the current model, where Nessus controls the son processes.
\layout List
\labelwidthstring 00.00.0000

kill as you might kill system processes if the arguments is not properly
 checked.
\layout Subsection

Adding new features to the grammar
\layout Subsubsection

caveat
\layout Standard

First, if you do not know what 
\begin_inset Quotes eld
\end_inset 

yacc
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

bison
\begin_inset Quotes erd
\end_inset 

 do, how they do it and why, if you ignore what a lexical analyzer is, a
 regular expression or a LALR context-free grammar, a finite state machine
 or a stack automata, just 
\emph on 
don't
\emph default 
 touch the grammar.
\layout Standard


\emph on 
This is important
\emph default 
: the current grammar is clean.
 The precedence of every operator is clearly defined; the grammar has only
 one shift/reduce conflict, the classical 
\begin_inset Quotes eld
\end_inset 

dangling else
\begin_inset Quotes erd
\end_inset 

 ambiguity.
 That's why there is an 
\begin_inset Quotes eld
\end_inset 


\series bold 
%expect 1
\series default 

\begin_inset Quotes erd
\end_inset 

 directive.
 If you modify the grammar and add ambiguities, you are 
\emph on 
not
\emph default 
 supposed to solve them by increasing the expected number of conflicts.
 Do whatever is necessary (and clean) to remove them.
\layout Standard

One last time: if you have never studied language theory and theoretical
 computer science, stop reading here!
\layout Subsubsection

Adding a new operator in the grammar
\layout Subsubsection

Adding a new type to the grammar
\layout Subsection

Checking the result
\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
newpage
\end_inset 


\layout Bibliography
\bibitem [RFC 821]{RFC821}

SMTP protocol...
\layout Bibliography
\bibitem [RFC 854 / STD 8]{RFC854}

Telnet protocol...
\layout Bibliography
\bibitem [RFC 1945]{RFC1945}

Hypertext Transfer Protocol -- HTTP/1.0.
 T.
 Berners-Lee, R.
 Fielding, H.
 Frystyk.
 May 1996.
\layout Bibliography
\bibitem [RFC2246]{RFC2246}

The TLS Protocol Version 1.0.
 T.
 Dierks, C.
 Allen.
 January 1999.
\layout Bibliography
\bibitem [RFC2616]{RFC2616}

Hypertext Transfer Protocol -- HTTP/1.1.
 R.
 Fielding, J.
 Gettys, J.
 Mogul, H.
 Frystyk, L.
 Masinter, P.
 Leach, T.
 Berners-Lee.
 June 1999.
\layout Bibliography
\bibitem [SSL v3]{SSL3}


\begin_inset LatexCommand \htmlurl[SSL 3.0 SPECIFICATION]{http://wp.netscape.com/eng/ssl3/}

\end_inset 


\layout Bibliography
\bibitem [SSL v3 (03/96)]{SSL301}


\begin_inset LatexCommand \htmlurl{http://wp.netscape.com/eng/ssl3/}

\end_inset 

 The SSL Protocol Version 3.0 - Internet Draft - March 1996 (Expires 9/96)
 - Alan O.
 Freier, Netscape Communications; Philip Karlton, Netscape Communications,
 Paul C.
 Kocher, Independent Consultant.
\layout Bibliography
\bibitem [SSL v3 (11/96)]{SSL302}


\begin_inset LatexCommand \htmlurl{http://wp.netscape.com/eng/ssl3/draft302.txt}

\end_inset 

 The SSL Protocol Version 3.0 - November 18, 1996 - Alan O.
 Freier, Netscape Communications; Philip Karlton, Netscape Communications,
 Paul C.
 Kocher, Independent Consultant.
\layout Bibliography
\bibitem [DCE/RPC]{DCERPC}

DCE/RPC over SMB - Luke Kenneth Casson Leighton - Macmillan Technical Publishing
 - ISBN 1-57870-150-3
\the_end
