Skip to content

Configuration

Jump to bottom
Jeff Johnson edited this page Jan 10, 2021 · 45 revisions

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.
    • 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.
    • 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.
  • 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.
    • 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 time to ban an ip address in DD:HH:MM:SS format (days, hours, minutes and seconds, 0 padded). 00:00:00:00 to ban forever. Be aware that banning forever will constantly grow the firewall rules, so watch out for performance and/or memory issues.
    • 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.
    • 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, 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, 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 (|). ###IPADDRESS### will be replaced with the actual IP which was banned. The pipe is required. Example: c:\system files\on_ip_banned.exe|###IPADDRESS### -q
    • ProcessToRunOnUnban - run an external process when a ban is removed. Separate the process and any arguments with a pipe (|). ###IPADDRESS### will be replaced with the actual IP which was unbanned. The pipe is required. Example: c:\system files\on_ip_banned.exe|###IPADDRESS### -q
    • 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 spearated);allowed port list (comma separated);platform regex. The name should be kept to 16 or less chars.
    • 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###&amp;remoteIp=###REMOTEIPADDRESS###&amp;name=###MACHINENAME###&amp;version=###VERSION###&amp;guid=###GUID###&amp;osname=###OSNAME###&amp;osversion=###OSVERSION###
    • GetUrlStart - a url to get when the service starts, empty for none. Example: http://192.168.1.2/ipban/start?ip=###IPADDRESS###&amp;remoteIp=###REMOTEIPADDRESS###&amp;name=###MACHINENAME###&amp;version=###VERSION###&amp;guid=###GUID###&amp;osname=###OSNAME###&amp;osversion=###OSVERSION###
    • GetUrlStop - a url to get when the service stops, empty for none. Example: http://192.168.1.2/ipban/stop?ip=###IPADDRESS###&amp;remoteIp=###REMOTEIPADDRESS###&amp;name=###MACHINENAME###&amp;version=###VERSION###&amp;guid=###GUID###&amp;osname=###OSNAME###&amp;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/

IPBan (c) 2012-Present Digital Ruby, LLC - https://ipban.com

Clone this wiki locally