Audit provenance

Data Model

The Audit reporter transforms records into an Open Provenance Model (OPM) representation.

The table below outlines the key-value annotations that decorate the OPM elements generated.

OPM element	Annotation Key	Annotation Value's semantics	Annotation Value's type	Presence
Agent*
	uid	operating system identifier of user that ran the program	unsigned integer	required
	euid	operating system identifier of effective user of program	unsigned integer	required
	gid	operating system identifier of user's group when they ran the program	unsigned integer	required
	egid	operating system identifier of effective group of program	unsigned integer	required
	suid	saved identifier when program's effective user has changed	unsigned integer	optional
	sgid	saved identifier when program's effective group has changed	unsigned integer	optional
	fsuid	program's user identifier for filesystem access checks	unsigned integer	optional
	fsgid	program's group identifier for filesystem access checks	unsigned integer	optional
	source	can be one of: /dev/audit - if information came from the Linux kernel's Audit subsystem /proc - if information was extracted from Linux's /proc pseudofilesystem	string (as enumerated)	required
Process
	name	command used to invoke program	string	optional
	pid	operating system process identifier	integer	required
	ppid	parent's process identifier	integer	required
	cwd	only for process from operation execve, current working directory of user (in the shell when they ran the program)	string	optional
	command line	only for process from operation execve, program name and arguments provided	string	optional
	start time	if known, when the process started (in Unix time). If BEEP unit then refers to the start time of the unit	floating point	optional
	unit	only if BEEP used, unique identifier of unit (with 0 denoting the non-unit part of the process)	long integer	optional
	count	only if BEEP used and unit≠0, number of times entire unit loop ran previously	long integer	optional
	iteration	only if BEEP used and unit≠0, number of times unit loop has iterated	long integer	optional
	source	can be one of: /dev/audit - if information came from the Linux kernel's Audit subsystem /proc - if information was extracted from Linux's /proc pseudofilesystem beep - if information came from BEEP	string (as enumerated)	required
Artifact
	subtype	can be one of: memory - for memory addresses file - for filesystem entities named pipe, unnamed pipe, and unix socket - for inter-process flow network socket - for network flows unknown - underlying artifact can be of subtype file, named pipe, unnamed pipe, unix socket, or network socket	string (as enumerated)	required
	memory address	only for subtype memory, location in memory	integer (in hexadecimal)	optional
	size	only for subtype memory, length of allocated memory	hexadecimal integer	optional
	pid	only for subtype named pipe, unnamed pipe, or unknown, process that created the artifact	integer	optional
	tgid	only for subtype memory, thread group id for threads sharing memory	integer	optional
	path	only for subtype file, named pipe, or unix socket, location in the local filesystem	string	optional
	permissions	only for subtype file, named pipe, or unix socket, existing permissions in the file system for the artifact	integer (in octal)	optional
	version	only for subtype file, named pipe, unnamed pipe, memory, unix socket, or unknown, how many times it has been written	integer	optional
	epoch	only for subtype file, named pipe, unnamed pipe, unix socket, network socket, or unknown, how many times an artifact has been created at specified path	integer	optional
	fd	only for subtype unknown, descriptor used to access file	integer	optional
	read fd	only for subtype unnamed pipe, descriptor used to read pipe	integer	optional
	write fd	only for subtype unnamed pipe, descriptor used to write pipe	integer	optional
	local address	only for subtype network socket, host from which connection originates	dotted octet	optional
	local port	only for subtype network socket, connection port used at originating host	unsigned short integer	optional
	remote address	only for subtype network socket, host at which connection terminates	dotted octet	optional
	remote port	only for subtype network socket, connection port used at terminating host	unsigned short integer	optional
	protocol	can be one of: udp or tcp, only for subtype network socket, connection protocol used	string (as enumerated)	optional
	source	can be one of: /dev/audit - if information came from the Linux kernel's Audit subsystem /proc - if information was extracted from Linux's /proc pseudofilesystem beep - if information came from BEEP	string (as enumerated)	required
