path: root/usr/src/man/man1m/bart.1m

'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH BART 1M "Oct 26, 2005"
.SH NAME
bart \- basic audit reporting tool
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/bart\fR create [ \fB-n\fR] [\fB-R\fR \fIroot_directory\fR]
     [\fB-r\fR \fIrules_file\fR | -]
.fi

.LP
.nf
\fB/usr/bin/bart\fR create [\fB-n\fR] [\fB-R\fR \fIroot_directory\fR] \fB-I\fR
     [\fIfile_name\fR]...
.fi

.LP
.nf
\fB/usr/bin/bart\fR compare [\fB-i\fR \fIattribute\fR ] [\fB-p\fR]
     [\fB-r\fR \fIrules_file\fR | -] \fIcontrol-manifest\fR \fItest-manifest\fR
.fi

.SH DESCRIPTION
.sp
.LP
\fBbart\fR(1M) is a tool that performs a file-level check of the software
contents of a system.
.sp
.LP
You can also specify the files to track and the types of discrepancies to flag
by means of a rules file, \fBbart_rules\fR. See \fBbart_rules\fR(4).
.sp
.LP
The \fBbart\fR utility performs two basic functions:
.sp
.ne 2
.na
\fB\fBbart create\fR\fR
.ad
.RS 16n
The manifest generator tool takes a file-level \fBsnapshot\fR of a system. The
output is a catalog of file attributes referred to as a \fBmanifest\fR. See
\fBbart_manifest\fR(4).
.sp
You can specify that the list of files be cataloged in three ways. Use \fBbart
create\fR with no options, specify the files by name on the command line, or
create a rules file with directives that specify which the files to monitor.
See \fBbart_rules\fR(4).
.sp
By default, the manifest generator catalogs all attributes of all files in the
root (\fB/\fR) file system. File systems mounted on the root file system are
cataloged only if they are of the same type as the root file system.
.sp
For example, \fB/\fR, \fB/usr\fR, and \fB/opt\fR are separate UFS file systems.
\fB/usr\fR and \fB/opt\fR are mounted on \fB/\fR. Therefore, all three file
systems are cataloged. However, \fB/tmp\fR, also mounted on \fB/\fR, is not
cataloged because it is a TMPFS file system. Mounted CD-ROMs are not cataloged
since they are HSFS file systems.
.RE

.sp
.ne 2
.na
\fB\fBbart compare\fR\fR
.ad
.RS 16n
The report tool compares two manifests. The output is a list of per-file
attribute discrepancies. These discrepancies are the differences between two
manifests: a control manifest and a test manifest.
.sp
A discrepancy is a change to any attribute for a given file cataloged by both
manifests. A new file or a deleted file in a manifest is reported as a
discrepancy.
.sp
The reporting mechanism provides two types of output: verbose and programmatic.
Verbose output is localized and presented on multiple lines, while programmatic
output is more easily parsable by other programs. See \fBOUTPUT\fR.
.sp
By default, the report tool generates verbose output where all discrepancies
are reported except for modified directory timestamps (\fBdirmtime\fR
attribute).
.sp
To ensure consistent and accurate comparison results, \fIcontrol-manifest\fR
and \fItest-manifest\fR must be built with the same rules file.
.RE

.sp
.LP
Use the rules file to ignore specified files or subtrees when you generate a
manifest or compare two manifests. Users can compare manifests from different
perspectives by re-running the \fBbart compare\fR command with different rules
files.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-i\fR \fIattribute\fR ...\fR
.ad
.RS 21n
Specify the file attributes to be ignored globally. Specify attributes as a
comma separated list.
.sp
This option produces the same behavior as supplying the file attributes to a
global \fBIGNORE\fR keyword in the rules file. See \fBbart_rules\fR(4).
.RE

.sp
.ne 2
.na
\fB\fB-I\fR [\fIfile_name\fR...]\fR
.ad
.RS 21n
Specify the input list of files. The file list can be specified at the command
line or read from standard input.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 21n
Prevent computation of content signatures for all regular files in the file
list.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 21n
Display manifest comparison output in ``programmatic mode,'' which is suitable
for programmatic parsing. The output is not localized.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR \fIrules_file\fR\fR
.ad
.RS 21n
Use \fIrules_file\fR to specify which files and directories to catalog, and to
define which file attribute discrepancies to flag. If \fIrules_file\fR is
\fB-\fR, then the rules are read from standard input. See \fBbart_rules\fR(4)
for the definition of the syntax.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR \fIroot_directory\fR\fR
.ad
.RS 21n
Specify the root directory for the manifest. All paths specified by the rules,
and all paths reported in the manifest, are relative to \fIroot_directory\fR.
.LP
Note -
.sp
.RS 2
The root file system of any non-global zones must not be referenced with the
\fB-R\fR option. Doing so might damage the global zone's file system, might
compromise the security of the global zone, and might damage the non-global
zone's file system. See \fBzones\fR(5).
.RE
.RE

