|
AnetTest
utility User guide Contents Imitation
of network application’s work Automatically
calculated values Defining
custom fields in packet Fields with
variable position and size All
commands and special values table Midnight
commander editor for UNIX Context
editor for Windows (www.contexteditor.org) General description
The program
Anettest may be used as a packet generator. It is possible
to generate any packets at channel layer (for Ethernet networks), some types of
packets at network layer (IP protocol), and at application layer (sending data blocks
within TCP session). Descriptions
of packets can be stored in text files or be specified in command line. The
syntax of description is simple enough (field name - value). The fields (format
of packet) are specified in header files (headers). There are some headers provided
for commonly known network protocols. The program allows you to define own headers. Numerical
data types, strings, IP address, MAC addresses are available. The
generation of packets can be alternated with waiting of
others. In the case of waiting a packet mask is used which is based on packet’s
content (an equality condition) but it may also have special conditions: not
equal, greater than, etc. The program
provides a simple but rather flexible language with variable,
branches and cycles. Thus, the statuses of
received packets, their content may be deeply analyzed to determine following
actions. It is
possible to use the program for implementing the automated tests of various
network devices and applications. It is achieved by the ability that after
packet’s description you may specify the requests according to which the packets will be
searched in trace-files or network will be scanned in real time. Generally it
will be possible to generate sets of packets then wait for the reaction of
various network devices and applications caused by these packets and finally
obtain the message “successful test” or the list of discrepancies. It is
possible to use the program as a slightly unusual sniffer.
If you describe a set of packets in a file the program may be a scanner of
network about the presence of specified packets. At a specified interval a report is displayed about the total number and the
intensity of packets of each type. The program
also has several operation modes for network filter (firewall) testing and the
ability of modifying trace-files. Installation
See README file from distribute. It contains recent updates. Home directory
In home folder program will search for "headers" folder,
"samples" folder, "traces" folder with headers, samples and
trace files. For UNIX it's /usr/local/anettest (if not changed during installation). For Windows it's folder from file "registry.reg". If you use another home folder it must be specified by -I option. The
current directory is also home directory (it has the highest priority when
searching for referenced files). Thus if you run program from the folder where
it’s been unpacked to then no problem must be. Base header There is a special header file among headers. Its name is
"base.fws". It will be processed before any file explicitly specified by -f option. All useful global definitions may be contained in this file. General notions
Main interface - by default it’s the first
interface specified by option -d. At this interface
packets will be generated. For some commands just on this interface packets
will be waited by default (command WAIT). It can be changed
by command MI. Packet mask – a part of packet’s description
which will be used while comparing of the packet with anyone accepted on
physical interface or from trace-file. In simple case the mask consists of
those fields for which values have been specified in packet’s description but
it is not always true (see command CLEARMASK, special mask conditions). Only
values of fields from mask will be considered while comparison a packet with
another. More about packet mask… Reception interfaces – physical network interfaces of computer or
trace-files, i.e. packets can be captured in real time or obtained from
specified trace-files. The logic of work does not change. Requests
to packet (as parameters to command SEND
or WAIT) will correspond to each reception interface. For the most of operating
modes reception interfaces – all opened
physical interfaces (go in the same order as they are specified by option -d). In online-test of packet
filter the first opened physical interface becomes the main interface the others will be reception interfaces. Requests to packet – the list of requests like "is
accepted" (ACCEPT, >>), "is not
accepted" (DROP, <<), «has no meaning» (ANY). Can be specified for any packet. Each request corresponds
to one reception interface. The first in the list - for the
first reception interface, the second - for
the second, etc. They are specified optionally as parameters to commands SEND
and WAIT.
It allows program to display summary report about correspondence of those
requests to what actually has happened. Syntax of
the list: <request>:: = “<<” | “>>” | “DROP” | “ACCEPT” | “ANY” <list of requests>:: = { <request> } While
working in multi-interface mode the list
of requests is another. Unique
name of interface – a name used to reference
interface. It may be specified in –d option after symbol #
(eth0#myname). The unique name for trace-file may be specified while its
opening by –c option. Basic operating modes
All options
and work modes are described in Table 1. Further the
review of the basic modes with examples is resulted. Packet generator
For the
generation of packets start the program by one of the next ways: anettest -d eth0 -f packets.fws anettest -d 10.0.0.1 -f packets.fws By means of
option -d
the name of a network adapter for work at channel level may be specified (ex: eth0). It is possible to look at the list of accessible
adapters, using option -i. Instead of adapter’s name it is possible to
specify the corresponding IP-address (as shown in the second case). The
IP-addresses corresponding to adapters can also be obtained by option -i. The
description of packets can be stored in text file which may be specified by
option -f. File packets.fws (the test script) can be like
the following: srcip lpc10 dstip 1.1.1.1 dstport 80 Before
packet’s description it is recommended to include one of header files using
command INCLUDE. Instead of “include
tcp.fws” it would be possible to type simply “tcp”, and program would
try to find a similar header file. The header file “tcp.fws” includes other
header files so that values of all the fields of each network header (Ethernet,
IP, TCP) are initialized by
correct default values, otherwise these values would just be
equal to 0. In the shown example after the inclusion of header file the values
of three fields (with names srcip, dstip, dstport) are changing how it is necessary for concrete packet. Command
SEND generates
the packet described before it. After command SEND it would
be possible to continue the packet description, i.e. change values of some
fields, and then use command SEND again to send the second
packet which is different from the first. More about the syntax of script. In the
program distribute there must be a HEADERS folder with headers of network
protocols. Names of fields of network protocols can be learned by watching
corresponding header files or by using option -k. It is
possible to specify packet’s description directly in command line: anettest -d eth0 tcp dstip 1.1.1.1 dstport 80 In the end
of packet’s description command SEND is automatically added
so it’s not necessary to type it. Word “tcp” means including of header file
(this word is treated as a part of packet’s description in command line). Ex: samples/generate_udp_packet, samples/generate_sequence_packets. See also: options -T
(working with data segments over TCP-sessions), command REP (multiple generation), command PAUSE, command INC (autoincrementing value of some field). Send/receive scenario
Alternation
of sending and receiving packets can be implemented in general operating mode. The program
should be started in usual mode (as packet generator): anettest -d eth0 -f packets.fws To generate
packets use command SEND (without parameters). To wait
packets use WAIT, OR,
WAITALL, SENDWAIT, SENDWAITOTHER. Some of commands just
register packet to wait but do not start waiting. Others just start waiting
packets registered before. Others do both. Waiting continues till any of the
registered packets arrives or timeout expires. Comparing packets is based on mask. RECV commands is more suitable when working with
TCP(UDP) connections. It is
possible to specify a timeout of waiting by command TIMEOUT.
IFR command allows you to determine when timeout happens and run a different
branch. COPYREC
command enables a mode when content of received packet is copied to the buffer
of current packet so then you can run complex code analyzing packet’s content. Results of
waiting of packets that has been added by commands WAIT or OR will be displayed in report which will be displayed upon
program termination. Command CLEARREG typed at the end
of script causes that report not to be displayed. See also PAUSE. Multi-interface mode
Generally
you can use many opened interfaces but only the first one will be generating.
To change generating interface as you want during script execution you need to
enable special mode. It is performed by command EXTENDED. In this
mode main interface can be changed by command MI. This command also automatically
calls EXTENDED when met first time. Requests for packets in this mode must be specified
differently: <request1>:: = “DROP” | “ACCEPT” | “ANY” <request2>:: = “<<” | “>>” <request>:: = (<request1> “ “ <unique name of interface>) | (<request2> [“ “] <unique name of interface>) <list of requests>:: = { <request> } After each
request there must be the unique
name of interface for which request is specified. << and >> may not
be separated by space from unique name. Example:
SEND <<0 >>1 <<2 Similarly requests in command DEFAULTS
and in command WAIT must be specified. Tracing packets
The program
implements one of standard functions of sniffers - tracing packets and
recording to file. The program does not display packet’s description but only
writes down their content in file (a file format libpcap). The physical adapter
(where to trace packets) is specified by option -d. The name of file for
record is specified by option -t. Packets content are fully
stored by default (see also option -s). Example:
anettest -d eth0 -t trace.pcap Note: if
the intensity of packets will be too high during enough big time interval then
some packets might not be registered (are not written down in file).
Nevertheless, the general number of packets accepted on the main interface
which will be displayed at the end of program work, will show the real number
of accepted packets. Total number of packets recieved on first interface = 1 Test reportsBy default
program outputs test reports with status for each packet that has been waited
during script execution. CLEARREG –
clear all statuses info, no report will be displayed, SHOWREP –
display report immediately, LASTRES –
value that holds the general status of last report displayed by SHOWREP: all
match or not. Tcp/udp connectionsUse –T
option to work with tcp connection using system socket. Generally
you can open tcp/udp connection using OPEN command. OPEN tcp “client:1.1.1.1:80#optional_name_of_this_connection” Above connects to server with specified address (waits till connected). OPEN tcp “server:localhost:80” Above binds
to given local address and listens for client connections (waits till
connected). TIMEOUT command may be used to set timeout of waiting for
connection. It works similarly
for udp but without connecting/waiting happening while opening. OPEN udp “client:1.1.1.1:80” OPEN udp “server:localhost:80” Then to send data use data ‘data’ To wait any
data For udp
everything is similar but use udp.data. Use CLOSE
command to close connection. CLOSE name_of_this_connection_specified_while_opening IFR command may be used to check the status of last waiting operation:
ok, error or timeout. See samples/tcp_gateway, samples/http_client, samples/http_server. See also NEWLINEIS command. Scanner mode
The scanner
will display statistics for packets described in script (separated by SEND command), show their intensity (the number of packets and
the amount of data) in real time, displaying periodically reports. This mode is
alternative to “packet filter
test” since there will be displayed information about the conformance of
current state of network and the requests to packets
specified in scenario. As well as in the test of the packet filter packets are divided by command SEND after which it is possible to specify requirements to
packet. Example of start of the
program:
anettest -d eth0 –r -v srcport 22 Program
will show statistic about packets with number of source port = 22. The sniffer
mode is turned on by option -r. The used network adapters
are specified by option -d. Packet’s description may be
specified in command line (like in shown example). It is possible to describe
several packets in file (option -f) then the program will
periodically display statistic for each of packets in the form of the table
(report). While working in this mode not packet’s content but packet mask will be used when comparing packet from
script with some received packet. In the
previous example to the end of packet’s description command SEND
will be added (like in the mode of packet generator). ALL open
physical interfaces specified by option -d will be reception interfaces. Unlike the test of packet filter in sniffer
mode the first network adapter which is specified by option
-d, will be also the first reception
interface (i.e. the first request to packet will
correspond to it). All subsequent adapters will be considered as the second,
the third … reception interfaces. This
difference should be considered while using commands SEND or DEFAULTS. Example: samples/tracing_packets.fws. See also: option -u (changing period of displaying reports). Working with trace files
The program
allows to change trace files (having libpcap format) by special commands. Trace
file can be open by command TRACE. To write down the changed file on disk there
is a command WRITE. After file
opening it is possible to use some simple commands: getpac - loads packet from trace file in
the buffer of currently described packet; setpac - writes down current packet in
file over existing packet; inspac - writes down current packet in
file, inserting a new packet into trace file; delpac - deletes specified packet from
trace file. There is a
command for changing several packets at once: chtrace. Examples: samples/work_with_traces, samples/work_with_traces1. Packet
filter test
It is a
mode for implementing automated tests of various packet
filters. Automatization means that you don’t need for manual review of
sniffer’s output in order to conclude if packets are passed through filter. If the all
used network segments (corresponding to physical interfaces) where it is
necessary to trace packets, are connected to one computer then it’s possible to
implement fast test: while generating packets tracing will be performed. Right
after generation of all packets the result of test will be available (called online-test). If network segments are connected to different
hosts then while packets generating from one host it is necessary to trace
packets on other hosts, recording them in trace-files and then to copy all of
these files on one computer and run offline-test. Both
tests will be described below. The file
with the description of packets which is set through an option-f,
can look so: fasttest // while online-test this command must be specified at the beginning of script INCLUDE tcp tcp.flags = syn dstport http send drop accept dstport ssh send accept drop dstport ftp send drop accept Here three
packets are described. They are separated from each other by the command SEND. The packets differ in the values
of destination TCP-port (dstport). The values of TCP-flags (tcp.flags) are equal
for all the packets. The values of other fields are defined in the included
header file tcp.
After the each command SEND requests for packet (ACCEPT or DROP) are specified. More details about syntax of script are
in other section. The using
of FULLMASK will be explained below. The Offline-test
To
implement the offline-test at first it’s necessary to start sniffers on all
participating hosts, for example: anettest -d eth0 -t trace1.fws anettest -d eth0 -t trace2.fws anettest -d eth0 -t trace3.fws These
sniffers will store any received packets in file. Then start
packet generator on one computer, for example: anettest -f packets.fws -d eth0 Then
collect all the resulted trace-files in one place and perform the direct offline-test: anettest -f packets.fws -c trace1 -c trace2 -c trace3 During the
direct offline-test each of the packets described in the script “packets.fws”
will be searched in the trace-files. While the comparison of packets packet mask
will be used. The result of search is compared with the requests
to packets which have been mentioned earlier. The first request after command SEND will correspond to the file “trace1”, the second and the
third - to the files “trace2” and “trace3”. ACCEPT -
means that the packet must be found in a trace-file, DROP –
not found. Thus, the program checks the conformance of the requests specified in the file “packets.fws”, and
search results for the trace-files. The message “successful test” that all requests are met, or the list of discrepancies will be
displayed. The
offline-test mode is always turned on by option -c. The Online-test
Trace-file
is a special type of reception interface. Files
trace1, trace2, trace3 were the first, second and third reception interfaces. If all of reception interfaces are connected to one host
then it’s possible to perform fast online-test: Only one
start is necessary: anettest -f packets.fws -d eth1#1 -d eth2#2 -d eth3#3 After
symbol # unique number of the interface
is specified. For
implementing such a test at the beginning of script file command FASTTEST must be typed which turns on the
online-test mode. If not to use this command packets from script will be simply
generated. Packets
will be generated from interface eth1 (main interface) and
will be registered on reception interfaces:
eth2, eth3. The first request will correspond to eth2, the second - eth3. In
other operating modes (sniffer mode,
using command WAIT) all open physical interfaces are reception interfaces, i.e. the first
requirement would correspond to eth1. While online-test only there is a shift. During the
test at first sniffers will be started on all opened interfaces, then there
will be an instant generation of all packets from script from the main
interface. After the generation of packets sniffers will be stopped, and there
will be performed the search of packets from script among the packets
registered by sniffers (is similarly to searching in trace-files). Pause
between starting of sniffers and the beginning of generation of packets = 100
ms. Pause
between the termination of generation and sniffers termination = 200 ms. If packets
in the beginning or in the end of script are registered as not accepted (though
actually they are passed through filter either too quickly, or too slowly) try
to increase pauses by command PAUSE,
having inserted it in the beginning or in the end. Reports
The output
of program for any type of test may be like this: Packet on line 10 (./test.fws): accepted (dev 2) Packet on line 14 (./test.fws): dropped (dev 2) Packet on line 19 (./test.fws): accepted (dev 2) For each
found discrepancy the name of file and the line in file are displayed, where
packet’s description was met (more precisely the position of command SEND before which there was packet’s description), the result
of search for the concrete reception interface
(interface number is enclosed in brackets). If unique
number has been specified for interface (in option –d) then it will be
shown (with prefix “dev”), otherwise the consecutive number according to the
order of opening interfaces will be shown (with prefix “sdev”). Command NAME allows to set the name for packet
which will be displayed in report. Command REP allows to specify that must be
received not one but several packets. Remark:
If in the
previous example someone not used the command FULLMASK then while the comparison of packets
there would be considered only those fields whose values are explicitly
specified in the script (they are tcp.flags and dstport). The other fields of tcp header whose values are
specified in the file “tcp.fws” would not participate in the comparison because
the command CLEARMASK is used in standard
header files including tcp header (it has been done for convenience while
working in other operating modes). Thus, it would be possible not to notice
some changes of packet’s content on their way or to treat foreign tcp packets
as own ones. Examples: samples/compare_mode, samples/compare_mode1,
samples/fasttest. Imitation of network application’s work
The imitation
of application's work is performed based on information from a trace-file
(specified by command TRACE). During a test program
imitates the work of one or several network applications sending packets in
strict sequence (following the trace-file) from different physical interfaces
(corresponding to a predefined test configuration – a set of end points). The program
doesn’t only send packets but also can check that other packets from trace-file
are being successfully received. Commonly, packets generation process is
synchronized with receiving process: a packet from trace-file is generated only
if all the previous packets have been received. If they haven’t then after a timeout
last packets are generated again and after several repeated generations the non-received
packets are marked as dropped and the process of generation continues. In requests
to the result of test it is possible to specify what packets should be received
and what are dropped. So you can implement automated tests of sophisticated application
firewalls using prepared complex templates in trace files. Those
packets from trace-file that must be generated or received are specified by end
points: generating and receiving ones. Other packets from trace-file are not
considered at all, which are not covered by an end point. Before
imitation start (command RUN) it is necessary to define some
end points (command EP, header "configSession"),
for example: ep togen 0 srcip first //1 ep torecv 1 srcip first //2 ep togen 1 srcip second //3 ep torecv 0 srcip second //4 The example
above corresponds to the imitation of an interaction between two hosts. The
first packet in trace file must be from the first host, the second packet –
from the second host. The first end point (generating one) indicates that
packets from trace file that have the value of field “srcmac” equal to the
value from first packet must be generated from the interface with unique name =
0. The second end point (receiving one) indicates that the same packets are
expected to be received at the interface with unique name = 1. During
imitation packets from trace-file are traversed consistently. Each generating
end point can send its packet only when all previous packets are accepted by receiving
end points. The first packet from trace-file covered by end point 1 is generated
immediately at interface 0. The second packet covered by end point 3 cannot be
generated untill end point 2 receives the first packet at interface 1. When it
happens the second packet is generated. If not then the first packet is
generated again several times, then marked as dropped and the second packet is
generated. It must be received at interface 0 by end point 4. Each packet
can belong to a single generating end point and a single receiving one. If receiving
end points are not specified packets will be simply generated. If generating
end points are not specified packets will be simply waited and marked as
dropped after timeout. It is
possible to start two parties of imitator on different hosts. The timeout for
the first packet is increased to 3 seconds so after the start of waiting it’s
enough time to start the generation of packets. If you don’t satisfy with 3
seconds then the first packet may be marked as dropped. Configured
test may be started by command RUN. The program
must be started in general mode: anettest -d eth0#0 -d eth1#1 -f session_test.fws After
implementing the first test it is possible to reset the configuration by
command DEFAULTTEST and then configure the next test. If some
intermediate point changes packets on their way (in a priory known manner) it
is possible to use command RM. It may be useful when testing NAT (Network Address Translation). If before
the test it is not known how the intermediate point will change packets, but it
will become known during the test then it is possible to use command ARM (testing NAT). If the
values of some fields of packets do not need to be considered while comparison,
then it is possible to use command CIEVE. Command NUMRET sets the number of repeated
generations. Command TIMEOUT set the timeout before repeated generation. Example:
Trace-file
content: 1 0.000000 194.85.99.33 88.210.60.143 TCP 54840> smtp [SYN] Seq=0 Len=0 WS=1 2 0.013321 88.210.60.143 194.85.99.33 TCP smtp> 54840 [SYN, ACK] Seq=0 Ack=1 3 0.013750 194.85.99.33 88.210.60.143 TCP 54840> smtp [ACK] Seq=1 Ack=1 4 0.030554 88.210.60.143 194.85.99.33 SMTP Response: 220 imap.r-and-k.com ESMTP 5 0.030996 194.85.99.33 88.210.60.143 TCP 54840> smtp [ACK] Seq=1 Ack=37 6 0.032663 194.85.99.33 88.210.60.143 SMTP Command: EHLO xperts1.rtc.ru 7 0.046934 88.210.60.143 194.85.99.33 SMTP Response: 250-imap.r-and-k.com Test
configuration (see command EP): //generating end point 1 ep togen 0 srcip 194.85.99.33 //generating packets for client on interface 0 //generating end point 2 ep togen 2 srcip 88.210.60.143 //generating packets for server on interface 2 //recieving end point 3 ep torecv 2 srcip 194.85.99.33 //waiting packets for client on interface 2 //recieving end point 4 ep torecv 0 srcip 88.210.60.143 //waiting packets for server on interface 0 The same
configuration can be also written so: //generating end point 1 ep togen 0 srcip first //generating packets for client on interface 0 //generating end point 2 ep togen 2 srcip second //generating packets for server on interface 2 //recieving end point 3 ep torecv 2 srcip first //waiting packets for client on interface 2 //recieving end point 4 ep torecv 0 srcip second //waiting packets for server on interface 0 At the
imitation beginning the packet which must be first waited will be found. It is
packet 1 belonging to end point 3. The packet will be waited on interface 2.
Then the packet which must be generated will be found. It is packet 1 belonging
to end point 1. Packet 1
will be generated on interface 0. The following packet which needs to be
generated is packet 2 belonging to end point 2. This packet cannot be
generated, while packet 1 is waited on interface 2. When the packet 1 will be
accepted on interface 2 transition to a following waited packet will be
performed. It is packet 2 belonging to end point 4. After such a transition
packet 2 can be generated by end point 2. If packet 1
is not accepted during timeout on interface 2 then packet 1 will be repeatedly
generated on interface 0. After several repeated generations packet 1 can be
marked as dropped and waiting of packet 2 will be started. Full
content of test script may be the following: trace smtp_client.pcap //generating end point 1 ep togen 0 srcip 194.85.99.33 //generating packets for client on interface 0 //generating end point 2 ep togen 2 srcip 88.210.60.143 //generating packets for server on interface 2 //recieving end point 3 ep torecv 2 srcip 194.85.99.33 //waiting packets for client on interface 2 //recieving end point 4 ep torecv 0 srcip 88.210.60.143 //waiting packets for server on interface 0 run drop 6 // all the packets, since 6 should be dropped Examples: samples/convtest1, samples/convtest2. The
standard configuration for imitation of client-server session is presented in
file headers/configSession.fws. The
standard configuration for imitation of client-server session with NAT between
them - headers/natConfigSession.fws. Configuration
NAT should be stored in file headers/natDefines.fws. Command line
Program return status
If a fatal
error raises then program terminates, returning status = 1. If there
are no fatal errors (test was completed) but specified requests
don’t correspond with test results then returned status = 2. If test is
successfully completed (all requests correspond with
test results) then returned status = 0. Command EXIT enables you to explicitly define the returned status. Anettest script
Script file
is a usual text file which can be edited in any text editor. It is recommended
to create such files with *.fws extension (for example: packets.fws). Comments
are the same as for languages C/C ++, Java. // - the
beginning of comments till the end of line. /* … */ -
comments of any number of lines. Most of
elements must be separated by space. Formal
syntax: <script> ::= { <element of script> } <element of script> ::= <command> | <packet modification> | <variable modification> | <file inclusion> | <field definition> Packet description
Script
works with one packet which consists of content and mask. The content is a sequence of bytes, the mask is a set of
conditions. Packet’s
content is initially filled by 0. Packet mask has no conditions initially, i.e.
corresponds to any packet. You can
modify the packet using several operators: <packet modification> :: = <packet’s content modification> | <packet mask modification> <packet’s content modification> ::= <field’s name> [“=”] <value> Content
modification means specifying some value for some field, ex: srcport = 100 srcport 100 While
content modification packet mask will also change: there will be added a new
condition that the specified field must have the specified value. So the mask
is based on content. If you
include some header file then packet’s content is filled by correct values
which are specified in header. Actually in
script you don’t describe multiple packets but only one packet. Commands SEND and others can simply get the current packet’s content
and mask and then generate it or store in separate buffer. It looks like
describing several packets but next packet inherits the content and mask of
previous. Byte pointerThere is a byte pointer which is used
in different operations. This pointer is initially equal to 0. After a
<packet’s content modification> it will be set just after the field and
will be equal to (field’s position + field’s size). Commands to manage byte
pointer: POS – sets position, PASS – increases pointer, BACK – decreases pointer, CURPOS –
gets current position. Program
also works with packet’s size.
This size may be used, for example, while packet generation. It will be equal
to maximum position of byte
pointer which was fixed from the start of script processing. So by default the
size cannot decrease and next packet cannot be smaller than previous. One
exception works: the size may decrease if the size of higher field decreases.
The higher field is field with maximum position. It may have string type of
value. Ex: tcp.data “hello” tcp.data “hel” SEND // size of this packet will be smaller then size of previous The mask
notion is described later. CLEARHISTORY,
CLEARMASK commands are used to start working as though nothing has been written
before. Simple file inclusion
<file inclusion> ::= <name of file> To include
a file you may not use command INCLUDE but simply type
the name of file. Program will search the specified file. Types
of values
Numbers
By default
numbers are decimal, but while using option -h they will be
hexadecimal. If you want
to explicitly specify the type of number then use 0x prefix for hexadecimal number and dot at the end for
decimal numbers: scrport = 0x8888 // hexadecimal number ethproto = 5. // decimal number ethproto = 5 // decimal number if option –h is not used The size of
hexadecimal number will be determined by its form: ttl = 0x8 // one byte ttl = 0x88 // one byte ethproto = 0x188 // two bytes For big
numbers the number of digits must be even. For decimal
number you don’t need to explicitly specify its size: the size will be
determined by field’s size. srcport 4 // field ‘srcport’ has size = 2, so 4 means the value of two bytes While field
definition you must explicitly specify the size for decimal numbers: .srcport 4s2 // after symbol ‘s’ the size of number is specified IP the address
Examples:
.srcip 1.1.1.1 srcip localhost srcip mycomp srcip www.yandex.ru While field
definition must be used the first format: four numbers
(indicates that the type of field is IP address). Further you can use DNS name. MAC the address
Examples:
.srcmac 11:22:33:44:55:66 srcmac 11-22-33-44-55-66 srcmac 0x112233445566 srcmac 112233445566 While field
definition must be used the first or second formats (indicates that the type of
field is MAC address). Further you can use any format. IPv6 address
ip6.src 1122:3344:5566:7788:99aa:bbcc:ddee:ff00 ip6.src 0:0:0:0:0:0cc:d00:0 DNS the
name is not accepted. Strings
String is a
set of characters enclosed with quotation marks or apostrophes. The
standard escape sequences are available: \r, \n, \’, \”, \t, \a, \b, \x00. If a string
is enclosed with apostrophes then it’s possible to insert references in this
string. The reference is a name of field, variable, substitution (defined by DEFINE or GDEF command) or some special
value which is enclosed with $. ‘value of field = $name$’ The
reference will be replaced by its value: ‘value of field = 2’ If name of
field is referenced then its value is generally obtained from the buffer of
current packet, not received one (only command MES gets it from received
packet). Use command COPYREC to get that value from received packet. Fields with
string type of value don’t have concrete size. So strings of any length may be specified as
value. It may be changed by command SETSIZE. See also
command NEWLINEIS. Automatically calculated values
There are some special fields for which values may be automaticly
calculated. Names of values: IPlen, IPcrc,
IPv6len, TCPcrc, UDPcrc, UDPlen, ICMPcrc. It is possible to specify such values for corresponding fields of network
headers. Ex: ip.crc = IPcrc They are already specified in standart headers, so when generating, for
example, TCP packet it will contain correctly calculated check sums. While calculating some values, program will demand, that certain fields
have been defined. For example, for values IPlen, IPcrc the field with
name ip.ver must be defined. Its position points to beginning of
IP header. The standard ip header (ip.fws) defines this field. Thus you can
build own packets where ip header has not standart position. The position of
redefined ip.ver field (see field definition) must point to actual
position of ip header. It is possible not to use automatic values. If you specify own value then
it will be used: ip.crc = 0 After some
actions (command CLEARHISTORY, command GETPAC) all
automatic values will be marked as no active so they will not be calculated. In
this case after these actions you must again explicitly specify ip.crc = IPcrc ip.len = Iplen For developers
ProtocolsExpert
class is used to calculate such values. IpTcpExpert class is derived from it.
You can implement your own class and add it in ExtendHelper ::
getProtocolsExperts method. Defining custom fields in packet
Sometimes
it is necessary to define new fields for the description of headers of custom network
protocols or simply to redefine the parameters of already known fields. Field’s
parameters: position (as the displacement in bytes from the beginning of
channel level header), size, type (i.e. the type of value). <field definition> ::= “.” <new field’s name> <initial value> Ex: .new_field1 11 // one-byte field, type: decimal number .new_field2 0x1122 // two-byte field, type: hexadecimal number .new_field3 11s2 // two-byte field, 11 in decimal format .new_field4 ‘GET host’ // type: string, size: till the end of data .new_field5 1.2.3.4 // type: IP address .new_field6 22-22-22-22-22-22 // type: MAC address .new_field7 See types of values for more info. The type of field and
its size are defined by specified value. Packet’s content will also change: the
specified value will be written in packet’s buffer. The position of a
newly created field is defined by the current position of byte pointer. After field
definition byte pointer will be increased by
the size of defined field. So it will point to position just after the defined
field. MASK,
OFFSET commands used when a field corresponds to specific bits (see how they used
in headers). See files
in “headers” folder. Fields with variable position and sizeCommands SETPOS,
SETSIZE allow you to set the position and size of a field
later. They may be calculated before. It happens usually during the analysis of
a received packet. After correct position and size are set you can reference
that field and get the corresponding part of packet’s content. .text_field “” int calc_pos = 0 int calc_size = 0 // … // a packet received, calculate its position and size // and store them in calc_pos and calc_size SETPOS text_field calc_pos SETSIZE text_field calc_size PRINTL text_field See
samples/http_parser. If some
field with specified name already exists then its parameters will be rewritten to
correspond to the new definition. Building packet from blocks
Full packet
(packet’s template) consists of several headers of different network protocols.
Program enables you to build such complex templates using prepared headers. Example:
include vlan include ip_header include tcp_header In example
above it’s shown how to build tcp packet with vlan header instead of simple
Ethernet II header (which is defined in standard header “tcp.fws”). Parameters
of fields from standard ip and tcp headers will be redefined. If you are
going to work with different formats of packet in single script then you may
define all variants of format at once. INCLUDE vlan INCLUDE ip_header int ip_header_end = curpos // store the position where ip header ends INCLUDE tcp_header POS ip_header_end // restore the position where ip header ends INCLUDE udp_header Now you can work with tcp and udp packets over vlan. Packet mask
Packet mask
is used while comparing a packet from script with some packet from trace-file
or packet received on physical interface. Mask is a set of conditions and is
based on packet’ content: srcport = 40 // modifies content but also adds condition in mask // that value of srcport must be equal to 40 When new field definition
is processed the mask is similarly changed. Some
special operations with mask are also available: <packet mask modification> ::= <adding a new condition to mask> | <removing condition from mask> <adding a new condition to mask> ::= <field’s name> <comparison qualifier> <value> <comparison qualifier> ::= “!=” | “>” | “<” | “>=” | “<=” <removing condition from mask> ::= <field’s name> [“=”] “any” Example: srcport != 40 // adds condition that srcport must not be equal to 40 srcport > 20 // adds condition that srcport must be greater than 40 srcport >= 20 srcport = any // removes from mask all the conditions related to field srcport Mask is always inherited by packet below in script. However equality conditions for a single field are being overwritten. CLEARMASK command is used to clear the mask so it corresponds to any packet. FILTER command allows you to set fast basic filter (in pcap library
format). See also FULLMASK, FIXMASK, UNFIXMASK. Variables
Variables
are some values stored separately from packet’s content. They may be changed by
special commands and their names may be used in parameters to commands instead
of concrete values. If you need just a simple variable then use this syntax String var1 = ‘’ Int int1 = 0 Hex hex1 = 0x0 // will be displayed as hexedicaimal, any length Variables are generally created by command VAR. VAR (v1, num, 1) This
command also provides some additional options. See its description. Variable may
be associated with some field and the type of variable’s value is the same as the
type of field’s value. In the above example “num” is a field from TCP header
(program knows this field a priory, you don’t need to always include tcp
header). A variable can be set to be auto-updated by a received packet. Value
of field in packet will be copied to variable. See
samples/variables. Created variables
may be modified by commands INCVAR, DECVAR,
MULVAR, DIVVAR. To store
and load variable from file see LOADVAR, WRITEVAR. For
modifying variables you can also use the following syntax: <variable modification> ::= <variable’s name> <operation with variable> <value> <operation with variable> ::= [“=”] | “+=” | “-=” Ex: v1 += 2 // adds 2 to variable v1 -= 4 // subtract 2 from variable v1 = 4 // sets value of variable Conditions and cyclesIF – to
compare any two entities and decide between two branches; IFR –
decide based on status of last waiting command; IFDEF,
IFNDEF – based on the fact whether something was defined by DEFINE (GDEF), CYC – to
make cycle; BREAK –
breaks cycle; RETURN –
break processing of current included file; EXIT –
exits program; Packet’s content analysisTo analyze
a received packet you need at first copy it to buffer of current packet by
COPYREC command or via use of RECV command. After that you can reference a
field by its name and value from received packet will be used. Then use variables and conditions.
Position and size of some fields are not known beforehand and need to be
calculated based on values of other fields. Read here
about it. GOTO –
searches for specified string in packet starting from current position of byte
pointer. GOTOB –
like GOTO but searches backwards. See
samples/http_parser. Command MES
allows you to output received packet content easily but without complex
analysis. Do not try to include header files or use any new field definitions after
receiving a packet as it will overwrite content of received packet. All fields and
variants of packet’s structure must be defined before waiting. See samples/http_parser. System interactionSYSCALL -
to run another program, PLAY – play
wav sound under Windows, BEEP –makes
sound via system speaker, LOADVAR –
read variable from file, WRITEVAR - store
variable in file, GETCH –
wait for key press Miscellaneous commandsNEWLINEIS –
defines what new line is \r\n or \n. DEFINE,
GDEF – define something like constant values with assigned names, in oder to
not write the same string each time, QUIET – do
not display some auxiliary messages on console, CURSIZE –
to get the size of current packet, CURTIME –
to get current time, PRINT,
PRINTL – display message, MES – show
message for each received packet. All commands and special values table
<command> ::= <command’s name> <command’s parameters> Parameters
to command may be enclosed in round brackets. Parameters
to command may be separated by space or by commas. Between the
name of command and its parameters symbol = may be typed.
Integration
with text editors
Text highlighting
|