Re: NSE Documentation System

[doug () hcsw org]

Hi Patrick,

Good to hear this project is being tackled. If you're looking for ideas,
you might want to take a quick look at the nuff system. Nuff is a platform
for experimenting with low level network protocols and stands for
"Network Universal Frame Forge":

http://hcsw.org/nuff/

Nuff can parse a program and determine if it does anything that requires
root privileges, whether the program can be chroot()ed or not, etc.
Nuff is written in scheme, not lua, so it has advantages over NSE with
respect to docs (and actually everything else.. *frax ducks* ;). In lisp/scheme
there is a function to parse any lisp program into a regular, queryable data
data-structure. This function is named "read".

All of these pages are generated mechanically from the code:

http://hcsw.org/nuff/code.html
http://hcsw.org/nuff/layers.html
http://hcsw.org/nuff/interfaces.html

The protocol layers code is fed into graphviz:

http://hcsw.org/nuff/nuff-layers.png

The docs are compiled to HTML and can also be compiled to ASCII
"on-demand" with the help command:

$ nuff -help trace
----nuff help for trace----
trace: Parallel, generic traceroute tool

Usage: nuff trace <dest> [options]
  <dest> : Destination Host  Test: (valid-host? x)

Options:
  -mode : Protocol to use  Default: udp  Test: (member x (quote ("udp" "tcp" "icmp")))
  -base : Base port  Default: 33434  Test: (<= 0 x 65535)
  -update : Update interval in seconds  Default: 0.1  Test: (< 0 x)
  -pipeline : Number of queries to do in parallel  Default: 10  Test: (and (integer? x) (>= x 1))
  -max-dist : Maximum distance to probe (in hops)  Default: 32  Test: (and (integer? x) (>= x 1))
  -n : No reverse DNS (numeric output)  Default: OFF
  -timeout : Maximum number of seconds to wait for a response  Default: 2  Test: (and (number? x) (> x 0))
  -retries : Maximum number of retries for a response  Default: 2  Test: (and (integer? x) (>= x 0))

For more information, see "nuff doc code"
----

I think on-demand docs would be handy for NSE if possible. Nuff also has
on-demand help for developers. It can describe protocol layers available:

$ nuff describe ip4
----nuff description of ip4----
ip4 is the nuff layer "Internet Protocol version 4".

REQUIRED ARGUMENTS:
  None.

OPTIONAL ARGUMENTS:
  (-tos "Type Of Service" 0 (<= 0 x 65535))
  (-ipid "IPID" 65535 (<= 0 x 65535))
  (-no-frag "Do Not Fragment Bit")
  (-more-frags "More Fragments Bit")
  (-evil-bit "Evil Bit")
  (-frag-offset "Fragment Offset" 0 (<= 0 x 4095))
  (-ttl "Time To Live" 64 (<= 0 x 255))
  (-proto "Protocol" ip-proto-tcp (<= 0 x 255))
  (-src "Source IP Address" "0.0.0.0" (inet-aton x))
  (-dst "Destination IP Address" "0.0.0.0" (inet-aton x))
  (-data "Data" "" (string? x))

ACCESSORS:
  (tos (getint x 8 8))
  (ipid (getint x 32 16))
  (no-frag (getint x 49 1))
  (more-frags (getint x 50 1))
  (evil-bit (getint x 51 1))
  (frag-offset (getint x 52 12))
  (ttl (getint x 64 8))
  (proto (getint x 72 8))
  (src (inet-ntoa (substring x 12 16)))
  (dst (inet-ntoa (substring x 16 20)))
  (data (substring x (* (getint x 4 4) 4)))

LAYER TRANSITIONS:
  (> (and (>= (strlen x) 20) (= 4 (getint x 0 4))))
  (>icmp4 (if (and (>= (strlen x-data) 4) (= x-proto ip-proto-icmp)) x-data))
  (>udp (if (and (>= (strlen x-data) 8) (= x-proto ip-proto-udp)) x-data))

POST-PROCESSOR:
  ip4 is post-processed by ip4-post
----


and interfaces:

$ nuff describe pcap
----nuff description of pcap----
pcap is the nuff interface "LBNL's Packet CAPture library".

pcap provides a Packet Transport Descriptor in READ-ONLY mode.

Opening pcap interfaces DOES require superuser (root) privileges.

REQUIRED ARGUMENTS:
  None.

OPTIONAL ARGUMENTS:
  (-device "PCAP device to accept packets on" (get-default-pcap-dev) (member x pcap-devs))
  (-filter "PCAP filter string" "" (string? x))
----


Because it is the best language ever invented, lisp makes it look easy. :)
I'm aware that "reflection" can be difficult or impossible in non-lisp
languages but maybe lua is up for it.

Good luck,

Doug

PS. Personally I've never liked documentation systems like javadoc etc that
store parameter docs as comments above the function. That is just moving the
documentation closer to the code and actually changes nothing. You still have
the possibility of forgetting to write the documentation and you still have to
keep it "in sync" every time you change the code. Documentation should BE code.

Attachment: signature.asc
Description: Digital signature

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