From b1ceb7cad4aa8221214a5f287d4d2cd235fc4123 Mon Sep 17 00:00:00 2001 From: Evan Anderson Date: Wed, 31 Aug 2011 11:41:45 -0400 Subject: Initial commit --- README.txt | 226 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 README.txt diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..1599c26 --- /dev/null +++ b/README.txt @@ -0,0 +1,226 @@ +ts_block.vbs - Blocks IP addresses generating invalid Terminal Services logons +Copyright 2011 Wellbury LLC - See LICENSE for license information + +Release 20110901 - Adapted from sshd_block release 20100120 + +For support, please contact Evan Anderson at Wellbury LLC +EAnderson@wellbury.com, (866) 569-9799, ext 801 + + +If you like this program please drop me an email. If you have any +ideas for enhancements or find a bug, I'd love to hear about that +too. + + +Overview +======== +ts_block is a VBScript program that acts as a WMI event sink to receive +events logged by Windows in response to invalid Terminal Services +logons. It parses these log entries and acts upon them as follows: + + - If the IP address attempts to logon with a username flagged as "block +immediately" the IP address is blocked immediately. + + - If the IP address attempts to logon with more frequently than is +allowed in a given time period the IP address is blocked. + +The "block immediately" usernames and thresholds associated with repeated +logon attempts are configurable in the "Configuration" section of the +script. Default settings are as follows: + + Block Immediately Usernames - administrator, root, guest + Logon attempts allowed - 5 in 120 seconds (2 minutes) + Duration of block - 300 seconds (5 minutes) + +The configuration variables for these values are reasonably +self-explanatory. Additional variables to enable/disable debugging and +event log usage are also present and self-explanatory. Review the +section "Registry Configuration Parameters" for information about +configuring via the registry (which is useful for management via Group +Policy). + +Four times per second IP addresses that have remained blocked for their +assigned block duration are unblocked. + +ts_block does not run under Windows 2000 Server (because I have no +machines handy to test it on and because the Terminal Services logon +type, 10, is not logged on Windows 2000 Server) and under Windows XP +(because the remote IP address is not included in the event log +message). + + +Pre-Requisite Computer Configuration +==================================== +For Windows Vista, 2008, 7, and 2008 R2 the "Advanced Firewall" is used +to create inbound firewall rules blocking traffic from the blocked host. +On these operating systems no special configuration of the registry or +network adapters is necessary. + +Because Windows Server 2003 lacks sufficient features in its built-in +firewall functionality a black-hole host route is used. Unfortunately, +the "trick" commonly used on Linux to black-hole traffic with a route to +"lo" (127.0.0.1) doesn't work on Windows. The "route" command will fail +if the destination specified isn't local to one of machine's interfaces, +as well. As such, there are two options for selecting the destination +address used for the black-hole route. + +You may specify the black-hole destination IP address as REG_SZ value as +described below in the "Registry Configuration Parameters" section. This +address must be local to (in the same IP subnet as) one of the server +computer's interfaces. It is recommended that you select an address that +is unused in your network. This is my preferred method of installation +because no device drivers need to be installed. + +Alternatively you may install a network interface with a static IP +address assigned and no default gateway specified be present on the +server computer. A physical hardware device is not necessary as the +Microsoft Loopback Adapter serves the purposes of this application. +Details about installing the Microsoft Loopback Adapter is available +from: http://support.microsoft.com/kb/842561 + +After you have installed the Microsoft Loopback Adapter (or chosen an +unused physical hardware NIC) specify a static IP address and no +default gateway in the TCP/IP version 4 properties for the adapter. The +IP address and subnet mask assigned to this adapter should not match any +network in use in your enterprise and should be in the RFC 1918 space. + +The ts_block script will locate the adapter with no default gateway +specified and use it as the destination for the black-hole route. + + +Registry Configuration Parameters +================================= +The following configuration paramters are available under the registry +path: HKLM\Software\Policies\Wellbury LLC\ts_block + +Parameter: BlockAttempts +Type: REG_DWORD +Explanation: The number of sequential failed logon attempts (with +accounts that are not considered "block immediately" accounts) that will +trigger a block. + +Parameter: BlockDuration +Type: REG_DWORD +Explanation: The duration, in seconds, of a block (either because of +reaching the BlockAttempts threshhold or because of a "block +immediately"). + +Parameter: BlockTimeout +Type: REG_DWORD +Explanation: The duration, in seconds, that must elapse between failed +logon attempts to reset the count of failed logon attempts for a given +IP address. + +Parameter: BlackholeIP +Type: REG_SZ +Explanation: The IP address used for the black-hole route (for Windows +Server 2003). If not specified the default algorithm of selecting the IP +address of a network interface with no default gateway specified will be +used. This setting is not used in Windows Server 2008 and later versions +of Windows. + +A Group Policy Administrative Template (ADM) file is included with this +distribution that is capable of setting these values. Deploying a GPO +near the top of the domain with the BlockAttempts, BlockDuration, and +BlockTimeout values specified and Site or OU-level GPOs with the +BlackholeIP value specified (as this will vary based on the subnets +where the server computers are located, and is only necessary for +Windows Server 2003 machines) is recommended. + + +Script Testing +============== +It is recommended that you copy the ts_block.vbs script to your desired +location, modify the configuration parameters if you are unsatisfied +with the defaults, and execute the script either. It is recommended that +you execute the script using the CSCRIPT.EXE utility, but it is possible +to execute the script using WSCRIPT.EXE via double-clicking on the +script file in Windows Explorer. Be aware that, should debugging be +enabled, execution is only effectively possible through CSCRIPT.EXE +because message logging to pop-up dialogs will "stall" the script until +the dialogs are dismissed. + +Test the functionality of the script by performing both invalid logons +using both a "block immediately" account and attempting repeated logons +with a valid or invalid account that is not in the "block immediately" +list. Blocking and unblocking events will be logged in the Application +event log. (It is recommended that you perform your tests via a remote +control mechanism such that you do not lose communication with the +server computer during testing.) + + +Windows Service Installation +============================ +A binary copy of the public domain "Non-Sucking Service Manager" (nssm, +available from http://iain.cx/src/nssm/) is included with ts_block to +facilitate installation as a Windows service. The Microsoft SRVANY tool +may also be used to run ts_block as a Windows Service. + +If you choose to use nssm, copy the nssm.exe file to the location of +your choice (in "%ProgramFiles%\ts_block", for example). + +After you are satisfied with the performance of the script in testing +and have copied nssm.exe to the desired location, install the script as +a Windows service using the following command-line (from the directory +where nssm was installed): + + nssm install ts_block %SystemRoot%\System32\cscript.exe + "\"%ProgramFiles%\ts_block\ts_block.vbs\"" + +The command is depicted as two lines above but should be entered on a +single line. It is necessary to enter the "\" characters as depicted +such that the resulting registry entry is surrounded by double quotes. +This command will create a service set to start automatically. (If your +ts_block.vbs is stored in a path w/o spaces then you don't need to go +through those gyrations.) + +After installing the service start it and verify that it functions +properly. + + +External Dependencies +===================== +The following external programs are required to be in the PATH for the +user context under which ssdh_block is executing: + +ROUTE.EXE - For black-hole routing blocked IP addresses under Windows XP + +NETSH.EXE - For creating Advanced Firewall rules on Windows Vista and + later versions of Windows + +EVENTCREATE.EXE - For writing to the event log + (only if event logging is enabled) + + +Performance and Security +======================== +A simple and fairly unscientific stress test function is included in the +script (and disabled by default). Testing with the parameters listed in +the script (but with the BLOCK_DURATION decreased from the default to 60 +seconds) on a Windows Server 2003 SP2 x86 Stadard Edition machine +resulted in peak memory usage of 6,780KB. As the blocked queue drained +at the end of the test, the memory usage decreased slightly. On the face +of it, it would appear that the script can handle at least thousands of +unique IP addresses being blocked at a rate of one IP address every 10 +to 50ms with no major issues. + +Parameters passed to calls to external programs for creating Windows +Event Log entries or altering IP routes are sanitized through a regular +expression match (allowing only the characters 0-9, a-z, A-Z, and +period, underscore, space, right-leaning slash, colon, and minus). + + +Windows Installer Package (MSI) +=============================== +A Windows Installer package (MSI) version of ts_block is included with +this distribution (along with the WiX source file used to create the +MSI). The MSI is self-contained (all necessary files are compressed and +embedded within it) and can be used for automated deployment of ts_block +as a service under NSSM. + + +Future Roadmap +============== +Exciting enhancement possibilities include: + + - Loading values for "block immediately" usernames from the registry. -- cgit v1.2.3