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