First pass at doc updates to cover v0.2.0 features

README.md

@@ -46,19 +46,28 @@ audience are still missing.
 This application is intended to be used as a HTTP endpoint that runs alongside
 an EZproxy instance. This endpoint receives webhook requests from a monitoring
 system (Splunk as of this writing), disables the user account identified by
-the monitoring system rules and generates one or more notifications listing
-the action taken. fail2ban is used to ban the offending IP for `MaxLifetime`
-minutes (EZproxy setting) + a small buffer to force active sessions associated
-with the disabled user account to timeout and terminate.
+the rules enabled on the monitoring system and generates one or more
+notifications listing the action taken. At this point, the associated user
+sessions can be optionally (and automatically) terminated using two
+approaches:
 
-The combination of stopping new logins for the disabled user account and
-timing out existing sessions works around the lack of native support for this
-behavior in EZproxy itself.
+1. using (not officially documented) EZproxy binary subcommand
+1. using the provided fail2ban config files
+
+If using native termination support, all active user sessions associated with
+the reported username will be terminated using the kill subcommand provided by
+the official ezproxy binary. The sysadmin will need to provide the path to the
+ezproxy and the associated Active Users and Hosts "state" file where sessions
+are tracked.
+
+If installed and configured appropriately, fail2ban can be used to to monitor
+the reported users log file and ban the associated IP address for
+`MaxLifetime` minutes (EZproxy setting) + a small buffer to force active
+sessions associated with the disabled user account to timeout and terminate.
 
 The net effect is that reported user accounts are immediately disabled and
-existing sessions forced to timeout, at which point compromised accounts can
-no longer be used on EZproxy until manually removed from the disabled users
-file.
+compromised accounts can no longer be used with EZproxy until manually removed
+from the disabled users file.
 
 **NOTE:** This application has not been designed to identify user accounts
 directly, but rather relies on other systems (currently limited to Splunk) to
@@ -75,6 +84,16 @@ See also:
 
 - Highly configurable (with more configuration choices to be exposed in the future)
 
+- Optional automatic (but not officially documented) termination of user
+  sessions via official EZproxy binary
+
+- `es` CLI application
+  - small CLI app to list and optionally terminate user sessions for a
+    specific username
+  - intended for quick troubleshooting or as an optional replacement for
+    logging into the admin UI to terminate user sessions for a specific
+    username
+
 - Supports configuration settings from multiple sources
   - command-line flags
   - environment variables
@@ -106,19 +125,27 @@ See also:
       - due to IP Address inclusion in ignore file for IP Addresses
     - username disabled
 
-- `contrib` files/content provided to allow for spinning up a [demo
-  environment](docs/demo.md) in order to provide a hands-on sense of what this
-  project can do
-  - `fail2ban`
-  - `postfix`
-  - `docker`
-    - `Maildev` container
-  - `brick`
-  - `rsyslog`
-  - `systemd`
-  - sample JSON payloads for use with `curl` or other http/API clients
-  - [demo environment](docs/demo.md) doc
-  - slides from group presentation/demo
+- `contrib` files/content
+  - intended solely for demo purposes
+    - `postfix`
+    - `docker`
+      - `Maildev` container
+    - sample JSON payloads for use with `curl` or other http/API clients
+    - [demo environment](docs/demo.md) doc
+    - slides from group presentation/demo
+    - shell scripts to setup test/demo environment
+  - intended for demo *and* as a template for production use
+    - `fail2ban`
+    - `brick`
+    - `rsyslog`
+    - `systemd`
+
+The `contrib` content is provided both to allow for spinning up a [demo
+environment](docs/demo.md) in order to provide a hands-on sense of what this
+project can do and (at least some of the files) to use as a template for a
+production installation (e.g., the `fail2ban` config files). At some point we
+hope to provide one or more Ansible playbooks (GH-29) to replace the shell
+scripts currently used by this project for setting up a test/demo environment.
 
 ### Missing
 
@@ -143,7 +170,7 @@ Known issues:
 
 See the [`CHANGELOG.md`](CHANGELOG.md) file for the changes associated with
 each release of this application. Changes that have been merged to `master`,
