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:

Possible values for Criterion:

Possible values for Action: 

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:

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
   
   
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.