Security rules configuration

Security server directory and files

Starting with v7.1, EZproxy servers contain a /security directory to store files related to the security rules and pseudonymous identifier features.

This directory contains two databases:

  1. identifier_v1.db (contains information pertaining to the pseudonymous identifier)
  2. security_v1.db (contains information pertaining to the security rules)

We recommend allocating a minimum of 200 MB of disk space to this directory. Please monitor the space allocated to this directory as very high-traffic systems may require more.

This directory also contains a configuration file called 000-default.txt. This file contains the active security rules on your system and allows modification by administrators. This file is generated with the following command:

ezproxy -ms

For example, on Linux systems, the command to create the configuration file would be:

./ezproxy -ms

 

Security rules syntax

The rules in your 000-default.txt configuration file adheres to the following pattern:

Rule name (50 bytes maximum, must be unique)

 if Criterion over Limit per Period then Action for (optional when Action = block) Period (optional when Action = block)
Examples:                    
EnforceOCLCByteLimit if bytes_transferred over 1500000000 per 60 then block for 60
OCLCIPLimit if network_address over 5 per 1200 then log    

 

Possible values for Criterion:

Value Description
bytes_transferred Total number of bytes transferred
country Country name as derived by IP to geography mapping 
ip_address High order 24 bits of the V4 IP address or 64 bits of V6 IP address (matching done only on this portion of the IP address)
login_failure Number of failures to successfully login
network_address Full V4 or V6 IP address (matching done with entire IP address)
pdf_bytes_transferred Number of bytes of PDF documents transferred
pdf_download Number of PDF files transferred
login_success Number of successful logins
login_relogin Number of relogin

 

Possible values for Action: 

Value Description
block If the rule is tripped, block the user for the specified Period of time.
log If the rule is tripped, do not block the user, but still log an evidence entry in the security database for the rule-tripping event.

 

Period specifies the length of the rule evaluation window or block period in minutes. The maximum value is 43200 minutes (30 days).

Default security rules

EZproxy v7.1 contains a default set of security rules. These rules are active from the time you upgrade, but can be modified to meet your institution's needs (see Tuning your security rules configuration below). The default security rules are:

  1. A user will be blocked if:
    1. They transfer over 2GB of data within an hour (EnforceOCLCByteLimit).
    2. They access EZproxy from more than four countries within a day (EnforceOCLCCountryLimit).
    3. They access EZproxy from more than 20 network addresses within an hour (EnforceOCLCIPLImit).
  2. A user will prompt a security event to be logged if:
    1. They transfer over 1GB of data within an hour (OCLCByteLimit1G).
    2. They access EZproxy from more than two countries within a day (OCLCCountryLimit).
    3. They make more than 10 failed password attempts within an hour (OCLCLoginFailureLimit).
    4. They access EZproxy from more than 10 network addresses within a day (OCLCIPLimit10day).
    5. They access EZproxy from more than 10 network addresses within an hour (OCLCIPLimit10).
    6. They transfer over 500MB of data in PDF format within an hour (OCLCPDFByteLimit).
    7. They transfer over 500MB of data in PDF format within a day  (OCLCPDFByteLimitlong).
    8. They download more than 150 PDF files within an hour (OCLCPDFLimit2).
    9. They download more than 50 PDF files within five minutes  (OCLCPDFLimitshort).
    10. They download more than 300 PDF files within a day (OCLCPDFLimitlong).

These rules appear as follows in the 000-default.txt configuration file:

EnforceOCLCByteLimit    if    bytes_transferred      over    2000000000  per    60    then    block
OCLCByteLimit1G         if    bytes_transferred      over    1000000000  per    60    then    log
OCLCCountryLimit        if    country                over    2           per    1440  then    log
EnforceOCLCCountryLimit if    country                over    4           per    1440  then    block
OCLCLoginFailureLimit   if    login_failure          over    10          per    60    then    log
EnforceOCLCIPLImit      if    network_address        over    20          per    60    then    block
OCLCIPLimit10day        if    network_address        over    10          per    1440  then    log
OCLCIPLimit10           if    network_address        over    10          per    60    then    log
OCLCPDFByteLimit        if    pdf_bytes_transferred  over    500000000   per    60    then    log
OCLCPDFByteLimitlong    if    pdf_bytes_transferred  over    500000000   per    1440  then    log
OCLCPDFLimit2           if    pdf_download           over    150         per    60    then    log    
OCLCPDFLimitshort       if    pdf_download           over    50          per    5     then    log    
OCLCPDFLimitlong        if    pdf_download           over    300         per    1440  then    log

Database maintenance directives

The following directives may be added to 000-default.txt in order to customize your security rules settings:

Directive Description
EvidenceRetentionDays number Number of days to retain data about rules that were tripped that had a block action. By default, this is set to 14 days.
PurgeTime hh:mm Time of day to purge security database; default is 03:30 local time.
ResolvedRetentionDays number Number of days to retain data about rules that were tripped that had a log action or the user that tripped the rule was set as exempt from rules enforcement. By default this is set to 14 days.
VacuumDay dayofweek Day of the week to perform database compacting. No data is deleted during this operation. Day of the week is specified as Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday. This operation happens following daily purge processing based on PurgeTime. Vacuum may be disabled by specifying Off as the day. By default, this will take place on a Wednesday.

 

Tuning your security rules configuration

EZproxy's security rules engine is designed to be tuned by the EZproxy administrator. Since many sites have customized workflows, the default blocking rules that are shipped with EZproxy 7.1 are intentionally generous in their settings to prevent legitimate usage from being blocked.  
 
In order to more finely tune the rules to block illegitimate use at your site, OCLC recommends the following steps: 

  1. Run with the default rules long enough to ensure that your users’ workflows have been exercised. 
  2. Analyze the results. For example, look at the rule(s) that have bytes_transferred as the trigger. Make your determinations about the largest legitimate value that was logged. This number gives you a good minimum in order to set up a blocking rule for this trigger.
  3. Repeat this process with other triggers.   
  4. Once you set a blocking rule, monitor the EZproxy administration UI frequently to verify that legitimate usage is not being blocked. 
  5. If you set a blocking rule but it isn’t tripping, create a logging copy of the blocking rule and set the limit lower. Then analyze any users that trip the logging rule. 
  6. Regularly review rule evidence to further tune your rules.

Configuring Email Notifications

EZproxy v7.2 introduced the ability to receive real-time email alerts for security rule alert events. EZproxy v7.3 specifies the name of the EZproxy server as part of the email. Prior versions will send the notifications without specifying the name of the EZproxy server.

Hosted EZproxy customers please contact OCLC support for assistance setting up email notifications.

Stand-alone EZproxy customers to setup email notifications you must obtain your WSkey secret. Please login to the developer network to view the wskey secret. For more information on accessing the developer network please visit this link.

Once you have obtained your Wskey secret. Please follow these steps:

  1. Visit your EZproxy's admin page. Please visit this link for more detail.
  2. Navigate to the security rules notification page by selecting View security rules > Tripped Security Rules Notifications
  3. You will see the following interface

    clipboard_ea724e79e92cd9efbe4dcefee018b78ce.png
  4. Input email address is the email address field. Use ' , ' to separate email addresses.
  5. If you choose to select "Receive Daily Email Digest" all email addresses will receive a single daily digest of notifications. This will disable the ability to receive real-time individual emails for each security event. Disabling the "Receive Daily Email Digest" option will not disable the daily email.
  6. Input the WSKey secret into the WSKey Secret field. Select the add button to apply the WSKey secret. This is a required field for emails to function.