= Hourglass 0.1
:bl: pass:[ +]

{bl}
{bl}
{bl}

image::hourglass-logo.png[align="center"]

{bl}
{bl}

This project is a collection of programs (scripts) that implement an
automated network access control policy, aptly named "Hourglass". The
general idea is to have the network open or closed on weekly policy
schedule, with an easy-to-use interface for adhoc adjustments.

<<<<<<<<<<
== Overview

The Hourglass policy setting includes open and close times separately
for each weekday, as well as limits of the accumulated usage during
the open times. For example, one could set up Hourglass to have the
network open between 11am and 4pm each day, closed otherwise and each
day allow for 2 hours of usage. The following is a snapshot of the
operator web view of the policy.

=== Operating Hourglass

.Hourglass Operator View
image::hourglass-operator.png[align="center"]

The operator view includes display of thecurrent usage, a control for
"open override", an "ascii art" graph showing a history of usage
timelines, and the weekly control policy setup and control.

<<<<<<<<<<
=== Hourglass Software Architecture

This policy control is accomplished by *Hourglass* as a software
architecture with three interlinked components that are on a "router"
that networking-wise is in between the sub network to control and the
Internet.

 * One component, the *Hourglass listener daemon* continuously
   monitors the network and generates a per-minute log of how many
   "network packets" there were in that minute. This is the measure
   Hourglass uses to determine whether the network is in use or not so
   as to allow for having a limit on the accumulated usage during the
   open time.

 * Another component, the *Hourglass policy bot*, is a per-minute
   "cron bot". It looks at the recent succession of activity measures
   to decide whether or not "usage" is happening, and then accumulates
   usage periods into the current total daily usage time measure. It
   regularly considers changing the networking settings as a matter of
   effectuating the (then) current policy.

 * The third component, *Hourglass web service*, provides tailored
   support for operators to view and modify the policy remotely. The
   applicable policy is actually held in plain text on the deployment
   host and it may of course also be directly modified with a text
   editor.

.Hourglass System Overview
image::hourglass-overview.png[align="center"]


NOTE: The Hourglass components run as +root+. It is possible to split
up the system into running some as +root+ and others as, say, a
dedicated +hourglass+ virtual user. However the boundaries between
these have not been fully nutted out as yet, so at present all is run
as +root+.

== Installing Hourglass

An Hourglass system is currently distributed as a tgz file, which
should be unpacked to the depolyment directory. The unpacking should
result in a two binaries, +hourglass+ and +hourglass-web+, a shell
script , +setup.sh+, and a deplyment configuration file,
+hourglass.conf+.

Following unpacking, the actions to take are:

 1. Edit +hourglass.conf+ for the new deployment
 2. Start Hourglass listener daemon
 3. Start Hourglass policy bot
 4. Start Hourglass web service



=== Hourglass Deployment Configuration

The Hourglass deployment configuration is a plain file named
+hourglass.conf+ containing variable settings to configure the system
appropriately for the installation. The full list of varaiables is
documented in <<Hourglass Deployment Varaibles>> below.

NOTE: The configuration should ideally remain unchanged after the
first installation changes.


=== Hourglass Listener Daemon

The Hourglass listener bot is adminstered via the +setup.sh+ control
script, using command line action arguments of +start+ or +stop+. This
script must be run as +root+ as it includes maniplations of the
networking +iptables+ rules.

Once started, the listener daemon remains running to continuously
update the activity log.

NOTE: The listener daemon is a network entity like a virtual host, and
by means of an +iptables+ +TEE+ rule it also receives copies of the
monitored network packets.

=== Hourglass Policy Bot

The Hourglass policy bot needs to be set up as a +cron+ bot that
executes once a minute. How this is done depends on the deployment
host, and in particular how scheduled invocations are set up on that
host.

For a system using +cron+, an applicable +crontab+ lines looks like
the following:

.Exsample crontab lines for regular Hourglass policy bot invocation
----
PATH=$PATH:hourglass-installation-directory
* * * * * hourglass control-logic > /dev/null 2>&1
----

// .The Hourglass Control Actuator

NOTE: The policy bot performs it control actions via an "ipset
actuator", which adds or removes the IP address detail of the
controlled network to (from) the dedicated +ipset+ set.

=== Hourglass Web Service

