Zonemaster/Engine.pm

filter: Statementstmt 90.4% 19 / 21 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 7 / 7 Podpod n/a totaltotal 92.8% 26 / 28 CC 1 SCAR 0.4
CC
1
Cov
90%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« auto/share/dist/Zonemaster-Engine/json2yaml.pl ↑ Summary Zonemaster/Engine/Nameserver.pm »
1 package Zonemaster::Engine;
2  
3 1 ▶use v5.16.0;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 1 ▶use version; our $VERSION = version->declare("v9.0.1");
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 1 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
9 # Locale::TextDomain (<= 1.20) doesn't know about File::ShareDir so give a helping hand.
10 # This is a hugely simplified version of the reference implementation located here:
11 # https://metacpan.org/source/GUIDO/libintl-perl-1.21/lib/Locale/TextDomain.pm
12 1 require File::ShareDir;
13 1 require Locale::TextDomain;
14 1 my $share = File::ShareDir::dist_dir( 'Zonemaster-Engine' );
15 1 Locale::TextDomain->import( 'Zonemaster-Engine', "$share/locale" );
16 }
17  
18 1 ▶use Class::Accessor "antlers";
Subroutine BEGIN: called CC=1 SCAR=0.0
19 1 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
20  
21 0 ▶use Zonemaster::Engine::Nameserver;
Subroutine BEGIN: called CC=1 SCAR=2.6
22 use Zonemaster::Engine::Logger;
23 use Zonemaster::Engine::Profile;
24 use Zonemaster::Engine::Zone;
25 use Zonemaster::Engine::Test;
26 use Zonemaster::Engine::Recursor;
27 use Zonemaster::Engine::ASNLookup;
28  
29 our $logger;
30 our $recursor = Zonemaster::Engine::Recursor->new;
31  
32 my $init_done;
33 sub init_engine {
34 return if $init_done++;
35 Zonemaster::Engine::Recursor::init_recursor();
36 }
37  
38 init_engine();
39  
40 sub logger {
41 return $logger //= Zonemaster::Engine::Logger->new;
42 }
43  
44 sub profile {
45 return Zonemaster::Engine::Profile->effective;
46 }
47  
48 sub ns {
49 my ( $class, $name, $address ) = @_;
50  
51 return Zonemaster::Engine::Nameserver->new( { name => $name, address => $address } );
52 }
53  
54 sub zone {
55 my ( $class, $name ) = @_;
56  
57 return Zonemaster::Engine::Zone->new( { name => Zonemaster::Engine::DNSName->new( $name ) } );
58 }
59  
60 sub test_zone {
61 my ( $class, $zname ) = @_;
62  
63 return Zonemaster::Engine::Test->run_all_for( $class->zone( $zname ) );
64 }
65  
66 sub test_module {
67 my ( $class, $module, $zname ) = @_;
68  
69 return Zonemaster::Engine::Test->run_module( $module, $class->zone( $zname ) );
70 }
71  
72 sub test_method {
73 my ( $class, $module, $method, $zname ) = @_;
74  
75 return Zonemaster::Engine::Test->run_one( $module, $method, $class->zone( $zname ) );
76 }
77  
78 sub all_tags {
79 my ( $class ) = @_;
80 my @res;
81  
82 foreach my $module ( sort { $a cmp $b } Zonemaster::Engine::Test->modules ) {
83 my $full = "Zonemaster::Engine::Test::$module";
84 my $ref = $full->metadata;
85 foreach my $list ( values %{$ref} ) {
86 push @res, map { uc( $module ) . q{:} . $_ } sort { $a cmp $b } @{$list};
87 }
88 }
89  
90 return @res;
91 }
92  
93 sub all_methods {
94 my ( $class ) = @_;
95 my %res;
96  
97 foreach my $module ( Zonemaster::Engine::Test->modules ) {
98 my $full = "Zonemaster::Engine::Test::$module";
99 my $ref = $full->metadata;
100 foreach my $method ( sort { $a cmp $b } keys %{$ref} ) {
101 push @{ $res{$module} }, $method;
102 }
103 }
104  
105 return %res;
106 }
107  
108 sub recurse {
109 my ( $class, $qname, $qtype, $qclass ) = @_;
110 $qtype //= 'A';
111 $qclass //= 'IN';
112  
113 return $recursor->recurse( $qname, $qtype, $qclass );
114 }
115  
116 sub add_fake_delegation {
117 my ( $class, $domain, $href, %flags ) = @_;
118 my $fill_in_empty_oob_glue = exists $flags{fill_in_empty_oob_glue} ? delete $flags{fill_in_empty_oob_glue} : 1;
119 croak 'Unrecognized flags: ' . join( ', ', keys %flags )
120 if %flags;
121 undef %flags;
122  
123 # Validate arguments
124 $domain =~ /[^.]$|^\.$/
125 or croak 'Argument $domain must omit the trailing dot, or it must be a single dot';
126 foreach my $name ( keys %{$href} ) {
127 $name =~ /[^.]$|^\.$/
128 or croak 'Each key of argument $href must omit the trailing dot, or it must be a single dot';
129 ( !defined $href->{$name} or ref $href->{$name} eq 'ARRAY' )
130 or croak 'Each value of argument $href must be an arrayref or undef';
131 $href->{$name} //= []; # normalize undef to empty arrayref
132 }
133  
134 # Check fake delegation
135 my $incomplete_delegation;
136 if ( $fill_in_empty_oob_glue ) {
137 foreach my $name ( keys %{$href} ) {
138 if ( !@{ $href->{$name} }
139 && !$class->zone( $domain )->is_in_zone( $name ) )
140 {
141 my @ips = map { $_->ip } Zonemaster::Engine::Recursor->get_addresses_for( $name );
142 push @{ $href->{$name} }, @ips;
143 if ( !@ips ) {
144 $incomplete_delegation = 1;
145 }
146 }
147 }
148 }
149 foreach my $name ( keys %{$href} ) {
150 if ( not @{ $href->{$name} } ) {
151 if ( $class->zone( $domain )->is_in_zone( $name ) ) {
152 Zonemaster::Engine->logger->add( #
153 FAKE_DELEGATION_IN_ZONE_NO_IP => { domain => $domain, nsname => $name }
154 );
155 }
156 else {
157 Zonemaster::Engine->logger->add( #
158 FAKE_DELEGATION_NO_IP => { domain => $domain, nsname => $name }
159 );
160 }
161 }
162 }
163  
164 $recursor->add_fake_addresses( $domain, $href );
165 my $parent = $class->zone( $recursor->parent( $domain ) );
166 foreach my $ns ( @{ $parent->ns } ) {
167 $ns->add_fake_delegation( $domain => $href );
168 }
169  
170 if ( $incomplete_delegation ) {
171 return;
172 }
173 return 1;
174 }
175  
176 sub add_fake_ds {
177 my ( $class, $domain, $aref ) = @_;
178  
179 my $parent = $class->zone( scalar( $recursor->parent( $domain ) ) );
180 if ( not $parent ) {
181 die "Failed to find parent for $domain";
182 }
183  
184 foreach my $ns ( @{ $parent->ns } ) {
185 $ns->add_fake_ds( $domain => $aref );
186 }
187  
188 return;
189 }
190  
191 sub can_continue {
192 my ( $class ) = @_;
193  
194 return 1;
195  
196 }
197  
198 sub save_cache {
199 my ( $class, $filename ) = @_;
200  
201 return Zonemaster::Engine::Nameserver->save( $filename );
202 }
203  
204 sub preload_cache {
205 my ( $class, $filename ) = @_;
206  
207 return Zonemaster::Engine::Nameserver->restore( $filename );
208 }
209  
210 sub asn_lookup {
211 my ( undef, $ip ) = @_;
212  
213 return Zonemaster::Engine::ASNLookup->get( $ip );
214 }
215  
216 sub modules {
217 return Zonemaster::Engine::Test->modules;
218 }
219  
220 sub start_time_now {
221 Zonemaster::Engine::Logger->start_time_now();
222 return;
223 }
224  
225 sub reset {
226 Zonemaster::Engine::Logger->start_time_now();
227 Zonemaster::Engine::Logger->reset_config();
228 Zonemaster::Engine::Nameserver->empty_cache();
229 $logger->clear_history() if $logger;
230 Zonemaster::Engine::Recursor->clear_cache();
231 Zonemaster::Engine::TestMethodsV2->clear_cache();
232 return;
233 }
234  
235 =head1 NAME
236  
237 Zonemaster::Engine - A tool to check the quality of a DNS zone
238  
239 =head1 SYNOPSIS
240  
241 my @results = Zonemaster::Engine->test_zone('iis.se')
242  
243 =head1 INTRODUCTION
244  
245 This manual describes the main L<Zonemaster::Engine> module. If what you're after is documentation on the Zonemaster test engine as a whole, see L<Zonemaster::Engine::Overview>.
246  
247 =head1 METHODS
248  
249 =over
250  
251 =item init_engine()
252  
253 Run the initialization tasks if they have not been run already. This method is called automatically at runtime.
254  
255 =item test_zone($name)
256  
257 Runs all available tests and returns a list of L<Zonemaster::Engine::Logger::Entry> objects.
258  
259 =item test_module($module, $name)
260  
261 Runs all available tests for the zone with the given name in the specified module.
262  
263 =item test_method($module, $method, $name)
264  
265 Run one particular test method in one particular module for one particular zone.
266 The requested module must be in the list of currently enabled modules (that is,
267 not a module disabled by the current profile), and the method must be listed in
268 the metadata of the module exports.
269 If those requirements are fulfilled, the method will be called with the provided
270 arguments.
271  
272 =item zone($name)
273  
274 Returns a L<Zonemaster::Engine::Zone> object for the given name.
275  
276 =item ns($name, $address)
277  
278 Returns a L<Zonemaster::Engine::Nameserver> object for the given name and address.
279  
280 =item profile()
281  
282 Returns the effective profile (L<Zonemaster::Engine::Profile> object).
283  
284 =item logger()
285  
286 Returns the global L<Zonemaster::Engine::Logger> object.
287  
288 =item all_tags()
289  
290 Returns a list of all the tags that can be logged for all available test modules.
291  
292 =item all_methods()
293  
294 Returns a hash, where the keys are test module names and the values are lists with the names of the test methods in that module.
295  
296 =item recurse($name, $type, $class)
297  
298 Does a recursive lookup for the given name, type and class, and returns the resulting packet (if any). Simply calls
299 L<Zonemaster::Engine::Recursor/recurse> on a globally stored object.
300  
301 =item can_continue()
302  
303 In case of critical condition that prevents tool to process tests, add test here and return False.
304  
305 =item save_cache($filename)
306  
307 After running the tests, save the accumulated cache to a file with the given name.
308  
309 =item preload_cache($filename)
310  
311 Before running the tests, load the cache with information from a file with the given name. This file must have the same format as is produced by
312 L</save_cache()>.
313  
314 =item asn_lookup($ip)
315  
316 Takes a single IP address (string or L<Net::IP::XS> object) and returns a list of AS numbers, if any.
317  
318 =item modules()
319  
320 Returns a list of the loaded test modules. Exactly the same as L<Zonemaster::Engine::Test/modules>.
321  
322 =item add_fake_delegation($domain, $data, %flags)
323  
324 This method adds some fake delegation information to the system.
325  
326 The arguments are a domain name, and a hashref with delegation information.
327 The keys in the hash are nameserver names, and the values are arrayrefs of IP
328 addresses for their corresponding nameserver.
329 Alternatively the IP addresses may be specified as an `undef` which is handled
330 the same as an empty arrayref.
331  
332 For each provided nameserver with an empty list of addresses, either a
333 C<FAKE_DELEGATION_NO_IP> or a C<FAKE_DELEGATION_IN_ZONE_NO_IP> message is
334 emitted.
335  
336 The only recognized flag is C<fill_in_empty_oob_glue>.
337 This flag is boolean and defaults to true.
338 If this flag is true, this method updates the given C<$data> by looking up and
339 filling in some glue addresses.
340 Specifically the glue addresses for any nameserver name that are
341 out-of-bailiwick of the given C<$domain> and that comes with an empty list of
342 addresses.
343  
344 Returns `1` if all name servers in C<$data> have non-empty lists of
345 glue (after they've been filled in) or if `fill_in_empty_oob_glue` is false.
346 Otherwise it returns `undef`.
347  
348 Examples:
349  
350 Zonemaster::Engine->add_fake_delegation(
351 'lysator.liu.se' => {
352 'ns1.nic.fr' => [ ],
353 'ns.nic.se' => [ '212.247.7.228', '2a00:801:f0:53::53' ],
354 'i.ns.se' => [ '194.146.106.22', '2001:67c:1010:5::53' ],
355 'ns3.nic.se' => [ '212.247.8.152', '2a00:801:f0:211::152' ]
356 },
357 );
358  
359 returns 1.
360  
361 Zonemaster::Engine->add_fake_delegation(
362 'lysator.liu.se' => {
363 'ns1.lysator.liu.se' => [ ],
364 'ns.nic.se' => [ '212.247.7.228', '2a00:801:f0:53::53' ],
365 'i.ns.se' => [ '194.146.106.22', '2001:67c:1010:5::53' ],
366 'ns3.nic.se' => [ '212.247.8.152', '2a00:801:f0:211::152' ]
367 }
368 );
369  
370 returns C<undef> (signalling that fake delegation with empty glue was added to
371 the system).
372  
373 Zonemaster::Engine->add_fake_delegation(
374 'lysator.liu.se' => {
375 'ns1.nic.fr' => [ ],
376 'ns.nic.se' => [ '212.247.7.228', '2a00:801:f0:53::53' ],
377 'i.ns.se' => [ '194.146.106.22', '2001:67c:1010:5::53' ],
378 'ns3.nic.se' => [ '212.247.8.152', '2a00:801:f0:211::152' ]
379 },
380 fill_in_empty_oob_glue => 0,
381 );
382  
383 returns 1. It does not even attempt to fill in glue for ns1.nic.fr.
384  
385 =item add_fake_ds($domain, $data)
386  
387 This method adds fake DS records to the system. The arguments are a domain
388 name, and a reference to a list of references to hashes. The hashes in turn
389 must have the keys C<keytag>, C<algorithm>, C<type> and C<digest>, with the
390 values holding the corresponding data. The digest data should be a single
391 unbroken string of hexadecimal digits.
392  
393 Example:
394  
395 Zonemaster::Engine->add_fake_ds(
396 'nic.se' => [
397 { keytag => 16696, algorithm => 5, type => 2, digest => '40079DDF8D09E7F10BB248A69B6630478A28EF969DDE399F95BC3B39F8CBACD7' },
398 { keytag => 16696, algorithm => 5, type => 1, digest => 'EF5D421412A5EAF1230071AFFD4F585E3B2B1A60' },
399 ]
400 );
401  
402 =item start_time_now()
403  
404 Set the logger's start time to the current time.
405  
406 =item reset()
407  
408 Reset logger start time to current time, empty the list of log messages, clear
409 nameserver object cache, clear recursor cache and clear all cached results of
410 MethodsV2.
411  
412 =back
413  
414 =head1 AUTHORS
415  
416 Vincent Levigneron <vincent.levigneron at nic.fr>
417 - Current maintainer
418  
419 Calle Dybedahl <calle at init.se>
420 - Original author
421  
422 =head1 LICENSE
423  
424 This is free software under a 2-clause BSD license. The full text of the license can
425 be found in the F<LICENSE> file included with this distribution.
426  
427 =cut
428  
429 1;
« auto/share/dist/Zonemaster-Engine/json2yaml.pl ↑ Summary Zonemaster/Engine/Nameserver.pm »