Trusted Solaris Audit Administration

Audit Token Structure

Logically, each token has a token type identifier followed by data specific to the token. Each token type has its own format and structure. The audit tokens are shown in the table below. Those marked TS in the TS8 column are in Trusted Solaris 2.5.1 and later versions only. Those not marked TS are modified versions of audit tokens from the Solaris Basic Security Module. The token scheme can be extended.

Table B–1 Trusted Solaris Audit Tokens


Token Name	Description	TS8
acl Token	Access Control List	TS
arbitrary Token	Data with format and type
arg Token	System call argument value
attr Token	File attributes
clearance Token	Clearance	TS
cmd Token	Command execution
exec_args Token	Exec system call arguments
exec_env Token	Exec system call environment variables
exit Token	Program exit
file Token	Audit file delimiter
groups Token (Obsolete)	Process supplementary group (obsolete)
header Token	Start of audit record
host Token	Host where audit record was collected	TS
in_addr Token	Internet address
ip Token	IP header information
ipc Token	System V IPC information
ipc_perm Token	System V IPC object tokens
iport Token	Internet port address
liaison Token	Liaison information for Trusted Networking	TS
newgroups Token	Process supplementary group information
opaque Token	Unstructured data (unspecified format)
path Token	Path (path)
upriv Token	Use of privilege	TS
privilege Token	Privilege set	TS
process Token	Process information
return Token	Status of system call
return Token	Sequence number
slabel Token	Sensitivity label	TS
socket Token	Socket type and addresses
subject Token	Subject
text Token	Character string
trailer Token	End of audit record
uauth Token	Use of authorization
xatom Token	X window atom identification	TS
xclient Token	X client identification	TS
xcolormap Token	X window color information	TS
xcursor Token	X window cursor information	TS
xfont Token	X window font information	TS
xgc Token	X window graphical context information	TS
xpixmap Token	Xwindow pixel mapping information	TS
xproperty Token	X window property information	TS
xselect Token	X window data information	TS
xwindow Token	X window window information	TS

An audit record always contains a header token and may contain a trailer token. The header token indicates where the audit record begins in the audit trail. The optional trailer token allows backward seeks of the audit trail. Every audit record contains a subject token, except for audit records from some non-attributable events. In the case of attributable events, these two tokens refer to the values of the process that caused the event. In the case of asynchronous events, the process tokens refer to the system. For an example of how to read an audit record, go to Reading an Audit Record.

acl Token

The acl token records information about ACLs. It consists of four fixed fields: a token ID that identifies this token as an acl token, a field that specifies the ACL type, an ACL ID field, and a field that lists the permissions associated with this ACL. The acl token appears as follows:

The following figure shows the token format.

Figure B–2 acl Token Format

A list of acl tokens is displayed by praudit(1M) as follows:

acl,user_obj,,rwx
acl,user,bin,---
acl,group_obj,,r-x
acl,class_obj,,r--
acl,other_obj,,r-x

arbitrary Token

The arbitrary token encapsulates data for the audit trail. It consists of four fixed fields and an array of data. The item array may have a number of items. The fields are:

A token ID
A suggested format, such as decimal
A size of encapsulated data, such as int
A count of the data array items
An item array

The following figure shows the token format.

Figure B–3 arbitrary Token Format

The print format field can take the values shown in Table B–2.

Table B–2 arbitrary Token Print Format Field Values


Value	Action
`AUP_BINARY`	Print date in binary
`AUP_OCTAL`	Print date in octal
`AUP_DECIMAL`	Print date in decimal
`AUP_HEX`	Print date in hex
`AUP_STRING`	Print date as a string

The item size field can take the values shown in Table B–3.

Table B–3 arbitrary Token Item Size Field Values


Value	Action
`AUR_BYTE`	Data is in units of bytes (1 byte)
`AUR_SHORT`	Data is in units of shorts (2 bytes)
`AUR_LONG`	Data is in units of longs (4 bytes)
`AUR_LONGLONG`	Data is in units of longlongs (8 bytes)

An arbitrary token is displayed by praudit as follows:

arbitrary,decimal,int,1
42

arg Token

The arg token contains system call argument information. A 32-bit integer system call argument is allowed in an audit record. The fields are:

A token ID
An argument ID of the relevant system call argument
The argument value
The length of an optional descriptive text string (does not show)
An optional text string

The following figure shows the token format.

