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