Sun Management Center Change Manager 1.0.1 Administration Guide

- Previous: Chapter 10 Parameters for Shared Profiles and Host Properties (Reference)
- Next: Appendix A Change Manager Browser Interface Navigation (Reference)

# Chapter 11 Audit Tool File Formats (Reference)

This chapter describes the file formats for the three audit-related files.

The following topics are described in this chapter:

- Audit Rules File Format

- Manifest File Format

- Comparison Report Format

# Audit Rules File Format

The rules file is a text file that is used by the audit commands. The rules file determines which files to validate and which file attributes of those files to ignore.

To create an audit rules file, see How to Create an Audit Rules File (Web Browser) and How to Import an Audit Rules File to the Change Manager Repository (Web Browser) or How to Import Audit Rules Files to the Change Manager Repository (Command Line).

Some lines are ignored by the manifest comparison tool. Ignored lines include blank lines, lines that consist only of white space, and comments that begin with `#`.

The rules file supports three directives: `CHECK`, `IGNORE`, and a subtree directive, which is an absolute path name plus optional pattern matching modifiers. The rules file uses the directives to create logical blocks.

## Syntax

The syntax for the rules file is as follows:

    [IGNOREattribute...]*
    [CHECK] [attribute...]*

    subtree1 [pattern...]*
    [IGNORE attribute...]*
    [CHECK] [attribute...]*

    subtree2 [pattern...]*
    subtree3 [pattern...]*
    subtree4 [pattern...]*
    [IGNORE attribute...]*
    [CHECK] [attribute...]*
    ...

## Rule Blocks

Rule blocks are composed of statements that are created by using directives and arguments. There are three types of blocks.

Global block

  The first block in the file. The block is considered “global” if it specifies `CHECK` and `IGNORE` statements, but no previous subtree statement. A global block pertains to all subsequent blocks.

Local block

  A block that specifies `CHECK` and `IGNORE` statements as well as a subtree directive. The rules in this block pertain to files and directories found in the specified subtree.

Heir block

  A block that contains a null `CHECK` statement, no arguments. This block inherits the global `CHECK` statements and global `IGNORE` statements.

Note –

The order in which `CHECK` and `IGNORE` statements appear in blocks is important. The `CHECK` and `IGNORE` statements are processed in the order in which they are read, with later statements overriding earlier statements.

Subtree specifications must appear one per line. Each specification must begin with an absolute path name. Optionally, each specification can be followed by pattern-matching arguments.

When a file being tracked belongs to more than one subtree directive, the resolution is performed by doing the following:

- Applying the `CHECK` and `IGNORE` statements set in a global block. Note that all `CHECK` and `IGNORE` statements are processed in order.

- Finding the last subtree directive that matches the file.

- Processing the `CHECK` and `IGNORE` statements that belong to the last matching subtree directive. These statements are processed in the order in which they are read, overriding global settings.

## Pattern Matching Statements

The syntax for the audit rules file enables you to perform ANDing and ORing operations.

### AND Statement

For a given subtree directive, all pattern matching statements are logically ANDed with the subtree. Patterns have the following syntax:

- Wildcards are permitted for both the subtree and pattern matching statements.

- The exclamation point (`!`) character represents logical NOT.

- A pattern that terminates with a slash is a subtree. The absence of a slash indicates that the pattern is not a directory. The subtree itself does not require an end slash.

For example, the following subtree example includes the contents of `/home/nickiso/src` except for object files, core files, and all of the SCCS subtrees. Note that directory names that terminate with `.o` and directories named `core` are not excluded because the patterns specified do not terminate with `/`.

    /home/nickiso/src !*.o !core !SCCS/
    CHECK	all

### OR Statement

Group multiple subtree directives together. Such subtree directives are logically ORed together.

    /home/nickiso/src !*.o !core
    /home/nickiso/Mail
    /home/nickiso/docs *.sdw
    CHECK	all
    IGNORE	mtime lnmtime dirmtime

