NSE Documentation System

["Patrick Donnelly" <batrick.donnelly () gmail com>]

Last Wednesday, Fyodor, David Fitfield, Philip Pickering, Diman
Todorov, and I went over what the NSE documentation system should
offer and what it should look like in scripts. Right now it looks like
I will implement a system (probably in Lua) which will read your
scripts as a regular Lua file and inspect globals that document your
script. The system will then create a html file that can be attached
to the script that can serve as both an API for other script
developers or as a "readme" for script users. A second system will
also make an xml version for inclusion with nmap's documentation
system.

The syntax _could_ look something like this:

----- SQLInject.nse ------

_PURPOSE = [[
Experimental SQL injection spider
---------------------------------
Spiders a http server looking for URLs containing queries.
It then proceeds to combine crafted sql commands with
susceptible urls in order to obtain errors. The errors
are analysed to see if the url is vulnerable to attack.
This uses the most basic form of SQL injection but anything
more complication is more suited to a stand alone tool.
Both meta and http redirects are supported.

It is not advisable to run this against unknown hosts.]]

_CAUTION = [[

* We may not have access to the servers true hostname.
 This means we cannot access virtually hosted sites and
 cannot follow absolute links when the hostname is
 different from the resolved ip address]]

require('url')
...

id = "sql-inject"
author = "Eddie Bell <ejlbell () gmail com>"
description = "spiders a http server looking for URLs containing queries \
       and tries to determines if they are vulnerable to injection attack"
license = "Same as Nmap--See http://nmap.org/book/man-legal.html";
categories = {"vulnerability"}
runlevel = 1.0

_GET_PAGE_PURPOSE = [[
Download a page from host:port http server. The url is passed
straight to the get request, so shouldn't include the domain name]]

_GET_PAGE_PARAM1 = "Host to scan"
_GET_PAGE_PARAM2 = "Port on host"
_GET_PAGE_PARAM3 = "The url of the page to get"

local function get_page(host, port, httpurl)
   local lines = ""
   local status = true
   local response = ""
   ...
end

----- / SQLInject.nse ------

Of course "get_page" would be considered private (and would be
reflected in the documentation).

Another possible syntax for the documentation is through comments
using something similar to LuaDoc (http://luadoc.luaforge.net):

--- Define special sequences of characters.
-- For each pair (find, subs), the function will create a field named with
-- find which has the value of subs.
-- It also creates an index for the table, according to the order of insertion.
-- @param subs The replacement pattern.
-- @param find The pattern to find.
function def_escapes (find, subs)
 ...
end

As this system will be used by you guys (the script authors), I'd like
your input regarding which you prefer, other possible tags for the
documentation, what you would like to see, etc.

-- 
-Patrick Donnelly

"One of the lessons of history is that nothing is often a good thing
to do and always a clever thing to say."

-Will Durant

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