Nmap Development mailing list archives
Re: NSE Documentation System
From: doug () hcsw org
Date: Sun, 11 May 2008 21:48:46 -0700
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
Current thread:
- NSE Documentation System Patrick Donnelly (May 11)
- Re: NSE Documentation System Patrick Donnelly (May 11)
- Re: NSE Documentation System Eddie Bell (May 11)
- Re: NSE Documentation System Kris Katterjohn (May 11)
- Re: NSE Documentation System doug (May 11)
- Re: NSE Documentation System Fyodor (May 12)