Dansguardian Denied Action
Triggers a custom action when a site is blocked/denied. Works by monitoring the access log of Dansguardian or e2guardian.
DansGuardian is an award winning Open Source web content filter. It filters the actual content of pages based on many methods including phrase matching, PICS filtering and URL filtering. It does not purely filter based on a banned list of sites like lesser totally commercial filters.
e2guardian is a fork of Dansguardian Project with many improvements and bug fixes, e2guardian is a web content filtering proxy that works in conjunction with another caching proxy such as Squid.
Installation
gem install dansguardian_denied_action
Usage
dansguardian_denied_action
follows the Observer pattern. See more information from the Ruby Rdocs. You can add as many observers as you'd like that are triggered when a denied action log is added to the access log. An observer is an instance of a class that has an update
method defined. The update
method is called whenever the observer is notified (when there is a denied log).
Currently only log file format 2 (CSV-style format) is supported. Please contribute if you'd like more formats supported. Make sure your /etc/dansguardian/dansguardian.conf
has the logfileformat
set as 2
. For example:
# Log File Format
# 1 = DansGuardian format (space delimited)
# 2 = CSV-style format
# 3 = Squid Log File Format
# 4 = Tab delimited
# 5 = Protex format
# 6 = Protex format with server field blanked
logfileformat = 2
Example
require 'dansguardian_denied_action'
# An observer class that outputs to the screen
class OutputToScreen
def update( log )
puts "IP: #{log.requesting_ip}"
puts "URL: #{log.requested_url}"
puts "Category: #{log.category}"
end
end
# An observer class that sends an email
class SendEmail
def update( log )
message = "Denied page accessed!\n\n"
message << "IP: #{log.requesting_ip}\n"
message << "URL: #{log.requested_url}\n"
message << "Category: #{log.category}"
`echo "#{message}" | mail -s "Denied page" admin@example.com`
end
end
# Initialize the access log class and select the format of dansguardian
@access_log = DansguardianDeniedAction::AccessLog.new( format: DansguardianDeniedAction::LOG_FORMAT_CSV )
# Add as many observers as you'd like
@access_log.add_observer( OutputToScreen.new )
@access_log.add_observer( SendEmail.new )
# Call the monitor method to monitor the log and notify
# your observers when a blocked page is accessed
@access_log.monitor
Customization
If you want to trigger your observers on an action other than DENIED
, you can specify one like so:
@access_log = DansguardianDeniedAction::AccessLog.new(
format: DansguardianDeniedAction::LOG_FORMAT_CSV,
action: 'INFECTED'
)
e2guardian
If you are using e2guardian rather than dansguardian, you want to point to the correct log path. For example:
@access_log = DansguardianDeniedAction::AccessLog.new(
format: DansguardianDeniedAction::LOG_FORMAT_CSV,
path: '/var/log/e2guardian/access.log'
)
Log methods
Your observer class which as the update
method defined accepts a log
as it's sole argument. This is an instance of DansguardianDeniedAction::Log
. The accessor methods available include:
- raw
- date_time
- requesting_user
- requesting_ip
- requested_url
- actions
- reason
- subreason
- method
- size
- weight
- category
- filter_group_number
- http_code
- mime_type
- client_name
- filter_group_name
- user_agent
More information on the data within these accessor methods can be found on the DansGuardian Documentation Wiki.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/eterry1388/dansguardian_denied_action. Please make sure
all tests pass before making a pull request. The tests require an OS with a /tmp
directory.
How to run system tests
rspec
The output should look something like this:
DansguardianDeniedAction
DansguardianDeniedAction::AccessLog
Updates observer for every new log
logs
DansguardianDeniedAction::CsvLog
raw
should eq "\"2016.1.8 19:46:10\",\"fred\",\"192.168.0.1\",\"http://example.com\",\"*DENIED* Banned site: example.com\",\"GET\",\"3804\",\"0\",\"Pornography\",\"1\",\"403\",\"text/html\",\"fred.example.com\",\"group-name\",\"Mozilla/5.0\""
date_time
should eq "2016.1.8 19:46:10"
requesting_user
should eq "fred"
requesting_ip
should eq "192.168.0.1"
requested_url
should eq "http://example.com"
actions
should eq "DENIED"
reason
should eq "Banned site: example.com"
subreason
should eq "Banned site: example.com"
method
should eq "GET"
size
should eq 3804
weight
should eq 0
category
should eq "Pornography"
filter_group_number
should eq 1
http_code
should eq 403
mime_type
should eq "text/html"
client_name
should eq "fred.example.com"
filter_group_name
should eq "group-name"
user_agent
should eq "Mozilla/5.0"
Finished in 4.03 seconds (files took 0.10009 seconds to load)
19 examples, 0 failures
License
The gem is available as open source under the terms of the MIT License.