Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AUDIT.LOG(5)		    BSD	File Formats Manual		  AUDIT.LOG(5)

NAME
     audit -- Basic Security Module (BSM) file format

DESCRIPTION
     The audit file format is based on Sun's Basic Security Module (BSM) file
     format, a token-based record stream to represent system audit data.  This
     file format is both flexible and extensible, able to describe a broad
     range of data types, and easily extended to describe new data types in a
     moderately	backward and forward compatible	way.

     BSM token streams typically begin and end with a "file" token, which pro-
     vides time	stamp and file name information	for the	stream;	when process-
     ing a BSM token stream from a stream as opposed to	a single file source,
     file tokens may be	seen at	any point between ordinary records identifying
     when particular parts of the stream begin and end.	 All other tokens will
     appear in the context of a	complete BSM audit record, which begins	with a
     "header" token, and ends with a "trailer" token, which describe the audit
     record.  Between these two	tokens will appear a variety of	data tokens,
     such as process information, file path names, IPC object information, MAC
     labels, socket information, and so	on.

     The BSM file format defines specific token	orders for each	record event
     type; however, some variation may occur depending on the operating	system
     in	use, what system options, such as mandatory access control, are
     present.

     This manual page documents	the common token types and their binary	for-
     mat, and is intended for reference	purposes only.	It is recommended that
     application programmers use the libbsm(3) interface to read and write to-
     kens, rather than parsing or constructing records by hand.

   File	Token
     The "file"	token is used at the beginning and end of an audit log file to
     indicate when the audit log begins	and ends.  It includes a pathname so
     that, if concatenated together, original file boundaries are still	ob-
     servable, and gaps	in the audit log can be	identified.  A "file" token
     can be created using au_to_file(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Seconds				4 bytes		   File	time stamp
	Microseconds			4 bytes		   File	time stamp
	File name length		2 bytes		   File	name of	audit
							   trail
	File pathname			N bytes	+ 1 NUL	   File	name of	audit
							   trail

   Header Token
     The "header" token	is used	to mark	the beginning of a complete audit
     record, and includes the length of	the total record in bytes, a version
     number for	the record layout, the event type and subtype, and the time at
     which the event occurred.	A 32-bit "header" token	can be created using
     au_to_header32(3);	a 64-bit "header" token	can be created using
     au_to_header64(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Record Byte Count		4 bytes		   Number of bytes in
							   record
	Version	Number			2 bytes		   Record version
							   number
	Event Type			2 bytes		   Event type
	Event Modifier			2 bytes		   Event sub-type
	Seconds				4/8 bytes	   Record time stamp
							   (32/64-bits)
	Nanoseconds			4/8 bytes	   Record time stamp
							   (32/64-bits)

   Expanded Header Token
     The "expanded header" token is an expanded	version	of the "header"	token,
     with the addition of a machine IPv4 or IPv6 address.  A 32-bit extended
     "header" token can	be created using au_to_header32_ex(3); a 64-bit	ex-
     tended "header" token can be created using	au_to_header64_ex(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Record Byte Count		4 bytes		   Number of bytes in
							   record
	Version	Number			2 bytes		   Record version
							   number
	Event Type			2 bytes		   Event type
	Event Modifier			2 bytes		   Event sub-type
	Address	Type/Length		1 byte		   Host	address	type
							   and length
	Machine	Address			4/16 bytes	   IPv4	or IPv6
							   address
	Seconds				4/8 bytes	   Record time stamp
							   (32/64-bits)
	Nanoseconds			4/8 bytes	   Record time stamp
							   (32/64-bits)

   Trailer Token
     The "trailer" terminates a	BSM audit record, and contains a magic number,
     AUT_TRAILER_MAGIC and length that can be used to validate that the	record
     was read properly.	 A "trailer" token can be created using
     au_to_trailer(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Trailer	Magic			2 bytes		   Trailer magic
							   number
	Record Byte Count		4 bytes		   Number of bytes in
							   record

   Arbitrary Data Token
     The "arbitrary data" token	contains a byte	stream of opaque (untyped)
     data.  The	size of	the data is calculated as the size of each unit	of
     data multiplied by	the number of units of data.  A	"How to	print" field
     is	present	to specify how to print	the data, but interpretation of	that
     field is not currently defined.  An "arbitrary data" token	can be created
     using au_to_data(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	How to Print			1 byte		   User-defined
							   printing
							   information
	Basic Unit			1 byte		   Size	of a unit in
							   bytes
	Unit Count			1 byte		   Number of units of
							   data	present
	Data Items			Variable	   User	data

   in_addr Token
     The "in_addr" token holds a network byte order IPv4 address.  An
     "in_addr" token can be created using au_to_in_addr(3) for an IPv4 ad-
     dress.

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	IP Address			4 bytes		   IPv4	address

   Expanded in_addr Token
     The "in_addr_ex" token holds a network byte order IPv4 or IPv6 address.
     An	"in_addr_ex" token can be created using	au_to_in_addr_ex(3) for	an
     IPv6 address.

     See the BUGS section for information on the storage of this token.

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	IP Address Type			1 byte		   Type	of address
	IP Address			4/16 bytes	   IPv4	or IPv6
							   address

   ip Token
     The "ip" token contains an	IP packet header in network byte order.	 An
     "ip" token	can be created using au_to_ip(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Version	and IHL			1 byte		   Version and IP
							   header length
	Type of	Service			1 byte		   IP TOS field
	Length				2 bytes		   IP packet length in
							   network byte	order
	ID				2 bytes		   IP header ID	for
							   reassembly
	Offset				2 bytes		   IP fragment offset
							   and flags, network
							   byte	order
	TTL				1 byte		   IP Time-to-Live
	Protocol			1 byte		   IP protocol number
	Checksum			2 bytes		   IP header checksum,
							   network byte	order
	Source Address			4 bytes		   IPv4	source address
	Destination Address		4 bytes		   IPv4	destination
							   address

   iport Token
     The "iport" token stores an IP port number	in network byte	order.	An
     "iport" token can be created using	au_to_iport(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Port Number			2 bytes		   Port	number in
							   network byte	order

   Path	Token
     The "path"	token contains a pathname.  A "path" token can be created us-
     ing au_to_path(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Path Length			2 bytes		   Length of path in
							   bytes
	Path				N bytes	+ 1 NUL	   Path	name

   path_attr Token
     The "path_attr" token contains a set of NUL-terminated path names.	 The
     libbsm(3) API cannot currently create a "path_attr" token.

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Count				2 bytes		   Number of NUL-
							   terminated
							   string(s) in	token
	Path				Variable	   count NUL-
							   terminated
							   string(s)

   Process Token
     The "process" token contains a description	of the security	properties of
     a process involved	as the target of an auditable event, such as the des-
     tination for signal delivery.  It should not be confused with the
     "subject" token, which describes the subject performing an	auditable
     event.  This includes both	the traditional	UNIX security properties, such
     as	user IDs and group IDs,	but also audit information such	as the audit
     user ID and session.  A "process" token can be created using
     au_to_process32(3)	or au_to_process64(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Audit ID			4 bytes		   Audit user ID
	Effective User ID		4 bytes		   Effective user ID
	Effective Group	ID		4 bytes		   Effective group ID
	Real User ID			4 bytes		   Real	user ID
	Real Group ID			4 bytes		   Real	group ID
	Process	ID			4 bytes		   Process ID
	Session	ID			4 bytes		   Audit session ID
	Terminal Port ID		4/8 bytes	   Terminal port ID
							   (32/64-bits)
	Terminal Machine Address	4 bytes		   IP address of
							   machine

   Expanded Process Token
     The "expanded process" token contains the contents	of the "process" to-
     ken, with the addition of a machine address type and variable length ad-
     dress storage capable of containing IPv6 addresses.  An "expanded
     process" token can	be created using au_to_process32_ex(3) or
     au_to_process64_ex(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Audit ID			4 bytes		   Audit user ID
	Effective User ID		4 bytes		   Effective user ID
	Effective Group	ID		4 bytes		   Effective group ID
	Real User ID			4 bytes		   Real	user ID
	Real Group ID			4 bytes		   Real	group ID
	Process	ID			4 bytes		   Process ID
	Session	ID			4 bytes		   Audit session ID
	Terminal Port ID		4/8 bytes	   Terminal port ID
							   (32/64-bits)
	Terminal Address Type/Length	1 byte		   Length of machine
							   address
	Terminal Machine Address	4 bytes		   IPv4	or IPv6
							   address of machine

   Return Token
     The "return" token	contains a system call or library function return con-
     dition, including return value and	error number associated	with the
     global variable errno.  A "return"	token can be created using
     au_to_return32(3) or au_to_return64(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Error Number			1 byte		   Errno value,	or 0
							   if undefined
	Return Value			4/8 bytes	   Return value
							   (32/64-bits)

   Subject Token
     The "subject" token contains information on the subject performing	the
     operation described by an audit record, and includes similar information
     to	that found in the "process" and	"expanded process" tokens.  However,
     those tokens are used where the process being described is	the target of
     the operation, not	the authorizing	party.	A "subject" token can be cre-
     ated using	au_to_subject32(3) and au_to_subject64(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Audit ID			4 bytes		   Audit user ID
	Effective User ID		4 bytes		   Effective user ID
	Effective Group	ID		4 bytes		   Effective group ID
	Real User ID			4 bytes		   Real	user ID
	Real Group ID			4 bytes		   Real	group ID
	Process	ID			4 bytes		   Process ID
	Session	ID			4 bytes		   Audit session ID
	Terminal Port ID		4/8 bytes	   Terminal port ID
							   (32/64-bits)
	Terminal Machine Address	4 bytes		   IP address of
							   machine

   Expanded Subject Token
     The "expanded subject" token consists of the same elements	as the
     "subject" token, with the addition	of type/length and variable size ma-
     chine address information in the terminal ID.  An "expanded subject" to-
     ken can be	created	using au_to_subject32_ex(3) or au_to_subject64_ex(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Audit ID			4 bytes		   Audit user ID
	Effective User ID		4 bytes		   Effective user ID
	Effective Group	ID		4 bytes		   Effective group ID
	Real User ID			4 bytes		   Real	user ID
	Real Group ID			4 bytes		   Real	group ID
	Process	ID			4 bytes		   Process ID
	Session	ID			4 bytes		   Audit session ID
	Terminal Port ID		4/8 bytes	   Terminal port ID
							   (32/64-bits)
	Terminal Address Type/Length	1 byte		   Length of machine
							   address
	Terminal Machine Address	4 bytes		   IPv4	or IPv6
							   address of machine

   System V IPC	Token
     The "System V IPC"	token contains the System V IPC	message	handle,	sema-
     phore handle or shared memory handle.  A System V IPC token may be	cre-
     ated using	+.Xr au_to_ipc 3 .

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Object ID type			1 byte		   Object ID
	Object ID			4 bytes		   Object ID

   Text	Token
     The "text"	token contains a single	NUL-terminated text string.  A "text"
     token may be created using	au_to_text(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Text Length			2 bytes		   Length of text
							   string including
							   NUL
	Text				N bytes	+ 1 NUL	   Text	string
							   including NUL

   Attribute Token
     The "attribute" token describes the attributes of a file associated with
     the audit event.  As files	may be identified by 0,	1, or many path	names,
     a path name is not	included with the attribute block for a	file; optional
     "path" tokens may also be present in an audit record indicating which
     path, if any, was used to reach the object.  An "attribute" token can be
     created using au_to_attr32(3) or au_to_attr64(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	File Access Mode		1 byte		   mode_t associated
							   with	file
	Owner User ID			4 bytes		   uid_t associated
							   with	file
	Owner Group ID			4 bytes		   gid_t associated
							   with	file
	File System ID			4 bytes		   fsid_t associated
							   with	file
	File System Node ID		8 bytes		   ino_t associated
							   with	file
	Device				4/8 bytes	   Device major/minor
							   number (32/64-bit)

   Groups Token
     The "groups" token	contains a list	of group IDs associated	with the audit
     event.  A "groups"	token can be created using au_to_groups(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Number of Groups		2 bytes		   Number of groups in
							   token
	Group List			N * 4 bytes	   List	of N group IDs

   System V IPC	Permission Token
     The "System V IPC permission" token contains a System V IPC access	per-
     missions.	A System V IPC permission token	may be created using
     au_to_ipc_perm(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Owner user ID			4 bytes		   User	ID of IPC
							   owner
	Owner group ID			4 bytes		   Group ID of IPC
							   owner
	Creator	user ID			4 bytes		   User	ID of IPC
							   creator
	Creator	group ID		4 bytes		   Group ID of IPC
							   creator
	Access mode			4 bytes		   Access mode
	Sequence number			4 bytes		   Sequence number
	Key				4 bytes		   IPC key

   Arg Token
     The "arg" token contains information about	arguments of the system	call.
     Depending on the size of the desired argument value, an Arg token may be
     created using au_to_arg32(3) or au_to_arg64(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Argument ID			1 byte		   Argument ID
	Argument value			4/8 bytes	   Argument value
	Length				2 bytes		   Length of the text
	Text				N bytes	+ 1 nul	   The string
							   including nul

   exec_args Token
     The "exec_args" token contains information	about arguments	of the exec()
     system call.  An exec_args	token may be created using au_to_exec_args(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Count				4 bytes		   Number of arguments
	Text				* bytes		   Count nul-
							   terminated strings

   exec_env Token
     The "exec_env" token contains current environment variables to an exec()
     system call.  An exec_args	token may be created using au_to_exec_env(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Count ID			4 bytes		   Number of variables
	Text				* bytes		   Count nul-
							   terminated strings

   Exit	Token
     The "exit"	token contains process exit/return code	information.  An
     "exit" token can be created using au_to_exit(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Status				4 bytes		   Process status on
							   exit
	Return Value			4 bytes		   Process return
							   value on exit

   Socket Token
     The "socket" token	contains information about UNIX	domain and Internet
     sockets.  Each token has four or eight fields.  Depending on the type of
     socket, a socket token may	be created using au_to_sock_unix(3),
     au_to_sock_inet32(3) or au_to_sock_inet128(3).

	Field		       Bytes		Description
	Token ID	       1 byte		Token ID
	Socket family	       2 bytes		Socket family
	Local port	       2 bytes		Local port
	Socket address	       4 bytes		Socket address

   Expanded Socket Token
     The "expanded socket" token contains information about IPv4 and IPv6
     sockets.  A "expanded socket" token can be	created	using
     au_to_socket_ex(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Socket domain			2 bytes		   Socket domain
	Socket type			2 bytes		   Socket type
	Address	type			2 byte		   Address type
							   (IPv4/IPv6)
	Local port			2 bytes		   Local port
	Local IP address		4/16 bytes	   Local IP address
	Remote port			2 bytes		   Remote port
	Remote IP address		4/16 bytes	   Remote IP address

   Seq Token
     The "seq" token contains a	unique and monotonically increasing audit
     event sequence ID.	 Due to	the limited range of 32	bits, serial number
     arithmetic	and caution should be used when	comparing sequence numbers.

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Sequence Number			4 bytes		   Audit event
							   sequence number

   privilege Token
     The "privilege" token ...

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID

   Use-of-auth Token
     The "use-of-auth" token ...

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID

   Command Token
     The "command" token ...

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID

   ACL Token
     The "ACL" token ...

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID

   Zonename Token
     The "zonename" token holds	a NUL-terminated string	with the name of the
     zone or jail from which the record	originated.  A "zonename" token	can be
     created using au_to_zonename(3).

	Field				Bytes		   Description
	Token ID			1 byte		   Token ID
	Zonename length			2 bytes		   Length of zonename
							   string including
							   NUL
	Zonename			N bytes	+ 1 NUL	   Zonename string
							   including NUL

SEE ALSO
     auditreduce(1), praudit(1), libbsm(3), audit(4), auditpipe(4), audit(8)

HISTORY
     The OpenBSM implementation	was created by McAfee Research,	the security
     division of McAfee	Inc., under contract to	Apple Computer Inc. in 2004.
     It	was subsequently adopted by the	TrustedBSD Project as the foundation
     for the OpenBSM distribution.

AUTHORS
     The Basic Security	Module (BSM) interface to audit	records	and audit
     event stream format were defined by Sun Microsystems.

     This manual page was written by Robert Watson <rwatson@FreeBSD.org>.

BUGS
     The "How to print"	field in the "arbitrary	data" token has	undefined val-
     ues.

     The "in_addr" and "in_addr_ex" token layout documented here appears to be
     in	conflict with the libbsm(3) implementation of au_to_in_addr_ex(3).

BSD			       November	5, 2006				   BSD

NAME | DESCRIPTION | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=audit.log&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help