-but not yet an official release may also be noted in the file under the
+but not yet in an official release may also be noted in the file under the
 `Unreleased` section. A helpful link to the Git commit history since the last
 official release is also provided for further review.
 

doc.go

@@ -15,19 +15,28 @@ PURPOSE
 This application is intended to be used as a HTTP endpoint that runs alongside
 an EZproxy instance. This endpoint receives webhook requests from a monitoring
 system (Splunk as of this writing), disables the user account identified by
-the monitoring system rules and generates one or more notifications listing
-the action taken. fail2ban is used to ban the offending IP for `MaxLifetime`
-minutes (EZproxy setting) + a small buffer to force active sessions associated
-with the disabled user account to timeout and terminate.
+the rules enabled on the monitoring system and generates one or more
+notifications listing the action taken. At this point, the associated user
+sessions can be optionally (and automatically) terminated using two
+approaches:
 
-The combination of stopping new logins for the disabled user account and
-timing out existing sessions works around the lack of native support for this
-behavior in EZproxy itself.
+(1) using (not officially documented) EZproxy binary subcommand
+(2) using the provided fail2ban config files
+
+If using native termination support, all active user sessions associated with
+the reported username will be terminated using the kill subcommand provided by
+the official ezproxy binary. The sysadmin will need to provide the path to the
+ezproxy and the associated Active Users and Hosts "state" file where sessions
+are tracked.
+
+If installed and configured appropriately, fail2ban can be used to to monitor
+the reported users log file and ban the associated IP address for
+`MaxLifetime` minutes (EZproxy setting) + a small buffer to force active
+sessions associated with the disabled user account to timeout and terminate.
 
 The net effect is that reported user accounts are immediately disabled and
-existing sessions forced to timeout, at which point compromised accounts can
-no longer be used on EZproxy until manually removed from the disabled users
-file.
+compromised accounts can no longer be used with EZproxy until manually removed
+from the disabled users file.
 
 NOTE: This application has not been designed to identify user accounts
 directly, but rather relies on other systems (currently limited to Splunk) to
@@ -49,58 +58,12 @@ FEATURES
 
 • Logging of all events (e.g., payload receipt, action taken due to payload)
 
-
+• Optional automatic (but not officially documented) termination of user sessions via official EZproxy binary
 
 USAGE
 
