Print this page
NEX-13644 File access audit logging
Reviewed by: Gordon Ross <gordon.ross@nexenta.com>
Reviewed by: Roman Strashkin <roman.strashkin@nexenta.com>
Reviewed by: Saso Kiselkov <saso.kiselkov@nexenta.com>
Reviewed by: Rick McNeal <rick.mcneal@nexenta.com>
Reviewed by: Yuri Pankov <yuri.pankov@nexenta.com>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1m/auditreduce.1m.man.txt
+++ new/usr/src/man/man1m/auditreduce.1m.man.txt
1 1 AUDITREDUCE(1M) Maintenance Commands AUDITREDUCE(1M)
2 2
3 3
4 4
5 5 NAME
6 6 auditreduce - merge and select audit records from audit trail files
7 7
8 8 SYNOPSIS
9 9 auditreduce [options] [audit-trail-file]...
10 10
11 11
12 12 DESCRIPTION
13 13 auditreduce allows you to select or merge records from audit trail
14 14 files. Audit files can be from one or more machines.
15 15
16 16
17 17 The merge function merges together audit records from one or more input
18 18 audit trail files into a single output file. The records in an audit
19 19 trail file are assumed to be sorted in chronological order (oldest
20 20 first) and this order is maintained by auditreduce in the output file.
21 21
22 22
23 23 Unless instructed otherwise, auditreduce will merge the entire audit
24 24 trail, which consists of all the audit trail files in the directory
25 25 structure audit_root_dir/*/files. Unless specified with the -R or -S
26 26 option, audit_root_dir defaults to /etc/security/audit. By using the
27 27 file selection options it is possible to select some subset of these
28 28 files, or files from another directory, or files named explicitly on
29 29 the command line.
30 30
31 31
32 32 The select function allows audit records to be selected on the basis of
33 33 numerous criteria relating to the record's content (see audit.log(4)
34 34 for details of record content). A record must meet all of the record-
35 35 selection-option criteria to be selected.
36 36
37 37 Audit Trail Filename Format
38 38 Any audit trail file not named on the command line must conform to the
39 39 audit trail filename format. Files produced by the audit system already
40 40 have this format. Output file names produced by auditreduce are in this
41 41 format. It is:
42 42
43 43 start-time.end-time.suffix
44 44
45 45
46 46
47 47
48 48 where start-time is the 14-character timestamp of when the file was
49 49 opened, end-time is the 14-character timestamp of when the file was
50 50 closed, and suffix is the name of the machine which generated the audit
51 51 trail file, or some other meaningful suffix (for example, all, if the
52 52 file contains a combined group of records from many machines). The end-
53 53 time can be the literal string not_terminated, to indicate that the
54 54 file is still being written to by the audit system. Timestamps are of
55 55 the form yyyymmddhhmmss (year, month, day, hour, minute, second). The
56 56 timestamps are in Greenwich Mean Time (GMT).
57 57
58 58 OPTIONS
59 59 File Selection Options
60 60 The file selection options indicate which files are to be processed and
61 61 certain types of special treatment.
62 62
63 63 -A
64 64
65 65 All of the records from the input files will be selected regardless
66 66 of their timestamp. This option effectively disables the -a, -b,
67 67 and -d options. This is useful in preventing the loss of records if
68 68 the -D option is used to delete the input files after they are
69 69 processed. Note, however, that if a record is not selected due to
70 70 another option, then -A will not override that.
71 71
72 72
73 73 -C
74 74
75 75 Only process complete files. Files whose filename end-time
76 76 timestamp is not_terminated are not processed (such a file is
77 77 currently being written to by the audit system). This is useful in
78 78 preventing the loss of records if -D is used to delete the input
79 79 files after they are processed. It does not apply to files
80 80 specified on the command line.
81 81
82 82
83 83 -D suffix
84 84
85 85 Delete input files after they are read if the entire run is
86 86 successful. If auditreduce detects an error while reading a file,
87 87 then that file is not deleted. If -D is specified, -A, -C and -O
88 88 are also implied. suffix is given to the -O option. This helps
89 89 prevent the loss of audit records by ensuring that all of the
90 90 records are written, only complete files are processed, and the
91 91 records are written to a file before being deleted. Note that if
92 92 both -D and -O are specified in the command line, the order of
93 93 specification is significant. The suffix associated with the latter
94 94 specification is in effect.
95 95
96 96
97 97 -M machine
98 98
99 99 Allows selection of records from files with machine as the filename
100 100 suffix. If -M is not specified, all files are processed regardless
101 101 of suffix. -M can also be used to allow selection of records from
102 102 files that contain combined records from many machines and have a
103 103 common suffix (such as all).
104 104
105 105
106 106 -N
107 107
108 108 Select objects in new mode.This flag is off by default, thus
109 109 retaining backward compatibility. In the existing, old mode,
110 110 specifying the -e, -f, -g, -r, or -u flags would select not only
111 111 actions taken with those IDs, but also certain objects owned by
112 112 those IDs. When running in new mode, only actions are selected. In
113 113 order to select objects, the -o option must be used.
114 114
115 115
116 116 -O suffix
117 117
118 118 Direct output stream to a file in the current audit_root_dir with
119 119 the indicated suffix. suffix can alternatively contain a full
120 120 pathname, in which case the last component is taken as the suffix,
121 121 ahead of which the timestamps will be placed, ahead of which the
122 122 remainder of the pathname will be placed. If the -O option is not
123 123 specified, the output is sent to the standard output. When
124 124 auditreduce places timestamps in the filename, it uses the times of
125 125 the first and last records in the merge as the start-time and end-
126 126 time.
127 127
128 128
129 129 -Q
130 130
131 131 Quiet. Suppress notification about errors with input files.
132 132
133 133
134 134 -R pathname
135 135
136 136 Specify the pathname of an alternate audit root directory
137 137 audit_root_dir to be pathname. Therefore, rather than using
138 138 /etc/security/audit/*/files by default, pathname/*/files will be
139 139 examined instead.
140 140
141 141 Note -
142 142
143 143 The root file system of any non-global zones must not be
144 144 referenced with the -R option. Doing so might damage the global
145 145 zone's file system, might compromise the security of the global
146 146 zone, and might damage the non-global zone's file system. See
147 147 zones(5).
148 148
149 149
150 150 -S server
151 151
152 152 This option causes auditreduce to read audit trail files from a
153 153 specific location (server directory). server is normally
154 154 interpreted as the name of a subdirectory of the audit root,
155 155 therefore auditreduce will look in audit_root_dir/server/files for
156 156 the audit trail files. But if server contains any `/' characters,
157 157 it is the name of a specific directory not necessarily contained in
158 158 the audit root. In this case, server/files will be consulted. This
159 159 option allows archived files to be manipulated easily, without
160 160 requiring that they be physically located in a directory structure
161 161 like that of /etc/security/audit.
162 162
163 163
164 164 -V
165 165
166 166 Verbose. Display the name of each file as it is opened, and how
167 167 many records total were written to the output stream.
168 168
169 169
170 170 Record Selection Options
171 171 The record selection options listed below are used to indicate which
172 172 records are written to the output file produced by auditreduce.
173 173
174 174
175 175 Multiple arguments of the same type are not permitted.
176 176
177 177 -a date-time
178 178
179 179 Select records that occurred at or after date-time. The date-time
180 180 argument is described under Option Arguments, below. date-time is
181 181 in local time. The -a and -b options can be used together to form a
182 182 range.
183 183
184 184
185 185 -b date-time
186 186
187 187 Select records that occurred before date-time.
188 188
189 189
190 190 -c audit-classes
191 191
192 192 Select records by audit class. Records with events that are mapped
193 193 to the audit classes specified by audit-classes are selected. Audit
194 194 class names are defined in audit_class(4). Using the audit flags,
195 195 one can select records based upon success and failure criteria.
196 196
197 197
198 198 -d date-time
199 199
200 200 Select records that occurred on a specific day (a 24-hour period
201 201 beginning at 00:00:00 of the day specified and ending at 23:59:59).
202 202 The day specified is in local time. The time portion of the
203 203 argument, if supplied, is ignored. Any records with timestamps
204 204 during that day are selected. If any hours, minutes, or seconds are
205 205 given in time, they are ignored. -d can not be used with -a or -b.
206 206
207 207
208 208 -e effective-user
209 209
210 210 Select records with the specified effective-user.
211 211
212 212
213 213 -f effective-group
214 214
215 215 Select records with the specified effective-group.
216 216
217 217
218 218 -g real-group
219 219
220 220 Select records with the specified real-group.
221 221
222 222
223 223 -j subject-ID
224 224
225 225 Select records with the specified subject-ID where subject-ID is a
226 226 process ID.
227 227
228 228
229 229 -l label
230 230
231 231 Select records with the specified label (or label range), as
232 232 explained under "Option Arguments," below. This option is available
233 233 only if the system is configured with Trusted Extensions.
234 234
235 235
236 236 -m event
237 237
238 238 Select records with the indicated event. The event is the literal
239 239 string or the event number.
240 240
241 241
242 242 -o object_type=objectID_value
243 243
244 244 Select records by object type. A match occurs when the record
245 245 contains the information describing the specified object_type and
246 246 the object ID equals the value specified by objectID_value. The
247 247 allowable object types and values are as follows:
248 248
249 249 file=pathname
250 250
251 251 Select records containing file system objects with the
252 252 specified pathname, where pathname is a comma separated list of
253 253 regular expressions. If a regular expression is preceded by a
254 254 tilde (~), files matching the expression are excluded from the
255 255 output. For example, the option file=~/usr/openwin,/usr,/etc
256 256 would select all files in /usr or /etc except those in
257 257 /usr/openwin. The order of the regular expressions is important
258 258 because auditreduce processes them from left to right, and
259 259 stops when a file is known to be either selected or excluded.
260 260 Thus the option file= /usr, /etc, ~/usr/openwin would select
261 261 all files in /usr and all files in /etc. Files in /usr/openwin
262 262 are not excluded because the regular expression /usr is matched
263 263 first. Care should be given in surrounding the pathname with
264 264 quotes so as to prevent the shell from expanding any tildes.
265 265
266 266
267 267 filegroup=group
268 268
269 269 Select records containing file system objects with group as the
270 270 owning group.
271 271
272 272
273 273 fileowner=user
274 274
275 275 Select records containing file system objects with user as the
276 276 owning user.
277 277
278 278
279 279 msgqid=ID
280 280
281 281 Select records containing message queue objects with the
282 282 specified ID where ID is a message queue ID.
283 283
284 284
285 285 msgqgroup=group
286 286
287 287 Select records containing message queue objects with group as
288 288 the owning or creating group.
289 289
290 290
291 291 msgqowner=user
292 292
293 293 Select records containing message queue objects with user as
294 294 the owning or creating user.
295 295
296 296
297 297 pid=ID
298 298
299 299 Select records containing process objects with the specified ID
300 300 where ID is a process ID. Process are objects when they are
301 301 receivers of signals.
302 302
303 303
304 304 procgroup=group
305 305
306 306 Select records containing process objects with group as the
307 307 real or effective group.
308 308
309 309
310 310 procowner=user
311 311
312 312 Select records containing process objects with user as the real
313 313 or effective user.
314 314
315 315
316 316 semid=ID
317 317
318 318 Select records containing semaphore objects with the specified
319 319 ID where ID is a semaphore ID.
320 320
321 321
322 322 semgroup=group
323 323
324 324 Select records containing semaphore objects with group as the
325 325 owning or creating group.
326 326
327 327
328 328 semowner=user
329 329
330 330 Select records containing semaphore objects with user as the
331 331 owning or creating user.
332 332
333 333
334 334 shmid=ID
335 335
336 336 Select records containing shared memory objects with the
337 337 specified ID where ID is a shared memory ID.
338 338
339 339
340 340 shmgroup=group
341 341
342 342 Select records containing shared memory objects with group as
343 343 the owning or creating group.
344 344
345 345
346 346 shmowner=user
347 347
348 348 Select records containing shared memory objects with user as
349 349 the owning or creating user.
350 350
351 351
352 352 sock=port_number|machine
353 353
354 354 Select records containing socket objects with the specified
|
↓ open down ↓ |
354 lines elided |
↑ open up ↑ |
355 355 port_number or the specified machine where machine is a machine
356 356 name as defined in hosts(4).
357 357
358 358
359 359 fmri=service instance
360 360
361 361 Select records containing fault management resource identifier
362 362 (FMRI) objects with the specified service instance. See smf(5).
363 363
364 364
365 + wsid=Windows SID
365 366
367 + Select records containing Windows SIDS matching the specified
368 + SID.
369 +
370 +
371 +
366 372 -r real-user
367 373
368 374 Select records with the specified real-user.
369 375
370 376
371 377 -s session-id
372 378
373 379 Select audit records with the specified session-id.
374 380
375 381
376 382 -u audit-user
377 383
378 384 Select records with the specified audit-user.
379 385
380 386
381 387 -z zone-name
382 388
383 389 Select records from the specified zone name. The zone name
384 390 selection is case-sensitive.
385 391
386 392
387 393
388 394 When one or more filename arguments appear on the command line, only
389 395 the named files are processed. Files specified in this way need not
390 396 conform to the audit trail filename format. However, -M, -S, and -R
391 397 must not be used when processing named files. If the filename is ``-''
392 398 then the input is taken from the standard input.
393 399
394 400 Option Arguments
395 401 audit-trail-file
396 402
397 403 An audit trail file as defined in audit.log(4). An audit trail file
398 404 not named on the command line must conform to the audit trail file
399 405 name format. Audit trail files produced as output of auditreduce
400 406 are in this format as well. The format is:
401 407
402 408 start-time . end-time . suffix
403 409
404 410 start-time is the 14 character time stamp denoting when the file
405 411 was opened. end-time is the 14 character time stamp denoting when
406 412 the file was closed. end-time can also be the literal string
407 413 not_terminated, indicating the file is still be written to by the
408 414 audit daemon or the file was not closed properly (a system crash or
409 415 abrupt halt occurred). suffix is the name of the machine that
410 416 generated the audit trail file (or some other meaningful suffix;
411 417 for example, all would be a good suffix if the audit trail file
412 418 contains a combined group of records from many machines).
413 419
414 420
415 421 date-time
416 422
417 423 The date-time argument to -a, -b, and -d can be of two forms: An
418 424 absolute date-time takes the form:
419 425
420 426 yyyymmdd [ hh [ mm [ ss ]]]
421 427
422 428 where yyyy specifies a year (with 1970 as the earliest value), mm
423 429 is the month (01-12), dd is the day (01-31), hh is the hour
424 430 (00-23), mm is the minute (00-59), and ss is the second (00-59).
425 431 The default is 00 for hh, mm and ss.
426 432
427 433 An offset can be specified as: +n d|h|m| s where n is a number of
428 434 units, and the tags d, h, m, and s stand for days, hours, minutes
429 435 and seconds, respectively. An offset is relative to the starting
430 436 time. Thus, this form can only be used with the -b option.
431 437
432 438
433 439 event
434 440
435 441 The literal string or ordinal event number as found in
436 442 audit_event(4). If event is not found in the audit_event file it is
437 443 considered invalid.
438 444
439 445
440 446 group
441 447
442 448 The literal string or ordinal group ID number as found in group(4).
443 449 If group is not found in the group file it is considered invalid.
444 450 group can be negative.
445 451
446 452
447 453 label
448 454
449 455 The literal string representation of a MAC label or a range of two
450 456 valid MAC labels. To specify a range, use x;y where x and y are
451 457 valid MAC labels. Only those records that are fully bounded by x
452 458 and y will be selected. If x or y is omitted, the default uses
453 459 ADMIN_LOW or ADMIN_HIGH respectively. Notice that quotes must be
454 460 used when specifying a range.
455 461
456 462
457 463 pathname
458 464
459 465 A regular expression describing a pathname.
460 466
461 467
462 468 user
463 469
464 470 The literal username or ordinal user ID number as found in
465 471 passwd(4). If the username is not found in the passwd file it is
466 472 considered invalid. user can be negative.
467 473
468 474
469 475 EXAMPLES
470 476 Example 1 The auditreduce command
471 477
472 478
473 479 praudit(1M) is available to display audit records in a human-readable
474 480 form.
475 481
476 482
477 483
478 484 This will display the entire audit trail in a human-readable form:
479 485
480 486
481 487 % auditreduce | praudit
482 488
483 489
484 490
485 491
486 492 If all the audit trail files are being combined into one large file,
487 493 then deleting the original files could be desirable to prevent the
488 494 records from appearing twice:
489 495
490 496
491 497 % auditreduce -V -D /etc/security/audit/combined/all
492 498
493 499
494 500
495 501
496 502 This displays what user milner did on April 13, 1988. The output is
497 503 displayed in a human-readable form to the standard output:
498 504
499 505
500 506 % auditreduce -d 19880413 -u milner | praudit
501 507
502 508
503 509
504 510
505 511 The above example might produce a large volume of data if milner has
506 512 been busy. Perhaps looking at only login and logout times would be
507 513 simpler. The -c option will select records from a specified class:
508 514
509 515
510 516 % auditreduce -d 19880413 -u milner -c lo | praudit
511 517
512 518
513 519
514 520
515 521 To see milner's login/logout activity for April 13, 14, and 15, the
516 522 following is used. The results are saved to a file in the current
517 523 working directory. Notice that the name of the output file will have
518 524 milnerlo as the suffix, with the appropriate timestamp prefixes. Notice
519 525 also that the long form of the name is used for the -c option:
520 526
521 527
522 528 % auditreduce -a 19880413 -b +3d -u milner -c login_logout -O milnerlo
523 529
524 530
525 531
526 532
527 533 To follow milner's movement about the file system on April 13, 14, and
528 534 15 the chdir record types could be viewed. Notice that in order to get
529 535 the same time range as the above example we needed to specify the -b
530 536 time as the day after our range. This is because 19880416 defaults to
531 537 midnight of that day, and records before that fall on 0415, the end-day
532 538 of the range.
533 539
534 540
535 541 % auditreduce -a 19880413 -b 19880416 -u milner -m AUE_CHDIR | praudit
536 542
537 543
538 544
539 545
540 546 In this example, the audit records are being collected in summary form
541 547 (the login/logout records only). The records are being written to a
542 548 summary file in a different directory than the normal audit root to
543 549 prevent the selected records from existing twice in the audit root.
544 550
545 551
546 552 % auditreduce -d 19880330 -c lo -O /etc/security/audit_summary/logins
547 553
548 554
549 555
550 556
551 557 If activity for user ID 9944 has been observed, but that user is not
552 558 known to the system administrator, then the command in the following
553 559 example searches the entire audit trail for any records generated by
554 560 that user. auditreduce queries the system about the current validity
555 561 of ID 9944 and displays a warning message if it is not currently
556 562 active:
557 563
558 564
559 565 % auditreduce -O /etc/security/audit_suspect/user9944 -u 9944
560 566
561 567
562 568
563 569
564 570 To get an audit log of only the global zone:
565 571
566 572
567 573 % auditreduce -z global
568 574
569 575
570 576 FILES
571 577 /etc/security/audit/server/files/*
572 578
573 579 location of audit trails, when stored
574 580
575 581
576 582 ATTRIBUTES
577 583 See attributes(5) for descriptions of the following attributes:
578 584
579 585
580 586
581 587
582 588 +--------------------+-----------------+
583 589 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
584 590 +--------------------+-----------------+
585 591 |Interface Stability | See below. |
586 592 +--------------------+-----------------+
587 593
588 594
589 595 The command invocation is Stable. The binary file format is Stable. The
590 596 binary file contents is Unstable.
591 597
592 598 SEE ALSO
593 599 praudit(1M), audit.log(4), audit_class(4), group(4), hosts(4),
594 600 passwd(4), attributes(5), smf(5)
595 601
596 602 DIAGNOSTICS
597 603 auditreduce displays error messages if there are command line errors
598 604 and then exits. If there are fatal errors during the run, auditreduce
599 605 displays an explanatory message and exits. In this case, the output
600 606 file might be in an inconsistent state (no trailer or partially written
601 607 record) and auditreduce displays a warning message before exiting.
602 608 Successful invocation returns 0 and unsuccessful invocation returns 1.
603 609
604 610
605 611 Since auditreduce might be processing a large number of input files, it
606 612 is possible that the machine-wide limit on open files will be exceeded.
607 613 If this happens, auditreduce displays a message to that effect, give
608 614 information on how many file there are, and exit.
609 615
610 616
611 617 If auditreduce displays a record's timestamp in a diagnostic message,
612 618 that time is in local time. However, when filenames are displayed,
613 619 their timestamps are in GMT.
614 620
|
↓ open down ↓ |
239 lines elided |
↑ open up ↑ |
615 621 BUGS
616 622 Conjunction, disjunction, negation, and grouping of record selection
617 623 options should be allowed.
618 624
619 625 NOTES
620 626 The -z option should be used only if the audit policy zonename is set.
621 627 If there is no zonename token, then no records will be selected.
622 628
623 629
624 630
625 - March 6, 2017 AUDITREDUCE(1M)
631 + July 10, 2018 AUDITREDUCE(1M)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX