hping wiki

Differences for page hping3 API

Current version compared with version Tue May 18 03:55:15 GMT 2004

...
  Hping uses the Tcl language as scripting language to write networking
  and security related applications, test suites, and software prototypes.
  To run hping in scripting mode just run it without arguments.
-  
+ 
   # hping
-  
+ 
  It will display a prompt, and will accept commands from the standard
  input. Here you can write Tcl commands, and use the embedded
  hping command to manipulate, send and receive packets, set filters,
...
  read the interface list and so on.
  
-  
+ 
  To execute an hping script, call the hping program with "exec"
  as first argument followed by the name of the script and
  the arguments.
...
-  
- # hping exec hping.htcl www.hping.org
-  
+ 
+  # hping exec hping.htcl www.hping.org
+ 
  The goal of this document is to describe the API exported by hping
  to the Tcl language. This document aims to be informative, but will
  not cover all the aspects of the API usage: the experienced user
...
  should be able to fully exploit the hping capabilities just reading
  this document and the examples under the 'lib' directory.
-  
+ 
  Note that the API is not yet complete: this document only covers the
  part already implemented in the current CVS version of hping3.
-  
+ 
  Also note that this document currently does NOT cover the hping standard
- library, that is an higher level API build on top of the low-level API
+ library, which is a higher level API build on top of the low-level API
  (for low-level API I mean what's described in this document).
-  
+ 
  ===API basics===
-  
+ 
  The main idea of the hping API is to export a single command for every
  'section' of the facilities provided by hping.
-  
+ 
  The most important command exported is 'hping', this command
  expects a subcommand that specify the operation to perform. The
  following subcommands are currently available:
...
  -> [hping setfield]
  -> [hping delfield]
  -> [hping checksum]
-  
+ -> [hping event]
+ 
  Most are to receive, send, and manage packets, and in general all the
  subcommands of the hping command are about networking.
-  
- ----
-  
-  OVERVIEW
-  
-  Hping uses the Tcl language as scripting language to write networking
-  and security related applications, test suites, and software prototypes.
-  To run hping in scripting mode just run it without arguments.
-  
-  # hping
-  
-  It will display a prompt, and will accept commands from the standard
-  input. Here you can write Tcl commands, and use the embedded
-  hping command to manipulate, send and receive packets, set filters,
-  read the interface list and so on.
-  
-  To execute an hping script, call the hping program with "exec"
-  as first argument followed by the name of the script and
-  the arguments.
-  
-  # hping exec hping.htcl www.hping.org
-  
-  The goal of this document is to describe the API exported by hping
-  to the Tcl language. This document aims to be informative, but will
-  not cover all the aspects of the API usage: the experienced user
-  should be able to fully exploit the hping capabilities just reading
-  this document and the examples under the 'lib' directory.
-  
-  Note that the API is not yet complete: this document only covers the
-  part already implemented in the current CVS version of hping3.
-  
-  Also note that this document currently does NOT cover the hping standard
-  library, that is an higher level API build on top of the low-level API
-  (for low-level API I mean what's described in this document).
-  
-  The plan is to start a Wiki to document hping3 in a collaborative way.
-  
-  --------------------------------------------------------------------------------
-  
-  API BASICS
-  
-  The main idea of the hping API is to export a single command for every
-  'section' of the facilities provided by hping.
-  
-  The most important command exported is 'hping', this command
-  expects a subcommand that specify the operation to perform. The
-  following subcommands are currently available:
-  
-  resolve
-  send
-  sendraw
-  recv
-  recvraw
-  iflist
-  outifa
-  getfield
-  hasfield
-  setfield
-  delfield
-  checksum
-  
-  Most are to receive, send, and manage packets, and in general all the
-  subcommands of the hping command are about networking.
-  
-  --------------------------------------------------------------------------------
-  
-  HPING SUBCOMMANDS
-  
-    hping resolve <hostname>
-  
-  The resolve subcommand translate an host name in its IPv4 address
-  using the DNS system. It is basically a gethostname() wrapper, that
-  just returns its input if <hostname> is already an IP address.
-  
-  Example:
-  
-  hping3.0.0-alpha> hping resolve www.hping.org
-  192.70.106.166
-  
-  --
-  
-  #######################################################
-    hping recv ?-hexdata? <interface> ?timeout? ?count?
-  #######################################################
-  
-  Receive packets as a Tcl list in the APD format. <interface> is
-  the interface from wich to read packets, ?timeout? is an optional
-  argument to set a timeout value in milliseconds, with the
-  exception that a zero timeout means to return as soon as possible
-  the packets that was already in queue when the recv subcommand
-  was called, while a -1 timeout value means to expect forever
-  for packets (no timeout). If ?timeout? is specified, an additional
-  (optional) ?count? parameter can be specified, modifing the recv
-  subcommand behaviour to return as soon as ?count? packets were
-  already received. A special ?count? value of zero means
-  to collect an infinite number of packets (at least until the
-  timeout is not reached).
-  
-  The optional ?-hexdata? switch specify to return packets payload
-  as hex digits instead of quoted strings. To use -hexdata is encouraged
-  for all the applications, but the ones that needs to display packets
-  in a human readable format.
-  
-  For default the timeout is set to -1, and count to 1 (in other
-  words hping will wait forever if no packets are available, but
-  will return when the first packet is received).
-  
-  Examples:
-  
-  # Capture a packet from eth0
-  hping3.0.0-alpha> hping recv eth0
-  {ip(ihl=5,ver=4,tos=02,totlen=58,id=63474,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=6,cksum=9ecb,saddr=192.168.1.6,daddr=213.82.224.41)+tcp(sport=33295,dport=110,seq=2486133764,ack=2745754339,x2=0,off=8,flags=pa,win=5840,cksum=7a69,urp=0)+tcp.nop()+tcp.nop()+tcp.timestamp(val=1021017,ecr=355869116)+data(str=STAT\0d\0a)}
-  
-  # Caputure a packet using the hex format for data payload
-  hping3.0.0-alpha> hping recv -hexdata eth0
-  ip(ihl=5,ver=4,tos=00,totlen=84,id=2435,fragoff=0,mf=0,df=0,rf=0,ttl=49,proto=1,cksum=25be,saddr=216.239.39.99,daddr=192.168.1.6)+icmp(type=0,code=0,id=55048,seq=512)+data(hex=3f565c1b000d7e4008090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f3031323334353637)
-  
-  # Wait for all the packets received in 5 seconds, and print how much they are
-  hping3.0.0-alpha> puts [llength [hping recv eth0 5000 0]]
-  36
-  
-  --
-  
-  ################
-    hping iflist
-  ################
-  
-  The iflist subcommand returns a list of all the available interfaces
-  (with the UP flag set), and information about every interface.
-  Interface informations are returned as a Tcl list, that's
-  an example:
-  
-  hping3.0.0-alpha> hping iflist
-  {lo 16436 {127.0.0.1} {LOOPBACK}} {eth0 1500 {192.168.1.6} {}} 
-  
-  # But this may be more clear:
-  
-  hping3.0.0-alpha> foreach i [hping iflist] {puts $i}
-  lo 16436 {127.0.0.1} {LOOPBACK}
-  eth0 1500 {192.168.1.6} {}
-  
-  # As you can see both the interface addresses and flags are reported
-  # as Tcl lists, in order to deal with multiple-flags and addresses
-  # interfaces. This is an example:
-  
-  hping3.0.0-alpha> foreach i [hping iflist] {puts $i}
-  lo0 33224 {127.0.0.1} {LOOPBACK}
-  xl0 1500 {191.224.144.21 64.238.141.219} {}
-  
-  # The above host has an IPv4 alias for xl0
-  
-  --
-  
-  #########################
-    hping outifa <target>
-  #########################
-  
-  Experienced users will not be satisfied with the iflist subcommand alone.
-  Suppose you want to rewrite the ping program in hping, you need to
-  know what is the interface used to send and receive packets for a given
-  destination. The outifa subcommand does exactly this: it returns the
-  IPv4 address of the outgoing interface for the <target> destination.
-  
-  Assuming there are no bugs nor hyper-strange configurations, the
-  address returned will match at least one of the interface addresses
-  returned with hping iflist. The implementation of this command
-  may not work in all the cases in this beta version of hping.
-  
-  Example:
-  
-  hping3.0.0-alpha> hping outifa www.google.com
-  192.168.1.6
-  hping3.0.0-alpha> hping iflist
-  {lo 16436 {127.0.0.1} {LOOPBACK}} {eth0 1500 {192.168.1.6} {}}
-  
-  # As you can see 192.168.1.6 is the eth0 unique address -- note that
-  # the host is configured with a 192.168.1.1 as default gateway.
-  
-  To write a Tcl procedure that returns the name of the interface
-  with a given address is trivial, such a procedure is included
-  in the hping standard library (hpingstdlib.htcl).
-  
-  --
-  
-  ##################################
-    hping send ?-nocompile? packet
-  ##################################
-  
-  This command is used to send TCP/IP packets. It is able to send
-  packets specified in the same format the command 'hping recv' returns
-  packets, this basically means that you can experiment with
-  'hping recv' in order to undrestand how to send a given packet.
-  Also note that a common pattern with hping3 is to receive
-  packets with 'hping recv', modify this packets in some way
-  and resend with 'hping send'. This makes the creation of scripts
-  to do NAT and all the sort of TCP/IP flow manipulation very easy.
-  
-  In order to send a TCP packet with the SYN flag set to the
-  host www.hping.org one can write:
-  
-  hping3> set target www.hping.org               
-  www.hping.org
-  hping3> set myaddr [hping outifa $target]
-  192.168.1.6
-  hping3> hping send "ip(saddr=$myaddr,daddr=$target,ttl=255)+tcp(sport=123,dport=80,flags=s)"
-  
-  Note that the first two commands are used to get the outgoing interface
-  address. From the example it should be clear that in the hping3 world
-  packets are strings rappresenting different layers of the packet.
-  When a given layer is not specified by the user, hping try to set
-  it at a reasonable value. For instance the user don't need to
-  specify IP and TCP checksums for normal packets because hping will
-  compute it automatically. Of curse to create broken packets it can
-  be useful to specify a checksum field.
-  
-  Working with packets as strings, it is handy to create a packet
-  starting with an empty string, adding a layer at a time: this makes
-  the code very simple to read. For example the previous code to
-  send a packet can be written this way:
-  
-   set target www.hping.org
-   set myaddr [hping outifa $target]
-   set syn {}
-   append syn "ip(saddr=$myaddr,daddr=$target,ttl=255)"
-   append syn "+tcp(sport=123,dport=80,flags=2)"
-   hping send $syn
-  
-  You can cut&paste the code in a file called 'example.htcl', then
-  run it using:
-  
-   hping3 exec example.htcl
-  
-  Note that you can use all the features of Tcl, for example
-  in order to send the same SYN packet with 10 different TTL values
-  it is possible to modify the previous script to obtain this:
-  
-   set target www.hping.org
-   set myaddr [hping outifa $target]
-   for {set ttl 0} {$ttl < 10} {incr ttl} {
-       set syn {}
-       append syn "ip(saddr=$myaddr,daddr=$target,ttl=$ttl)"
-       append syn "+tcp(sport=123,dport=80,flags=2)"
-       hping send $syn
-   }
-  
-  The '-nocompile' optional switch is used to tell hping to don't
-  compile the packet (packet compilation calculate stuff like
-  checksums, tot length, and so on), it is useful in order to
-  send broken packets.
-  
-  --
-  
-  ##################################################
-    hping getfield layer field ?skip? packet
-    hping hasfield layer field ?skip? packet
-    hping setfield layer field value ?skip? packet
-    hping delfield layer field ?skip? packet
-  ##################################################
-  
-  So in hping packets are strings, this makes to work with packets
-  simple, but sometimes to modify a field may require to use
-  string substitution, regexp, or alike, not very clean nor fast,
-  so hping API exports functions to set, read, and test for
-  given fields in given layers.
-  
-  'hping getfield' returns the value of the given 'field' in the given
-  'layer', for 'packets'. For example:
-  
-  hping3> hping getfield ip ttl "ip(saddr=1.2.3.4,daddr=5.6.7.8,ttl=64)"
-  64
-  
-  If the layer does not exists, an empty string is returned.
-  
-  In complex packets the same layer can be present more times,
-  for example an ICMP error message can have its own IP header
-  and the IP header of the quoted packet. In order to specify
-  what is the right layer the 'skip' argument of get/has/set field
-  is used. This argument specify how many layers of the specified
-  type to skip before to get the field value, so to specify a
-  skip value of 1 means to get the field from the second IP layer
-  and so on. Example:
-  
-  hping3.0.0-alpha> set p [hping recv eth0]
-  {ip(ihl=5,ver=4,tos=c0,totlen=58,id=62912,fragoff=0,mf=0,df=0,rf=0,ttl=64,proto=1,cksum=e500,saddr=192.168.1.7,daddr=192.168.1.6)+icmp(type=3,code=3,unused=0)+ip(ihl=5,ver=4,tos=00,totlen=30,id=60976,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=17,cksum=40c9,saddr=192.168.1.6,daddr=192.168.1.7)+udp(sport=33169,dport=10,len=10,cksum=94d6)+data(str=f\0a)}
-  
-  Remember that 'hping recv' returns a Tcl list, for default this list
-  is composed of only one element, but anyway we need to get extract
-  this element from the list:
-  
-  hping3.0.0-alpha> set packet [lindex $p 0]
-  ip(ihl=5,ver=4,tos=c0,totlen=58,id=62912,fragoff=0,mf=0,df=0,rf=0,ttl=64,proto=1,cksum=e500,saddr=192.168.1.7,daddr=192.168.1.6)+icmp(type=3,code=3,unused=0)+ip(ihl=5,ver=4,tos=00,totlen=30,id=60976,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=17,cksum=40c9,saddr=192.168.1.6,daddr=192.168.1.7)+udp(sport=33169,dport=10,len=10,cksum=94d6)+data(str=f\0a)
-  
-  Now 'packet' is set to an ICMP error obtained using netcat to send an UDP packet
-  to a non-bound port. We can ask for the checksum of the first ip layer:
-  
-  hping3.0.0-alpha> hping getfield ip cksum $packet
-  e500
-  
-  If we want the second, we add a 'skip' argument of 1:
-  
-  hping3.0.0-alpha> hping getfield ip cksum 1 $packet
-  40c9
-  
-  A 'skip' value of 0 is valid, and is equivalent to the
-  form without the skip argument.
-  
-  'hping hasfield' is similar to getfield, but just returns 1 if the
-  specified layer/field exists, otherwise 0 is returned.
-  
-  'hping setfield' is used to set a given field in a packet, it returns
-  a new packet with the given field set to the specified value:
-  
-  hping3.0.0-alpha> hping setfield udp sport 2000 $packet
-  ip(ihl=5,ver=4,tos=c0,totlen=58,id=62912,fragoff=0,mf=0,df=0,rf=0,ttl=64,proto=1,cksum=e500,saddr=192.168.1.7,daddr=192.168.1.6)+icmp(type=3,code=3,unused=0)+ip(ihl=5,ver=4,tos=00,totlen=30,id=60976,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=17,cksum=40c9,saddr=192.168.1.6,daddr=192.168.1.7)+udp(sport=2000,dport=10,len=10,cksum=94d6)+data(str=fa)
-  
-  So in order to modify a packet hold in a Tcl variable it is possible
-  to write:
-  
-   set packet [hping setfield udp sport 2000 $packet]
-  
-  'hping setfield' can't add fields, so an attempt to set a non-existent
-  layer/field returns an error.
-  
-  Note that get/has/set field commands are not enough to deal
-  with packets without to use 'regexp', 'regxub', 'split', and so,
-  but other hping commands to directly add/remove layers, add
-  fields, and so on, will be added before the hping3 stable release.
-  
-  Btw, note that field name and values are guaranteed to don't contain
-  a '+', ',', ')', and other similar characters that are used in
-  the syntax to describe packets, so to split packets in layers using
-  + as separator, or to split a layer in fields using ',' as separator
-  is prefrectly legal. Some example:
-  
-  hping3.0.0-alpha> foreach layer [split $packet +] {puts $layer}
-  ip(ihl=5,ver=4,tos=c0,totlen=58,id=62912,fragoff=0,mf=0,df=0,rf=0,ttl=64,proto=1,cksum=e500,saddr=192.168.1.7,daddr=192.168.1.6)
-  icmp(type=3,code=3,unused=0)
-  ip(ihl=5,ver=4,tos=00,totlen=30,id=60976,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=17,cksum=40c9,saddr=192.168.1.6,daddr=192.168.1.7)
-  udp(sport=33169,dport=10,len=10,cksum=94d6)
-  data(str=fa)
-  
-  A more complex example: a Tcl procedure that split a packet in layers
-  and fields.
-  
-  ################################### split.htcl #################################
-  set packet "ip(ihl=5,ver=4,tos=c0,totlen=58,id=62912,fragoff=0,mf=0,df=0,rf=0,ttl=64,proto=1,cksum=e500,saddr=192.168.1.7,daddr=192.168.1.6)+icmp(type=3,code=3,unused=0)+ip(ihl=5,ver=4,tos=00,totlen=30,id=60976,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=17,cksum=40c9,saddr=192.168.1.6,daddr=192.168.1.7)+udp(sport=33169,dport=10,len=10,cksum=94d6)+data(str=f\0a)"
-  
-  foreach layer [split $packet +] {
-      set t [split $layer ()]
-      set name [lindex $t 0]
-      set fields [lindex $t 1]
-      puts $name
-      foreach field [split $fields ,] {
-          puts "  $field"
-      }
-      puts {}
-  }
-  ################################################################################
-  
-  This script produce the following output:
-  
-  ip
-    ihl=5
-    ver=4
-    tos=c0
-    totlen=58
-    id=62912
-    fragoff=0
-    mf=0
-    df=0
-    rf=0
-    ttl=64
-    proto=1
-    cksum=e500
-    saddr=192.168.1.7
-    daddr=192.168.1.6
-  
-  icmp
-    type=3
-    code=3
-    unused=0
-  
-  ip
-    ihl=5
-    ver=4
-    tos=00
-    totlen=30
-    id=60976
-    fragoff=0
-    mf=0
-    df=1
-    rf=0
-    ttl=64
-    proto=17
-    cksum=40c9
-    saddr=192.168.1.6
-    daddr=192.168.1.7
-  
-  udp
-    sport=33169
-    dport=10
-    len=10
-    cksum=94d6
-  
-  data
-    str=fa
-  
-  You can create your own procedure to deal with packets, but eventually
-  the interface that seems the more useful will be included in the
-  hping standard library. Two functions to convert hping APD packets
-  to Tcl lists, and the reverse are already included in the hping standard
-  library. Check for 'apd2list' and 'list2apd'. That's how they works:
-  
-  # Get a packet...
-  hping3.0.0-alpha> set p [lindex [hping recv eth0] 0]
-  ip(ihl=5,ver=4,tos=00,totlen=52,id=28845,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=6,cksum=bb46,saddr=192.168.1.5,daddr=192.168.1.6)+tcp(sport=3733,dport=4662,seq=2054230415,ack=1135045853,x2=0,off=8,flags=a,win=63700,cksum=a509,urp=0)+tcp.nop()+tcp.nop()+tcp.timestamp(val=6860018,ecr=13978115)
-  
-  # Convert it to a Tcl list
-  hping3.0.0-alpha> apd2list $p
-  {ip {ihl 5} {ver 4} {tos 00} {totlen 52} {id 28845} {fragoff 0} {mf 0} {df 1} {rf 0} {ttl 64} {proto 6} {cksum bb46} {saddr 192.168.1.5} {daddr 192.168.1.6}} {tcp {sport 3733} {dport 4662} {seq 2054230415} {ack 1135045853} {x2 0} {off 8} {flags a} {win 63700} {cksum a509} {urp 0}} tcp.nop tcp.nop {tcp.timestamp {val 6860018} {ecr 13978115}}
-  
-  With the Tcl list representation we can do what we like, than go back
-  to the more human friedlty representation:
-  
-  hping3.0.0-alpha> list2apd $list
-  ip(ihl=5,ver=4,tos=00,totlen=52,id=28845,fragoff=0,mf=0,df=1,rf=0,ttl=64,proto=6,cksum=bb46,saddr=192.168.1.5,daddr=192.168.1.6)+tcp(sport=3733,dport=4662,seq=2054230415,ack=1135045853,x2=0,off=8,flags=a,win=63700,cksum=a509,urp=0)+tcp.nop()+tcp.nop()+tcp.timestamp(val=6860018,ecr=13978115)
-  
-  Simple, isn't it?
-  
-  Btw, note that for most scripts you don't need to perform this kind of
-  stuff, the hping native representation try to balance between the
-  human and computer vision of packets.
-  
-  Finally, 'hping delfield' is able to remove the given layer/field
-  from the packet. This is very useful in order to resend a packet
-  got with 'hping recv': before to resend it we often need to remove
-  the checksum fields from ip/udp/tcp/icmp layers so hping will
-  recompute it again.
-  
-  --
-  
-  ###############################################
-    hping recvraw ifname ?timeout? ?maxpackets?
-  ###############################################
-  
-  'hping recvraw' works exactly like 'hping recv', but packets
-  are returned as raw binary data. This is useful for low-level
-  access to packets using the 'binary' Tcl command.
-  
-  This will be more useful once the commands 'hping build' and 'hping describe'
-  commands will be added (for APD -> binary, binary -> APD conversion).
-  
-  Example:
-  
-  hping3.0.0-alpha> string length [hping recvraw eth0]
-  1540
-  
-  --
-  
-  ######################
-    hping sendraw data
-  ######################
-  
-  Send binary data: that's like to call write(2) against a raw socket.
-  It can be used in order to build special packets that can't be
-  specified using the usual string representation (APD, from Ars Packet
-  Description), but will be more useful once all the hping output
-  operation will be able to handle layer-2. For now hping3's business
-  is only at layer-3.
-  
-  + Click on the links to have more information about every specific command.
+ 
+ 
+ See also [hpingstdlib.htcl] for functions included in the standard library.
+ 
+ 
+ See also [Parsing APD fields].

The following is the old page content