WasControlledBy**
	operation	can be one of: setuid or setgid - process ownership changed	string (as enumerated)	optional
	time	if known, when the event occurred (in Unix time)	floating point	optional
	event id	if source is /dev/audit, underlying event's identifier	unsigned integer	optional
	source	can be one of: /dev/audit - if information came from the Linux kernel's Audit subsystem /proc - if information was extracted from Linux's /proc pseudofilesystem	string (as enumerated)	required
WasTriggeredBy
	operation	can be one of: fork - another independent process was created clone - another process created with shared state execve - child process replaced parent unknown - underlying operation can be of type fork, clone, or execve setuid or setgid - process ownership changed unit - creation of a BEEP unit (by a program loop) unit dependency - a BEEP unit read a memory location written previously by another BEEP unit	string (as enumerated)	optional
	time	if known, when the event occurred (in Unix time)	floating point	optional
	event id	if source is /dev/audit, underlying event's identifier	unsigned integer	optional
	source	can be one of: /dev/audit - if information came from the Linux kernel's Audit subsystem /proc - if information was extracted from Linux's /proc pseudofilesystem beep - if information came from BEEP	string (as enumerated)	required
WasGeneratedBy
	operation	can be one of: create - file was created open - file was opened for writing write - data was transferred to memory, file, or network send - data was transferred from process to network connect - outgoing network connection was established truncate - data at end of file was removed rename (write) - to new file, after renaming link (write) - to new file, after linking mmap (write) - to mapped memory chmod - changed file permissions mprotect - changed memory protection unlink - file was deleted close - file descriptor was closed	string (as enumerated)	required
	size	only for operations write and send, number of bytes transferred	long integer	optional
	mode	only for operations chmod, open and create, permissions applied to file	integer (in octal)	optional
	flags	only for operations open, and create, flags passed in system call as mentioned in open(2) manpage. Example: O_TRUNCATE|O_RDWR	string	optional
	protection	only for operations mmap, and mprotect, permissions set for memory location	hexadecimal integer	optional
	offset	only for system calls pwrite, and pwritev, offset in the file where bytes were written	long	optional
	time	if known, when the event occurred (in Unix time)	floating point	required
	event id	if source is /dev/audit, underlying event's identifier	unsigned integer	required
	source	can be one of: /dev/audit - if information came from the Linux kernel's Audit subsystem /proc - if information was extracted from Linux's /proc pseudofilesystem beep - if information came from BEEP	string (as enumerated)	required
Used
	operation	can be one of: open - file was opened for reading read - data was transferred from memory, file, or network recv - data was transferred from network to process accept - incoming network connection was established rename (read) - from original file, before renaming link (read) - from original file, before linking mmap (read) - from mapped file load - dynamic library loaded close - file descriptor was closed	string (as enumerated)	required
	size	only for operations read and recv, number of bytes transferred	long integer	optional
	mode	only for operation open, permissions applied to file	integer (in octal)	optional
	offset	only for system calls pread, and preadv, offset in the file from where bytes were read	long	optional
	time	if known, when the event occurred (in Unix time)	floating point	required
	event id	if source is /dev/audit, underlying event's identifier	unsigned integer	required
	source	can be one of: /dev/audit - if information came from the Linux kernel's Audit subsystem /proc - if information was extracted from Linux's /proc pseudofilesystem beep - if information came from BEEP	string (as enumerated)	required
WasDerivedFrom
	operation	can be one of: update - the artifact has been modified rename - the same artifact has a new name link - a new name can be used to refer to the old artifact mmap - a file has been mapped into memory	string (as enumerated)	required
	pid	process that performed the operation	integer	optional
	time	if known, when the event occurred (in Unix time)	floating point	required
	event id	if source is /dev/audit, underlying event's identifier	unsigned integer	required
	source	can be one of: /dev/audit - if information came from the Linux kernel's Audit subsystem /proc - if information was extracted from Linux's /proc pseudofilesystem beep - if information came from BEEP	string (as enumerated)	required

*If agents enabled then all annotations listed for Agent are included in Process.

**Only if agents are enabled.

NOTE: Though some operation values match system call names, the semantics differ. In particular, the interpretation is provenance-oriented. Multiple system calls may map to a single operation value (such as chmod() and fchmod() both reported as chmod). Some system calls have an indirect effect (such as dup() resulting in a new file descriptor resolving to the old path during read() and write() calls). The mapping of system calls to OPM edges is outlined here.