# The &knmap; Handbook

## Introduction

This program is a complete re-write of one by the same name written by Alexandre Sagala. The last version of that program was 0.9 which was released on 2003-03-09 and targeted the KDE 2.2 and QT 2.3 environments. Unfortunately it does not compile on today's KDE / QT environments.

Not to mention that it did not cater for the full set of `nmap` options. Or, perhaps, `nmap` progressed whilst that version of Knmap languished.

The icons used in this application are from the Open Clip Art Library. I am indebted to those damn fine folk as my artistic ability is zero - which is marginally above my programming ability. :-(

Version 1.0 of &knmap; was merely a re-write of the original. Version 2.0 adds the extra functionality of multiple concurrent `nmap` scans from within the one instance of &knmap;. Version 2.1 allows a normal (non-root) user to use the privileged nmap functions via to 'kdesu' utility. (Previously, the privileged options were only available if &knmap; was run by root.)

## Using &knmap;

It is assumed that you are familiar with the operation of `nmap`.

If your aren't, then please refer to `nmap(1)` or any other resource you can lay your hands on. This document is all about how to use &knmap; as a front end to `nmap`.

This following screenshot shows an actual run of `nmap` under the control of &knmap;. The main &knmap; window is divided into two partitions - the Index Window on the left and (a stack of) Scan Windows on the right. Each Scan Window is composed of three partitions - from top to bottom: the Options Window, the Button Bar, and the Output Window.

The following sections contain screenshots that describe the contents of the various components of &knmap;'s main window. In the main, the contents of the Scan Window should be self-explanatory for readers familiar with `nmap`

### Index Window

This window contains the names of all Scan Windows - with the current entry highlighted (in the KDE "Alternate Background in Lists" colour). When a scan is active, the entry for that scan will flash. When the scan has completed, if that scan is not the current entry, then the entry will be highlighted in the KDE "Selected Background" colour.

Left clicking on an entry will display the Scan Window for that scan. The caption of the &knmap; main window will be updated to show the name of the scan and its associated profile.

Entries can be manipulated via options in the "File" menu and via a RMB Context Menu. The order of the entries can be changed by dragging individual entries (multiple entries cannot be dragged concurrently).

Scans for which the "Use target host name" property is active will have an asterisk displayed before their name.

### Output Window

As its name implies, this window displays the output of an `nmap` scan. As can be seen from the previous screenshot, the text appearance varies. The following list explains how each type of output is displayed.

Standard Input

- No font modifiers.

Standard Output

- Text is displayed in bold-face font.

Standard Error

- Text is displayed in bold-face, italic font.

### Button Bar

This row of buttons control the operation of &knmap;. The following screenshot shows the button row in its normal state.

The `Start nmap` and `Stop nmap` buttons should require no explanation. (No - I wont now launch into a multi-thousand word explanation of the bloody obvious.)

The `Clear output` button does just that - deletes all the text in the Output Window.

The `Hide options` button can be used to enlarge the Output Window so as to reduce scrolling as shown in the following screenshot. The text of the button reflects the state of the Options Window.

### Common Options

This screenshot shows the `nmap` options that are common to most network scans.

New data range

- The range of ports are entered here in the format specified in the `nmap` man page for the `-p` parametere, BUT without the protocol specifier.

Protocol

- Select the protocol(s) for the port list shown in the input area. Note that the list of ports can contain a combination of protocols. &knmap; will ensure that the port ranges do not overlap.

Add

- As soon as data has been entered in the input area, the `Add` button will be activated. Pressing this button will cause &knmap; to read the input and, if, valid, add it to the list of existing port ranges.

Delete

- To delete a port range, double click on the entry in the list. That entry will be copied to the input area, the `Protocol` combo box updated to reflect the selected entry and the `Delete` button will be activated.

  If the button is then pressed, the input area will NOT be cleared and the `Add` button will be activated. The allows for the port range to be added back into the list if the deletion was performed in error.

### Compound Options

This screenshot shows those `nmap` options that require a value. The associated input area is activated when the option is activated. Options preceded by a hash (#) require root privileges. When the "Start nmap" button is pressed, the 'kdesu' facility will be invoked to run nmap as the super user.

### Logging Options

This screenshot shows the `nmap` options that relate to logging.

&knmap; considers the `--resume` option to be a logging option as its use requires that logging was enabled in the interrupted scan.

### `man` Page

&knmap; comes packaged with the `man` page for `nmap` version 3.93 in HTML format. See the Settings -> `man` page stylesheet... menu option for how to control the appearance of this documentation and the Settings -> Zoom in / out / custom options for controlling the size..

### Ping and Scan Options

This screenshot shows the `nmap` options that control the types of ping and scans that will be performed. Options preceded by a hash (#) require root privileges. When the "Start nmap" button is pressed, the 'kdesu' facility will be invoked to run nmap as the super user.

### Simple Options

This screenshot shows the boolean `nmap` options, i.e., those options that do not require a value. Options preceded by a hash (#) require root privileges. When the "Start nmap" button is pressed, the 'kdesu' facility will be invoked to run nmap as the super user.

### Timing Options

This screenshot shows the `nmap` options that control the timing of network activity. Note that the `Default` does nothing. It is provided as a means to disable the other timing options.

## Command Reference

### The &knmap; Menu Options

#### The File Menu

&Ctrl;S File Save

- Saves the current content of the Output Window. Note, however, that all text formatting is lost. If you don't like this - tough. Go tell someone that gives a shit!

File Save As...

- Given the above explanation of what "File -> Save" does, this option should need no further explanation.

&Ctrl;N File New scan...

- Creates a new Scan Window. The dialog box shown below will be displayed to allow the name of the scan to be entered. The "Use target host name" option allows the name of the scan to automatically track the target of the nmap scan. If that option is not selected, the name of the scan can be entered in the edit window - which is activated when the "Use target host name" option is unchecked.

&Ctrl;C File Duplicate scan

- As the name imples, the current scan is duplicated. Unusual / unfortunate and / or strange behaviour may / will result if the name of the scan is not changed but a different profile is associated with the duplicated scan (name).

F2 File Rename scan...

- Obvious - but it is also possible to select the "Use target host name" property via this menu item.

F2 File Use target host name

- This is a toggle item that causes the name of the scan to automatically track the target of the nmap scan.

&Ctrl;W File Close scan

- Obvious - but if the profile has been updated you will be asked whether it should be saved.

&Ctrl;Q File Quit

- Quits &knmap;

#### The Profiles Menu

Before launching into the explanation of the items under this menu, it is necessary to define what a "Profile" is.

Quite simply, a Profile is the set of values of all the `nmap` options supported by &knmap; and some &knmap;-specific data (e.g., the order of the tabs in the Options Window and the current options tab).

The status of the Hide / Show buttons is not saved. All windows are shown on &knmap; startup regrardless of their status at the time a Profile saved.

Having the same profile associated with multiple scans is not recommended - unusual / unfortunate and / or strange behaviour may / will result.

The following screenshot shows the dialog window that controls all options in this menu. The top window is used for the entry of new names for the copy and rename functions. The lower window lists all known profiles. (For the technically minded, the profiles are stored in the standard KDE `knmaprc` configuration file - but with the name "Knmap_<profile name>".)

The copy, delete and rename functions available in this menu are also available when a profile name is right-clicked in the list window.

Profiles Load profile...

- Equivalent to a "File -> Open" in your favourite editor. If the current profile has been modified you will be asked if you want to save it prior to loading the new profile.

Profiles Save profile...

- Equivalent to a "File -> Save" in your favourite editor.

Profiles Save profile as...

- Equivilent to a "File -> Save" as in your favourite editor.

Profiles Copy profile...

- The selected profile is copied, the name of the new profile is entered in the upper input window.

Profiles Delete profile...

- Bloody obvious.

Profiles Rename profile...

- The name of the selected profile is changed to the name entered in the upper input window.

#### The Settings Menu

Settings Wrap text

- Selects whether the nmap output should be word-wrapped at the windows right-border.

Settings 'man' page stylesheet...

- Allows for the selection of the stylesheet to be used when the nmap man page is displayed.

Settings Use local 'man' page

- This is a toggle action, the text changes depending upon its state. If the &knmap; nmap man page is being displayed, this option allows for the >man page stored on the local machine to be displayed. This is useful when the local version of the nmap man page differs from the version distrubuted with &knmap;.

  When the local man page is being displayed, this option allows for the &knmap; version to be displayed.

Settings Zoom in

- Increases the font size in the man page window by 25% - limits are 20% - 300%.

Settings Zoom out

- Decreases the font size in the man page window by 25% - limits are 20% - 300%.

Settings Zoom custom

- Allows manual control of the font size - limits are 20% - 300%.

The remaining options in this menu are standard KDE options.

#### The Help Menu

&help.menu.documentation;

## Developer's Guide to &knmap;

The only item worthy of mention here is the file `nmap_manpage.html.diff`. This file contains a `diff` of the `nmap` version 3.93 HTML formatted `man` page and that distributed with &knmap;. You can use this to update your version of that `man` page.

## Credits and License

&knmap;

Program copyright 2005, 2006 Kevin Gilbert kev.gilbert@cdu.edu.au

Documentation copyright 2005, 2006 Kevin Gilbert kev.gilbert@cdu.edu.au

&underFDL; &underGPL;

## Installation

### How to obtain &knmap;

Now let me see... You're reading this documentation - which come packaged with &knmap;, which means that you have &knmap; installed, which means that you have somehow obtained &knmap;, and now you want to know how to obtain &knmap;?

You have _way_ too much time on your hands! ;-)

Okay, Okay. Go to http://sourceforge.net/projects/knmap and follow the download links.

### Requirements

&knmap; was developed and tested under Qt 3.3.4 / KDE 3.4 & 3.5. YMMV vary if your configuration differs from this.

And, of course, you will need `nmap`. Go to http://www.insecure.org/nmap for details on how to download `nmap`.

### Compilation and Installation

&install.compile.documentation;
&documentation.index;