$Id: using.txt,v 1.4 2003/10/02 03:48:03 visigoth_6 Exp $

This doc is bad and will be re-written soon!

-----------============< Using MetaCoretex >============-----------

1. Startup/Basics
2. Global Options
3. Configuring Probes
4. Scan Progress
5. Reports
6. Updating
7. Advanced Usage

===================================================================
Startup/Basics

MetaCoretex should be capable of starting by using the mctx.sh startup
script located in the top directory of the distribution.  If you find
that startup does not occur properly, make sure you have a recent
1.4 series JRE from http://java.sun.com/  If you would like to use
the probe generators/compilers, install the SDK as well.  Be sure
to set both JAVA_HOME and JDK_HOME environment variables.


===================================================================
Global Options

The following global options can be set from the "Global Configuration"
window:

probe.timeout - Probe timeout for general probes in seconds.

threads.max - The maximum number of attacker threads to spawn on launch.

conf.dir - Location of the MetaCoretex configs

probe.compiler.classpath - Classpath to the Sun SDK JAVA Compiler

safe.checks.only - If true, probes should only do "safe" stuff...

probe.dir - Dir to load probes from.

template.dir - Location of template files for probe generators

update.url - URL Location for the MetaWeb XML Updater

===================================================================
Configuring Probes

The "Probe Configuration" window may be reached by either clicking
Window->Probe Config, or clicking the second button from the top on
the left side tool-bar.  Probes are sorted into semi-logical groups
represented by tabs across the top.  Each probe has a help entry 
explaining it's purpose and any options it uses.  This probe specific
help can be accessed by clicking the "?" when the probe in question
is highlighted.  Probe options may be configured by clicking on a
probe and editing the Value section of the Option->Value table in the
lower half of the window.

It is highly likely that some probes will require tweaking in order
to carry out their operations.  Particularly, Auth Probes may require
service specific authentication information if they are unable to
discover any default accounts.  Keep in mind, that a failure of any
one probe, will usually cause any dependant probes to fail or exit
without reportable information.

Once a scan is fully configured, it may be saved by using the
File->Save->Scan Configuration menu.  This will allow you to choose
a location and file name.  I would recommend using the file extension
.xml for config files and reports.

===================================================================
Scan Progress

During the scan process, each thread will have an entry in the JTable
shown in the "Scan Status" window.  A thread is only finished when
the target column becomes "none" and "Current Probe" is completed.
Some probes may pause, or require up to probe.timout seconds to
complete.  Any probes which timeout will be listed in the later report
section.  Any Attacker thread may be killed by selecting the row in
the table and clicking on the red "stop" button at the bottom tool-bar.
Probes interrupted in this fashion usually exit cleanly, however this
is not a guarentee...

===================================================================
Reports

Reports may be viewed by the reporting interface accessed by Window->
Reports or the bottom button on the left side tool-bar.  Each scanned
host will be listed in the top JTable, with a breakdown of the total
number of reports, severities, and probe failures.  Probes have the
following severity rating categories:

Blue - Data Gathering: Could be good or bad.  Requires analysis.
Yellow - Low Risk
Orange - (currently pink, will fix) Medium Risk
Red - High Risk

All ratings are, of course, completely objective and perfectly acurate
in all circumstances (not).  Always double check your findings.

Many probes are capable of dynamically setting their severity based
on the results of their activities.  For example, the OracleDefaults
probe tests for default oracle accounts.  If any are found which are
also UNLOCKED, the probe will report High Risk.

Reports may be saved and later reloaded in XML format.  Data may be
coppied and pasted from the reporting window for your report
drafting pleasure... :P

===================================================================
Updating

Users are encouraged to use the XML Web Services based updating
engine on a regular basis.  This creates an HTTPS connection to
xml.metacoretex.com:8443 to process the current list of probes, files,
and versions.  The updating interface will automatically build and
publish any probes which are checked into the CVS repository and
approved by a release engineer.  Tools->Update->Interactive.

===================================================================
Advanced Usage

-------------------------------------------------------------------
Probe Generators

Many common types of probes have probe generators available to allow
users to create JAVA source files which implement the Probe interface.
Context sensitive help should be available for every step in the
generation process.  This particular feature is still a little tweaky
regarding text processing and whatnot.

JAVA source files will be created in probes/ directory and named the
same as the JAVA Classname you choose during the wizard process.

-------------------------------------------------------------------
Probe Compiler

I have included support which hooks the JDK supplied JAVA source
compiler to allow users to compile probes from the GUI.  All this
does is call the javac compiler with a classpath which includes the
necissary MetaCoretex.jar.  Any compiler failures will result in
terminal output from the window used to start MetaCoretex, and a
JOptionPane message for success/failure.

-------------------------------------------------------------------
Dynamic Probe Loading

Probes may be loaded from JAVA class files even after the
application has started up.  To load a Probe class, click: File->
Load->Probe and select your probe in the JFileChooser.  Your probe 
should be loaded and have it's dependencies resolved.  If the probe 
being loaded has an already existing ProbeId, it will be loaded to
replace the probe with that ID. To confirm your probe
is loaded or check where it was placed in the firing order:
Help->About Probes...
Probes in this list are ordered by their firing order based on
their declared dependencies.  This technique can be useful for
testing probes ,rebuilding them, and reloading them without having
to restart the application.  This functionality will eventually be
used for dynamic probe updates.

--------------------------------------------------------------------
Probe Submission

If you write a probe that you think is cool, please submit it!  You
may either email them to visigoth@securitycentric.com or use the
probe submission wizard found in the Tools menu (select the JAVA
source file).

===================================================================
