README.technical

 


 $Id: README.technical,v 1.3 1999/03/22 04:57:18 crowland Exp crowland $
 
 HostSentry - Login Anomaly Detector
 
 
 Introduction
 =-=-=-=-=-=-
 
 HostSentry is a program designed to detect security relevant events occuring
 at login time for users, or more specifically: Login Anomaly Detection.
 
 The HostSentry program itself is designed to run a variety of detection
 modules that are executed during either a user login or logout. These
 modules can perform a variety of actions upon detecting a security
 relevant event. Such actions include:
 
 - Logging the violation.
 - Blocking the violating host IP address with TCP Wrappers.
 - Blocking the violating host IP address with packet filters.
 - Blocking the violating host IP address with bad route.
 - Disabling the user account.
 
 The various modules included are described in the supporting
 documentation.
 
 
 Basic Components
 =-=-=-=-=-=-=-=-
 
 HostSentry consists of a series of files that allow it to run. These files
 allow for database access, wtmp entry processing, logging, and response
 actions. 
 
 The basic function of HostSentry is to simply maintain two databases: User and
 Active TTY. HostSentry also runs extension modules depending on the event
 (login or logout). 
 
 The user database consists of all users that have logged in while HostSentry
 has been in operation. This database stores user login objects which are
 formed with the following schema and is persistent between executions of
 HostSentry:
 
 username - The login name of the user
 
 recordCreated - The date in Unix epoch time when the record was first
 created
 
 firstLogin - The first login recorded for this user.
 
 trackLogins - A list of logins the user has made. This list is variable in
 size depending on your configuration. Old logins roll off the end once
 maximum size is achieved.
 
 validLoginDays - The days this user is allowed to log into the system.
 
 validLoginHours - The hours this user is allowed to log into the system.
 
 adminDisabled - A flag indicating this account has been disabled by an
 administrator.
 
 securityDisabled - A flag indicating this account has been disabled by an
 automated module action.
 
 totalLogins - Total logins this user has had since HostSentry began operation.
 
 version - The database schema version. 
 
 
 The TTY database helps HostSentry maintain a list of active connections and
 allows the program to know when a user has logged out so their main record
 can be updated with this time. This is done because wtmp entries for
 logouts have a NULL user and the associated TTY. Without this
 information HostSentry would have no idea who owned the TTY the logout
 occurred on without doing a search of the entire wtmp file. 
 
 Because this information is not needed between runs, this database
 is re-generated each time HostSentry is executed. The following items are
 tracked in this database schema:
 
 tty - The TTY the user was recorded logging into.
 username - The name of the user.
 loginStamp - A timestamp unique to the user's login.
 version - The database schema version.
 
 Login Stamps
 =-=-=-=-=-=-
 
 Login stamps are used by HostSentry in many places. A login stamp contains
 information necessary for processing by the system components and is
 formed as follows:
 
 loginIP@loginHostname@loginTTY@loginTime@logoutTime
 
 Where:
 
 loginIP - The IP address of the host logging in.
 loginHostname - The FQDN of the host logging in.
 loginTTY - The TTY the user is logging into.
 loginTime - The time in Unix epoch form of the login.
 logoutTime - The time in Unix epoch form of the logout.
 
 NOTE: logoutTime will not be present on some records if the user has not
 logged out yet, or if a system crash didn't allow the DB to be updated
 properly.
 
 Example:
 
 Without logoutTime:
 192.168.2.10@www.somehost.com@ttyp0@908330397@
 
 With logoutTime:
 192.168.2.10@www.somehost.com@ttyp0@908330397@908330399
 
 
 Login Processing
 =-=-=-=-=-=-=-=-
 
 During a login HostSentry will process the wtmp data to form a login stamp
 (minus logoutTime). This stamp will be used in various DB operations:
 
 1) Check for username in User DB.
 	- Create record if non-existent
 
 2) Retrieve data from User DB and populate user object.
 
 3) Update user object with current login stamp.
 	- Insert loginTrack entry.
 	- Update totalLogins
 
 4) Write user object with updated data back to User DB.
 
 5) Populate TTY object and add entry to TTY DB to allow tracking of
 current login session for user.
 
 6) Execute modules with user object and login stamp as parameters.
 	- Runs login() method in module.
 
 7) Return to monitoring wtmp.
 
 
 Logout Processing
 =-=-=-=-=-=-=-=-=
 
 During a logout HostSentry will process the wtmp data to form a logout stamp
 (same as login stamp plus logoutTime appended to end). This stamp is used
 in the following operations:
 
 1) Lookup logout TTY in TTY DB. 
 	- wtmp only reports tty and NULL user on logout.
 
 2) Retrieve TTY information and pull logged in username and loginStamp
 from file.
 
 3) Delete TTY from TTY DB. 
 
 4) Use loginStamp to find corresponding login for user in User DB.
 	- This allows for multiple logins by the same user because
 	the login stamp is unique the each session.
 
 5) Update the user object with the logoutTime.
 
 6) Write out user object back to User DB.
 
 7) Execute modules with user object and logout stamp as parameters.
 	- Runs logout() method in module.
 
 8) Return to monitoring wtmp.
 
 
 Conclusion
 =-=-=-=-=-
 
 This is all the HostSentry program is doing during it's run. Of course there
 is a lot more going under the hood, but essentially this is all HostSentry is
 designed to do. Please read the file README.modules to find out how to
 make modules and use the supporting API's for HostSentry.
 
 -- Craig
 
 <crowland@psionic.com>