The Hourglass web service is a CGI service aimed at editing the
Hourglass control policy through a simple HTML for page that also
includes a presentation of current usage and an optional control
override.

The CGI service is wrapped into a single binary +hourglass-web+ that
recognises its invocation name (link name), and the service as a whole
is installed with the following:
----
$ ./hourglass-web install
----
That installation sets up a small +www+ sub directory with "CGI"
scripting to provide the Hourglass User Interface on the selected
port.

NOTE: The Hourglass Web Service requires a front-end HTTP server.

<<<<<<<<<<
== APPENDIX

=== Hourglass Deployment Variables

This is an enumeration of all Hourglass deployment variables as
provided with the sample +hourglass.conf+. The configuration file may
also include comments, which are lines starting with semi-colon (;) or
hash (#) to end of line, and blank lines.

.listener variables
****
These variables are predominantly used by the Hourglass listener
daemon.

listener.net = 192.168.123:: is the first three quads of the IP
address to use for the "listener network", with a final component
being +1+ for the host and +2+ for the listener daemon. The listener
daemon acts as a virtual host and is set up vie +setup.sh+ to receive
copies of some network packets for the purpose of measuring activity.

listener.ports = 80 443:: is the port numbers of concern, separated by
whitespace or comma, towards activity detection. Only packets to these
ports will be considered.

listener.activity.dir = activity :: is the directory in which the
activity files are stored. The Hourglass listener daemon operates
continuously and populates one measure per day with a full sequence of
(roughly) per-minute packet count measures.

listener.tap = hourglass:: is the name to use for the network tap that
is set up to be the interface for the virtual listener host.
****

.control bot variables
****
These variables are predominantly used by the Hourglass policy bot.

control.action = ipset-control.lsp:: is the name of the control action
script to use. Currently only +ipset-control.lsp+ is available.

control.dat = control.dat:: is the pathname for the policy file. The
content is a newlisp format expression; a list with sublists to
represent the desired control policy. It is typically generated by the
Hourglass web service and then used by the Hourglass control bot.

control.net = 10.0.0.0/8:: is the IP/bits code of the network to be
controlled.

control.extra.dat = control-extra.dat:: is the pathname for the ad-hoc
time override. This is a pair of numbers that define an overriding
"network open" time period of that many hours and minutes starting at
the modification time of the file itself

control.usage.dat = usage.dat:: the filename to use for the usage
state. This is a newlisp expression of the current hours and minutes
of usage. The file is generated by the Hourglass policy bot to be used
and displayed via the Hourglass web service.

control.usage.tmp = usage.tmp:: is the temporary filename to use for
the usage state update. The state update is written to this file which
then is renamed as per +control.usage.dat+; this process avoids the
risk of the Hourglass web service accessing an incompletely written
file.

control.activity.gap = 10:: is how many minutes of low activity is
needed for identifying an idle period.

control.activity.clip = 1000:: is the count measure limit for low
activity.
****

----
; control.dat example
; Updated at Sun Aug  8 22:53:01 2021
((1 timed (5 30) (2 0) (20 0))
 (2 timed (7 30) (1 0) (20 0))
 (3 timed (7 30) (1 0) (20 0))
 (4 timed (7 30) (1 0) (20 0))
 (5 timed (7 30) (3 0) (22 0))
 (6 timed (7 30) (1 0) (20 0))
 (7 timed (7 30) (1 0) (20 0))
 )
----

.ipset control action variables
****
These variables are used by the +ipset-control.lsp+ control action
script to translate the desire of open/closed network into control
actions of adding/removing the +control.net+ network to/from the
+ipset+ set that is set up via +setup.sh+ to constitute a blocking
+iptables+ rule for network traffic.

ipset.bin = /sbin/ipset:: is the pathname for the +ipset+ binary.

ipset.table = TIMO:: is the name of the ipset set.
****

.web service variables
****
These variables are predominantly used by the Hourglass web service.

wui.port = 1070:: is the port for the HTTP service.

wui.passwd = .htpasswd:: is the pathname for the file of authorizable
users. Each line consists of the base64 encoding of a "user:password"
pair as is used in the HTTP Basic Authorization scheme.
****

.special variables
****
libc = /lib/x86_64-linux-gnu/libc.so.6:: is the pathname for the libc6
dynamic library.

tundev = /dev/net/tun:: is the pathname for the tuntap device
generator.
****