The files included in the previous example are as follows:

- Everything under `/home/nickiso/src` except for `*.o` and `core` files

- Everything under `/home/nickiso/Mail`

- All files under `/home/nickiso/docs` that end in `*.sdw`

For these files, all attributes are checked except for modification times.

## File Attributes

The audit rules file uses `CHECK` and `IGNORE` statements to define which attributes to track or ignore. Each attribute has an associated keyword.

The attribute keywords are as follows:

- `acl`

- `all`

- `contents`

- `dest`

- `devnode`

- `dirmtime`

- `gid`

- `lnmtime`

- `mode`

- `mtime`

- `size`

- `type`

- `uid`

- `xattrs`

The `all` keyword refers to all file attributes. See Manifest File Format.

## Rules File Example

    # Global rules, track everything except dirmtime.
    CHECK	all
    IGNORE	dirmtime

    # The files in /data* are expected to change, so don't bother
    # tracking the attributes expected to change.
    # Furthermore, by specifying "IGNORE contents," you save
    # time and resources.
    /data*
    IGNORE	contents mtime size

    /home/nickiso f* bar/
    IGNORE	acl

    # For /usr, apply the global rules.
    /usr
    CHECK

    # Note: Since /usr/tmp follows the /usr block, the /usr/tmp
    # subtree is subjected to the "IGNORE all."
    /usr/tmp
    /home/nickiso *.o
    /home/nickiso core
    /home/nickiso/proto
    IGNORE	all

The following files are cataloged based on the sample rules file:

- All attributes, except for `dirmtime`, `mtime`, `size`, and `contents`, are tracked for files under the `/data*` subtrees.

- Files under the `/usr` subtree, except for `/usr/tmp`, are cataloged by using the global rules.

- If the `/home/nickiso/foo.c` file exists, its attributes, except for `acl` and `dirmtime`, are cataloged.

- All `.o` and `core` files under `/home/nickiso`, as well as the `/home/nickiso/proto` and `/usr/tmp` subtrees, are ignored.

- If the `/home/nickiso/bar/foo.o` file exists, it is ignored because it is subject to the last block.

# Manifest File Format

The software audit generates a manifest that describes the contents of a managed host. A manifest consists of a header and entries. Each entry represents a single file. Entries are sorted in ascending order by file name. Any nonstandard file names, such as those that contain embedded newline or tab characters, have the special characters quoted prior to being sorted. See Quoting Syntax.

Lines that begin with `!` supply metadata about the manifest. The manifest version line indicates the manifest specification version. The date line shows the date on which the manifest was created, in `date` form. See the date(1) man page.

Some lines are ignored by the manifest comparison tool. Ignored lines include blank lines, lines that consist only of white space, and comments that begin with `#`.

In addition to metadata lines, the header contains the format comment block. This comment block lists the attributes reported for each file type.

To see the format of a manifest, see Manifest Output Example.

## Manifest File Entries

Each manifest file entry is a single line of one of the following forms, depending on the file type:

    fname D size mode acl dirmtime uid gid [xattr xcontents]*
    fname P size mode acl mtime uid gid [xattr xcontents]*
    fname S size mode acl mtime uid gid [xattr xcontents]*
    fname F size mode acl mtime uid gid contents [xattr xcontents]*
    fname L size mode acl lnmtime uid gid dest [xattr xcontents]*
    fname B size mode acl mtime uid gid devnode [xattr xcontents]*
    fname C size mode acl mtime uid gid devnode [xattr xcontents]*

Each entry begins with fname, which is the name of the file. To prevent parsing problems that are caused by special characters embedded in file names, file names are encoded as described in Quoting Syntax.

Subsequent fields represent the following file attributes:

type

  Type of file. Possible values are as follows:

  - `B` for a block device node

  - `C` for a character device node

  - `D` for a directory

  - `F` for a file

  - `L` for a symbolic link

  - `P` for a pipe

  - `S` for a socket

size

  File size in bytes.

