NSE Version Numbering:
----------------------

o Introduction
o The version numbering scheme
o The proposed interface for NSE


o Introduction:
---------------
Lot of users have requested an automatic way to update NSE scripts [1]
and since lot of new features are added to NSE, updating scripts
without updating Nmap/NSE core can introduce incompatibility errors.

This is an attempt to introduce version numbering to NSE, in order to
identify and load/execute only supported scripts.


o The version numbering scheme:
-------------------------------
As proposed by Patrick [2] the version numbering should be the
revision number in the repository, this will be "automatic".

How to extract the svn revision number:
o Unix/Mac OS X:
  * Releases and tarballs (svn info missing):
  Write the appropriate revision number manually to a file 'svn_revision'
  or use some external shell scripts (nmap-private-dev) to do it.
  This 'svn_revision' file should be distributed with Nmap.

  * SVN info is available (developers):
  Use svn to extract the correct revision number.

  Note: the content of the 'svn_revision' file will take precedence over
  the svn info when determining the appropriate revision number.

  A new shell script 'svn_revision.sh' called by make during build will
  write the svn revision number (NSE version) to the 'nse_version.h' file.
  This file will not be under svn control.


o Windows:
  Need help.


o The proposed interface for NSE:
---------------------------------
o Add a new special script argument to load only the supported scripts.
  The special argument is 'strictnse', if specified then NSE will be in
  the strict mode, which means load only the supported scripts.
  This may change in the future and the default bahaviour of NSE would
  be: "strict mode by default: load only supported scripts".

o Add a new Lua number field to scripts: "nse = $VERSION"
  If this field is specified, and if it's greater than the version
  of the current NSE, then a warnning will be printed and the script
  will be dropped, which means that users must update their Nmap/NSE
  core version, otherwise the script will be loaded normally.
  If NSE is not in the strict mode (no 'strictnse' argument) which is
  *currently* the default behaviour, then this field will be ignored
  (all scripts will be loaded).

  Script writers should use a new NSE version only when their scripts
  need/depend on a new feature that was just added to Nmap/NSE core,
  otherwise using the *same* NSE version that was specified in the Nmap
  release should be fine.
 
  Note:
  Nmap developers will announce on nmap-dev mailing list the revision
  of each committed patch.


o Add a new variable to stdnse.lua "stdnse.VERSION" which contains the
  current NSE version (Lua number), this way scripts can run normally
  and check this variable before requesting an unsupported function or
  behaviour.
  Perhaps we should use the word "REVISION" instead of the word
  "VERSION" ?

  If this variable is nil that means that the build process has failed to
  determin and to write the NSE version, in this case a warning messsage
  will be printed, and all scripts will be loaded normally, no strict
  mode. This should not happen, however we make sure that Nmap and NSE
  don't fail if this happens (to let the possiblity to run other scripts).

o Show or print if the script is *fully* supported by NSE or not.
  Perhaps show this info in the output of the new option --script-help.
  (not implemented).

Notes:
In all these situations when loading scripts Nmap and NSE should not fail.

Updating NSE scripts and libraries will be discussed perhaps in the next
proposal :)

[1] http://seclists.org/nmap-dev/2010/q4/420
[2] http://seclists.org/nmap-dev/2010/q4/694