<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook v4.4//EN"
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<article>
  <artheader>
    <title>Comparing Results</title>
    <author>
      <firstname>Adriano</firstname>
      <surname>Marques</surname>
      <copyright>
        <year>2006</year>
	<holder>Adriano Monteiro Marques</holder>
      </copyright>
    </author>
  </artheader>

  <section>
    <title>Introduction</title>

    <para>The Compare Results Window, is a tool that allows you to compare two
    distinct scan results, highlighting any difference that may occour between
    one to another in a easy to read manner. This feature is intended to let you compare
    two given scans, let's say one made in the morning and other made in the evening, and not
    if in the mean time a given host has left the network, or if a given host is still serving
    on the same port as in the morning, for example. It can be really usefull for network
    administrators, as with regular scans of it's network can be compared to show abnormalities.
    </para>

    <section id="open_instruc">
      <title>Openning Instructions</title>
      <para>To reach the Compare Results Window, make sure that <application>Zenmap</application> 
      is open, and then do one of  the following:</para>

      <procedure>
        <title>Use the key-stroke</title>
	<step>The key-stroke that shows the Compare Results Window is 
	<accel>CTRL + D</accel>.</step>
      </procedure>

      <procedure>
        <title>Single click on the Compare Results Icon in the Main Toolbar</title>
	<step>The Compare Results Icon in the Main Toolbar may differ from theme to theme, but 
	it is always the <guibutton>6th icon counting from left to right.</guibutton></step>
      </procedure>

      <procedure>
        <title>Access from the Main Menu</title>
	<step>Go to the <emphasis>Main Menu</emphasis> (the one on the top of the application),
	<guimenu>File</guimenu>-&gt;<guimenuitem>Compare Results</guimenuitem>.</step>
      </procedure>
    </section>
  </section>

  <section>
    <title>Loaded/Loading Results</title>
    <para>To avoid too much user interaction, and usability problems, 
    <application>Zenmap</application> automatically make available at the <emphasis>Compare 
    Results Window</emphasis> combo boxes, the scan results currently loaded in the 
    main interface. As you may have already noted, scans are loaded separatedly inside scan
    tabs, that are describe with a title that may be the scan result file name, a combination 
    of the Profile Name + Target used in the scan or something else. Thoose scan tabs titles, 
    are used as identifiers that loads the respective scan result for comparison when 
    selected at those combo boxes.</para>

    <para>If one or both of the scan results that you wish to compare are not loaded in 
    <application>Zenmap's</application> main interface, you can compare then by loading then 
    inside the <emphasis>Compare Results Window</emphasis> without the need of closing the
    window, loading the results into scan tabs, and then openning the <emphasis>Compare 
    Results Window</emphasis> again. To load then directly, use the <guibutton>Open</guibutton>
    button that resides on the right of each combo box.</para>

    <para>You may also want to compare results that are not saved into files, but inside the
    <application>Zenmap's</application> search data base. To load those results, you'll have 
    to load then into scan tabs first, and then open the <emphasis>Compare Results 
    Window</emphasis> to compare them. It's a bit cumbersome, but loading then directly 
    from the <emphasis>Compare Results Window</emphasis> would implicate on creating 
    more widgets inside the window and making it more complex, thus lowing it's 
    usability anyway.</para>
  </section>

  <section>
    <title>Comparing Results</title>
    <para>To quickly start comparing two given resuls, simply select the results you wish to 
    compare at the <quote><emphasis>Scan Result 1</emphasis></quote> and 
    <quote><emphasis>Scan Result 2</emphasis></quote> combo boxes. The only thing you 
    should pay attention while selecting the scan results, is that the comparison is 
    done by highlighting what has changed (or is not present) in the second result when 
    compared to the first one. So, if you chage the order of the scan results selection, 
    you'll end up with a different comparison result, that probably won't show what you're 
    looking for.</para>

    <para>If you just want to compare changes on your network, a simple rule that won't let you
    get in trouble always select the older result first, and then the newest one. By following 
    this, you'll get a comparison that shows which hosts has left your network in the mean time,
    or, which ports appeared or disappeared, etc. By selecting the newest one first, you'll have
    a not so usefull comparison.
    </para>
  </section>

  <section>
    <para>Let's say that you have two different scans loaded in <application>Zenmap</application>,
    and you wish to compare then. The first one, called <quote><emphasis>Quick Scan on 
    192.168.204.128</emphasis></quote> is a scan result made 2 days ago, and the second 
    one, called <quote><emphasis>Regular Scan on 192.168.204.128</emphasis></quote> is 
    a just finished scan result. The goal is to verify if something has changed during this
    2 days, like if a service has been put up, or down in the mean while.</para>

    <para>Having those scans already loaded, simply open the <emphasis>Compare Results 
    Window</emphasis>, by following <xref linkend="open_instruc"/> mentioned in the 
    beginning. Doing so, you'll end up with a window like this:</para>

    <screenshot>
      <graphic fileref="screenshots/comparing_results1.png" align="center"/>
    </screenshot>

    <para>The screenshot above shows the appearance of the <emphasis>Compare Results 
    Window</emphasis> running the <quote><emphasis>Compare Mode</emphasis></quote>
    just after it's openning.</para>

    <para>At <emphasis>Scan Result 1</emphasis> combo box, select <quote><emphasis>Quick Scan on 
    192.168.204.128</emphasis></quote> and at <emphasis>Scan Result 2</emphasis>, select 
    <quote><emphasis>Regular Scan on 192.168.204.128</emphasis></quote>. In the moment you 
    finish the selection of the results you want to compare, <application>Zenmap</application>
    detects your choices and generates automatically the comparison result.</para>

    <screenshot>
      <graphic fileref="screenshots/comparing_results2.png" align="center"/>
    </screenshot>

    <para>The <emphasis>Compare Results Window</emphasis> with selected results and the 
    comparison generated automatically by <application>Zenmap</application></para>

    <screenshot>
      <graphic fileref="screenshots/comparing_results3.png" align="center"/>
    </screenshot>

    <para>The same window, now showing the <quote><emphasis>Text mode</emphasis></quote>
    comparison result.</para>
  </section>

  <section>
    <title>The Text Diff Mode</title>

    <para>If you're an old Zenmap user, you won't be surprised with the text mode. But maybe,
    if you are a new user, you will probably be questionning why there is a 
    <quote><emphasis>Text mode</emphasis></quote>, if you've got the <quote><emphasis>Compare 
    mode</emphasis></quote>, that is easier to read and understand. Here goes the answer: 
    The <quote><emphasis>Text mode</emphasis></quote> is the first comparison mode, and it's
    quite usefull in some situations. If you simply want to visually compare two different scans,
    the <quote><emphasis>Compare mode</emphasis></quote> is just what you need. But, if you need
    to report changes and save them for historical purposes, the <quote><emphasis>Text 
    mode</emphasis></quote> will generate for you a text diff that can be copied and pasted
    anywhere. This mode is not so complete as the <quote><emphasis>Compare 
    mode</emphasis></quote>, but it's the only one that you can save for latter analysis. In the 
    future, <application>Zenmap</application> will feature a report generation tool, to ease this
    task.</para>

    <section>
      <title>Reading and Understanding</title>
      <para>The text diff is basically the first result plus extra lines that describes what
      is missing or what has changed in the second one. Those extra lines are marked up with
      symbols that describes what happenned in that part of the text result.</para>

      <table frame="all">
        <title>Text diff symbols and their meanings</title>
	<tgroup cols="2" align="center">
	  <colspec colname="Symbol"/>
	  <colspec colname="Meaning"/>
	  <thead>
	    <row>
	      <entry align="center">Symbol</entry>
	      <entry align="center">Meaning</entry>
	    </row>
	  </thead>
	
	  <tbody>
	    <row>
	      <entry>+</entry>
	      <entry>The line has appeared/changed in the second result</entry>
	    </row>

	    <row>
	      <entry>-</entry>
	      <entry>The line was removed/changed from the first result</entry>
	    </row>

	    <row>
	      <entry>?</entry>
	      <entry>Indicates that this line contains symbols that show what was modified 
	      in the line above</entry>
	    </row>

	    <row>
	      <entry>^</entry>
	      <entry>Indicates what was modified in the line above</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
    </section>

    <section>
      <title>Changing colors</title>
      <para>If you like the colored highlight mode, you may want to change the colors to those
      which you may feel better with, or that may show better in a given situation. Doing so,
      is quite easy and every change is automatically saved, so you'll won't have to worry
      about changing the colors everytime you use this window.</para>

      <para>Click once on the <guibutton><emphasis>Color Descriptions</emphasis></guibutton> 
      button. The folowing dialog will show up:</para>

      <screenshot>
        <graphic fileref="screenshots/comparing_results4.png" align="center"/>
      </screenshot>

      <para>If you're running the <quote><emphasis>Text mode</emphasis></quote>,
      there is only two colors that you may want to change here (as this mode only uses two). 
      Those colors are describe as <emphasis>Property was Added</emphasis> and 
      <emphasis>Property is Not Present</emphasis>. Click once in the button that holds the
      current color you want to change, and a color selection dialog will be shown.</para>

      <para>The colors will be automatically updated as soon as you leave the <emphasis>Color 
      Descriptions</emphasis> dialog.</para>
    </section>
  </section>

  <section>
    <title>The Comparison Mode</title>

    <para>Yet the best comparison mode for quick verification of changes betwen results, this
    mode shows informations that doesn't exist in the regular nmap output. Thus, this mode
    gives you more informations than the text one.</para>

    <section>
      <title>Reading and Understanding</title>

      <para>Reading and understanding this mode is easy and intuitive, as it shows only one
      information (or property) per line, and the symbol before each property describes 
      it's state in the second result. If you have the colored highlight mode enabled, 
      you'll have a more intuitive experience, as you won't have to bother about 
      understanding those symbols.</para>

      <para>Here follows a list of symbols, followed by their meannings:</para>

      <table frame="all">
        <title>Compare mode symbols and their meanings</title>
	<tgroup cols="2" align="center">
	  <colspec colname="Symbol"/>
	  <colspec colname="Meaning"/>
	  <thead>
	    <row>
	      <entry align="center">Symbol</entry>
	      <entry align="center">Meaning</entry>
	    </row>
	  </thead>
	
	  <tbody>
	    <row>
	      <entry>U</entry>
	      <entry>The property remained <emphasis>U</emphasis>nchanged in the second 
	      result.</entry>
	    </row>

	    <row>
	      <entry>A</entry>
	      <entry>The property was <emphasis>A</emphasis>dded in the second result.</entry>
	    </row>

	    <row>
	      <entry>M</entry>
	      <entry>The property was <emphasis>M</emphasis>odified in the second 
	      result.</entry>
	    </row>

	    <row>
	      <entry>N</entry>
	      <entry>The property is <emphasis>N</emphasis>ot present in the second 
	      result.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
    </section>

    <section>
      <title>Changing colors</title>

      <para>If you like the colored highlight mode, you may want to change the colors to those
      which you may feel better with, or that may show better in a given situation. Doing so,
      is quite easy and every change is automatically saved, so you'll won't have to worry
      about changing the colors everytime you use this window.</para>

      <para>Click once on the <guibutton><emphasis>Color Descriptions</emphasis></guibutton> 
      button. The folowing dialog will show up:</para>

      <screenshot>
        <graphic fileref="screenshots/comparing_results4.png" align="center"/>
      </screenshot>

      <para>If you're running the <quote><emphasis>Compare mode</emphasis></quote>, you can
      change any color that you feel like, by clicking in the button that holds the color you
      wish to change, and they will be update as soon as you leave the <emphasis>Color 
      Descriptions</emphasis> dialog.</para>

    </section>
  </section>

  <section>
    <title>Openning in Browser</title>

    <para>If you want to generate a quick HTML report of the generated diff, and view in you 
    default web browser, just click once in the <guibutton><emphasis>Open in 
    Browser</emphasis></guibutton> button. The HTML report holds another diff visualization
    mode, followed by the text one. After openned in the browser, you can simply save it
    for latter view, or historical purposes, if needed.</para>

    <section>
      <title>Known issues</title>
      
      <para>There's a bug that avoids the use of this feature when 
      <application>Zenmap</application> is been executed with <emphasis>sudo</emphasis> in Linux.
      </para>
    </section>
  </section>
</article>