
Osiris 4.0.0

This file contains only a high level overview of how Osiris works.  For more
detailed information, see the /docs directory or mail to osiris@shmoo.com and
someone will help you.  For installation information, see the INSTALL file
included with this source distribution.

Overview
----------------------

Osiris consists of three major components: The Management console, a scan
agent, and a management application (currently only a CLI).

       osiris <---> osirismd <---> osirisd 

[components]

The management console is to be installed on a trusted host.  This is where
all of the information about managed hosts are kept, including configs, logs,
databases, and others.

The scan agent is a lightweight process that runs on each host to be
monitored.  The scan agent is responsible for scanning the local
environment and sending the data back to the management host.

The management application is used by the administrator to manage the 
details of the scanned hosts.  It communicates directly with only the
management console.


[communication]

All communications between the three components happen over an SSL session.  The
management host stores a cert and key on the local filesystem.  Custom certs
can be used, but if none exists, the management console will create a 
self-signed certificate when launched.

The management console maintains a listing of hosts that are allowed to talk to
it.  By default, the config only allows connections from the local host.
Management applications save the presented certificate and use it for
verification upon subsequent connects.  This is very similar to the way
OpenSSH behaves.

The scan agent (like the management app) also saves the presented
certificate to the local filesystem.  The scan agent authenticates
requests with this certificate, the intent being to ensure that it only
communicates with the trusted management host.  The management host's
authentication of the scan agent is a bit tricky.  First, the scans
themselves serve as a means of authenticating the scan agent.  An
attacker would have to maintain a consistent sequence of scan data. 
Since none of the databases are stored on the host, this would not be trivial.
Second, the scan agent is assigned a key by the management host.
This key is kept only in resident memory, not on the filesystem.  Upon
each request, the managment host requires the scan agent to present
a hash of this key first before any communication can proceed.  The
management console maintains the hash of this key.  If the key doesn't match,
the management console refuses to deal with the host.  If the host
is rebooted it loses the key and the management host will issue a replacement
key.

known issues with this release
----------------------------------

-none.


THANKS
----------------------

Thanks to the following people who have helped and been very involved with
the development of Osiris in all its versions:


    Bruce Potter
    Preston Norvell
    Paul Holman
    Adam Shand
    John Viega
    Tina Bird
    Scott Hallock
    Brian Daugherty
    Spike Illaqua
    Yuri D'Elia
    Tim Laughlin & folks at Indra's Net.
    Aaron Racine
    Peter Johanson
    Jeremy Verne
    Alexei Roudnev
    Luke West
    Duane Dunston
    Amihai Silverman
    Richard Johnson
    Thomas Jones
    Peter Frey
    Karen Wieprecht

