Calin's Humble Scanner - User Guide

## Command Line usage

Description
Return Values
Windows Event Logs - Event IDs
Examples

## Description

The `CHScanner` can be made scriptable by calling it from a script and suppling corresponding parameters in the command line. I am calling this "automatic mode" from now on.

After the automatic mode execution terminates, the application returns an error code and writes an event in the Windows Event Logs, under the Application section. There are now 8 error codes (including the success one) returned and there are also 8 corresponding event ids to be written in Windows Event Log. All these are detailed in the next sections of this page.

The parameters are:

- Passive [RunningTimeInSeconds] for starting the application in the Passive Scanning Mode.
  If the RunningTimeInSeconds is supplied, the application will run for the specified ammount of time then will save the results and terminate it's execution. Otherway, the application must be manually stopped.
  The minimum allowed ammount of time to run is 10 seconds. The maximum allowed time to run is 86400 seconds (one day).
- Scan <ScanConfigurationFileName> for loading a scanning configuration file, running a scan, saving the results and terminates it's execution.
  The scan configuration file MUST be in the application's folder named Configs !

Note

The command line parameters are NOT case sensitive.

## Return Values

After running in automatic mode, the `CHScanner` application returns one of the following values:

- 0 for success;
- 1 if an invalid parameter was passed in the command line;
- 2 if the specified ammount of time to run, for passive mode, is not valid (i.e. not between 10 and 86400 seconds);
- 3 if the scan has failed because the timeout timer, for timed passive mode, could not be set;
- 4 if the specified scan configuration file could not be loaded;
- 5 if the scan process could not be initiated;
- 6 if the scan process has failed;
- 7 if the export of results has failed.

To get the return code, in a batch file, check the value of the %errorlevel% defined variable. To do a quick test, just do a `echo %errorlevel%` after calling `CHScanner` with some parameters in your batch file.

## Windows Event Logs - Event IDs

After running in automatic mode, the `CHScanner` application will write one of the following events using Windows Event Logs, under the Application item:

- 0x10 for success. The duration of the scan process and the name of the file with scan results will be recorded too;
- 0x21 if an invalid parameter was passed in the command line;
- 0x22 if the specified ammount of time to run, for passive mode, is not valid (i.e. not between 10 and 86400 seconds);
- 0x23 if the scan has failed because the timeout timer, for timed passive mode, could not be set;
- 0x24 if the specified scan configuration file could not be loaded;
- 0x25 if the scan process could not be initiated;
- 0x26 if the scan process has failed;
- 0x27 if the export of results has failed. The duration of the scan process will be recorded too.

## Examples

### Command line examples

- Passive mode:
  " `CHScanner.exe -Passive` " will run the application in passive scanning mode.
  The application must be manually stopped. When stopped, the application will export the results and terminate it's execution.
- Passive mode with timer:
  " `CHScanner.exe -Passive 25` " will run the application in passive scanning mode for 25 seconds then will export the results and terminate it's execution.
- Automatic scanning mode:
  " `CHScanner.exe -Scan testScanCfg.chs` " will run the application in automatic scanning mode, using the scanning parameters from the `testScanCfg.chs` file, then will export the results and terminate it's execution.

### Batch file, first example

Small and dumb example of a batch file:

    @echo off
    CHScanner -Passive 25
    echo The application has returned the code %errorlevel%

### Batch file, second example

Another, not so small but equally dumb, example of a batch file:

    @echo off
    CHScanner -Scan testScanCfg.chs
    goto result%errorlevel%

    :result0
    echo Done.
    goto :EOF

    :result1
    echo Invalid parameter !
    goto :EOF

          ... and so on ...

[ User Guide ]

Copyright © 2006 - 2009 Calin Radoni Hosted on http://www.geocities.com/calinradoni Last page modification is 08 August 2006