.SH OPERANDS
.sp
.LP
bart allows quoting of operands. This is particularly important for white-space
appearing in subtree and subtree modifier specifications.
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIcontrol-manifest\fR\fR
.ad
.RS 20n
Specify the manifest created by \fBbart create\fR on the control system.
.RE

.sp
.ne 2
.na
\fB\fItest-manifest\fR\fR
.ad
.RS 20n
Specify the manifest created by \fBbart create\fR on the test system.
.RE

.SH OUTPUT
.sp
.LP
The \fBbart create\fR and \fBbart compare\fR commands write output to standard
output, and write error messages to standard error.
.sp
.LP
The \fBbart create\fR command generates a system manifest. See
\fBbart_manifest\fR(4).
.sp
.LP
When the \fBbart compare\fR command compares two system manifests, it generates
a list of file differences. By default, the comparison output is localized.
However, if the \fB-p\fR option is specified, the output is generated in a form
that is suitable for programmatic manipulation.
.SS "Default Format"
.sp
.in +2
.nf
\fIfilename\fR
\fIattribute\fR control:\fIxxxx\fR test:\fIyyyy\fR
.fi
.in -2
.sp

.sp
.ne 2
.na
\fB\fIfilename\fR\fR
.ad
.RS 13n
Name of the file that differs between \fIcontrol-manifest\fR and
\fItest-manifest\fR. For file names that contain embedded whitespace or newline
characters, see \fBbart_manifest\fR(4).
.RE

.sp
.ne 2
.na
\fB\fIattribute\fR\fR
.ad
.RS 13n
The name of the file attribute that differs between the manifests that are
compared. \fIxxxx\fR is the attribute value from \fIcontrol-manifest\fR, and
\fIyyyy\fR is the attribute value from \fItest-manifest\fR. When discrepancies
for multiple attributes occur for the same file, each difference is noted on a
separate line.
.sp
The following attributes are supported:
.sp
.ne 2
.na
\fBacl\fR
.ad
.RS 12n
ACL attributes for the file. For a file with ACL attributes, this field
contains the output from \fBacltotext()\fR.
.RE

.sp
.ne 2
.na
\fBall\fR
.ad
.RS 12n
All attributes.
.RE

.sp
.ne 2
.na
\fBcontents\fR
.ad
.RS 12n
Checksum value of the file. This attribute is only specified for regular files.
If you turn off context checking or if checksums cannot be computed, the value
of this field is \fB-\fR.
.RE

.sp
.ne 2
.na
\fBdest\fR
.ad
.RS 12n
Destination of a symbolic link.
.RE

.sp
.ne 2
.na
\fBdevnode\fR
.ad
.RS 12n
Value of the device node. This attribute is for character device files and
block device files only.
.RE

.sp
.ne 2
.na
\fBdirmtime\fR
.ad
.RS 12n
Modification time in seconds since 00:00:00 UTC, January 1, 1970 for
directories.
.RE

.sp
.ne 2
.na
\fBgid\fR
.ad
.RS 12n
Numerical group ID of the owner of this entry.
.RE

.sp
.ne 2
.na
\fBlnmtime\fR
.ad
.RS 12n
Creation time for links.
.RE

.sp
.ne 2
.na
\fBmode\fR
.ad
.RS 12n
Octal number that represents the permissions of the file.
.RE

.sp
.ne 2
.na
\fBmtime\fR
.ad
.RS 12n
Modification time in seconds since 00:00:00 UTC, January 1, 1970 for files.
.RE

.sp
.ne 2
.na
\fBsize\fR
.ad
.RS 12n
File size in bytes.
.RE

.sp
.ne 2
.na
\fBtype\fR
.ad
.RS 12n
Type of file.
.RE

.sp
.ne 2
.na
\fBuid\fR
.ad
.RS 12n
Numerical user ID of the owner of this entry.
.RE

.RE

.sp
.LP
The following default output shows the attribute differences for the
\fB/etc/passwd\fR file. The output indicates that the \fBsize\fR, \fBmtime\fR,
and \fBcontents\fR attributes have changed.
.sp
.in +2
.nf
/etc/passwd:
  size  control:74  test:81
  mtime  control:3c165879  test:3c165979
  contents  control:daca28ae0de97afd7a6b91fde8d57afa
test:84b2b32c4165887355317207b48a6ec7
.fi
.in -2
.sp

