path: root/ndiff/docs/ndiff.xml

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

<refentry>
  <refmeta>
    <refentrytitle>ndiff</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source">Ndiff</refmiscinfo>
    <refmiscinfo class="manual">User Commands</refmiscinfo>
  </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 id="ndiff-man-description">
    <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 id="ndiff-man-options">
    <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 id="ndiff-man-example">
    <title>Example</title>

    <para>
    Let's use Ndiff to compare the output of two Nmap scans that use
    different options. In the first, we'll do a fast scan
    (<option>-F</option>), which scans fewer ports for speed. In the
    second, we'll scan the larger default set of ports, and run an NSE
    script.
    </para>

<screen>
# <userinput>nmap -F scanme.nmap.org -oX scanme-1.xml</userinput>
# <userinput>nmap --script=html-title scanme.nmap.org -oX scanme-2.xml</userinput>
$ <userinput>ndiff -v scanme-1.xml scanme-2.xml</userinput>
-Nmap 5.35DC1 at 2010-07-16 12:09
+Nmap 5.35DC1 at 2010-07-16 12:13

 scanme.nmap.org (64.13.134.52):
 Host is up.
-Not shown: 95 filtered ports
+Not shown: 993 filtered ports
 PORT      STATE  SERVICE VERSION
 22/tcp    open   ssh
 25/tcp    closed smtp
 53/tcp    open   domain
+70/tcp    closed gopher
 80/tcp    open   http
+|_ html-title: Go ahead and ScanMe!
 113/tcp   closed auth
+31337/tcp closed Elite
</screen>

    <para>
    Changes are marked by a <literal>-</literal> or <literal>+</literal>
    at the beginning of a line. We can see from the output that the scan
    without the <option>-F</option> fast scan option found two
    additional ports: 70 and 31337. The
    <filename>html-title</filename> script produced some additional
    output for port 80. From the port counts, we may infer that the fast
    scan scanned 100 ports (95 filtered, 3 open, and 2 closed), while
    the normal scan scanned 1000 (993 filtered, 3 open, and 4 closed).
    </para>

    <para>
    The <option>-v</option> (or <option>--verbose</option>) option to
    Ndiff made it show even the ports that didn't change, like 22 and
    25. Without <option>-v</option>, they would not have been shown.
    </para>
  </refsect1>

  <refsect1 id="ndiff-man-output">
    <title>Output</title>

    <para>
    There are two output modes: text and XML. Text output is the
    default, and can also be 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" xrefstyle="select: label nopage"/>
    is an example of text output. Here, port 80 on the host
    photos-cache-snc1.facebook.com gained a service
    version (<computeroutput>lighttpd 1.5.0</computeroutput>). The host
    at 69.63.179.25 changed its reverse DNS name. The host at
    69.63.184.145 was completely absent in the first scan but came up in
    the second.
    </para>

    <example id="ndiff-man-ex-text-output">
      <title>Ndiff text output</title>
<screen>
-Nmap 4.85BETA3 at 2009-03-15 11:00
+Nmap 4.85BETA4 at 2009-03-18 11:00

 photos-cache-snc1.facebook.com (69.63.178.41):
 Host is up.
 Not shown: 99 filtered ports
 PORT   STATE SERVICE VERSION
-80/tcp open  http
+80/tcp open  http    lighttpd 1.5.0

-cm.out.snc1.tfbnw.net (69.63.179.25):
+mailout-snc1.facebook.com (69.63.179.25):
 Host is up.
 Not shown: 100 filtered ports

