Zonemaster/Engine/Util.pm

filter: Statementstmt 35.0% 40 / 114 Branchbran 13.3% 4 / 30 Conditioncond 16.6% 3 / 18 MC/DCmcdc 20.0% 2 / 10 Subroutinesub 50.0% 11 / 22 Podpod 100% 11 / 11 totaltotal 34.6% 71 / 205 CC 25 SCAR 47.6
CC
25
Cov
29%
parse_hints
306.0
serial_gt
20.0
ipversion_ok
12.0
CRAP 117.2
« Zonemaster/Engine/Test/Syntax.pm ↑ Summary Zonemaster/Engine/Test/Connectivity.pm »
1 package Zonemaster::Engine::Util;
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("v1.1.13");
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 1 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
9 1 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
10 1 our @EXPORT_OK = qw[
11 escape_unprintable
12 info
13 ipversion_ok
14 name
15 ns
16 parse_hints
17 should_run_test
18 scramble_case
19 test_levels
20 zone
21 ];
22 1 our %EXPORT_TAGS = ( all => \@EXPORT_OK );
23  
24 ## no critic (Modules::ProhibitAutomaticExportation)
25 1 our @EXPORT = qw[ ns info name scramble_case ];
26 }
27  
28 1 ▶use Net::DNS::ZoneFile;
Subroutine BEGIN: called CC=1 SCAR=0.0
29 1 ▶use Pod::Simple::SimpleTree;
Subroutine BEGIN: called CC=1 SCAR=0.0
30  
31 1 ▶use Zonemaster::Engine::Constants qw[:ip :soa];
Subroutine BEGIN: called CC=1 SCAR=0.0
32 1 ▶use Zonemaster::Engine::DNSName;
Subroutine BEGIN: called CC=1 SCAR=0.0
33 1 ▶use Zonemaster::Engine::Profile;
Subroutine BEGIN: called CC=1 SCAR=0.0
34 1 ▶use Zonemaster::Engine::Nameserver;
Subroutine BEGIN: called CC=1 SCAR=0.0
35  
36 0 ▶sub ns {
Subroutine ns: not called CC=1 SCAR=6.9
Pod documented
37 0 my ( $name, $address ) = @_;
38 0 return Zonemaster::Engine::Nameserver->new( { name => $name, address => $address } );
39 }
40  
41 0 ▶sub info {
Subroutine info: not called CC=1 SCAR=6.9
Pod documented
42 0 my ( $tag, $argref ) = @_;
43  
44 0 return Zonemaster::Engine->logger->add( $tag, $argref );
45 }
46  
47 0 ▶sub zone {
Subroutine zone: not called CC=1 SCAR=6.9
Pod documented
48 0 my ( $name ) = @_;
49  
50 0 return Zonemaster::Engine::Zone->new( { name => Zonemaster::Engine::DNSName->new( $name ) } );
51 }
52  
53 0 ▶sub should_run_test {
Subroutine should_run_test: not called CC=1 SCAR=6.9
Pod documented
54 0 my ( $test_name ) = @_;
55 0 my %test_names = map { $_ => 1 } @{ Zonemaster::Engine::Profile->effective->get( q{test_cases} ) };
56  
57 0 return exists $test_names{$test_name};
58 }
59  
60 0 ▶sub ipversion_ok {
Subroutine ipversion_ok: not called CC=3 SCAR=24.8
Pod documented
61 0 my ( $version ) = @_;
62  
63 0 ▶ if ( $version == $IP_VERSION_4 ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($version == $Zonemaster::Engine::Util::IP_VERSION_4) { } 0 0 0
elsif ($version == $Zonemaster::Engine::Util::IP_VERSION_6) { } 0 0 0
64 0 return Zonemaster::Engine::Profile->effective->get( q{net.ipv4} );
65 }
66 elsif ( $version == $IP_VERSION_6 ) {
67 0 return Zonemaster::Engine::Profile->effective->get( q{net.ipv6} );
68 }
69 else {
70 0 return;
71 }
72 }
73  
74 0 ▶sub test_levels {
Subroutine test_levels: not called CC=1 SCAR=6.9
Pod documented
75 0 return Zonemaster::Engine::Profile->effective->get( q{test_levels} );
76 }
77  
78 ## no critic (Subroutines::RequireArgUnpacking)
79 0 ▶sub name {
Subroutine name: not called CC=1 SCAR=6.9
Pod documented
80 # We do not unpack @_ here for performance reasons.
81 # If we did, the calling convention is: my ( $name ) = @_.
82 0 return Zonemaster::Engine::DNSName->new( @_ );
83 }
84  
85 # Function from CPAN package Text::Capitalize that causes
86 # issues when installing ZM.
87 #
88 0 ▶sub scramble_case {
Subroutine scramble_case: not called CC=3 SCAR=24.8
Pod documented
89 0 my $string = shift;
90 0 my ( @chars, $uppity, $newstring, $uppers, $downers );
91  
92 0 @chars = split //, $string;
93  
94 0 $uppers = 2;
95 0 $downers = 1;
96 0 foreach my $c ( @chars ) {
97 0 $uppity = int( rand( 1 + $downers / $uppers ) );
98  
99 0 ▶ if ( $uppity ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($uppity) { } 0 0 0
100 0 $c = uc( $c );
101 0 $uppers++;
102 }
103 else {
104 0 $c = lc( $c );
105 0 $downers++;
106 }
107 }
108 0 $newstring = join q{}, @chars;
109 0 return $newstring;
110 } # end sub scramble_case
111  
112 0 ▶sub parse_hints {
Subroutine parse_hints: not called CC=17 SCAR=57.2
Pod documented
113 0 my $string = shift;
114  
115 # Reject anything that is forbidden in hints files but allowed in zone files
116 # in general.
117 0 ▶ if ( $string =~ /^\$(TTL|INCLUDE|ORIGIN|GENERATE)/m ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($string =~ /^\$(TTL|INCLUDE|ORIGIN|GENERATE)/mu) 0 0 0
118 0 die "Forbidden directive \$$1\n";
119 }
120  
121 0 my $rrs = Net::DNS::ZoneFile->parse( \$string );
122 0 ▶ if ( !defined $rrs ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $rrs) 0 0 0
123 0 die "Unable to parse root hints\n";
124 }
125  
126 0 my %ns;
127 my %glue;
128 0 for my $rr ( @$rrs ) {
129 0 ▶ if ( $rr->class ne 'IN' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rr->class ne "IN") 0 0 0
130 0 my $rrclass = $rr->class;
131 0 die "Forbidden RR class $rrclass\n";
132 }
133  
134 0 ▶ if ( $rr->type eq 'NS' ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($rr->type eq 'NS') { } 0 0 0
elsif ($rr->type eq 'A' or $rr->type eq 'AAAA') { } 0 0 0
135 0 ▶ if ( $rr->owner ne '.' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rr->owner ne ".") 0 0 0
136 0 my $owner = $rr->owner;
137 0 die "Owner name for NS record must be \".\"\n";
138 }
139 0 $ns{ $rr->nsdname } = 0;
140 }
141 ▶ elsif ( $rr->type eq 'A' || $rr->type eq 'AAAA' ) {
Condition0%0/3
$rr->type eq "A" or $rr->type eq "AAAA"
l!l&&r!l&&!r
000
MC/DC0%0/2
$rr->type eq "A" or $rr->type eq "AAAA"
$rr->type eq "A" $rr->type eq "AAAA"
Truth table0%0/3
A or B
A= $rr->type eq "A"B= $rr->type eq "AAAA"
ABresult
1X1
011
000
142 0 $glue{ $rr->owner } = $rr->type;
143 }
144 else {
145 0 my $rrtype = $rr->type;
146 0 die "Forbidden RR type $rrtype\n";
147 }
148 } ## end for my $rr ( @$rrs )
149  
150 0 for my $owner ( sort keys %glue ) {
151 0 ▶ if ( exists $ns{$owner} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $ns{$owner}) { } 0 0 0
152 0 $ns{$owner} = 1;
153 }
154 else {
155 0 my $rrtype = $glue{$owner};
156 0 die "Owner name of $rrtype record does not match any NS RDATA\n";
157 }
158 }
159  
160 0 for my $nsdname ( sort keys %ns ) {
161 0 ▶ if ( $ns{$nsdname} == 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ns{$nsdname} == 0) 0 0 0
162 0 die "No address record found for NS $nsdname\n";
163 }
164 }
165  
166 0 ▶ if ( !%ns ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (%ns) 0 0 0
167 0 die "No NS record found\n";
168 }
169  
170 # Extract hint data
171 0 my %hints;
172 0 for my $rr ( @{ $rrs } ) {
173 0 ▶ if ( $rr->type eq 'A' or $rr->type eq 'AAAA' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rr->type eq "A" or $rr->type eq "AAAA") 0 0 0
Condition0%0/3
$rr->type eq "A" or $rr->type eq "AAAA"
l!l&&r!l&&!r
000
MC/DC0%0/2
$rr->type eq "A" or $rr->type eq "AAAA"
$rr->type eq "A" $rr->type eq "AAAA"
Truth table0%0/3
A or B
A= $rr->type eq "A"B= $rr->type eq "AAAA"
ABresult
1X1
011
000
174 0 push @{ $hints{$rr->owner} }, $rr->address;
175 }
176 }
177  
178 0 return \%hints;
179 }
180  
181 0 ▶sub serial_gt {
Subroutine serial_gt: not called CC=4 SCAR=30.0
Pod documented
182 0 my ( $sa, $sb ) = @_;
183  
184 0 ▶ return ( ( $sa < $sb and ( ($sb - $sa) > 2**( $SERIAL_BITS - 1 ) ) ) or
Condition0%0/9
$sa < $sb && $sb - $sa > 2 ** ($Zonemaster::Engine::Util::SERIAL_BITS - 1) || $sa > $sb && $sa - $sb < 2 ** ($Zonemaster::Engine::Util::SERIAL_BITS - 1)
l!l&&r!l&&!r
000
$sa < $sb and $sb - $sa > 2 ** ($Zonemaster::Engine::Util::SERIAL_BITS - 1)
!ll&&!rl&&r
000
$sa > $sb and $sa - $sb < 2 ** ($Zonemaster::Engine::Util::SERIAL_BITS - 1)
!ll&&!rl&&r
000
MC/DC0%0/4
$sa < $sb && $sb - $sa > 2 ** ($Zonemaster::Engine::Util::SERIAL_BITS - 1) || $sa > $sb && $sa - $sb < 2 ** ($Zonemaster::Engine::Util::SERIAL_BITS - 1)
$sa < $sb $sb - $sa > 2 ** ($Zonemaster::Engine::Util::SERIAL_BITS - 1) $sa > $sb $sa - $sb < 2 ** ($Zonemaster::Engine::Util::SERIAL_BITS - 1)
Truth table0%0/7
A and B || C and D
A= $sa < $sbB= $sb - $sa > 2 ** ($Zonemaster::Engine::Util::SERIAL_BITS - 1)C= $sa > $sbD= $sa - $sb < 2 ** ($Zonemaster::Engine::Util::SERIAL_BITS - 1)
ABCDresult
11XX1
0X111
10111
0X0X0
0X100
100X0
10100
185 ( $sa > $sb and ( ($sa - $sb) < 2**( $SERIAL_BITS - 1 ) ) )
186 );
187 }
188  
189 {
190 # HACK: It would be cleaner to use a state variable, but Perl versions
191 # older than 5.28.0 disallow initializing list state variables, e.g.
192 # writing “state @a = qw(a b c)”.
193 #
194 # A workaround could be to use a state arrayref variable for the
195 # substitution table, but this incurs a performance penalty.
196 #
197 # Once we support Perl ⩾ 5.28, we can rewrite this function using proper
198 # state variables. See also:
199 # <https://perldoc.perl.org/5.28.0/perldelta#Initialisation-of-aggregate-state-variables>.
200 my @substitution_table = map {
201 1 ▶ if ( $_ == 92 ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($_ == 92) { } 1 255 256
elsif ($_ >= 32 and $_ <= 126) { } 94 161 255
202 1 '\\\\'
203 }
204 ▶ elsif ( $_ >= 32 and $_ <= 126 ) {
Condition100%3/3
$_ >= 32 and $_ <= 126
!ll&&!rl&&r
3212994
MC/DC100%2/2
$_ >= 32 and $_ <= 126
$_ >= 32 $_ <= 126
Truth table100%3/3
A and B
A= $_ >= 32B= $_ <= 126
ABresult
0X0
100
111
205 94 chr $_
206 }
207 else {
208 161 sprintf '\%03d', $_
209 }
210 } 0..255;
211  
212 0 ▶ sub escape_unprintable {
Subroutine escape_unprintable: not called CC=2 SCAR=17.9
Pod documented
213 0 my ( $input ) = @_;
214  
215 0 my $output = '';
216 0 $output .= $substitution_table[$_] foreach (unpack "C*", $input);
217  
218 0 return $output;
219 }
220 }
221  
222 1 1;
223  
224 =head1 NAME
225  
226 Zonemaster::Engine::Util - utility functions for other Zonemaster modules
227  
228 =head1 SYNOPSIS
229  
230 use Zonemaster::Engine::Util;
231 info(TAG => { some => 'argument'});
232 my $ns = ns($name, $address);
233 my $name = name('whatever.example.org');
234  
235 =head1 EXPORTED FUNCTIONS
236  
237 =over
238  
239 =item info($tag, $href)
240  
241 Creates and returns a L<Zonemaster::Engine::Logger::Entry> object. The object
242 is also added to the global logger object's list of entries.
243  
244 =item ns($name, $address)
245  
246 Creates and returns a nameserver object with the given name and address.
247  
248 =item name($string_name_or_zone)
249  
250 Creates and returns a L<Zonemaster::Engine::DNSName> object for the given argument.
251  
252 =item zone($name)
253  
254 Returns a L<Zonemaster::Engine::Zone> object for the given name.
255  
256 =item parse_hints($string)
257  
258 Parses a string in the root hints format into the format expected by
259 Zonemaster::Engine::Resolver->add_fake_addresses().
260  
261 Returns a hashref with domain names as keys and arrayrefs to IP addresses as
262 values.
263  
264 Throws an exception if the inputs is not valid root hints text.
265  
266 A root hints file is a valid RFC 1035 zone file of the same type IANA publishes
267 to be used as hint file for name servers
268 L<https://www.internic.net/domain/named.root>.
269  
270 In addition to being valid zone file the following restrictions are imposed on
271 the root hints format:
272  
273 =over
274  
275 =item *
276 The file must not contain any $TTL, $ORIGIN, $INCLUDE or $GENERATE directives.
277  
278 =item *
279 The class field of all records must be "IN" or absent. If class is absent, IN is
280 assumed.
281  
282 =item *
283 The TTL field may be absent or present. The TTL value is ignored.
284  
285 =item *
286 The RR type of all DNS records must be NS, A or AAAA.
287  
288 =item *
289 The file must contain at least one NS record.
290  
291 =item *
292 The owner name of all NS records must be C<.>.
293  
294 =item *
295 For every NS record there must be at least one address record (A or AAAA) whose
296 owner name is identical to the domain name in the RDATA of the NS record.
297  
298 =item *
299 All address records (A or AAAA) must have an owner name that is identical to the
300 domain name in the RDATA of some NS record in the zone.
301  
302 =back
303  
304 =item serial_gt($serial_a, $serial_b)
305 Checks if serial_a is greater than serial_b, according to
306 serial number arithmetic as defined in RFC1982, section 3.2.
307  
308 Return a boolean.
309  
310 =item scramble_case
311  
312 This routine provides a special effect: sCraMBliNg tHe CaSe
313  
314 =item should_run_test
315  
316 Check if a test is blacklisted and should run or not.
317  
318 =item ipversion_ok
319  
320 Check if IP version operations are permitted. Tests are done against Zonemaster::Engine::Profile->effective content.
321  
322 =item escape_unprintable
323  
324 Replaces all non-ASCII characters and control characters in a byte string with
325 decimal escape codes. The resulting string only contains printable ASCII
326 characters, which makes it safer for display on a terminal or for storage in a
327 database.
328  
329 For example, C<"hello \x1B[34mworld!\x1B[0m\\\xFF"> is turned into
330 C<'hello \027[34mworld!\027[0m\\\255'>.
331  
332 Do not use this function on character strings, or it might produce invalid
333 results. Only use it on byte strings, e.g. UTF-8 encoded text returned by
334 calling Encode::encode() on a character string, or raw data received from
335 Zonemaster-LDNS.
336  
337 Space (ASCII 0x20) characters are left as they are, but all other ASCII
338 whitespace characters, i.e. HORIZONTAL TAB (ASCII 0x09), LINE FEED (ASCII
339 0x0A), VERTICAL TAB (ASCII 0x0B), FORM FEED (ASCII 0x0C) and CARRIAGE RETURN
340 (ASCII 0x0D) will be replaced by their equivalent decimal escapes.
341  
342 Beware that the resulting string might still contain sequences of characters
343 that can be dangerous in other contexts, requiring further escaping. For
344 example, if the string is meant to be displayed on an HTML GUI, the result
345 must have angle brackets and ampersand characters escaped in a second pass.
346  
347 =item test_levels
348  
349 WIP, here to please L<Pod::Coverage>.
350  
351 =back
« Zonemaster/Engine/Test/Syntax.pm ↑ Summary Zonemaster/Engine/Test/Connectivity.pm »