INTRUspect

Version 1.1.0, 20th January 2025

Copyright © 2017-2025 Mark G. Daniel
Licensed under the Apache License, Version 2.0 (the "License");
https://www.apache.org/licenses/LICENSE-2.0
Software distributed under the License is on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

Contents



INTRUspect  (pronounced "in-truh-spect")  is an in-browser, real-time VMS intrusion database monitor.

INTRUspect should work with all relatively modern browsers. Developed against Chrome, Firefox, MSIE (10+), and Safari, on OS X and Windows platforms. It uses HTML5 elements and will not work with the HTML4 generation of browsers.

INTRUspect operates as a CGI web application and so is suitable for VMS Apache, OSU and WASD scripting. It can also run as a CGIplus and WebSocket application under WASD 10.1 or later, improving latency and performance.

INTRUspect caches entries as they present in the intrusion database and this is used to track some additional items (e.g. count delta). The cache also allows the item to be visible after the intrusion entry expires (or is manually deleted), providing a recent history.

Usage

INTRUspect is activated by accessing the URL for its script location. This is usually something like (and may well open INTRUspect on this system)
http://the.site.name/cgi-bin/intruspect
opening an in-line monitor, though can be a
a bookmarklet
opening a stand-alone window.

If intrusion records exist then INTRUspect opens displaying a relatively simple table of intrusion data. Many of these reflect the command-line SHOW INTRUSION data. Initial ordering of the table entries reflects the order of the system intrusion database at that time. Subsequent entires are added to the top of the table and so ordered from most to least recent. The following (contrived) example shows the essentials of the report and are described below.
The elements of intrusion data are described in the OpenVMS Guide to System Security (September 2003 edition referenced), Managing System Access chapter, Controlling the Login Process section, Detecting Intruders and Understanding The Intrusion Database subsections.

INTRUspect controls:
Click and hold to enlarge ... or ... intruspect.png

(Safari 18 on macOS, showing standalone INTRUspect)

 top-left The unlabeled checkbox located in the top-left of the monitor displays a section allowing the URLs for multiple INTRUspect sites (one per line) to be configured into a single display. Do not try to mix http:// and https:// specifications in any combination; browsers often block content with mixed security domains. Note that MonDeSi, à la mode and INTRUspect URLs can be combined on the one display in either application, as well as DCLinabox terminal URLs.
 left Adjacent to the node name, the checkbox minimises the per-node display. When unchecked, provides a synopsis of the current INTRUspect data.
Collect Enables and disables data collection from the server.
Update Disabling display update retains the server connection but does not disturb the current report.
Print the current report.
Zero and otherwise reset INTRUspect data.
 
INTRUspect tabled data:
Type INTR[UDER] or SUSP[ECT]
Class NETW[ORK], TE[RM]_US[ER], TERM[INAL] or USER[NAME]
Node Clustered systems show the node name of the intrusion.
Non-clustered systems do not show this item.
Network Commonly an IP address or host domain name. Can be a DECnet node name.
When enabled displays geolocation data.
Source The original intrusion record (what you see with SHOW INTRUSION).
Ident Additional information on the authentication source or username. Not always present.
Count The total number of failed authentication attemps.
Delta The number of recent failed attempts. This count continues as long as an additional failed attempt occured during the preceding 30 seconds.
Noticed Time a new record was noticed. Records existing at the start of processing are shown as initial. Shows the age of the entry following the time. (e.g. -05:34)
Expires When the current record is due for re-evaluation and/or removal. If expiry is still future the period is shown as a positive value (e.g. +10:08), and if already expired as a negative value (e.g. -03:54), with the expiry time struck-through (e.g. 13:50:15).  An entry manually $ DELETE/INTRUSION is reported DELETED.
** The network, source and ident items are parsed from from the single SHOW INTRUSION Source datum. The elements of this are somewhat free-form, resulting in variability in parsed results.

From VMS V7.3 the default has been to maintain a cluster-wide intrusion database. Any single node will register intrusions from itself and any other node in a cluster.

Recently noticed entries are highlighted with a  green background  for 30 seconds.

Entries of type intruder (in contrast to suspect) are highlighted with a  red background. 

Entries with a changed count value are highlighted using a  yellow background  for 30 seconds.

Entries (manually) deleted before expiry are highlighted using the same yellow background for 30 seconds.

Expired entries (those no longer present in the system intrusion database) are highlighted using an  off-white background  and then with a  pale yellow background  for 15 seconds before being purged. Note that an expired entry can be reactivated, is then highlighted as recently noticed, and can show a higher count than the equivalent SHOW INTRUSION as the INTRUspect count is cumulative across those multiple activities.

Installation

Is relatively straight-forward. Adapt for a non-WASD environment as required.

Update

An update follows the above installation steps, generally without the need to configure the application or modify the startup procedures (though check the release notes for any modification requirements). Instead ...