.SS "Programmatic Format"
.sp
.in +2
.nf
\fIfilename\fR \fIattribute\fR \fIcontrol-val\fR \fItest-val\fR [\fIattribute\fR \fIcontrol-val\fR \fItest-val\fR]*
.fi
.in -2
.sp

.sp
.ne 2
.na
\fB\fIfilename\fR\fR
.ad
.sp .6
.RS 4n
Same as \fIfilename\fR in the default format.
.RE

.sp
.ne 2
.na
\fB\fIattribute\fR \fIcontrol-val\fR \fItest-val\fR\fR
.ad
.sp .6
.RS 4n
A description of the file attributes that differ between the control and test
manifests for each file. Each entry includes the attribute value from each
manifest. See \fBbart_manifest\fR(4) for the definition of the attributes.
.RE

.sp
.LP
Each line of the programmatic output describes all attribute differences for a
single file.
.sp
.LP
The following programmatic output shows the attribute differences for the
\fB/etc/passwd\fR file. The output indicates that the \fBsize\fR, \fBmtime\fR,
and \fBcontents\fR attributes have changed.
.sp
.in +2
.nf
/etc/passwd size 74 81 mtime 3c165879 3c165979
contents daca28ae0de97afd7a6b91fde8d57afa 84b2b32c4165887355317207b48a6ec7
.fi
.in -2
.sp

.SH EXIT STATUS
.SS "Manifest Generator"
.sp
.LP
The manifest generator returns the following exit values:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Success
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 6n
Non-fatal error when processing files; for example, permission problems
.RE

.sp
.ne 2
.na
\fB\fB>1\fR\fR
.ad
.RS 6n
Fatal error; for example, invalid command-line options
.RE

.SS "Report Tool"
.sp
.LP
The report tool returns the following exit values:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
No discrepancies reported
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 6n
Discrepancies found
.RE

.sp
.ne 2
.na
\fB\fB>1\fR\fR
.ad
.RS 6n
Fatal error executing comparison
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreating a Default Manifest Without Computing Checksums
.sp
.LP
The following command line creates a default manifest, which consists of all
files in the \fB/\fR file system. The \fB-n\fR option prevents computation of
checksums, which causes the manifest to be generated more quickly.

.sp
.in +2
.nf
bart create -n
.fi
.in -2
.sp

.LP
\fBExample 2 \fRCreating a Manifest for a Specified Subtree
.sp
.LP
The following command line creates a manifest that contains all files in the
\fB/home/nickiso\fR subtree.

.sp
.in +2
.nf
bart create -R /home/nickiso
.fi
.in -2
.sp

.LP
\fBExample 3 \fRCreating a Manifest by Using Standard Input
.sp
.LP
The following command line uses output from the \fBfind\fR(1) command to
generate the list of files to be cataloged. The \fBfind\fR output is used as
input to the \fBbart create\fR command that specifies the \fB-I\fR option.

.sp
.in +2
.nf
find /home/nickiso -print | bart create -I
.fi
.in -2
.sp

.LP
\fBExample 4 \fRCreating a Manifest by Using a Rules File
.sp
.LP
The following command line uses a rules file, \fBrules\fR, to specify the files
to be cataloged.

.sp
.in +2
.nf
bart create -r rules
.fi
.in -2
.sp

.LP
\fBExample 5 \fRComparing Two Manifests and Generating Programmatic Output
.sp
.LP
The following command line compares two manifests and produces output suitable
for parsing by a program.

.sp
.in +2
.nf
bart compare -p manifest1 manifest2
.fi
.in -2
.sp

.LP
\fBExample 6 \fRComparing Two Manifests and Specifying Attributes to Ignore
.sp
.LP
The following command line compares two manifests. The \fBdirmtime\fR,
\fBlnmtime\fR, and \fBmtime\fR attributes are not compared.

.sp
.in +2
.nf
bart compare -i dirmtime,lnmtime,mtime manifest1 manifest2
.fi
.in -2
.sp

.LP
\fBExample 7 \fRComparing Two Manifests by Using a Rules File
.sp
.LP
The following command line uses a rules file, \fBrules\fR, to compare two
manifests.

.sp
.in +2
.nf
bart compare -r rules manifest1 manifest2
.fi
.in -2
.sp

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
\fBcksum\fR(1), \fBdigest\fR(1), \fBfind\fR(1), \fBbart_manifest\fR(4),
\fBbart_rules\fR(4), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
The file attributes of certain system libraries can be temporarily altered by
the system as it boots. To avoid triggering false warnings, you should compare
manifests only if they were both created with the system in the same state;
that is, if both were created in single-user or both in multi-user.