Updated relevant section in the book concerning the --script switch which may

now use boolean operators.

docs/scripting.xml

@@ -427,31 +427,103 @@ and <literal>vuln</literal>.  Category names are not case sensitive.  The follow
      <varlistentry>
         <term>
           <indexterm><primary><option>--script</option></primary></indexterm>
-          <option>--script <replaceable>script-categories</replaceable>|<replaceable>directory</replaceable>|<replaceable>filename</replaceable>|all</option></term>
+          <option>--script <replaceable>predicate</replaceable>|<replaceable>directory</replaceable>|<replaceable>filename</replaceable></option></term>
 
 <listitem>
 
-<para>Runs a script scan (like <option>-sC</option>) using the comma-separated list of
-script categories, individual scripts, or directories containing
-scripts, rather than the default set. Nmap first tries to interpret the
-arguments as categories, then (if that fails) as files or
-directories. A script or directory of scripts may be specified as an
-absolute or relative path. Absolute paths are used as
-supplied. Relative paths are searched for in the following places
-until found:<indexterm><primary>data files</primary><secondary>directory search order</secondary></indexterm><indexterm><primary>scripts, location of</primary></indexterm>
-<filename>--datadir/</filename>; 
-<filename>$NMAPDIR/</filename>;<indexterm><primary><envar>NMAPDIR</envar> environment variable</primary></indexterm>
-<filename>~/.nmap/</filename> (not searched on Windows);<indexterm><primary sortas="nmap directory"><filename>.nmap</filename> directory</primary></indexterm>
-<literal>NMAPDATADIR</literal>/ or<indexterm><primary>NMAPDATADIR</primary></indexterm>
-<filename>./</filename>.  A <filename>scripts/</filename> subdirectory
-is also tried in each of these.</para>
+<para>
+Turns on the use of NSE for script scanning and specifies the scripts to be
+loaded and possibly run. The argument to --script is a comma seperated list of
+predicates, files or directories of scripts. A predicate is used to load a
+script based on categories or filename. Any one of these comma delimited
+strings is first interpretted as a predicate and then as a file or directory
+if the predicate was not used to load a script.
+</para>
 
-<para>If a directory is specified and found, Nmap loads all NSE
+<para>
+A --script predicate is a case-insensitive boolean equation made up of
+categories, filenames or a filename pattern conforming to a basic pattern. The
+boolean operators are the same as in Lua: <literal>and</literal>,
+<literal>or<literal> and <literal>not</literal>. Using these boolean operators,
+you may form equations that give you tight control over which scripts may be
+run in a flexible and easy manner. Typically, these predicates must be quoted
+in the shell as they often contain spaces or other special shell characters.
+</para>
+
+<para>
+When NSE first attempts to intepret a string as a predicate, each category,
+filename or filename pattern is considered a boolean variable, true or
+false. When this predicate is tested for a script in the script database:
+(1) a category is only true if the script entry
+is of that category; (2) a filename is only true if the
+script entry has the same filename (optionally ignoring the extension);
+or (3) a filename pattern is only true if the script entry in the
+database has a filename that matches the pattern. The category "all" matches
+all script entires. A filename pattern may be expressed using an appropriately
+placed <literal>*</literal> character which expands to 0 or more characters in
+the filename. A couple predicate examples at this point may prove illustrative:
+
+--script "intrusive"
+
+Matches scripts that are under the intrusive category.
+
+--script "all and not intrusive"
+
+Matches scripts all scripts that not under the intrusive category.
+
+--script "safe or http-brute"
+
+Matches scripts that are under the safe category or have the filename
+"http-brute".
+
+--script "discovery or http-*"
+
+Matches scripts that are under the discovery category or have a filename
+beginning with "http-".
+
+--script "(all and not intrusive) or (
+
+You may use parenthesis to force operator associations.  A script predicate
+conforms to a very strict syntax which is included here in ABNF notation:
+
+<programlisting>
+predicate = exp / ("(" exp ")")
+exp       = name / predicate binop predicate / unop predicate
+binop     = "and" / "or"
+unop      = "not"
+name      = %x21-%x27 /
+            %x2A-%x2B /
+            %x2D-%x3A /
+            %x3C-%x7E ; All visible characteres except ',', '(', ')', and ';'
+</programlisting>
+</para>
+
+<para>
+If using the string as a predicate did not result in any files being loaded,
+then NSE finally attempts to interpret the string as a script filename or
+directory. You may specify a script or directory of scripts as an absolute
+or relative path.  Absolute paths are used as supplied. Relative paths are
+searched for in the following places until found:<indexterm><primary>data
+files</primary><secondary>directory search
+order</secondary></indexterm><indexterm><primary>scripts, location
+of</primary></indexterm> <filename>--datadir/</filename>;
+<filename>$NMAPDIR/</filename>;<indexterm><primary><envar>NMAPDIR</envar>
+environment variable</primary></indexterm> <filename>~/.nmap/</filename> (not
+    searched on Windows);<indexterm><primary sortas="nmap
+directory"><filename>.nmap</filename> directory</primary></indexterm>
+<literal>NMAPDATADIR</literal>/
+or<indexterm><primary>NMAPDATADIR</primary></indexterm>
+<filename>./</filename>.  A <filename>scripts/</filename> subdirectory is also
+tried in each of these.
+</para>
+<para>
+If a directory is specified and found, Nmap loads all NSE
 scripts (any filenames ending with <literal>.nse</literal>) from that
 directory. Filenames without the <literal>nse</literal> extension are
 ignored. Nmap does not search recursively into subdirectories to find
 scripts.  If individual file names are specified, the file extension
-does not have to be <literal>nse</literal>.</para>
+does not have to be <literal>nse</literal>.
+</para>
 
 <para>Nmap scripts are stored in a <filename>scripts</filename>
 subdirectory of the Nmap data directory by default (see
@@ -462,7 +534,10 @@ which lists the category or categories in which each script belongs.
 Give the argument <literal>all</literal> to execute all scripts in the
 Nmap script database.</para>
 
-<para>Scripts are not run in a sandbox and thus could accidentally or maliciously damage your system or invade your privacy.  Never run scripts from third parties unless you trust the authors or have carefully audited the scripts yourself.</para>
+<para>Scripts are not run in a sandbox and thus could accidentally or
+maliciously damage your system or invade your privacy.  Never run scripts from
+third parties unless you trust the authors or have carefully audited the
+scripts yourself.</para>
 
 
           </listitem>