And remember that the more recent JavaScript will need to be (re)loaded into browsers (perhaps requiring browser cache clearing) and that a WASD CGIplus/WebSocket application will require any currently instantiated processes flushed with $ HTTPD/DO=DCL=DELETE (caution! - peremptorily removes all script processes).

Geolocation

INTRUspect can provide geolocation data for IP address information.

https://en.wikipedia.org/wiki/Internet_geolocation

Disabled by default, geolocation is enabled by defining the INTRUSPECT_GEOLOCATE logical name. 

$ DEFINE /SYSTEM INTRUSPECT_GEOLOCATE *

Configuration

JavaScript and other resources located in the [.RUNTIME] subdirectory of the source code must be available to INTRUspect. These must be mapped into application web-space. For WASD this will be using a WASD_CONFIG_MAP rule similar to the following: 

pass /intruspect/-/* /wasd_root/src/intruspect/runtime/*

WASD WebSocket access requires CGIplus. The script internally ensures this for the standard script activation path but this can also be implemented using a mapping rule. 

redirect /cgi-bin/intruspect* ///cgiplus-bin/intruspect*
pass /intruspect/-/* /wasd_root/src/intruspect/runtime/*
...
exec+ /cgiplus-bin/* /cgi-bin/*

Script must be subject to authorisation or INTRUspect aborts. For WASD an authorisation rule such as the following might be used. 

# WASD_CONFIG_AUTH
["System Admin"=SYSADMIN=ID]
/cgi*-bin/intruspect* r+w,https:
At the time of writing (early 2017) not all (the major) browsers (Chrome, Edge, Firefox, Opera - not Safari) implement HTTP authorisation over WebSocket. WASD users employing WebSocket and authorisation are currently required to disable WebSocket for any other than these!

To disable WebSocket for all but selected user-agents define a multi-valued logical name with zero followed by values containing unique strings found in capable user-agent strings. 

$ DEFINE /SYSTEM INTRUSPECT_WEBSOCKET 0,"Chrome","Firefox","Edge","Opera"

Disabling WebSocket adds a little latency and server overhead to some actions but does not affect overall functionality.

Example Apache Config

Assumes APACHE$COMMON:[INTRUSPECT] and APACHE$COMMON:[CGI-BIN]INTRUSPECT.EXE. 

Alias /intruspect/-/ "/apache$common/intruspect/runtime/"

<Location /cgi-bin/intruspect>
AuthType Basic
AuthName "OpenVMS authentication"
AuthUserOpenVMS On
require valid-user
</Location>

Intrusion Database

Very large intrusion databases can be expensive to process and transfer to the client. These are quite rare. There is a default limit of 250 records after which INTRUspect stops further record processing and alerts the client. The effective limit depends on the processing power of the server system and the network available between server and client. The actual limit may be adjusted up or down using the configRecordsMax(integer) configuration function.

Where the limit is exceeded, entries are no longer reported as DELETED (in the Expires field). It is not possible to infer an entry that "disappears" before expiry has been manually deleted or whether due to intrusion database (re-)ordering is now present within the excess entries currently not being reported on.

Configuration File

The logical name INTRUSPECT_CONFIG locates the configuration file. It needs to be SYSTEM accessible. 

$ DEFINE /SYSTEM INTRUSPECT_CONFIG HERE:[IT.IS]INTRASPECT.CONF

The file name can be anything but the content must be legal JavaScript. The content is incorporated into the client infrastructure and then executed (JavaScript interpreted) to provide any site configuration required. All configuration is performed by calling a JavaScript function with appropriate parameter(s).

Function Description Parameter(s) Default
configDeletedSecs() seconds a (manually) deleted record is highlighted <integer> 30
configDeltaSecs() seconds a record with inceasing count is highlighted <integer> 30
configHistorySecs() seconds an expired record remains visible
(when Purge is not checked) 		<integer> 120
configFadingSecs() seconds an expired record is highlighted before removal <integer> 15
configForceXHR() force (WASD) to use XHR rather than WebSocket <boolean> false
configNotifySecs() seconds a new record is highlighted <integer> 30
configRecordsMax() maximum intrusion records processed <integer> 250
configUpdateSecs() interval at which server supplies intrusion data <integer> 2

JavaScript is used directly to maximise flexibility. An error in configuration (JavaScript) will be reported in a browser alert and INTRUspect will continue to initialise (sans the broken configuration).

NOTE: The configuration file is only read at the activation of the INTRUspect executable. When using CGIplus/WebSocket the script instance would need to be deleted to load another configuration.

Problems?

Releases
v1.1.0  20-JAN-2025
•  integrate geolocation
•  64 bit native data
v1.0.1  01-MAR-2017
•  minor tweaks and fixes
v1.0.0  13-FEB-2017
•  initial