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:
- identifier_v1.db (contains information pertaining to the pseudonymous identifier)
- 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:
- A user will be blocked if:
- They transfer over 2GB of data within an hour (
EnforceOCLCByteLimit
). - They access EZproxy from more than four countries within a day (
EnforceOCLCCountryLimit
). - They access EZproxy from more than 20 network addresses within an hour (
EnforceOCLCIPLImit
).
- They transfer over 2GB of data within an hour (
- A user will prompt a security event to be logged if:
- They transfer over 1GB of data within an hour (
OCLCByteLimit1G
). - They access EZproxy from more than two countries within a day (
OCLCCountryLimit
). - They make more than 10 failed password attempts within an hour (
OCLCLoginFailureLimit
). - They access EZproxy from more than 10 network addresses within a day (
OCLCIPLimit10day
). - They access EZproxy from more than 10 network addresses within an hour (
OCLCIPLimit10
). - They transfer over 500MB of data in PDF format within an hour (
OCLCPDFByteLimit
). - They transfer over 500MB of data in PDF format within a day (
OCLCPDFByteLimitlong
). - They download more than 150 PDF files within an hour (
OCLCPDFLimit2
). - They download more than 50 PDF files within five minutes (
OCLCPDFLimitshort
). - They download more than 300 PDF files within a day (
OCLCPDFLimitlong
).
- They transfer over 1GB of data within an hour (
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:
- Run with the default rules long enough to ensure that your users’ workflows have been exercised.
- 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.
- Repeat this process with other triggers.
- Once you set a blocking rule, monitor the EZproxy administration UI frequently to verify that legitimate usage is not being blocked.
- 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.
- 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:
- Visit your EZproxy's admin page. Please visit this link for more detail.
- Navigate to the security rules notification page by selecting View security rules > Tripped Security Rules Notifications
- You will see the following interface
- Input email address is the email address field. Use ' , ' to separate email addresses.
- 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.
- 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.