RFC: Nping requirements and user interface

["Luis M." <luis.mgarc () gmail com>]

Hi!

It's been a busy week but finally I found the time to work on Nping
requirements, output and command-line interface.

I attach 3 files:

NpingRequirements.txt  : Contains the list of requirements for Nping,
tagged by priority.
NpingCommandLine.txt : Contains the command line syntax specification.
NpingExamples.txt         : Contains the output of some typical usage
examples, thanks to Brandon Enright.

Hopefully, these three files will provide enough information to get an
idea of what to expect from Nping and how it will look like. I'd
appreciate it if some of you had a look at them. Command line syntax is
just a first proposal. I've tried to use nmap-like syntax but I'm sure
there are a lot of things that could be improved. If you come up with
better alternatives, please let me know.

Regards,


Luis.



 








++++++++++++++++++++++++++++++++++
|  NPING COMMAND LINE INTERFACE  |
++++++++++++++++++++++++++++++++++

This document presents Nping's command line interface. All option flags are
provisional. Comments and suggestions are welcome.



Nping 0.0.1-SoC9 ( http://nmap.org/nping )

Usage: nping [Ping Type] [Options] {target specification}

TARGET SPECIFICATION: {See [1]}
  Targets may be specified as hostnames, IP addresses, networks, etc.
  Ex: scanme.nmap.org, microsoft.com/24, 192.168.0.1; 10.0.0-255.1-254
  -iL <inputfilename>: Read targets from list of hosts or networks

PING TYPES:
  -pT, --tcp   : TCP ping mode.
  -pU, --upd   : UPD ping mode.
  -pI, --icmp  : ICMP ping mode.
  -pA, --arp   : ARP ping mode.
  -tr, --traceroute : Traceroute mode (can be used together with TCP/UDP/ICMP 
                      pings, but not with ARP ping)

TCP PING MODE:
   -g, --source-port <portnumber>  : Set source port.
   -p, --dest-port <portnumber>    : Set destination port.
   --seq <seqnumber>               : Set sequence number.
   --flags <flags>                 : Set TCP flags.
   --ack <acknumber>               : Set ACK number.
   --win <size>                    : Set window size.
   --badsum                        : Use a random invalid checksum. 
   --mss <size>                    : Set maximum segment size.
   --ws  <n>                       : Set window scale.
   --sack [To be defined]          : Selective ACK.
   --ts <echo,reply>               : Set timestamp (echo and reply fields).

UDP PING MODE:
   -g, --source-port <portnumber>  : Set source port.
   -p, --dest-port <portnumber>        : Set destination port.
   --badsum                        : Use a random invalid checksum. 

ICMP PING MODE:
  -I3, --dest       : Send "destination unreacheable" messages.
  -I8, --echo       : Send "echo request" messages.
  -I13, --timestamp : Send "timestamp request" messages.
  -I15, --info      : Send "Information request" messages.
  -I17, --netmask   : Send "Netmask request" messages.
  --icmp-code <code>: ICMP code.
  --icmp-id <id>    : Sets field "Identifier" in echo messages (16bits).
  --icmp-seq <n>    : Sets field "Sequence number" in echo messages (16 bits).
  TODO: Add options for all fields required by those ICMP msg types.

ARP PING MODE:
  --sender-mac <mac> : Set sender MAC address.
  --sender-ip  <ip>  : Set sender IP address.
  --target-mac <mac> : Set target MAC address.
  --target-ip  <ip>  : Set target IP address.

ETHERNET OPTIONS:
  --dest-mac   : Set destination mac address. This disables ARP resolution. 
  --source-mac : Set source MAC address.
  --spoof-mac  : Set source MAC address (provides same flag as nmap).

IP OPTIONS:
  --source-ip  : Set source IP address.
  -S,--spoof-ip: Set source IP address. (consistent with --spoof-mac format)
  --dest-ip    : Set destination IP address (used as an alternative to 
                 {target specification} ). 
  --tos <val>  : Set type of service field (8bits).
  --id  <val>  : Set identification field (16 bits).
  --df         : Set Dont Fragment flag.
  --mf         : Set More Fragments flag.
  --ttl <val>  : Set time to live [0-256].
  --badsum-ip  : Use a random invalid checksum. 
  --ip-options S|R [route]|L [route]|T|U ... : Set IP options
  --ip-options hex string                    : Set IP options
  --mtu <len>  : Set MTU. Packets get fragmented if MTU is small enough.
  -f           : Fragment packets.

PAYLOAD OPTIONS:
  --payload <hex string>     : Include TCP/UPD/ICMP payload (if it makes sense).
  --payload-file <filename>  : Get payload from specified file.
  --payload-random <len>     : Include len random bytes as payload.
  --data-length <len>        : Same previous one but with nmap syntax.  (??)


ECHO CLIENT/SERVER:

  -K, --ekey <hex> : Key to be used for encryption/decryption.
  -P, --passphrase : Passphrase to derive an encryption key from.
  --channel-udp <port> : Use an UDP-based side channel (Server:listen on that
                         port, Client: communicate to that port)
  --channel-tcp <port> : Use a TCP-based side channel (Server:listen on that
                         port, Client: communicate to that port)

  CLIENT-ONLY OPTIONS:
    --client         : Run Nping in client mode.
    --interpret      : Interpret received echoes.

  SERVER-ONLY OPTIONS:
    --server         : Run Nping in server mode.
    --echo-link      : Return back: link+net+transport+payload
    --echo-net       : Return back: net+transport+payload
    --echo-trans     : Return back: transport+payload
    --echo-data      : Just return payload.


TIMING AND PERFORMANCE:
  Options which take <time> are in milliseconds, unless you append 's'
  (seconds), 'm' (minutes), or 'h' (hours) to the value (e.g. 30m).
  -T[0-5]               : Set timing template (higher is faster).
  -i, --interval <time> : Adjust delay between probes (hping flag).
  --ping-delay <time>   : Adjust delay between probes(nmap-like flag). (??)
  --host-timeout <time> : Give up on target after this long.
  
MISC:
  -h, --help      : Display help information on stardard output.
  -V, --version   : Display Nping current version number. 
  -c, --count <n> : Stop  after  sending  (and  receiving) n response packets.
  -e, --interface <name> : Use supplied network interface.
  --privileged    : Assume that the user is fully privileged.
  --unprivileged  : Assume the user lacks raw socket privileges.
  --send-eth      : Send packets at the raw ethernet layer.
  --send-ip       : Send packets using raw IP sockets.

OUTPUT:
  -v              : Increment verbosity level by one.
  -v[level]       : Set verbosity level. E.g: -v4
  -d              : Increment debugging level by one.
  -d[level]       : Set debugging level. E.g: -d3
  --quiet         : Sets verbosity and debug level to zero. (Same as -v0 -d0)
  --debug         : Sets verbosity and debug to their highest level.

EXAMPLES:
  nping scanme.nmap.org
  nping --tcp --dest-port 80  --ttl 2 192.168.1.1
  nping --debug --icmp -I17 --ping-delay 2s microsoft.com

SEE THE MAN PAGE FOR MANY MORE OPTIONS, DESCRIPTIONS, AND EXAMPLES





+------------------------------------------------------------------------------+

NOTES:

In places where a port number, an IP address, etc, is expected, it is possible
to specify the word "random", so Nping sets a random value for that option.

E.g:  nping --tcp --dest-port random 192.168.1.1
      nping --udp --source-port random  --source-mac random 207.46.197.32
      nping --arp --sender-ip random --ttl random scanme.nmap.org


In places where a MAC address is expected, it is possible to especify a MAC 
address, a prefix or a vendor name. Missing information will be completed with
random values.

[1] QUESTION: Should we support specification of more than one host? Do we 
    really need to ping more than one host? Nmap is probably more appropriate
    if we want to test multiple hosts. However we have different choices:
       - Send only one packet if more that one host is specified and show 
         the replies.
       - Loop over the target list sending packets and displaying replies.
       - Ping the first target until the user hits CTRL-Z or "count" packets
         have been sent.

+------------------------------------------------------------------------------+









++++++++++++++++++++++++++++++
|  NPING EXECUTION EXAMPLES  |
++++++++++++++++++++++++++++++

This document presents some examples of typical Nping executions, designed
by Brandon Enright.



+----------------------------------------------------+
| BASIC NPING                                        |
+----------------------------------------------------+

$ nping -v --tcp --syn -p 80 --count 2 www.google.com 

Starting Nping 0.0.1-SoC9 ( http://nmap.org/nping ) at 2009-05-11 22:34 UTC
NPING[2] www.google.com (66.102.7.99) with: TCP; flags: S; header: 40; data: 0

REPLY +14ms 66.102.7.99 with TCP; flags: SA; sport 80; ttl 53; rtt 14ms
REPLY +24ms 66.102.7.99 with TCP; flags: SA; sport 80; ttl 53; rtt 10ms

--- www.google.com nping statistic ---
2 packets tramitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 10/12/14 ms

Nping done: 1 IP address (1 host responded) pinged in 24ms






+----------------------------------------------------+
| BASIC NPING ECHO CLIENT                            |
+----------------------------------------------------+

$ nping  -v --client --channel-tcp 1337 --tcp --syn -p 80 --count 2  192.168.1.50

Starting Nping 0.0.1-SoC9 ( http://nmap.org/nping ) at 2009-05-11 22:34 UTC

------------------------------------------------------------
Connected to server on TCP 192.168.1.50:1638
------------------------------------------------------------
NPING[2] with: TCP; flags: S; header: 40; data: 0; ttl 64
REPLY +1ms 192.168.1.50 with TCP; flags: SA; sport 80; ttl 127; rtt 1ms
SERVER SAW 192.168.1.100 TCP; flags; S; header 40; data 0; sport 55322; ttl 63
REPLY +2ms 192.168.1.50 with TCP; flags: SA; sport 80; ttl 127; rtt 1ms
SERVER SAW 192.168.1.100 TCP; flags; S; header 40; data 0; sport 55323; ttl 63

--- 192.168.1.50 nping statistic ---
2 packets transmitted, 2 packets seen by server, 2 packets received 0% packet loss
round-trip min/avg/max = 1/1/1 ms

Nping done: 1 IP address (1 host responded) pinged in 31ms






+----------------------------------------------------+
| BASIC NPING ECHO SERVER                            |
+----------------------------------------------------+

$ nping --debug --server --channel-tcp 1337

Starting Nping 0.0.1-SoC9 ( http://nmap.org/nping ) at 2009-05-11 22:34 UTC

------------------------------------------------------------
Server listening for clients on TCP 0.0.0.0:1337
------------------------------------------------------------
[1] Client 192.168.1.100 connected with sport 36299
[1] Client reports NPING[2] 192.168.1.50:80 with: TCP; flags: S; header: 40; data: 0; ttl: 64
[1] Setting up receive filter "tcp dst port 80"
[1] Got probe[1]: TCP; flags; S; header 40; data 0; sport 55321; ttl 63
[1] Got probe[2]: TCP; flags; S; header 40; data 0; sport 55322; ttl 63
[1] Client 192.168.1.100 finished, disconnected
------------------------------------------------------------

--- server nping statistic ---
2 packets received, 2 packets expected, 0% packet loss

Nping done: 1 client connected. Server ran 100 seconds






+----------------------------------------------------+
| ADVANCED NPING ECHO CLIENT                         |
+----------------------------------------------------+

$ nping  -vv -d --client --channel-tcp 1337 --interpret --tcp --syn -p 80 --count 2 12.34.56.78

Starting Nping 0.0.1-SoC9 ( http://nmap.org/nping ) at 2009-05-11 22:34 UTC

------------------------------------------------------------
Connecting to Nping server TCP 12.34.56.78:1337...    [Done]
Establishing parameters...                            [Done]
Connected to Nping server on TCP 12.34.56.78:1337
------------------------------------------------------------
ECHO Server reports our public IP as 24.131.36.158
   [+] 24.131.36.158 not 192.168.1.100 : Could be behind NAT

NPING[2] with: TCP; flags: S; header: 40; data: 0; ttl 64
REPLY +1ms 12.34.56.78 with TCP; flags: SA; sport 80; ttl 120; rtt 90ms
SERVER SAW 24.131.36.158 TCP; flags; S; header 40; data 0; sport 35322; ttl 200
   [+] 24.131.36.158 not 192.168.1.100 : Could be behind NAT
   [+] sport 35322 not 55322 : could be behind PAT/NAT
   [+] TTL increased : expected decrease, something mangling packets?
   [+] DF bit set : is PMTU on?
REPLY +2ms 192.168.1.50 with TCP; flags: SA; sport 80; ttl 120; rtt 92ms
SERVER SAW 192.168.1.100 TCP; flags; S; header 40; data 0; sport 55323; ttl 63
   [+] 24.131.36.158 not 192.168.1.100 : Could be behind NAT
   [+] sport 35323 not 55323 : could be behind PAT/NAT
   [+] TTL increased : expected decrease, something mangling packets?
   [+] DF bit set : is PMTU on?

--- 12.34.56.78 nping statistic ---
2 packets transmitted, 2 packets seen by server, 2 packets received, 0% packet loss
round-trip min/avg/max = 90/91/92 ms

Nping done: 1 IP address (1 host responded) pinged in 300ms






++++++++++++++++++++++++++++++++
|  NPING PROJECT REQUIREMENTS  |
++++++++++++++++++++++++++++++++

This document presents a list of requirements for the tool Nping that will
be developed during this summer as a project for the program Google Summer of
Code. 

Each requirement is tagged with one of the following tags:

[MustHave]   It definitely must be met.
[ShouldHave] It should be met if providing there is enough time for it.
[CouldHave]  It would be nice to have but it's not essential.
[OnRequest]  It would be added to the todo-list if someone asks for it on the
             list, provides a good reason and some usage scenarios.

+------------------------+
| GENERAL                |
+------------------------+

* Documentation for end-users.........................................[MustHave]
* Documentation of the source code using Doxygen syntax..............[Couldhave]
* Command line interface with well-defined option flags...............[MustHave]
* 6 levels of verbosity (0 to 5)......................................[MustHave]
* 6 levels of debugging information...................................[MustHave]
* Written in C++......................................................[MustHave]
* Run and be tested under Linux.......................................[MustHave]
* Run and be tested under Windows.....................................[MustHave]
* Run and be tested under OS X........................................[MustHave]
* Compile as a single, statically-linked executable..................[CouldHave] 
* Use of libdnet......................................................[MustHave]
* Designed to be integrated into Nmap tarball.........................[MustHave]
* Design to allow easy extension to other protocols...................[MustHave]


+------------------------+
| LINK LAYER             |
+------------------------+
* Raw Ethernet frame generation.......................................[MustHave]
  - Destination MAC address...........................................[MustHave]
  - Spoofed source MAC address........................................[MustHave]
  - Custom Ethertype/Length..........................................[OnRequest]       
  - Invalid CRC32 checksum...........................................[OnRequest]   

* ARP ping............................................................[MustHave]

* Custom ARP packet generation
  - Hardware type....................................................[OnRequest]  
  - Protocol type....................................................[OnRequest]  
  - Hardware length..................................................[OnRequest]  
  - Protocol length .................................................[OnRequest]  
  - Operation .......................................................[OnRequest]  
  - Sender hardware address...........................................[MustHave]
  - Sender protocol address...........................................[MustHave]
  - Target hardware address...........................................[MustHave]
  - Target protocol address...........................................[MustHave]


+------------------------+
| NETWORK LAYER          |
+------------------------+

* Custom IPv4 packet generation.......................................[MustHave]
  - Custom version number............................................[OnRequest]
  - Invalid header lengths...........................................[OnRequest]
  - Type of Service..................................................[CouldHave]
  - Invalid total lengths............................................[OnRequest]
  - Custom Idenfication number......................................[ShouldHave]
  - Do Not Fragment Flag............................................[ShouldHave]
  - More Fragments Flag...............................................[MustHave]
  - Reserved flag....................................................[OnRequest]
  - Incorrect fragment offset........................................[OnRequest]
  - Custom TTL........................................................[MustHave]
  - Custom Protocol number...........................................[OnRequest]
  - Invalid header checksum.........................................[ShouldHave]
  - Spoofed source address............................................[MustHave]
  - Destination address...............................................[MustHave]
  - IP options......................................................[ShouldHave]

* IPv6 packet generation
  - IPv6 support for TCP connect() ping.............................[ShouldHave]
  - IPv6 support for UDP pings......................................[ShouldHave]
  - IPv6 packet generation..........................................[ShouldHave]

* ICMP packet generation..............................................[MustHave]
  - Echo Request......................................................[MustHave]
  - Timestamp request.................................................[MustHave]
  - Information Request...............................................[MustHave]
  - Netmask Request...................................................[MustHave]
  - Redirect........................................................[ShouldHave]
  - Fake Destination Unreachable Message.............................[CouldHave]
  - Fake Echo Reply Message..........................................[OnRequest]
  - Fake Source Quench Message.......................................[OnRequest]
  - Fake Time Exceeded message.......................................[OnRequest]
  - Fake Parameter Problem Message...................................[OnRequest]
  - Timestamp reply..................................................[OnRequest]
  - Information Reply................................................[OnRequest]
  - Netmask Reply....................................................[OnRequest]



+------------------------+
| TRANSPORT LAYER        |
+------------------------+
* Custom TCP packet generation........................................[MustHave]
   - Source port......................................................[MustHave]
   - Destination port.................................................[MustHave]
   - Sequence Number..................................................[MustHave]
   - ACK Number.......................................................[MustHave]
   - Invalid offset values...........................................[OnRequest]
   - Custom data in "Reserved" field.................................[OnRequest]
   - TCP Flags (including CWR and ECE)................................[MustHave]
   - Window size......................................................[MustHave]
   - Invalid checksum.................................................[MustHave]
   - Custom Urgent Pointer...........................................[OnRequest]
   - TCP Options......................................................[MustHave]

* Custom UDP packet generation........................................[MustHave]
   - Source / Dest ports .............................................[MustHave]
   - Incorrect length.................................................[MustHave]
   - Invalid checksum..................................................[MustHave]

+------------------------+
| APPLICATION LAYER      |
+------------------------+
* Custom DNS request generation......................................[CouldHave]


+------------------------+
| Nping ECHO SERVER      |
+------------------------+
* Encrypted communications symmetrict encryption......................[MustHave]
* Use of covert channels to transfer information back 
  to the nping client................................................[CouldHave]
* Echo back layers link+net+transport+payload
* Echo back layers net+transport+payload
* Echo back layerstransport+payload
* Echo back only payload



+------------------------+
| MISCELLANEOUS          |
+------------------------+
* Traceroute mode.....................................................[MustHave] 
  - Traceroute to a TCP port..........................................[MustHave] 
  - Traceroute to a UDP port..........................................[MustHave] 
* Nmap style packet output............................................[MustHave]   



_______________________________________________
Sent through the nmap-dev mailing list
http://cgi.insecure.org/mailman/listinfo/nmap-dev
Archived at http://SecLists.Org