Figure B–4 arg Token Format

An arg token is displayed by praudit as follows:

argument,2,0x3,cmd

attr Token

The attribute token contains file attribute information from the kernel's internal representation of a file or folder. This token usually accompanies a path token and is produced during path searches. In the event of a path-search error, this token is not included as part of the audit record since the file attribute information is not available. The fields are:

A token ID
The file access mode and type
The owner user ID
The owner group ID
The file system ID
The inode ID
The device ID that the file might represent

See the statvfs(2) man page for further information about the file system ID and the device ID. The following figure shows the token format.

Figure B–5 attr Token Format

An attr token is displayed by praudit as follows:

attribute,100555,root,root,1805,13871,-4288

clearance Token

The clearance token contains Trusted Solaris clearance information. The fields are:

A token ID
The CMW clearance, containing
- A pad ID identifying the label type
- The clearance's classifications
- The clearance's compartments

The following figure shows the token format.

Figure B–6 clearance Token Format

A clearance token is displayed by praudit as follows:

clearance,TOP SECRET

cmd Token

The cmd token records the arguments and environment in which a command executes. The fields are:

A token ID
The number of arguments to the command
The argument values
The number of environment variables
Zero or more names of the variables

A cmd token is displayed by praudit as follows:

cmd,2,/export/share/tsol8,label_encodings

exec_args Token

The exec_args token records the arguments to an exec() system call. The fields are:

A token ID
A count that represents the number of arguments passed to the exec call
Zero or more null-terminated strings, the arguments of the exec call

The following figure shows an exec_args token.

Figure B–7 exec_args Token Format

Note –

The exec_args token is output only when the audit policy argv is active. See Dynamic Auditing (Tasks) for more information.

An exec_args token is displayed by praudit as follows:

exec_args,

exec_env Token

The exec_env token records the current environment variables to an exec() system call. The fields are:

A token ID
A count of the current environment variables in the exec call
Zero or more null-terminated strings, the variables of the exec call

The following figure shows an exec_env token.

Figure B–8 exec_env Token Format

Note –

The exec_env token is output only when the audit policy arge is active. See Dynamic Auditing (Tasks) for more information.

An exec_env token is displayed by praudit as follows:

exec_env,

exit Token

The exit token records the exit status of a program and a return value. The fields are:

A token ID
A program exit status as passed to the exit() system call
A return value that describes the exit status or indicates a system error number

The following figure shows an exit token.

Figure B–9 exit Token Format

An exit token is displayed by praudit as follows:

exit,Error 0,0

file Token

The file token is a special token generated by the audit daemon to mark the beginning of a new audit trail file and the end of an old file as it is deactivated. The audit daemon builds a special audit record containing this token to link together successive audit files into one audit trail. The fields are:

A token ID
A time and date stamp that identifies the time the file was created or closed
A byte count of the file name including a null terminator (does not show)
The file null-terminated name

The following figure shows the token format.

Figure B–10 file Token Format

A file token is displayed by praudit as follows:

file,Fri Jan 23 13:32:42 1997, + 792 msec,
/etc/security/audit/patchwork/files/19920901202558.19920901203241.patchwork

groups Token (Obsolete)

This token has been replaced by the newgroups token, which provides the same type of information but requires less space. A description of the groups token is provided here for completeness, but the application designer should use the newgroups token. Note that praudit does not distinguish between the two tokens as both token IDs are labelled groups when character output is displayed.

The groups token records the groups entries from the process's credential. The fields are:

A token ID
An array of groups entries of size NGROUPS_MAX (16)

The following figure shows a groups token.

Figure B–11 groups Token Format

A groups token is displayed by praudit as follows:

group,staff,wheel,daemon,kmem,bin,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1

Note –

The groups token is output only when the audit policy group is active.

header Token

The header token is special in that it marks the beginning of an audit record and combines with the trailer token to bracket all the other tokens in the record. The fields are:

A token ID
The record length in bytes, including the header and trailer tokens
An audit record structure version number
An event ID identifying the type of audit event from the /etc/security/audit_event file:
- The praudit -l command displays the event description, for example, system booted.
- The praudit -r command displays the event number, for example, 113.
- The praudit -s command displays the event ID, for example, AUE_SYSTEMBOOT.
An event ID modifier with descriptive information about the event type
For extended headers, an IP address type
For extended headers, the IP address of the source machine in IPv6 or IPv4 format
The time and date the record was created

