Home page logo
/

nmap-dev logo Nmap Development mailing list archives

Re: NSE Documentation System
From: "Eddie Bell" <ejlbell () gmail com>
Date: Sun, 11 May 2008 11:00:41 +0100

I think this will be really useful once it's implemented. Personally I
prefer the luadoc syntax because it's so much cleaner.

The problem with the global approach is that each variable name must
be unique and therefore there is no 'consistent' interface which
burdens the programmer with remembering his/her nomenclature. Even if
the nomenclature is standardised, IMHO, it still comes off as rather
messy.

thanks
  - eddie


2008/5/11 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


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


  By Date           By Thread  

Current thread:
[ Nmap | Sec Tools | Mailing Lists | Site News | About/Contact | Advertising | Privacy ]
AlienVault