nmap/ndiff/docs/ndiff.xml

<!-- This is the DocBook XML source for the Ndiff manual page. -->

<refentry>
  <refmeta>
    <refentrytitle>ndiff</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>ndiff</refname>
    <refpurpose>Utility to compare the results of Nmap scans</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>ndiff</command>
      <arg choice='opt'>
        <replaceable>options</replaceable>
      </arg>
      <arg choice='req'>
        <replaceable><filename>a.xml</filename></replaceable>
      </arg>
      <arg choice='req'>
        <replaceable><filename>b.xml</filename></replaceable>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>
    Ndiff is a tool to aid in the comparison of Nmap scans. It takes two
    Nmap XML output files and prints the differences between them. The
    differences observed are:
    <itemizedlist>
      <listitem>
        <para>Host states (e.g. up to down)</para>
      </listitem>
      <listitem>
        <para>Port states (e.g. open to closed)</para>
      </listitem>
      <listitem>
        <para>Service versions (from <option>-sV</option>)</para>
      </listitem>
      <listitem>
        <para>OS matches (from <option>-O</option>)</para>
      </listitem>
      <listitem>
        <para>Script output</para>
      </listitem>
    </itemizedlist>
    </para>

    <para>
    Ndiff, like the standard <command>diff</command> utility, compares two scans
    at a time.
    </para>
  </refsect1>

  <refsect1>
    <title>Options Summary</title>

    <variablelist>
      <varlistentry>
        <term><option>-h</option></term>
        <term><option>--help</option></term>
        <listitem>
          <para>
          Show a help message and exit.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-v</option></term>
        <term><option>--verbose</option></term>
        <listitem>
          <para>
          Include all hosts and ports in the output, not only those that
          have changed.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--text</option></term>
        <listitem>
          <para>
          Write output in human-readable text format.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--xml</option></term>
        <listitem>
          <para>
          Write output in machine-readable XML format. The document
          structure is defined in the file
          <filename>ndiff.dtd</filename> included in the distribution.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>
    Any other arguments are taken to be the names of Nmap XML output
    files. There must be exactly two.
    </para>
  </refsect1>

  <refsect1>
    <title>Output</title>

    <para>
    There are two output modes: text and XML. Text output is the
    default, and is also selected with the <option>--text</option>
    option. Text output resembles a unified diff of Nmap's normal
    terminal output. Each line is preceded by a character indicating
    whether and how it changed. <literal>-</literal> means that the line
    was in the first scan but not in the second; <literal>+</literal>
    means it was in the second but not the first. A line that changed is
    represented by a <literal>-</literal> line followed by a
    <literal>+</literal> line. Lines that did not change are preceded by
    a blank space.
    </para>

    <para>
    <xref linkend="ndiff-man-ex-text-output"/> is an example of text
    output.
    </para>

    <example id="ndiff-man-ex-text-output">
      <title>Ndiff text output</title>
<screen>
</screen>
    </example>
  </refsect1>

  <refsect1>
    <title>Example</title>

    <para>
    Using Nmap, Ndiff, cron, and a shell script, it's possible to scan a
    network daily and get email reports of the state of the network and
    changes since the previous scan.
    <xref linkend="ndiff-man-ex-cron"/> shows the script that ties it
    together.
    </para>

    <example id="ndiff-man-ex-cron">
      <title>Scanning a network periodically with Ndiff and cron</title>
<programlisting>
#!/bin/sh
TARGETS="<replaceable>targets</replaceable>"
OPTIONS="-v -T4 -F -sV"
date=`date +%F`
cd /root/scans
nmap $OPTIONS $TARGETS -oA scan-$date &gt; /dev/null
if [ -e scan-prev.xml ]; then
        ndiff scan-prev.xml scan-$date.xml &gt; diff-$date
        echo "*** NDIFF RESULTS ***"
        cat diff-$date
        echo
fi
echo "*** NMAP RESULTS ***"
cat scan-$date.nmap
ln -sf scan-$date.xml scan-prev.xml
</programlisting>
    </example>

    <para>
    If the script is saved as <filename>/root/scan-ndiff.sh</filename>,
    add the following line to root's crontab:
<programlisting>
0 12 * * * /root/scan-ndiff.sh
</programlisting>
    </para>
  </refsect1>

  <refsect1>
    <title>Bugs</title>
    <para>
    Report bugs to the <citetitle>nmap-dev</citetitle> mailing list at
    <email>nmap-dev@insecure.org</email>.
    </para>
  </refsect1>

  <refsect1>
    <title>History</title>

    <para>
    Ndiff started as a project by Michael Pattrick during the 2008
    Google Summer of Code. Michael designed the program and led the
    discussion of its output formats. He wrote versions of the program
    in Perl and C++, but the summer ended shortly after it was decided
    to rewrite the program in Python for the sake of Windows (and
    Zenmap) compatibility. This Python version was written by David
    Fifield.  James Levine <ulink url="http://seclists.org/nmap-hackers/2000/0315.html">released</ulink> a Perl script named Ndiff with
    similar functionality in 2000.
    </para>
  </refsect1>

  <refsect1>
    <title>Authors</title>

    <para>
    David Fifield <email>david@bamsoftware.com</email>
    </para>
    <para>
    Michael Pattrick <email>mpattrick@rhinovirus.org</email>
    </para>
  </refsect1>

  <refsect1>
    <title>Web site</title>

    <para>
    <ulink url="http://nmap.org/ndiff/"/>
    </para>
  </refsect1>
</refentry>