Configuration

The IPBan config file uses XML. The config file is located at https://github.com/DigitalRuby/IPBan/blob/master/IPBanCore/ipban.config.

For a built in GUI and mass administration of many clients, please visit https://ipban.com and use IPBan Pro.

A complete overview of the configuration file follows.

Here are the possible sections that can be defined in the configuration:

• LogFilesToParse. This section defines log files to scan periodically. This element must contain a single root element called LogFiles. Inside of the LogFiles element you can define 0 or more LogFile elements. The LogFile element is configured as follows:
  • Source - a short identifier for the protocol or system being checked for failed logins, i.e. RDP or SSH.
  • PathAndMask - add folder and file masks to scan, one entry per line, i.e. /var/log/auth*.log. Log file names can have {year}, {month} and {day} placeholders that will replace with UTC time, 0 padded, i.e. 2019-06-09. For local time, {year-local}, {month-local} and {day-local} placeholders can be used. Glob syntax is used, ** can be used for recursion.
  • FailedLoginRegex - a regular expression to scan for failed login text. This regex must have an ipaddress group, and ideally a username group. Example: failed\s+password\s+for\s+(invalid\s+user\s+)?(?<username>.+?\s+)from\s+(?<ipaddress>.+?)\s+port\s+[0-9]+\s+ssh.
  • FailedLoginRegexTimestampFormat - if the failed login regex contains a timestamp group, this can be used to specify the parsing format of the timestamp. By default, a generic date/time parse will be attempted.
  • FailedLoginLogLevel - log level to use for failed logins, will default to Warning if not specified.
  • SuccessfulLoginRegex - a regular expression to scan for successful logins. This regex also must have an ipaddress group, and ideally a username group. for IPBan Pro, this can be used to notify of successful logins, allowing you to take immediate action in the event you see something you don't recognize.
  • SuccessfulLoginRegexTimestampFormat - if the successful login regex contains a timestamp group, this can be used to specify the parsing format of the timestamp. By default, a generic date/time parse will be attempted.
  • SuccessfulLoginLogLevel - log level to use for successful logins, will default to Warning if not specified.
  • PlatformRegex - a regular expression to determine what platforms to run this log file on. For example, you don't want to try and scan /var/log on Windows. Valid values for this regex are 'Windows' or 'Linux'.
  • PingInterval - how often, in milliseconds, to ping the log file for changes. IPBan forces the log file to flush in order to get the most up-to-date data so this should not be too low. The default value of 10000 milliseconds (10 seconds) is sufficient for most cases.
  • MaxFileSize - the max file size, in bytes, to allow any scanned file to grow to. Once a scanned file grows beyond this, it will be truncated back to 0 size. Set this to 0 for unlimited size and to disable this truncation.
  • FailedLoginThreshold - override the standard failed login count before ban, ignored if not specified.
• ExpressionsToBlock - on Windows, this element contains the event viewer expressions to check for failed logins. This element must have a single Groups element, which can contain 0 o more Group elements. The Group element is configured as follows:
  • Source - a short identifier for the protocol or system being checked for failed logins, i.e. RDP or SSH.
  • Keywords - the event viewer keywords to check, this uses a boolean AND to match, example: 0x8010000000000000.
  • Path - the event viewer path to check, i.e. Application or Security.
  • FailedLoginThreshold - override the standard failed login count to block, ignored if not specified.
  • LogLevel - the log level to use to log the event, defaults to Warning if not specified.
  • Expressions - contains 1 or more Expression elements. The Expression element contains XPath and Regex elements. Both must match in order for the event log entry to be considered. Regex can be left blank to simply check for the existence of the element in the event log entry. Example: <Expression><XPath>//EventID</XPath><Regex>^(4625|5152)$</Regex></Expression>
  • At least one of the Expression elements must have a Regex element with an ipaddress group, and ideally a username group as well.