The following figure shows a header token.

Figure B–12 header Token Format

The event modifier field has the following flags defined:

Value	Constant Name	Description
0x0001	PAD_READ	Data read from object
0x0002	PAD_WRITE	Data written to object
0x0080	PAD_SPRIVUSE	Successfully used privilege
0x0100	PAD_FPRIVUSE	Failed use of privilege
0x4000	PAD_NONATTR	Nonattributable event
0x8000	PAD_FAILURE	Failed audit event

For the Trusted Solaris 7 and Trusted Solaris 8 4/01 releases, the header token can be displayed with a 64-bit time stamp, in place of the 32-bit time stamp.

For the Trusted Solaris 8 4/01 release, the Internet Address can be displayed as a IPv4 address using 4 bytes, or as an IPv6 address using 16 bytes to describe the type, and 16 bytes to describe the address.

A header token is displayed by praudit as follows:

header,240,1,ioctl(2),,Tue Sept  7 16:11:44 2000, + 270 msec

host Token

The host token contains the machine ID for the system which generated this audit record. The fields are:

A token ID
The system ID of the host that generated the audit record

The following figure shows the token format.

Figure B–13 host Token Format

A host token is displayed by praudit as follows:

host,patchwork

in_addr Token

The in_addr token contains an Internet address. This 4-byte value is an Internet Protocol address. The fields are:

A token ID
An Internet address

The following figure shows the token format.

Figure B–14 in_addr Token Format

An in_addr token is displayed by praudit as follows:

ip address,192.168.110.3

ip Token

The ip token contains a copy of an Internet Protocol header but does not include any IP options. The IP options may be added by including more of the IP header in the token. The IP header structure is defined in /usr/include/netinet/ip.h. The fields are:

A token ID
A 20-byte copy of an IP header (all 20 bytes)

The following figure shows the token format.

Figure B–15 ip Token Format

An ip token is displayed by praudit as follows:

ip,0.0.0.0

ipc Token

The ipc token contains the System V IPC message/semaphore/shared-memory handle used by the caller to identify a particular IPC object. The fields are:

A token ID
An IPC object type identifier
The IPC object handle

The following figure shows the token format.

Figure B–16 ipc Token Format

An ipc token is displayed by praudit as follows:

IPC,msg,3

Note –

The IPC object identifiers violate the context-free nature of the Solaris CMW audit tokens. No global “name” uniquely identifies IPC objects; instead, they are identified by their handles, which are valid only during the time the IPC objects are active. The identification should not be a problem since the System V IPC mechanisms are seldom used and they all share the same audit class.

The IPC object type field may have the values shown in Table B–4. The values are defined in </usr/include/bsm/audit.h>.

Table B–4 IPC Object Type Field


Name	Value	Description
`AU_IPC_MSG`	1	IPC message object
`AU_IPC_SEM`	2	IPC semaphore object
`AU_IPC_SHM`	3	IPC shared memory object

ipc_perm Token

The ipc_perm token contains a copy of the System V IPC access information. Audit records for shared memory, semaphore, and message IPCs have this token added. The fields are:

A token ID
The IPC owner's user ID
The IPC owner's group ID
The IPC creator's user ID
The IPC creator's group ID
The IPC access modes
The IPC sequence number
The IPC key value

The values are taken from the ipc_perm structure associated with the IPC object. The following figure shows the token format.

Figure B–17 ipc_perm Token Format

An ipc_perm token is displayed by praudit as follows:

IPC_perm,root,wheel,root,wheel,0,0,0x00000000

iport Token

The iport token contains the TCP (or UDP) port address. The fields are:

A token ID
A TCP/UDP address

The following figure shows the token format.

Figure B–18 iport Token Format

An iport token is displayed by praudit as follows:

iport,0xf6d6

liaison Token

The liaison token contains a liaison ID used by the Trusted Networking software. The fields are:

A token ID
The liaison ID

The following figure shows the token format.

Figure B–19 liaison Token Format

A liaison token is displayed by praudit as follows:

liaison,17

newgroups Token

This token is the replacement for the groups token. Note that praudit does not distinguish between the two tokens as both token IDs are labelled groups when character output is displayed.

The newgroups token records the groups entries from the process's credential. The fields are:

A token ID field
A count of the number of groups contained in this audit record.
Zero or more group entries.