mode

  Octal number that represents the permissions of the file.

acl

  ACL attributes for the file. For a file with ACL attributes, this field contains the output from `acltotext()`.

uid

  Numerical user ID of the owner of this entry.

gid

  Numerical group ID of the owner of this entry.

dirmtime, lnmtime, mtime

  Last modification time, in seconds since 00:00:00 UTC, January 1, 1970, for directories, links, and other files, respectively.

contents

  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 `-`.

dest

  Destination of a symbolic link.

devnode

  Value of the device node. This attribute is for character device files and block device files only.

[xattr xcontents]*

  Zero or more checksum values for files with extended attributes. The attributes are described in alphabetical order. If the `-n` option or the `IGNORE contents` directive is specified, the value of xcontents is `-`.

## Quoting Syntax

The rules file supports a quoting syntax for representing nonstandard file names.

When generating a manifest for file names that embed tab, space, or newline characters, the special characters are encoded in their octal forms.

The following table shows the quoted form of special characters.

Input Character | Quoted Character
--- | ---
(space) | \(space)
(tab) | \(tab)
(newline) | \(newline)
? | \?
[ | \[
* | \*

## Manifest Output Example

Following is a sample system manifest. The file entries are sorted by the encoded versions of the file names to correctly handle special characters.

    ! Version 1.0
    ! Mon Feb 11 10:55:30 2002
    # Format:
    # fname D size mode acl dirmtime uid gid [xattr xcontents]*
    # fname P size mode acl mtime uid gid [xattr xcontents]*
    # fname S size mode acl mtime uid gid [xattr xcontents]*
    # fname F size mode acl mtime uid gid contents [xattr xcontents]*
    # fname L size mode acl lnmtime uid gid dest [xattr xcontents]*
    # fname B size mode acl mtime uid gid devnode [xattr xcontents]*
    # fname C size mode acl mtime uid gid devnode [xattr xcontents]*
    /etc D 3584 40755 user::rwx,group::r-x,mask::r-x,other::r-x, 3c6803d7 0 3
    /etc/.login F 524 100644 user::rw-,group::r--,mask::r--,other::r--, 3c165878
    	0 3 27b53d5c3e844af3306f1f12b330b318
    /etc/.pwd.lock F 0 100600 user::rw-,group::---,mask::---,other::---,
            3c166121 0 0 d41d8cd98f00b204e9800998ecf8427e
    /etc/.syslog_door L 20 120777 user::rw-,group::r--,mask::rwx,other::r--,
    	3c6803d5 0 0 /var/run/syslog_door
    /etc/autopush L 16 120777 user::r-x,group::r-x,mask::r-x,other::r-x,
            3c165863 0 0 ../sbin/autopush
    /etc/cron.d/FIFO P 0 10600 user::rw-,group::---,mask::---,other::---,
            3c6803d5 0 0

# Comparison Report Format

The Audit command produces output that describes differences between two manifests on a per-file basis.

    filename
    	attribute	control:xxxx test:yyyy

filename

  Name of the file that differs between control-manifest and test-manifest. For file names that contain embedded whitespace or newline characters, see Quoting Syntax.

attribute

  The name of the file attribute that differs between the manifests that are compared. xxxx is the attribute value from control-manifest, and yyyy is the attribute value from test-manifest. When discrepancies for multiple attributes occur for the same file, each difference is noted on a separate line.

The following default output shows the attribute differences for the `/etc/passwd` file. The output indicates that the `size`, `mtime`, and `contents` attributes have changed.

    /etc/passwd:
      size  control:74  test:81
      mtime  control:3c165879  test:3c165979
      contents  control:daca28ae0de97afd7a6b91fde8d57afa
    	test:84b2b32c4165887355317207b48a6ec7

- Previous: Chapter 10 Parameters for Shared Profiles and Host Properties (Reference)
- Next: Appendix A Change Manager Browser Interface Navigation (Reference)

- © 2010, Oracle Corporation and/or its affiliates