lib/Log/Munger/RuleFileParser.pm

filter: Statementstmt 85.8% 97 / 113 Branchbran 62.5% 30 / 48 Conditioncond 33.3% 1 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 100% 14 / 14 Podpod 100% 3 / 3 totaltotal 79.2% 145 / 183 CC 28 SCAR 23.7
CC
28
Cov
78%
load_no_templating
20.5
load
8.5
_normalized_var_value
5.6
CRAP 10.7
« lib/Log/Munger/RulesTemplateOrder.pm ↑ Summary lib/Log/Munger/App/Command/test_all.pm »
1 package Log::Munger::RuleFileParser;
2  
3 32 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 32 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 32 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 32 ▶use YAML::XS qw(Load);
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # a rule file is data; never bless objects out of YAML tags. Old YAML::XS
9 # versions default LoadBlessed on, which is an object-injection risk when
10 # loading a third-party rule file
11 32 $YAML::XS::LoadBlessed = 0;
12 32 ▶use Log::Munger::WhichRuleFile ();
Subroutine BEGIN: called CC=1 SCAR=0.0
13 32 ▶use File::Slurp qw(read_file);
Subroutine BEGIN: called CC=1 SCAR=0.0
14 32 ▶use Template;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 32 ▶use Hash::Merge ();
Subroutine BEGIN: called CC=1 SCAR=0.0
16 32 ▶use Log::Munger::RulesTemplateOrder;
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 =head1 NAME
19  
20 Log::Munger::RuleFileParser - Reads a Log::Munger rule file into a rules hash.
21  
22 =head1 VERSION
23  
24 Version 0.0.1
25  
26 =cut
27  
28 32 our $VERSION = '0.0.1';
29  
30 =head1 SYNOPSIS
31  
32 use Log::Munger::RuleFileParser;
33  
34 my $parser = Log::Munger::RuleFileParser->new;
35 my $rules = $parser->load( 'file' => 'sshd' );
36  
37 print $rules->{'vars'}{'SSH_FAILED'} . "\n";
38  
39 Loading a rule file is four steps. The name is resolved to a path via
40 L<Log::Munger::WhichRuleFile>, the YAML is read in, anything under C<includes> is
41 merged in with the file itself winning on a conflict (and an earlier include
42 winning over a later one), and finally everything under C<vars_templated> is run
43 through L<Template> and folded into C<vars>.
44  
45 That last step is why order matters: a templated var may reference another
46 templated var, so L<Log::Munger::RulesTemplateOrder> sorts them by dependency
47 first and each one is resolved only once everything it references already is.
48  
49 Trailing newlines are stripped from every var at every step. A YAML C<|> block
50 scalar keeps its terminating newline, and one of those landing in the middle of a
51 composed pattern would quietly stop it matching single line logs.
52  
53 =head1 METHODS
54  
55 =head2 new
56  
57 Creates a parser. Takes no arguments.
58  
59 my $parser = Log::Munger::RuleFileParser->new;
60  
61 =cut
62  
63 224 ▶sub new {
Subroutine new: called CC=1 SCAR=0.0
Pod documented
64 224 my ( $blank, %opts ) = @_;
65  
66 224 my $self = {};
67 224 bless $self;
68  
69 224 return $self;
70 }
71  
72 =head2 load
73  
74 Loads a rule file, merging its includes and resolving its templated vars.
75  
76 Every resolved C<vars_templated> entry is written back into C<< $rules->{vars} >>,
77 so by the time this returns there is one flat namespace of named regexps and
78 C<vars_templated> is only of interest for seeing how a var was written.
79  
80 - file :: The file to load. Either a bare name resolved through the search
81 path, such as "sshd", or a path. Required.
82 Default :: undef
83  
84 Returns the rules hash ref. Dies if the file cannot be found, is not valid YAML,
85 does not parse to a hash, names an include that cannot be found, references a var
86 that is not defined anywhere, or holds a var that will not template.
87  
88 my $rules = $parser->load( 'file' => 'sshd' );
89  
90 =cut
91  
92 322 ▶sub load {
Subroutine load: called CC=8 SCAR=21.4
Pod documented
93 322 my ( $self, %opts ) = @_;
94  
95 322 ▶ if ( !defined( $opts{'file'} ) ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not defined $opts{'file'}) { } 0 322 322
elsif (ref $opts{'file'} ne '') { } 0 322 322
96 0 die('$opts{file} is undef');
97 } elsif ( ref( $opts{'file'} ) ne '' ) {
98 0 die( '$opts{file} ref is "' . ref( $opts{'file'} ) . '" and not ""' );
99 }
100  
101 322 my $rules;
102 322 eval { $rules = $self->load_no_templating( 'file' => $opts{'file'} ); };
103 322 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 2 320 322
104 2 die( 'Failed to call load_no_templating for "' . $opts{'file'} . '"... ' . $@ );
105 }
106  
107 320 my $template_order = Log::Munger::RulesTemplateOrder->order_for_rules_hash( 'rules' => $rules );
108  
109 318 my $tt = Template->new;
110  
111 318 my $template_hash = 'vars_templated';
112 318 ▶ if ( defined( $rules->{$template_hash} ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rules->{$template_hash}) 317 1 318
113 317 ▶ if ( ref( $rules->{$template_hash} ) ne 'HASH' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $rules->{$template_hash} ne "HASH") 0 317 317
114 die( '$rules->{'
115 . $template_hash
116 . '} exists and is of ref "'
117 0 . ref( $rules->{$template_hash} )
118 . '" and not HASH' );
119 }
120  
121 317 foreach my $item ( @{$template_order} ) {
122 # strip trailing newlines off the template source so a block-scalar
123 # terminator does not survive into the composed pattern
124 11263 $rules->{$template_hash}{$item} = _normalized_var_value( $rules->{$template_hash}{$item},
125 '$rules->{' . $template_hash . '}{' . $item . '}' );
126  
127 11263 my $results;
128 11263 ▶ $tt->process( \$rules->{$template_hash}{$item}, $rules->{'vars'}, \$results )
Branch: 1 branch
BranchTrueFalseTotal
$tt->process(\$rules->{$template_hash}{$item}, $rules->{"vars"}, \$results) or die 'Failed to process $rules->{' . $template_hash . '}{' . $item . '} ... ' . $tt->error 11263 0 11263
129 || die( 'Failed to process $rules->{' . $template_hash . '}{' . $item . '} ... ' . $tt->error() );
130 # strip before writing back to the stash: dependency ordering means
131 # this value may be interpolated into a later var, and an embedded
132 # newline mid-pattern would keep it from matching single-line logs
133 11263 $results =~ s/[\r\n]+\z//;
134 11263 $rules->{'vars'}{$item} = $results;
135 } ## end foreach my $item ( @{$template_order} )
136 } ## end if ( defined( $rules->{$template_hash} ) )
137  
138 318 return $rules;
139 } ## end sub load
140  
141 =head2 load_no_templating
142  
143 Same as L</load>, but stops short of resolving C<vars_templated>. The includes are
144 still merged and the plain C<vars> are still normalized, so what comes back is the
145 rule file as written rather than as compiled.
146  
147 This is what the template ordering tooling uses. Working out which var depends on
148 which means reading the C<[% VAR %]> references before they are substituted away.
149  
150 - file :: The file to load. Either a bare name resolved through the search
151 path, such as "sshd", or a path. Required.
152 Default :: undef
153  
154 Returns the rules hash ref, with C<vars_templated> left untouched. Dies under the
155 same conditions as L</load>, minus the templating.
156  
157 my $rules = $parser->load_no_templating( 'file' => 'sshd' );
158  
159 =cut
160  
161 326 ▶sub load_no_templating {
Subroutine load_no_templating: called CC=16 SCAR=30.2
Pod documented
162 326 my ( $self, %opts ) = @_;
163  
164 326 ▶ if ( !defined( $opts{'file'} ) ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not defined $opts{'file'}) { } 0 326 326
elsif (ref $opts{'file'} ne '') { } 0 326 326
165 0 die('$opts{file} is undef');
166 } elsif ( ref( $opts{'file'} ) ne '' ) {
167 0 die( '$opts{file} ref is "' . ref( $opts{'file'} ) . '" and not ""' );
168 }
169  
170 326 my $file_location = Log::Munger::WhichRuleFile->rule_file_location( 'file' => $opts{'file'} );
171  
172 326 ▶ if ( !defined($file_location) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $file_location) 2 324 326
173 die( '"'
174 . $opts{'file'}
175 . '" could not be found by Log::Munger::WhichRuleFile->rule_file_location(file =>"'
176 2 . $opts{'file'}
177 . '")' );
178 }
179  
180 324 my $rules;
181 324 eval { $rules = _read_yaml_hash($file_location); };
182 324 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 324 324
183 0 die( 'Failed to read in and parse "' . $file_location . '"... ' . $@ );
184 }
185  
186 324 ▶ if ( defined( $rules->{'includes'} ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rules->{"includes"}) 306 18 324
187 306 ▶ if ( ref( $rules->{'includes'} ) ne 'ARRAY' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $rules->{"includes"} ne "ARRAY") 0 306 306
188 die( '.includes in "'
189 . $file_location
190 . '" is of ref "'
191 0 . ref( $rules->{'includes'} )
192 . '" and not "ARRAY"' );
193 }
194 306 ▶ if ( defined( $rules->{'includes'}[0] ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rules->{"includes"}[0]) 306 0 306
195 # LEFT_PRECEDENT with the file on the left: the file wins a conflict
196 # with an include, and an earlier include wins over a later one.
197 # Arrays merge by appending the include's entries, which is also what
198 # lets the loop below pick up an include's own includes as they are
199 # merged in
200 306 my $merger = Hash::Merge->new('LEFT_PRECEDENT');
201 306 my %included;
202 306 my $include_int = 0;
203 306 ▶ while ( defined( $rules->{'includes'}[$include_int] ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rules->{"includes"}[$include_int]) 308 306 614
204 308 ▶ if ( ref( $rules->{'includes'}[$include_int] ) ne '' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $rules->{"includes"}[$include_int] ne "") 0 308 308
205 die( '.includes.'
206 . $include_int
207 . ' is a ref of "'
208 0 . ref( $rules->{'includes'}[$include_int] )
209 . '" and not ""' );
210 }
211  
212 308 ▶ if ( !$included{ $rules->{'includes'}[$include_int] } ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($included{$rules->{"includes"}[$include_int]}) 308 0 308
213 308 $included{ $rules->{'includes'}[$include_int] } = 1;
214  
215 my $include_location = Log::Munger::WhichRuleFile->rule_file_location(
216 308 'file' => $rules->{'includes'}[$include_int] );
217 308 ▶ if ( !defined($include_location) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $include_location) 0 308 308
218 die( '.includes.'
219 . $include_int . ', "'
220 0 . $rules->{'includes'}[$include_int]
221 . '", could not be found by Log::Munger::WhichRuleFile->rule_file_location' );
222 }
223 308 my $rule_include;
224 308 eval { $rule_include = _read_yaml_hash($include_location); };
225 308 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 308 308
226 die( '.includes.'
227 . $include_int . ', "'
228 0 . $rules->{'includes'}[$include_int]
229 . '", could not be loaded... '
230 . $@ );
231 }
232  
233 308 $rules = $merger->merge( $rules, $rule_include );
234 } ## end if ( !$included{ $rules->{'includes'}[$include_int...]})
235  
236 308 $include_int++;
237 } ## end while ( defined( $rules->{'includes'}[$include_int...]))
238  
239 } ## end if ( defined( $rules->{'includes'}[0] ) )
240 } ## end if ( defined( $rules->{'includes'} ) )
241  
242 324 ▶ if ( defined( $rules->{'vars'} ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rules->{"vars"}) 322 2 324
243 322 ▶ if ( ref( $rules->{'vars'} ) ne 'HASH' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $rules->{"vars"} ne "HASH") 0 322 322
244 0 die( '$rules->{vars} exists and is of ref "' . ref( $rules->{'vars'} ) . '" and not HASH' );
245 }
246  
247 322 foreach my $item ( keys( %{ $rules->{'vars'} } ) ) {
248 # every plain var feeds the Template Toolkit stash; strip trailing
249 # newlines (YAML "|" block-scalar terminators) so they cannot leak
250 # into the middle of a composed pattern during templating
251 15346 $rules->{'vars'}{$item} = _normalized_var_value( $rules->{'vars'}{$item}, '$rules->{vars}{' . $item . '}' );
252 }
253 } ## end if ( defined( $rules->{'vars'} ) )
254  
255 324 return $rules;
256 } ## end sub load_no_templating
257  
258 # Reads a YAML file and returns the hash ref it parses to.
259 #
260 # Args:
261 #
262 # - $path :: The path of the file to read.
263 #
264 # Returns the parsed hash ref. Dies when the file cannot be read, is not valid
265 # YAML, or parses to something other than a hash, such as a list or nothing at
266 # all.
267 #
268 # my $rules = _read_yaml_hash($file_location);
269 632 ▶sub _read_yaml_hash {
Subroutine _read_yaml_hash: called CC=3 SCAR=12.0
270 632 my ($path) = @_;
271  
272 632 my $raw = read_file($path);
273 632 my $parsed = Load($raw);
274 632 ▶ if ( !defined($parsed) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $parsed) 0 632 632
275 0 die( 'Load(read_file("' . $path . '")) returned undef' );
276 }
277 632 ▶ if ( ref($parsed) ne 'HASH' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $parsed ne "HASH") 0 632 632
278 0 die( 'Load(read_file("' . $path . '")) returned a ref of "' . ref($parsed) . '" and not "HASH"' );
279 }
280  
281 632 return $parsed;
282 } ## end sub _read_yaml_hash
283  
284 # Normalizes one var value as it came out of the YAML. A value written as an
285 # array of strings is joined into a single string, and trailing newlines are
286 # stripped, since a YAML "|" block scalar keeps its terminating newline and one
287 # of those landing in the middle of a composed pattern would quietly stop it
288 # matching single-line logs.
289 #
290 # Args:
291 #
292 # - $value :: The value as YAML::XS returned it. A plain string or an
293 # array ref of strings.
294 #
295 # - $where :: Where the value lives, such as '$rules->{vars}{FOO}'. Used in
296 # the die message.
297 #
298 # Returns the normalized string. Dies when the value is neither a plain string
299 # nor an array ref.
300 #
301 # $rules->{'vars'}{$item} = _normalized_var_value( $rules->{'vars'}{$item}, '$rules->{vars}{' . $item . '}' );
302 26609 ▶sub _normalized_var_value {
Subroutine _normalized_var_value: called CC=4 SCAR=17.3
303 26609 my ( $value, $where ) = @_;
304  
305 26609 ▶ if ( ( ref($value) ne 'ARRAY' ) && ( ref($value) ne '' ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $value ne "ARRAY" and ref $value ne "") 0 26609 26609
Condition33%1/3
ref $value ne "ARRAY" and ref $value ne ""
!ll&&!rl&&r
0266090
MC/DC0%0/2
ref $value ne "ARRAY" and ref $value ne ""
ref $value ne "ARRAY" ref $value ne ""
Truth table33%1/3
A and B
A= ref $value ne "ARRAY"B= ref $value ne ""
ABresult
0X0
100
111
306 0 die( $where . ' is of ref "' . ref($value) . '" and not "ARRAY" or ""' );
307 }
308 26609 ▶ if ( ref($value) eq 'ARRAY' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $value eq "ARRAY") 0 26609 26609
309 0 $value = join( '', @{$value} );
310 }
311 26609 $value =~ s/[\r\n]+\z//;
312  
313 26609 return $value;
314 } ## end sub _normalized_var_value
315  
316 32 1; # End of Log::Munger::RuleFileParser
« lib/Log/Munger/RulesTemplateOrder.pm ↑ Summary lib/Log/Munger/App/Command/test_all.pm »