+69.63.184.145:
+Host is up.
+Not shown: 98 filtered ports
+PORT    STATE SERVICE  VERSION
+80/tcp  open  http     Apache httpd 1.3.41.fb1
+443/tcp open  ssl/http Apache httpd 1.3.41.fb1
</screen>
    </example>

    <para>
    XML output, intended to be processed by other programs, is selected
    with the <option>--xml</option> option. It is based on Nmap's XML
    output, with a few additional elements to indicate differences. The
    XML document is enclosed in <varname>nmapdiff</varname> and
    <varname>scandiff</varname> elements. Host differences are enclosed
    in <varname>hostdiff</varname> tags and port differences are
    enclosed in <varname>portdiff</varname> tags. Inside a
    <varname>hostdiff</varname> or <varname>portdiff</varname>,
    <varname>a</varname> and <varname>b</varname> tags show the state of
    the host or port in the first scan (<varname>a</varname>) or the
    second scan (<varname>b</varname>).
    </para>

    <para>
    <xref linkend="ndiff-man-ex-xml-output" xrefstyle="select: label nopage"/>
    shows the XML diff of the same scans shown above in
    <xref linkend="ndiff-man-ex-text-output" xrefstyle="select: label"/>.
    Notice how port 80 of
    photos-cache-snc1.facebook.com is enclosed in
    <varname>portdiff</varname> tags. For 69.63.179.25, the old hostname
    is in <varname>a</varname> tags and the new is in
    <varname>b</varname>. For the new host 69.63.184.145, there is a
    <varname>b</varname> in the <varname>hostdiff</varname> without a
    corresponding <varname>a</varname>, indicating that there was no
    information for the host in the first scan.
    </para>

    <example id="ndiff-man-ex-xml-output">
      <title>Ndiff XML output</title>
<screen>
<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<nmapdiff version="1">
  <scandiff>
    <hostdiff>
      <host>
        <status state="up"/>
        <address addr="69.63.178.41" addrtype="ipv4"/>
        <hostnames>
          <hostname name="photos-cache-snc1.facebook.com"/>
        </hostnames>
        <ports>
          <extraports count="99" state="filtered"/>
          <portdiff>
            <port portid="80" protocol="tcp">
              <state state="open"/>
              <a>
                <service name="http"/>
              </a>
              <b>
                <service name="http" product="lighttpd" version="1.5.0"/>
              </b>
            </port>
          </portdiff>
        </ports>
      </host>
    </hostdiff>
    <hostdiff>
      <host>
        <status state="up"/>
        <address addr="69.63.179.25" addrtype="ipv4"/>
        <hostnames>
          <a>
            <hostname name="cm.out.snc1.tfbnw.net"/>
          </a>
          <b>
            <hostname name="mailout-snc1.facebook.com"/>
          </b>
        </hostnames>
        <ports>
          <extraports count="100" state="filtered"/>
        </ports>
      </host>
    </hostdiff>
    <hostdiff>
      <b>
        <host>
          <status state="up"/>
          <address addr="69.63.184.145" addrtype="ipv4"/>
          <ports>
            <extraports count="98" state="filtered"/>
            <port portid="80" protocol="tcp">
              <state state="open"/>
              <service name="http" product="Apache httpd"
                       version="1.3.41.fb1"/>
            </port>
            <port portid="443" protocol="tcp">
              <state state="open"/>
              <service name="http" product="Apache httpd" tunnel="ssl"
                       version="1.3.41.fb1"/>
            </port>
          </ports>
        </host>
      </b>
    </hostdiff>
  </scandiff>
</nmapdiff>]]></screen>
    </example>
  </refsect1>

  <refsect1 id="ndiff-man-periodic">
    <title>Periodic Diffs</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" xrefstyle="select: label nopage"/>
    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 id="ndiff-man-exit-code">
    <title>Exit Code</title>

    <para>
    The exit code indicates whether the scans are equal.
    <itemizedlist spacing="compact">
      <listitem><para>0 means that the scans are the same in all the
      aspects Ndiff knows about.</para></listitem>
      <listitem><para>1 means that the scans differ.</para></listitem>
      <listitem><para>2 indicates a runtime error, such as the failure
      to open a file.</para></listitem>
    </itemizedlist>
    </para>
  </refsect1>

  <refsect1 id="ndiff-man-bugs">
    <title>Bugs</title>
    <para>
    Report bugs to the <citetitle>nmap-dev</citetitle> mailing list at
    <email>dev@nmap.org</email>.
    </para>
  </refsect1>

  <refsect1 id="ndiff-man-history">
    <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="https://seclists.org/nmap-hackers/2000/315">released</ulink> a Perl script named Ndiff with
    similar functionality in 2000.
    </para>
  </refsect1>

  <refsect1 id="ndiff-man-authors">
    <title>Authors</title>

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

  <refsect1 id="ndiff-man-web">
    <title>Web site</title>

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