| 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; | ||