The following figure shows the token format.

Figure B–20 newgroups Token Format

Note –

The newgroups token is output only when the audit policy group is active.

A newgroups token is displayed by praudit as follows:

newgroups,1,analysts

opaque Token

The opaque token contains unformatted data as a sequence of bytes. The fields are:

A token ID
A byte count of the data array
An array of byte data

The following figure shows the token format.

Figure B–21 opaque Token Format

An opaque token is displayed by praudit as follows:

opaque,12,0x4f5041515545204441544100

path Token

The path token contains access path information for an object. The fields are:

A token ID
A byte count of the path length (does not show)
An absolute path to the object based on the real root of the system

The following figure shows the token format.

Figure B–22 path Token Format

A path token is displayed by praudit as follows:

path,/etc/security/audit/patchwork

privilege Token

The privilege token contains privilege information for an object or a subject. The fields are:

A token ID
The type of privilege
The privilege set

where type is one of the following:

Value	Type
0	Unknown or Undefined
1	Forced
2	Allowed
3	Effective
4	Inheritable
5	Permitted
6	Saved

The following figure shows the token format.

Figure B–23 privilege Token Format

A privilege token is displayed by praudit as follows:

privilege,Forced,proc_tcb_audit

process Token

The process token contains information describing a process as an object such as the recipient of a signal. The fields are:

A token ID
The user audit ID
The effective user ID
The effective group ID
The real user ID
The real group ID
The process ID
The audit session ID
A terminal ID made up of
- A device ID
- A system ID

The audit ID, user ID, group ID, process ID, and session ID are long instead of short.

Note –

The process token fields for the session ID, the real user ID, or the real group ID might be unavailable. The entry is then set to -1.

For the Trusted Solaris 7 release, the process token can be displayed using a 64-bit device ID, in place of the 32-bit value.

For the Trusted Solaris 8 4/01 release, the terminal ID can report an IPv6 address by changing the format to use either 4 or 8 bytes to describe the device, 16 bytes to describe the type, and 16 bytes to describe the address.

The following figure shows the token format.

Figure B–24 Format for process and subject Tokens

subject

A process token is displayed by praudit as follows:

process,root,root,wheel,root,wheel,0,0,0,0.0.0.0

return Token

The return token contains the return status of the system call (u_error) and the process return value (u_rval1). The token indicates exit status and other return values in application auditing. This token is always returned as part of kernel-generated audit records for system calls. The fields are:

A token ID
The system call error status
The system call return value

The following figure shows the token format.

Figure B–25 return Token Format

A return token is displayed by praudit as follows:

return,failure: No such file or directory,-1

seq Token

The seq token (sequence token) is an optional token that contains an increasing sequence number. This token is for debugging. The token is added to each audit record when the AUDIT_SEQ policy is active. The fields are:

A token ID
A 32-bit unsigned long-sequence number

The sequence number is incremented every time an audit record is generated and put onto the audit trail. The following figure shows the token format.

Figure B–26 seq Token Format

A seq token is displayed by praudit as follows:

sequence,1292

slabel Token

The slabel token contains a sensitivity label. The fields are:

A token ID
A sensitivity label

The following figure shows the token format.

Figure B–27 slabel Token Format

An slabel token is displayed by praudit as follows:

slabel,ADMIN_LOW

socket Token

The socket token contains information describing an Internet socket. The fields are:

A token ID
A socket type field (TCP/UDP/UNIX)
The local port address
The local Internet address
The remote port address
The remote Internet address

The socket type is taken from the designated socket and the port and Internet addresses are taken from the socket's inpcb control structure. The following figure shows the token format.

Figure B–28 socket Token Format

A socket token is displayed by praudit as follows:

socket,0x0000,0x0000,0.0.0.0,0x0000,0.0.0.0

socket,0x0002,0x8008,patchwork

subject Token

The subject token describes a subject (process). The structure is the same as the process token:

A token ID
The user audit ID
The effective user ID
The effective group ID
The real user ID
The real group ID
The process ID
The session ID
A terminal ID made up of
- A device ID
- A system ID

This token is always returned as part of kernel-generated audit records for system calls. The audit ID, user ID, group ID, process ID, and session ID are long instead of short. Figure B–24 shows the token format.

Note –

The subject token fields for the session ID, the real user ID, or the real group ID may be unavailable. The entry is then set to -1.