• ExpressionsToNotify - on Windows, this element contains the event viewer expressions to check for successful logins. This element is setup and configured identically to the ExpressionsToBlock element, except that it is looking for successful logins instead of failed logins. For IPBan Pro, these successful logins can send notifications so you take immediate action if you see something you don't recognize.
• appSettings - this section contains settings that control how IPBan operates, how long to ban ip addresses, etc.
  • FailedLoginAttemptsBeforeBan - how many failed logins before banning an ip address.
  • BanTime - The duration of time to ban an ip address (DD:HH:MM:SS) - 00:00:00:00 for 9999 days (the max duration). This can contain multiple time spans, separated by commas. For multiple time spans: When the previous ban time expires, the next failed login that causes a ban for the ip address will cause it to move to the next ban time. Once the last ban time has been passed, the ip address will be removed from the database and start back at the first ban time. Multiple time spans must be in strictly ascending order.
  • ResetFailedLoginCountForUnbannedIPAddresses - Ignored if only a single BanTime is specified. If this value is true, the failed login count will be reset to 0, causing the next failed login to start at 1 and then the ip address will move to the next ban time once the failed login count reaches FailedLoginAttemptsBeforeBan. If this value is false, then the failed login count will not be reset, and the next failed login will cause an immediate ban of the ip address into the next ban time in the BanTime list.
  • ClearBannedIPAddressesOnRestart - whether to remove all banned ip addresses from the ipban database and firewall upon startup of the service. This can be useful if you ban forever and only want to reset things manually.
  • ClearFailedLoginsOnSuccessfulLogin - whether to clear all failed logins for an ip address if there is a successful login from that ip address.
  • ProcessInternalIPAddresses - whether to process internal ip addresses. Default is false. Set to true if you want to allow ip addresses like 10.x.x.x to be detected and/or banned.
  • ExpireTime - Remove failed logins that have not yet been banned after this time in DD:HH:MM:SS format (days, hours, minutes and seconds, 0 padded). 00:00:00:00 to never forget a failed login.
  • CycleTime - how often to run processing and housekeeping, in DD:HH:MM:SS format (days, hours, minutes and seconds, 0 padded). IPBan will ban ip addresses, forget failed logins, etc. every cycle. Log parsing and event viewer parsing happens in a separate thread and queues up entries immediately, which are then processed in bulk on every cycle.
  • MinimumTimeBetweenFailedLoginAttempts - The minimum time between failed login attempts for an ip address to increment the ban counter, in DD:HH:MM:SS format (days, hours, minutes and seconds, 0 padded). This is useful when you have a number of log parsing or event viewer parsing matches but you want to aggregate them over a short time span. The default is 1 second. For example a failed RDP login might match several event log filters at once, but you would only want to count it as 1 failed login.
  • MinimumTimeBetweenSuccessfulLoginAttempts - same as MinimumTimeBetweenFailedLoginAttempts but for successful logins.
  • FirewallRulePrefix - the firewall rule prefix. You can come up with your own or leave as the default. It is recommended to suffix this rule prefix with an underscore, i.e. 'IPBan_'
  • Whitelist - comma separated list of ip addresses, cidr masks, urls or DNS names that are never banned. These will be added to a whitelist rule in the firewall. Put your static ip address in here if you have one, that way you don't accidentally lock yourself out. Whitelist takes precedence over blacklist. If you use a url, each ip entry in the response should be newline delimited, example: https://uptimerobot.com/inc/files/ips/IPv4andIPv6.txt. Urls in this config entry should have a small number of ip addresses.
  • WhitelistRegex - regular expression for whitelisting, allows for pattern matching or range of ip addresses.
  • Blacklist - comma separated list of ip addreses, cidr masks, urls or DNS names to always ban and never unban. Same format as Whitelist. For urls with large lists of blacklisted ips, FirewallUriRules is a better option as it will update less frequently.
  • BlacklistRegex - regular expression for blacklisting, allows for pattern matching or banning of range of ip addresses.
  • UserNameWhitelist - Comma separated list of user names that are allowed. UserNameWhiteListMinimumEditDistance is checked for user names not in the list to determine whether a failed user name should be banned. Case is ignored. Empty user names are always allowed. *** IMPORTANT *** This can represent an attack vector by a hacker. If they know you are using IPBan and they don't get locked out right away, they might know they are somewhat close to the right user name. Make sure your passwords are complex enough and this shouldn't be a problem.
  • UserNameWhiteListMinimumEditDistance - if the edit distance (levenshtein distance) of a failed user name is greater than this distance away, the user name is immediately banned. Set to 0 to ban all failed user names if UserNameWhitelist has entries. Case is ignored. Empty user names are always allowed. Ignored if UserNameWhitelist is empty.
  • FailedLoginAttemptsBeforeBanUserNameWhitelist - if a user name is on the user name whitelist, then the failed login attempts before ban is this value instead of FailedLoginAttemptsBeforeBan.
  • ProcessToRunOnBan - Run an external process when a ban occurs. Separate the process and any arguments with a pipe (|). The pipe is required even if arguments are empty.
    Example: c:\files\on_ip_banned.exe|###IPADDRESS### -q
    ###IPADDRESS### will be replaced with the actual IP which was banned.
    ###USERNAME### will be replaced with the username if known.
    ###SOURCE### will be replaced with the source if known.
    ###APP### will be replaced with the app name and version.
    ###COUNT### will be replaced with the number of events.
    ###LOG### will be replaced with matching log text that triggered the event, if known.
    Can run multiple processes by delimiting each with a newline
  • ProcessToRunOnUnban - Run an external process when an unban occurs. Separate the process and any arguments with a pipe (|). The pipe is required even if arguments is empty.
    Example: c:\files\on_ip_unbanned.exe|###IPADDRESS### -q
    ###IPADDRESS### will be replaced with the actual IP which was unbanned.
    Can run multiple processes by delimiting each with a newline
  • FirewallRules - Firewall rules to create to allow or block ip addresses, one per line. Great way to persist firewall rules. Format is rule-name;allow or block;ip list (comma separated);allowed port list (comma separated);platform regex.
    For allow rules, port list is allowed ports, so if you wanted to allow port 3389, just enter 3389.
    For block rules, port list is ignored ports, so if you wanted to block port 3389, you'd enter 0-3388,3390-65535.
    The name should be kept to 16 or less chars.
    See https://www.mediawiki.org/wiki/Help:Range_blocks and https://www.mediawiki.org/wiki/Help:Range_blocks/IPv6
    Negative look ahead regex: https://stackoverflow.com/questions/23724661/regex-to-negate-the-whole-word
    Put your allow rules first, then your block rules, for Linux iptables this is important, on Windows order does not matter, block rules have precedence
    On Windows firewall, all traffic is blocked by default, so only allow rules are needed, order does not matter
    On Linux iptables, all traffic is allowed by default, so allow rules are still needed but should go before any block rules
    On Linux, ipset has a bug where cidr mask /0 is not allowed, so you must split half and half of the ipv4 and ipv6 range
    Example that allows Reddis from certain ip, and blocks everything except ssh, rdp, http/https:
    ReddisAllowIP;allow;10.0.0.1,10.0.0.2,192.168.1.168/24;6379;.
    WebOnly;block;0.0.0.0/1,128.0.0.0/1,::/1,8000::/1;22,80,443,3389;^(?:(?!Windows).)+$
  • UseDefaultBannedIPAddressHandler - whether to use the default banned ip address handler for banned ip address sharing. Set to false to turn this off.
  • FirewallUriRules - External firewall uri rules to block, format is (one per line): [RulePrefix],[Interval in DD:HH:MM:SS],[URI][Newline]
  • ExternalIPAddressUrl - specify an external url to get the remote ip address of the machine, i.e. https://checkip.amazonaws.com/.
  • GetUrlUpdate - a url to get when the service cycle runs, empty for none. Example: http://192.168.1.2/ipban/update?ip=###IPADDRESS###&remoteIp=###REMOTEIPADDRESS###&name=###MACHINENAME###&version=###VERSION###&guid=###GUID###&osname=###OSNAME###&osversion=###OSVERSION###
  • GetUrlStart - a url to get when the service starts, empty for none. Example: http://192.168.1.2/ipban/start?ip=###IPADDRESS###&remoteIp=###REMOTEIPADDRESS###&name=###MACHINENAME###&version=###VERSION###&guid=###GUID###&osname=###OSNAME###&osversion=###OSVERSION###
  • GetUrlStop - a url to get when the service stops, empty for none. Example: http://192.168.1.2/ipban/stop?ip=###IPADDRESS###&remoteIp=###REMOTEIPADDRESS###&name=###MACHINENAME###&version=###VERSION###&guid=###GUID###&osname=###OSNAME###&osversion=###OSVERSION###
  • GetUrlConfig - a url to get config file from, empty for none. Example: http://192.168.1.2/ipban/config?guid=###GUID###
  • IPBanPro_UrlWebSocket - a url to connect to an IPBan Pro server via web socket. Allows sending and receiving data and commands via web socket. Ignored for free version. Examples: ws://localhost:52664/