diff options
Diffstat (limited to 'ndiff/docs/ndiff.xml')
| -rw-r--r-- | ndiff/docs/ndiff.xml | 413 |
1 files changed, 413 insertions, 0 deletions
diff --git a/ndiff/docs/ndiff.xml b/ndiff/docs/ndiff.xml new file mode 100644 index 0000000..bdb953e --- /dev/null +++ b/ndiff/docs/ndiff.xml @@ -0,0 +1,413 @@ +<!-- 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 > /dev/null +if [ -e scan-prev.xml ]; then + ndiff scan-prev.xml scan-$date.xml > 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> |