-Help output is below. See the README for examples.
-
-$ ./brick -h
-
-Automatically disable EZproxy users via webhook requests
-
-brick x.y.z
-https://github.com/atc0005/brick
-
-
-Usage: brick [--port PORT] [--ip-address IP-ADDRESS] [--log-level LOG-LEVEL] [--log-output LOG-OUTPUT] [--log-format LOG-FORMAT] [--disabled-users-file DISABLED-USERS-FILE] [--disabled-users-entry-suffix DISABLED-USERS-ENTRY-SUFFIX] [--disabled-users-file-perms DISABLED-USERS-FILE-PERMS] [--reported-users-log-file REPORTED-USERS-LOG-FILE] [--reported-users-log-file-perms REPORTED-USERS-LOG-FILE-PERMS] [--ignored-users-file IGNORED-USERS-FILE] [--ignored-ips-file IGNORED-IPS-FILE] [--teams-webhook-url TEAMS-WEBHOOK-URL] [--teams-notify-delay TEAMS-NOTIFY-DELAY] [--teams-notify-retries TEAMS-NOTIFY-RETRIES] [--ignore-lookup-errors] [--config-file CONFIG-FILE]
-
-Options:
-  --port PORT            TCP port that this application should listen on for incoming HTTP requests.
-  --ip-address IP-ADDRESS
-                         Local IP Address that this application should listen on for incoming HTTP requests.
-  --log-level LOG-LEVEL
-                         Log message priority filter. Log messages with a lower level are ignored.
-  --log-output LOG-OUTPUT
-                         Log messages are written to this output target.
-  --log-format LOG-FORMAT
-                         Log messages are written in this format.
-  --disabled-users-file DISABLED-USERS-FILE
-                         fully-qualified path to the EZproxy include file where this application should write disabled user accounts.
-  --disabled-users-entry-suffix DISABLED-USERS-ENTRY-SUFFIX
-                         The string that is appended after every username added to the disabled users file in order to deny login access.
-  --disabled-users-file-perms DISABLED-USERS-FILE-PERMS
-                         Desired file permissions when this file is created. Note: The ezproxy daemon will need to be able to read this file.
-  --reported-users-log-file REPORTED-USERS-LOG-FILE
-                         Fully-qualified path to the log file where this application should log user disable request events for fail2ban to ingest.
-  --reported-users-log-file-perms REPORTED-USERS-LOG-FILE-PERMS
-                         Desired file permissions when this file is created. Note: fail2ban will need to be able to read this file.
-  --ignored-users-file IGNORED-USERS-FILE
-                         Fully-qualified path to the file containing a list of user accounts which should not be disabled and whose IP Address reported in the same alert should not be disabled by this application. Leading and trailing whitespace per line is ignored.
-  --ignored-ips-file IGNORED-IPS-FILE
-                         Fully-qualified path to the file containing a list of individual IP Addresses which should not be disabled and which user account reported in the same alert should not be disabled by this application. Leading and trailing whitespace per line is ignored.
-  --teams-webhook-url TEAMS-WEBHOOK-URL
-                         The Webhook URL provided by a preconfigured Connector. If specified, this application will attempt to send client request details to the Microsoft Teams channel associated with the webhook URL.
-  --teams-notify-delay TEAMS-NOTIFY-DELAY
-                         The number of seconds to wait between Microsoft Teams message delivery attempts.
-  --teams-notify-retries TEAMS-NOTIFY-RETRIES
-                         The number of attempts that this application will make to deliver Microsoft Teams messages before giving up.
-  --ignore-lookup-errors
-                         Whether application should continue if attempts to lookup existing disabled or ignored status for a username or IP Address fail.
-  --config-file CONFIG-FILE
-                         Full path to optional TOML-formatted configuration file. See contrib/brick/config.example.toml for a starter template.
-  --help, -h             display this help and exit
-  --version              display version and exit
+See the README for examples.
+
 
 */
 package main

docs/deploy.md

@@ -144,7 +144,8 @@ docs did).
 
 Depending on your target environment, you'll either need the 32-bit or 64-bit
 version of the binary that you generated earlier by following the [build
-instructions](build.md).
+instructions](build.md). Replace the `v0.1.0-0-g721e6d2` pattern below with
+the latest available stable version.
 
 | If you see this `uname -m` output | Use the filename with this pattern    | Your EZProxy server has this architecture |
 | --------------------------------- | ------------------------------------- | ----------------------------------------- |
@@ -153,8 +154,7 @@ instructions](build.md).
 
 For example, if you run `uname -m` on your EZproxy server and get `x86_64` as
 the output, you will want to deploy the `brick-v0.1.0-0-g721e6d2-linux-amd64`
-binary. Replace the `v0.1.0-0-g721e6d2` pattern with the latest available
-stable version.
+binary.
 
 #### Deploying the binary
 
@@ -177,6 +177,9 @@ version.
 1. Copy the starter/template configuration file from
    `contrib/brick/config.example.toml` and modify accordingly using the
    [configuration](configure.md) guide.
+1. Decide whether you will enable automatic sessions termination or use
+   `fail2ban`. See the [fail2ban](fail2ban.md) doc and the
+   [configuration](configure.md) guide for more information.
 1. Set a Microsoft Teams webhook URL to enable Teams channel notifications.
    - Skip this step if you don't use Microsoft Teams.
 1. Copy the starter/template "ignore" files and modify accordingly

docs/ezproxy.md

@@ -22,9 +22,19 @@ user accounts using an authentication method different from the one users are
 normally authenticated with. This allows user accounts to authenticate using
 LDAP, but be explicitly disabled using flat-files.
 
