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: syscall - if information came from a Linux kernel Audit system call record /proc - if information came 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 (or unit) started (in Unix time)	floating point	optional
	seen time	if start time not known, (Unix) time of first event seen from process	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: syscall - if information came from a Linux kernel Audit system call record /proc - if information came 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, link, directory, block device, character device - for filesystem entities named pipe, unnamed pipe, unix socket, unix socket pair, and network socket pair - for inter-process flow network socket - for network flows unknown - underlying artifact can be of subtype file, link, directory, block device, character device, named pipe, unnamed pipe, unix socket, network socket, network socket pair, or unix socket pair	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
	tgid	only for subtype memory, unnamed pipe, unknown, unix socket pair, or network socket pair, group identifier of threads that share memory or file descriptors	integer	optional
	time	only for subtype memory, unnamed pipe, 'unknown', unix socket pair, or network socket pair, start or seen time of group identifier of threads that share memory or file descriptors	floating point	optional
	path	only for subtype file, named pipe, link, directory, block device, character device, or unix socket, location in the local filesystem	string	optional
	permissions	only for subtype file, link, directory, block device, character device, named pipe, or unix socket, filesystem access mode	integer (in octal)	optional
	version	only for subtype file, link, directory, block device, character device, named pipe, unnamed pipe, memory, unix socket, or unknown, how many times it has been written	integer	optional
	epoch	only for subtype file, link, directory, block device, character device, 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
	fd 0	only for subtypes unix socket pair and network socket pair, descriptor used to access connected socket pair	integer	optional
	fd 1	only for subtypes unix socket pair and network socket pair, descriptor used to access connected socket pair	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: syscall - if information came from a Linux kernel Audit system call record netfilter - if information came from a Linux kernel Audit network filter record /proc - if information came from Linux's /proc pseudofilesystem beep - if information came from BEEP	string (as enumerated)	required
WasControlledBy
	operation	can be one of: update - implicit process ownership change setuid or setgid - explicit process ownership change	string (as enumerated)	optional
	time	if known, when the event occurred (in Unix time)	floating point	optional
	event id	if source is syscall, underlying event's identifier	unsigned integer	optional
	source	can be one of: syscall - if information came from a Linux kernel Audit system call record /proc - if information came 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 update - implicit process ownership change setuid or setgid - explicit process ownership change unit - creation of a BEEP unit (by a program loop) unit dependency - dependent unit read memory written by another unit ptrace - trace another process kill - send signal to another process	string (as enumerated)	optional
	flags	only for operation clone, clone flags	string	optional
	request	only for operation ptrace, action performed on the tracee	string	optional
	signal	only for operation kill, signal sent	integer	optional
	time	if known, when the event occurred (in Unix time)	floating point	optional
	event id	if source is syscall, underlying event's identifier	unsigned integer	optional
	source	can be one of: syscall - if information came from a Linux kernel Audit system call record /proc - if information came 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 tee (write) - data copied to pipe splice (write) - data transferred to destination vmsplice - data mapped to pipe chmod - changed file permissions mprotect - changed memory protection unlink - file was deleted close - file was closed	string (as enumerated)	required
	size	only for operations truncate, tee (write), splice (write), vmsplice, 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, status or creation flags	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 syscall, underlying event's identifier	unsigned integer	required
	source	can be one of: syscall - if information came from a Linux kernel Audit system call record /proc - if information came 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 tee (read) - data copied from pipe splice (read) - data transferred from source load - dynamic library loaded close - file was closed init_module - module loaded from memory finit_module - module loaded from file	string (as enumerated)	required
	size	only for operations read, tee (read), splice (read), and recv, number of bytes transferred	long integer	optional
	mode	only for operation open, permissions applied to file	integer (in octal)	optional
	flags	only for operation open, status flags	string	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 syscall, underlying event's identifier	unsigned integer	required
	source	can be one of: syscall - if information came from a Linux kernel Audit system call record /proc - if information came 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 tee - data copied between pipes splice - data transferred between artifacts	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 syscall, underlying event's identifier	unsigned integer	required
	source	can be one of: syscall - if information came from a Linux kernel Audit system call record netfilter - if information came from a Linux kernel Audit network filter record /proc - if information came from Linux's /proc pseudofilesystem beep - if information came from BEEP	string (as enumerated)	required

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.