README
1NAME
2 URPL::Prepare -- prepare hostname for URBL domain lookup
3
4SYNOPSIS
5 require URBL::Prepare;
6
7 my $ubp = new URBL::Prepare;
8
9 $tlds = $blessed->cachetlds($localfilelistptr);
10 $whitelist = $blessed->cachewhite($localfilelistptr);
11 $domain = $blessed->urbldomain($hostname);
12 $response_code = $proto->loadcache($url,$localfile);
13 ($response,$message) = $proto->loadcache($url,$localfile);
14 $rv = $blessed->urblblack($hostname);
15 $rv = $blessed->urblwhite($hostname);
16
17DESCRIPTION
18 * my $urbl = new URBL::Prepare;
19 This method returns a blessed reference to an empty hash.
20
21 For use with other modules:
22
23 require URBL::Prepare;
24
25 @ISA = qw(URBL::Prepare);
26
27URBL Preparation for lookup methods
28 The following three methods are for facilitating URBL lookups.
29
30 SEE: http://www.uribl.com/about.shtml
31 and http://www.surbl.org/guidelines
32
33 * $tldlist = $blessed->cachetlds($localfilelistptr);
34 This method opens local files in "file list" and extracts the tld's
35 found therein.
36
37 input: ptr to array of local/file/path/names
38 return: array ptr to list of tld's
39
40 NOTE: place level 3 tld's ahead of level 2 tld's
41
42 * $whitelist = $blessed->cachewhite($localfilelistptr);
43 This method opens local file(s) in "file list" and extracts the
44 domains found therein.
45
46 See http://wiki.apache.org/spamassassin/DnsBlocklists and
47 http://spamassasin.googlecode.com/svn-history/r6/trunk/share/spamassassin/
48
49 Note:: these URL's may change
50
51 input: ptr to array of local/file/path/names
52 return: array ptr to whitelist domain names
53
54 * $blacklist = $blessed->cacheblack($localfilelistptr);
55 This method opens local file(s) in "file list" and extracts the
56 domains found therein. The domains may be space seperated many to a
57 line.
58
59 input: ptr to array of local/file/path/names
60 return: ptr to blacklist domain names
61
62 * $domain = $blessed->urbldomain($hostname)
63 This method extracts a domain name to check against an SURBL. If the
64 hostname is whitelisted, the return value is false, otherwise a domain
65 name is returned.
66
67 input: hostname
68 return: false if whitelisted
69 else domain to check against SURBL
70
71 NOTE: optionally white or tld testing will be bypassed if the pointer
72 is undefined or points to an empty array.
73
74 * $rv = $blessed->urblblack($hostname)
75 This method check if a hostname is found within the local black
76 list(s).
77
78 input: hostname
79 return: domain found, else false
80
81 * $rv = $blessed->urbwhite($hostname)
82 This method check if a hostname is found within the local white list.
83
84 input: hostname
85 return: domain found, else false
86
87 * $response_code = $proto->loadcache($url,$localfile);
88 * ($response,$message) = $proto->loadcache($url,$localfile);
89 This method uses LWP::UserAgent::mirror to conditionally retrieve
90 files to fill local cache with WHITELIST and TLD names. The response
91 code is the result returned by the HTTP fetch and should be one of 200
92 or 304. At the time this module was released the files were as
93 follows:
94
95 WHITE LIST URL
96 http://spamassasin.googlecode.com/svn-history/r6/trunk/share/spamassassin/25_uribl.cf
97
98 and
99
100 TLDLIST URL (include some known abusive tlds)
101 http://george.surbl.org/three-level-tlds
102 http://george.surbl.org/two-level-tlds
103
104 input: path/name/for/localfile
105 return: http response code,
106 response message
107
108 In scalar context only the http response code is returned. In array
109 context the numeric response code and a related text message are
110 returned.
111
112 200 OK file cached
113 304 Not Modified file is up-to-date
114
115 Any other response code indicates and error.
116
117 Usage:
118 $rv = URBL::Prepare->loadcache($url,$localfile);
119
120APPLICATION EXAMPLES
121 This example shows how to include URBL::Prepare in another module
122
123 #!/usr/bin/perl
124 package = Some::Package
125
126 use vars qw(@ISA);
127 require URBL::Prepare;
128
129 @ISA = qw( URBL::Prepare );
130
131 sub new {
132 my $proto = shift;
133 my $class = ref $proto || $proto || __PACKAGE__;
134 my $methodptr = {
135 ....
136 };
137 bless $methodptr, $class;
138 }
139 ... package code ...
140 1;
141
142 ...end
143 ......................
144
145 #!/usr/bin/perl
146 # my application
147 #
148 use Net::DNS::Dig;
149 use Some::Package;
150
151 my $dig = new Net::DNS::Dig;
152 my $sp = new Some::Package;
153 #
154 # initialiaze URBL::Prepare
155 #
156 $sp->cachewhite($localwhitefiles);
157 $sp->cachetlds($localtldfiles);
158
159 # set multi.surbl.org bit mask
160 # 2 = comes from SC
161 # 4 = comes from WS
162 # 8 = comes from PH
163 # 16 = comes from OB (OB is deprecated as of 22 October 2012.)
164 # 16 = comes from MW (MW active as of 1 May 2013.)
165 # 32 = comes from AB
166 # 64 = comes from JP
167
168 # test as: surbl-org-permanent-test-point.com.multi.surbl.org
169
170 my $mask = 0xDE;
171
172 ... application ...
173 ... generates ...
174 ... hostname ...
175
176 my $domain = $sp->urbldomain($hostname)
177
178 my $response = $dig->for($hostname . 'multi.surbl.org')
179 if $domain; # if not whitelisted
180
181 # if an answer is returned
182 if ($domain && $response->{HEADER}->{ANCOUNT}) {
183 # get packed ipV4 answer
184 my $answer = $response->{ANSWER}->[0]->{RDATA}->[0];
185 if ($mask & unpack("N",$answer)) {
186 # answer is found in selected surbl list
187 } else {
188 # answer not found in selected surbl list
189 }
190 }
191 # domain not found in surbl
192
193 ...end
194
195 This is an example of a script file to keep the whitelist and tldlist
196 current. Run as a cron job daily.
197
198 #!/usr/bin/perl
199 #
200 # cache refresh cron job
201 #
202 require URBL::Prepare;
203
204 my $whiteurl =
205 'http://spamassasin.googlecode.com/svn-history/r6/trunk/share/spamassassin/25_uribl.cf';
206
207 my $tld2url = 'http://george.surbl.org/two-level-tlds';
208 my $tld3url = 'http://george.surbl.org/three-level-tlds';
209
210 my $cachedir = './cache';
211 my $lvl2file = $cachedir .'/level2';
212 my $lvl3file = $cachedir .'/level3';
213 my $whtfile = $cachedir .'/white';
214
215 mkdir $cachedir unless -d $cachedir;
216
217 URBL::Prepare->loadcache($whiteurl,$whtfile);
218 URBL::Prepare->loadcache($tld2url,$lvl2file);
219 URBL::Prepare->loadcache($tld3url,$lvl3file);
220
221AUTHOR
222 Michael Robinton <michael@bizsystems.com>
223
224COPYRIGHT
225 Copyright 2013-2014, Michael Robinton <michael@bizsystems.com>
226
227 This program is free software; you may redistribute it and/or modify it
228 under the same terms as Perl itself.
229
230 This program is distributed in the hope that it will be useful, but
231 WITHOUT ANY WARRANTY; without even the implied warranty of
232 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
233
234See also:
235 the LWP::Request manpage, the Net::DNS::Dig manpage
236
237