For the Trusted Solaris 7 release, the process token can be displayed using a 64-bit device ID, in place of the 32-bit value.

A subject token is displayed by praudit as follows:

subject,root,root,staff,root,staff,552,552,24 3 patchwork

text Token

The text token contains a text string. The fields are:

A token ID
The length of the text string (does not show)
A text string

The following figure shows the token format.

Figure B–29 text Token Format

A text token is displayed by praudit in 7–bit ASCII with control characters in the form ^L, as follows:

text,Enter your name on the next line^JName:

trailer Token

A trailer token it marks the end of an audit record to support backward seeks of the audit trail. It is an optional token that is added as the last token of each record only when the AUDIT_TRAIL audit policy has been set. The fields are:

A token ID
A pad number that marks the end of the record (does not show)
The total number of audit record characters including the header and trailer tokens

The following figure shows the token format.

Figure B–30 trailer Token Format

A trailer token is displayed by praudit as follows:

trailer,136

uauth Token

The uauth token contains a text string. The fields are:

A token ID
The length of the text string (does not show)
A text string

The following figure shows the token format.

Figure B–31 uauth Token Format

A uauth token is displayed by praudit as follows:

uauth,solaris.device.allocate

upriv Token

The upriv token contains use of privilege information. The fields are:

A token ID
A success/failure field indicating whether the use of privilege was successful (1 success, 0 failure)
The privilege being tested

The following figure shows a priv token.

Figure B–32 upriv Token Format

A upriv token is displayed by praudit as follows:

use of privilege,failed use of priv,win_mac_write

xatom Token

The xatom token contains information concerning an X atom. The fields are:

A token ID
The string length
A text string identifying the atom

The following figure shows the token format.

Figure B–33 xatom Token Format

An xatom token is displayed by praudit as follows:

X atom,_DT_SAVE_MODE

xclient Token

The xclient token contains information concerning the X client. The fields are:

A token ID
The client ID

The following figure shows the token format.

Figure B–34 xclient Token Format

An xclient token is displayed by praudit as follows:

X client,15

xcolormap Token

The xcolormap token contains information about the colormaps. The fields are:

A token ID
The X server identifier
The creator's user ID

The following figure shows the token format.

Figure B–35 Format for xcolormap, xcursor, xfont, xgc, xpixmap, and xwindow Tokens

An xcolormap token is displayed by praudit as follows:

X color map,0x08c00005,srv

xcursor Token

The xcursor token contains information about the cursors. The fields are:

A token ID
The X server identifier
The creator's user ID

Figure B–35 shows the token format.

An xcursor token is displayed by praudit as follows:

X cursor,0x0f400006,srv

xfont Token

The xfont token contains information about the fonts. The fields are:

A token ID
The X server identifier
The creator's user ID

Figure B–35 shows the token format.

An xfont token is displayed by praudit as follows:

X font,0x08c00001,srv

xgc Token

The xgc token contains information about the xgc. The fields are:

A token ID
The X server identifier
The creator's user ID

Figure B–35 shows the token format.

An xgc token is displayed by praudit as follows:

Xgraphic context,0x002f2ca0,srv

xpixmap Token

The xpixmap token contains information about the pixel mappings. The fields are:

A token ID
The X server identifier
The creator's user ID

Figure B–35 shows the token format.

An xpixmap token is displayed by praudit as follows:

X pixmap,0x08c00005,srv

xproperty Token

The xproperty token contains information about various properties of a window. The fields are:

A token ID
The X server identifier
The creator's user ID
A string length
A string (atom name)

The following figure shows an xproperty token format.

Figure B–36 xproperty Token Format

An xproperty token is displayed by praudit as follows:

X property,0x000075d5,root,_MOTIF_DEFAULT_BINDINGS

xselect Token

The xselect token contains the data moved between windows. This data is a byte stream with no assumed internal structure, and a property string. The fields are:

A token ID
The length of the property string
The property string
A length for the property type
The property type string
A length field that gives the number of bytes of data
A byte string containing the data

The following figure shows the token format.

Figure B–37 xselect Token Format

An xselect token is displayed by praudit as follows:

X selection,

xwindow Token

The xwindow token contains information about a window. The fields are:

A token ID
The X server identifier
The creator's user ID

Figure B–35 shows the token format.

An xwindow token is displayed by praudit as follows:

X window,0x07400001,gww