-As of April 2020 (v7.0.16), the OCLC Support team has confirmed that EZproxy
-does not support automatic/programmatic termination of active sessions. This
-means two things:
+When asked, the OCLC Support team confirmed that EZproxy (April 2020, v7.0.16)
+did not officially support automatic/programmatic termination of active
+sessions. I later learned otherwise (GH-13, GH-31) and was told (paraphrasing)
+that while it may work now, the feature I discovered was not officially
+supported. I took this to mean that the feature could be pulled (or simply
+stop working) in the future.
+
+`brick` v0.2.0 added optional support for automatic user sessions termination.
+See the [configure](configure.md) doc and the main [README](../README.md) file
+for additional information for this feature. If enabled, `fail2ban` becomes an
+optional layer in abuse control.
+
+If automatic/native user sessions termination is not enabled:
 
 - abusive user login sessions continue to be active until they are manually
   terminated or timeout
@@ -37,12 +47,12 @@ currently supports. This is accomplished by adding user accounts to a specific
 file, one per line, with an explicit `::deny` suffix per user account entry.
 When those user accounts attempt to login again they will be denied access.
 
-To handle terminating active sessions, this application relies upon a local
+To handle timing out active sessions, this application relies upon a local
 installation of `fail2ban` which runs alongside an EZproxy instance and this
-application.
+application. See the [fail2ban](fail2ban.md) document for settings specific to
+`fail2ban`.
 
-This document covers specific settings used by EZproxy. See the
-[fail2ban](fail2ban.md) document for settings specific to `fail2ban`.
+This document covers specific settings used by EZproxy.
 
 ## Settings
 
@@ -82,7 +92,7 @@ EZproxy honors it and denies login access to the user account when the next
 login attempt occurs. As already noted, active sessions must be manually
 terminated or timed out in order to interrupt access.
 
-By default, this application is configured to write entries to
+By default, this application is [configured](configure.md) to write entries to
 `/var/cache/brick/users.brick-disabled.txt`. This can be overridden by
 command-line flag (e.g., systemd unit file) or configuration file (usually
 located at `/usr/local/etc/brick/config.toml`). To configure EZproxy to use

docs/fail2ban.md

@@ -26,9 +26,13 @@ terminate. New Splunk alerts should trigger causing further IP Addresses to
 be logged (and banned) until all (or nearly all) sessions for IP Addresses
 associated with the disabled user account are terminated.
 
-`fail2ban` is in a lot of ways the "missing piece" for this application.
-Without `fail2ban`, `brick` serves the purpose by helping control new abuse,
-but is otherwise (at this time) unable to reliably stop *active* abuse.
+**NOTE**: As of v0.2.0, `brick` has the ability to perform session termination
+using the official `ezproxy` binary's `kill` subcommand. This support can be
+used alongside `fail2ban` or in place of it.
+
+The directions in this doc assume that you wish to either use both methods to
+control user sessions *or* that you will use `fail2ban` exclusively for this
+purpose.
 
 ## Directions
 
@@ -38,8 +42,7 @@ but is otherwise (at this time) unable to reliably stop *active* abuse.
   - substitute with the appropriate package manager for your Linux
     distribution (e.g., replace `apt-get` with `yum`).
 - your EZproxy server is *not* a Windows system.
-  - Note: Due to `brick` relying on `fail2ban`, Windows is not a supported
-    platform at this time.
+  - Note: Windows is not a supported platform at this time.
 - your EZproxy server does not already have `fail2ban` installed
 - you are going to test these (and all other setup instructions) in a test
   environment *first* before deploying to production

docs/rsyslog.md

@@ -29,12 +29,13 @@ messages destined for our remote log server(s).
 You may need to disable this directive if you encounter problems with messages
 not forwarding as expected in your environment.
 
-Tangent: If you're not already  forwarding/centralizing your server log
-messages, you should consider doing so. Having log messages centralized in one
-searchable location (e.g., Graylog, Splunk, ...) makes
-troubleshooting/monitoring much more effective and with lower cost
-alternatives such as Graylog, centralized log management becomes approachable
-for even lightly staffed IT teams.
+Tangent:
+
+If you're not already forwarding/centralizing your server log messages, you
+should consider doing so. Having log messages centralized in one searchable
+location (e.g., Graylog, Splunk, ...) makes troubleshooting much more
+effective. With lower cost alternatives such as Graylog, centralized log
+management becomes approachable for even lightly staffed IT teams.
 
 ## Log files