From fc37d2f1c8d8bf42c731b2738e6e2d0612f35fa4 Mon Sep 17 00:00:00 2001 From: Matthew Bobrowski Date: Sat, 12 Jan 2019 12:56:15 +1100 Subject: [PATCH] fanotify_mark.2, fanotify.7: Document FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM New event masks have been added to the fanotify API. Documentation to support the use and behaviour of these new masks has been added accordingly. Signed-off-by: Matthew Bobrowski Reviewed-by: Amir Goldstein Signed-off-by: Michael Kerrisk --- man2/fanotify_mark.2 | 60 ++++++++++++++++++++++++++++++++++++++++++++ man7/fanotify.7 | 18 +++++++++++++ 2 files changed, 78 insertions(+) diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 index a9a482fe70..613c86cc49 100644 --- a/man2/fanotify_mark.2 +++ b/man2/fanotify_mark.2 @@ -149,6 +149,12 @@ Create an event when a read-only file or directory is closed. .B FAN_OPEN Create an event when a file or directory is opened. .TP +.B FAN_OPEN_EXEC +Create an event when a file is opened with the intent to be executed. +See +.B NOTES +for additional details. +.TP .B FAN_Q_OVERFLOW Create an event when an overflow of the event queue occurs. The size of the event queue is limited to 16384 entries if @@ -164,6 +170,18 @@ or .B FAN_CLASS_CONTENT is required. .TP +.B FAN_OPEN_EXEC_PERM +Create an event when a permission to open a file for execution is +requested. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +or +.B FAN_CLASS_CONTENT +is required. +See +.B NOTES +for additional details. +.TP .B FAN_ACCESS_PERM Create an event when a permission to read a file or directory is requested. An fanotify file descriptor created with @@ -309,6 +327,48 @@ was introduced in version 2.6.36 of the Linux kernel and enabled in version 2.6.37. .SH CONFORMING TO This system call is Linux-specific. +.SH NOTES +When using either +.B FAN_OPEN_EXEC +or +.B FAN_OPEN_EXEC_PERM +within the +.IR mask , +events of these types will only be returned when the direct execution of a +program occurs. +More specifically, this means that events of these types shall be generated +for files that are opened using system calls +.BR execve(2) , +.BR execveat(2) , +or +.BR uselib(2) . +Events of these types will not be raised in the situation where an +interpreter reads data as input and subsequently results in arbitrary +computation. +.PP +Additionally, if a mark has also been placed on the Linux dynamic +linker/loader, a user should also expect to receive an event for it when +an ELF object has been successfully opened using system calls +.BR execve(2) +or +.BR execveat(2) . +.PP +For example, if the following ELF binary were to be invoked and a +.BR FAN_OPEN_EXEC +mark has been placed on /: +.PP +.EX + ~> /bin/echo foo +.EE +.PP +The listening application in this case will receive events +.BR FAN_OPEN_EXEC +for both the ELF binary and interpreter, respectively: +.PP +.EX + /bin/echo + /lib64/ld-linux-x86-64.so.2 +.EE .SH BUGS The following bugs were present in Linux kernels before version 3.16: .IP * 3 diff --git a/man7/fanotify.7 b/man7/fanotify.7 index 00e080522a..cc24577356 100644 --- a/man7/fanotify.7 +++ b/man7/fanotify.7 @@ -250,6 +250,14 @@ A file or a directory (but see BUGS) was accessed (read). .B FAN_OPEN A file or a directory was opened. .TP +.B FAN_OPEN_EXEC +A file was opened with the intent to be executed. +See +.B NOTES +in +.BR fanotify_mark (2) +for additional details. +.TP .B FAN_MODIFY A file was modified. .TP @@ -285,6 +293,16 @@ access the filesystem object shall be granted. An application wants to open a file or directory. The reader must write a response that determines whether the permission to open the filesystem object shall be granted. +.TP +.B FAN_OPEN_EXEC_PERM +An application wants to open a file for execution. +The reader must write a response that determines whether the permission to +open the filesystem object for execution shall be granted. +See +.B NOTES +in +.BR fanotify_mark (2) +for additional details. .PP To check for any close event, the following bit mask may be used: .TP -- 2.39.2