blib/lib/SignalWire/Utils/UrlValidator.pm

filter: Statementstmt 76.1% 86 / 113 Branchbran 59.6% 37 / 62 Conditioncond 65.9% 29 / 44 MC/DCmcdc 46.1% 12 / 26 Subroutinesub 76.9% 10 / 13 Podpod 0.0% 0 / 1 totaltotal 67.1% 174 / 259 CC 52 SCAR 28.6
CC
52
Cov
69%
_resolve
48.3
_is_ip_literal
20.0
validate_url
19.6
CRAP 17.5
« blib/lib/SignalWire/REST/Pagination.pm ↑ Summary blib/lib/SignalWire/Contexts.pm »
1 package SignalWire::Utils::UrlValidator;
2  
3 # Copyright (c) 2025 SignalWire
4 # Licensed under the MIT License.
5 # See LICENSE file in the project root for full license information.
6  
7 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 1 ▶use Socket qw(getaddrinfo unpack_sockaddr_in unpack_sockaddr_in6 AF_INET AF_INET6);
Subroutine BEGIN: called CC=1 SCAR=0.0
11 1 ▶use URI;
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 1 ▶use SignalWire::Logging;
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 # SSRF-prevention guard for user-supplied URLs.
16 #
17 # Mirrors Python's signalwire.utils.url_validator.validate_url:
18 # rejects non-http(s) schemes, missing hostnames, and any URL whose
19 # hostname resolves to a private / loopback / link-local / cloud-metadata
20 # IP. Either the second argument $allow_private being truthy, or the
21 # SWML_ALLOW_PRIVATE_URLS env var with value "1", "true" or "yes"
22 # (case-insensitive), bypasses the IP-blocklist check.
23 #
24 # validate_url is exported as a module-level free function. The Perl
25 # enumerate_signatures.py adapter projects packages with class=undef as
26 # Python module-level functions, so this maps to
27 # signalwire.utils.url_validator.validate_url directly.
28  
29 # Cross-port SSRF block list. Order matches the Python reference.
30 1 our @BLOCKED_NETWORKS = (
31 '10.0.0.0/8',
32 '172.16.0.0/12',
33 '192.168.0.0/16',
34 '127.0.0.0/8',
35 '169.254.0.0/16', # link-local / cloud metadata
36 '0.0.0.0/8',
37 '::1/128',
38 'fc00::/7', # IPv6 private (ULA)
39 'fe80::/10', # IPv6 link-local
40 );
41  
42 # Pluggable resolver. Tests inject a coderef to keep the suite hermetic;
43 # production calls Socket::getaddrinfo. Underscore-prefixed so the
44 # adapter's _-name filter keeps it out of the public surface.
45 1 our $_RESOLVER;
46  
47 22 ▶sub validate_url {
Subroutine validate_url: called CC=18 SCAR=29.8
Pod undocumented
48 22 my ($url, $allow_private) = @_;
49 22 ▶ $allow_private //= 0;
Condition100%2/2
$allow_private //= 0
l!l
121
MC/DC100%1/1
$allow_private //= 0
$allow_private
Truth table100%2/2
A
A= $allow_private
Aresult
11
00
50  
51 22 my $log = SignalWire::Logging->get_logger('signalwire.url_validator');
52  
53 22 my $parsed = eval { URI->new($url) };
54 22 ▶ if (!$parsed || $@) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $parsed or $@) 0 22 22
Condition33%1/3
not $parsed or $@
l!l&&r!l&&!r
0022
MC/DC0%0/2
not $parsed or $@
not $parsed $@
Truth table33%1/3
not(A) or B
A= not $parsedB= $@
ABresult
1X1
011
000
55 0 $log->warn("URL validation error: $@");
56 0 return 0;
57 }
58  
59 22 ▶ my $scheme = lc($parsed->scheme // '');
Condition50%1/2
$parsed->scheme // ""
l!l
220
MC/DC0%0/1
$parsed->scheme // ""
$parsed->scheme
Truth table50%1/2
A
A= $parsed->scheme
Aresult
11
00
60 22 ▶ if ($scheme ne 'http' && $scheme ne 'https') {
Branch: 1 branch
BranchTrueFalseTotal
if ($scheme ne "http" and $scheme ne "https") 3 19 22
Condition100%3/3
$scheme ne "http" and $scheme ne "https"
!ll&&!rl&&r
1813
MC/DC100%2/2
$scheme ne "http" and $scheme ne "https"
$scheme ne "http" $scheme ne "https"
Truth table100%3/3
A and B
A= $scheme ne "http"B= $scheme ne "https"
ABresult
0X0
100
111
61 3 ▶ $log->warn("URL rejected: invalid scheme " . ($parsed->scheme // '(none)'));
Condition50%1/2
$parsed->scheme // "(none)"
l!l
30
MC/DC0%0/1
$parsed->scheme // "(none)"
$parsed->scheme
Truth table50%1/2
A
A= $parsed->scheme
Aresult
11
00
62 3 return 0;
63 }
64  
65 19 ▶ my $hostname = $parsed->host // '';
Condition50%1/2
$parsed->host // ""
l!l
190
MC/DC0%0/1
$parsed->host // ""
$parsed->host
Truth table50%1/2
A
A= $parsed->host
Aresult
11
00
66 19 ▶ if ($hostname eq '') {
Branch: 1 branch
BranchTrueFalseTotal
if ($hostname eq "") 1 18 19
67 1 $log->warn('URL rejected: no hostname');
68 1 return 0;
69 }
70 # URI keeps brackets in host for IPv6 literals; strip them.
71 18 ▶ if ($hostname =~ /^\[(.+)\]$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($hostname =~ /^\[(.+)\]$/) 0 18 18
72 0 $hostname = $1;
73 }
74  
75 18 ▶ if ($allow_private || _env_allows_private()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($allow_private or _env_allows_private()) 4 14 18
Condition100%3/3
$allow_private or _env_allows_private()
l!l&&r!l&&!r
1314
MC/DC100%2/2
$allow_private or _env_allows_private()
$allow_private _env_allows_private()
Truth table100%3/3
A or B
A= $allow_privateB= _env_allows_private()
ABresult
1X1
011
000
76 4 return 1;
77 }
78  
79 14 my $ips = _resolve($hostname);
80 14 ▶ if (!$ips || @$ips == 0) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $ips or @$ips == 0) 1 13 14
Condition66%2/3
not $ips or @$ips == 0
l!l&&r!l&&!r
1013
MC/DC50%1/2
not $ips or @$ips == 0
not $ips @$ips == 0
Truth table66%2/3
not(A) or B
A= not $ipsB= @$ips == 0
ABresult
1X1
011
000
81 1 $log->warn("URL rejected: could not resolve hostname $hostname");
82 1 return 0;
83 }
84  
85 13 foreach my $ip (@$ips) {
86 13 foreach my $cidr (@BLOCKED_NETWORKS) {
87 73 ▶ if (_cidr_contains($cidr, $ip)) {
Branch: 1 branch
BranchTrueFalseTotal
if (_cidr_contains($cidr, $ip)) 10 63 73
88 10 $log->warn("URL rejected: $hostname resolves to blocked IP $ip (in $cidr)");
89 10 return 0;
90 }
91 }
92 }
93  
94 3 return 1;
95 }
96  
97 17 ▶sub _env_allows_private {
Subroutine _env_allows_private: called CC=5 SCAR=16.1
98 17 ▶ my $v = lc($ENV{SWML_ALLOW_PRIVATE_URLS} // '');
Condition100%2/2
$ENV{"SWML_ALLOW_PRIVATE_URLS"} // ""
l!l
413
MC/DC100%1/1
$ENV{"SWML_ALLOW_PRIVATE_URLS"} // ""
$ENV{"SWML_ALLOW_PRIVATE_URLS"}
Truth table100%2/2
A
A= $ENV{"SWML_ALLOW_PRIVATE_URLS"}
Aresult
11
00
99 17 ▶ return ($v eq '1' || $v eq 'true' || $v eq 'yes') ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$v eq '1' || $v eq 'true' || $v eq 'yes' ? : 3 14 17
Condition100%6/6
$v eq 1 or $v eq "true" or $v eq "yes"
l!l&&r!l&&!r
2114
$v eq 1 or $v eq "true"
l!l&&r!l&&!r
1115
MC/DC100%3/3
$v eq 1 or $v eq "true" or $v eq "yes"
$v eq 1 $v eq "true" $v eq "yes"
Truth table100%4/4
A or B or C
A= $v eq 1B= $v eq "true"C= $v eq "yes"
ABCresult
1XX1
01X1
0011
0000
100 }
101  
102 # Resolve a hostname to a list of IP-string addresses, or undef on failure.
103 14 ▶sub _resolve {
Subroutine _resolve: called CC=8 SCAR=38.8
104 14 my ($hostname) = @_;
105 14 ▶ if ($_RESOLVER) {
Branch: 1 branch
BranchTrueFalseTotal
if ($SignalWire::Utils::UrlValidator::_RESOLVER) 14 0 14
106 14 return $_RESOLVER->($hostname);
107 }
108 # Literal-IP shortcut.
109 0 ▶ if (_is_ip_literal($hostname)) {
Branch: 1 branch
BranchTrueFalseTotal
if (_is_ip_literal($hostname)) 0 0 0
110 0 return [$hostname];
111 }
112 0 my ($err, @res) = getaddrinfo($hostname, undef, { socktype => 1 });
113 0 ▶ return undef if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 0 0
114 0 my @ips;
115 0 for my $r (@res) {
116 0 my $fam = $r->{family};
117 0 ▶ if ($fam == AF_INET) {
Branch: 2 branches
BranchTrueFalseTotal
if ($fam == 2) { } 0 0 0
elsif ($fam == 10) { } 0 0 0
118 0 my ($port, $ipv4) = unpack_sockaddr_in($r->{addr});
119 0 push @ips, _bytes_to_ipv4($ipv4);
120 } elsif ($fam == AF_INET6) {
121 0 my ($port, $ipv6) = unpack_sockaddr_in6($r->{addr});
122 0 push @ips, _bytes_to_ipv6($ipv6);
123 }
124 }
125 0 ▶ return @ips ? \@ips : undef;
Branch: 1 branch
BranchTrueFalseTotal
@ips ? : 0 0 0
126 }
127  
128 0 ▶sub _is_ip_literal {
Subroutine _is_ip_literal: not called CC=4 SCAR=30.0
129 0 my ($s) = @_;
130 0 ▶ return 1 if $s =~ /^\d{1,3}(\.\d{1,3}){3}$/;
Branch: 1 branch
BranchTrueFalseTotal
if $s =~ /^\d{1,3}(\.\d{1,3}){3}$/ 0 0 0
131 0 ▶ return 1 if $s =~ /^[0-9a-fA-F:]+$/ && $s =~ /:/;
Branch: 1 branch
BranchTrueFalseTotal
if $s =~ /^[0-9a-fA-F:]+$/ and $s =~ /:/ 0 0 0
Condition0%0/3
$s =~ /^[0-9a-fA-F:]+$/ and $s =~ /:/
!ll&&!rl&&r
000
MC/DC0%0/2
$s =~ /^[0-9a-fA-F:]+$/ and $s =~ /:/
$s =~ /^[0-9a-fA-F:]+$/ $s =~ /:/
Truth table0%0/3
A and B
A= $s =~ /^[0-9a-fA-F:]+$/B= $s =~ /:/
ABresult
0X0
100
111
132 0 return 0;
133 }
134  
135 0 ▶sub _bytes_to_ipv4 {
Subroutine _bytes_to_ipv4: not called CC=1 SCAR=6.9
136 0 my ($bytes) = @_;
137 0 return join('.', unpack('C4', $bytes));
138 }
139  
140 0 ▶sub _bytes_to_ipv6 {
Subroutine _bytes_to_ipv6: not called CC=1 SCAR=6.9
141 0 my ($bytes) = @_;
142 0 my @parts = unpack('n8', $bytes);
143 0 return sprintf('%x:%x:%x:%x:%x:%x:%x:%x', @parts);
144 }
145  
146 # CIDR membership test. Handles both IPv4 and IPv6 input strings.
147 73 ▶sub _cidr_contains {
Subroutine _cidr_contains: called CC=11 SCAR=24.5
148 73 my ($cidr, $ip) = @_;
149 73 my ($net_str, $prefix) = split('/', $cidr, 2);
150 73 ▶ return 0 unless defined $prefix;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $prefix 0 73 73
151  
152 73 my $ip_bytes = _ip_to_bytes($ip);
153 73 my $net_bytes = _ip_to_bytes($net_str);
154 73 ▶ return 0 unless defined $ip_bytes && defined $net_bytes;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $ip_bytes and defined $net_bytes 0 73 73
Condition33%1/3
defined $ip_bytes and defined $net_bytes
!ll&&!rl&&r
0073
MC/DC0%0/2
defined $ip_bytes and defined $net_bytes
defined $ip_bytes defined $net_bytes
Truth table33%1/3
A and B
A= defined $ip_bytesB= defined $net_bytes
ABresult
0X0
100
111
155 73 ▶ return 0 if length($ip_bytes) != length($net_bytes);
Branch: 1 branch
BranchTrueFalseTotal
if length $ip_bytes != length $net_bytes 27 46 73
156  
157 46 my $total = length($ip_bytes) * 8;
158 46 ▶ return 0 if $prefix < 0 || $prefix > $total;
Branch: 1 branch
BranchTrueFalseTotal
if $prefix < 0 or $prefix > $total 0 46 46
Condition33%1/3
$prefix < 0 or $prefix > $total
l!l&&r!l&&!r
0046
MC/DC0%0/2
$prefix < 0 or $prefix > $total
$prefix < 0 $prefix > $total
Truth table33%1/3
A or B
A= $prefix < 0B= $prefix > $total
ABresult
1X1
011
000
159 46 my $full = int($prefix / 8);
160 46 my $rem = $prefix % 8;
161 46 ▶ return 0 if $full > 0 && substr($ip_bytes, 0, $full) ne substr($net_bytes, 0, $full);
Branch: 1 branch
BranchTrueFalseTotal
if $full > 0 and substr($ip_bytes, 0, $full) ne substr($net_bytes, 0, $full) 35 11 46
Condition100%3/3
$full > 0 and substr($ip_bytes, 0, $full) ne substr($net_bytes, 0, $full)
!ll&&!rl&&r
2935
MC/DC100%2/2
$full > 0 and substr($ip_bytes, 0, $full) ne substr($net_bytes, 0, $full)
$full > 0 substr($ip_bytes, 0, $full) ne substr($net_bytes, 0, $full)
Truth table100%3/3
A and B
A= $full > 0B= substr($ip_bytes, 0, $full) ne substr($net_bytes, 0, $full)
ABresult
0X0
100
111
162 11 ▶ if ($rem > 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rem > 0) 4 7 11
163 4 my $mask = (0xFF << (8 - $rem)) & 0xFF;
164 4 my $i = ord(substr($ip_bytes, $full, 1)) & $mask;
165 4 my $n = ord(substr($net_bytes, $full, 1)) & $mask;
166 4 ▶ return 0 if $i != $n;
Branch: 1 branch
BranchTrueFalseTotal
if $i != $n 1 3 4
167 }
168 10 return 1;
169 }
170  
171 146 ▶sub _ip_to_bytes {
Subroutine _ip_to_bytes: called CC=11 SCAR=25.2
172 146 my ($ip) = @_;
173 146 ▶ return undef unless defined $ip;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $ip 0 146 146
174 146 ▶ if ($ip =~ /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ip =~ /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/) 107 39 146
175 107 return pack('C4', $1, $2, $3, $4);
176 }
177 39 ▶ if ($ip =~ /:/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ip =~ /:/) 39 0 39
178 # IPv6: expand and pack.
179 39 my @groups;
180 39 ▶ if ($ip =~ /::/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ip =~ /::/) { } 39 0 39
181 39 my ($head, $tail) = split('::', $ip, 2);
182 39 ▶ $head //= '';
Condition50%1/2
$head //= ""
l!l
390
MC/DC0%0/1
$head //= ""
$head
Truth table50%1/2
A
A= $head
Aresult
11
00
183 39 ▶ $tail //= '';
Condition50%1/2
$tail //= ""
l!l
390
MC/DC0%0/1
$tail //= ""
$tail
Truth table50%1/2
A
A= $tail
Aresult
11
00
184 39 ▶ my @h = $head eq '' ? () : split(':', $head);
Branch: 1 branch
BranchTrueFalseTotal
$head eq '' ? : 13 26 39
185 39 ▶ my @t = $tail eq '' ? () : split(':', $tail);
Branch: 1 branch
BranchTrueFalseTotal
$tail eq '' ? : 9 30 39
186 39 my $missing = 8 - (@h + @t);
187 39 ▶ return undef if $missing < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $missing < 0 0 39 39
188 39 @groups = (@h, ('0') x $missing, @t);
189 } else {
190 0 @groups = split(':', $ip);
191 }
192 39 ▶ return undef if @groups != 8;
Branch: 1 branch
BranchTrueFalseTotal
if @groups != 8 0 39 39
193 39 return pack('n8', map { hex($_) } @groups);
194 }
195 0 return undef;
196 }
197  
198 1 1;
« blib/lib/SignalWire/REST/Pagination.pm ↑ Summary blib/lib/SignalWire/Contexts.pm »