{"componentChunkName":"component---src-templates-post-template-js","path":"/clamav-onaccess-scanning-en","result":{"data":{"markdownRemark":{"id":"0271b640-d212-5c20-a7b1-fb898371ef53","html":"
\n

This page has been machine-translated from the original page.

\n
\n

Out of the blue, but at the online market for Technical Book Fest 17, which has been running since 11/2, I am distributing a free technical doujin book titled A part of Anti-Virus -Learning Windows filesystem minifilter driver from public sample code-.

\n

In that book, I explain how AntiVirus software for Windows uses filesystem minifilter drivers for real-time file scanning (On-Access scanning).

\n

\n \n \n#define _GNU_SOURCE\n\n#include <stdio.h>\n#include <signal.h>\n#include <string.h>\n#include <unistd.h>\n#include <stdlib.h>\n#include <poll.h>\n#include <errno.h>\n#include <limits.h>\n#include <sys/stat.h>\n#include <sys/signalfd.h>\n#include <fcntl.h>\n\n#include <linux/fanotify.h>\n\n/* Structure to keep track of monitored directories */\ntypedef struct\n{\n /* Path of the directory */\n char *path;\n} monitored_t;\n\n/* Size of buffer to use when reading fanotify events */\n#define FANOTIFY_BUFFER_SIZE 8192\n\n/* Enumerate list of FDs to poll */\nenum\n{\n FD_POLL_SIGNAL = 0,\n FD_POLL_FANOTIFY,\n FD_POLL_MAX\n};\n\n/* Setup fanotify notifications (FAN) mask. All these defined in fanotify.h. */\nstatic uint64_t event_mask =\n (FAN_ACCESS | /* File accessed */\n FAN_MODIFY | /* File modified */\n FAN_CLOSE_WRITE | /* Writtable file closed */\n FAN_CLOSE_NOWRITE | /* Unwrittable file closed */\n FAN_OPEN | /* File was opened */\n FAN_ONDIR | /* We want to be reported of events in the directory */\n FAN_EVENT_ON_CHILD); /* We want to be reported of events in files of the directory */\n\n/* Array of directories being monitored */\nstatic monitored_t *monitors;\nstatic int n_monitors;\n\nstatic char *\nget_program_name_from_pid(int pid,\n char *buffer,\n size_t buffer_size)\n{\n int fd;\n ssize_t len;\n char *aux;\n\n /* Try to get program name by PID */\n sprintf(buffer, \"/proc/%d/cmdline\", pid);\n if ((fd = open(buffer, O_RDONLY)) < 0)\n return NULL;\n\n /* Read file contents into buffer */\n if ((len = read(fd, buffer, buffer_size - 1)) <= 0)\n {\n close(fd);\n return NULL;\n }\n close(fd);\n\n buffer[len] = '\\0';\n aux = strstr(buffer, \"^@\");\n if (aux)\n *aux = '\\0';\n\n return buffer;\n}\n\nstatic char *\nget_file_path_from_fd(int fd,\n char *buffer,\n size_t buffer_size)\n{\n ssize_t len;\n\n if (fd <= 0)\n return NULL;\n\n sprintf(buffer, \"/proc/self/fd/%d\", fd);\n if ((len = readlink(buffer, buffer, buffer_size - 1)) < 0)\n return NULL;\n\n buffer[len] = '\\0';\n return buffer;\n}\n\nstatic void event_process(struct fanotify_event_metadata *event)\n{\n char path[PATH_MAX];\n\n printf(\"Received event in path '%s'\",\n get_file_path_from_fd(event->fd,\n path,\n PATH_MAX)\n ? path\n : \"unknown\");\n printf(\" pid=%d (%s): \\n\",\n event->pid,\n (get_program_name_from_pid(event->pid,\n path,\n PATH_MAX)\n ? path\n : \"unknown\"));\n\n if (event->mask & FAN_OPEN)\n printf(\"\\tFAN_OPEN\\n\");\n if (event->mask & FAN_ACCESS)\n printf(\"\\tFAN_ACCESS\\n\");\n if (event->mask & FAN_MODIFY)\n printf(\"\\tFAN_MODIFY\\n\");\n if (event->mask & FAN_CLOSE_WRITE)\n printf(\"\\tFAN_CLOSE_WRITE\\n\");\n if (event->mask & FAN_CLOSE_NOWRITE)\n printf(\"\\tFAN_CLOSE_NOWRITE\\n\");\n fflush(stdout);\n\n close(event->fd);\n}\n\nstatic void\nshutdown_fanotify(int fanotify_fd)\n{\n int i;\n\n for (i = 0; i < n_monitors; ++i)\n {\n /* Remove the mark, using same event mask as when creating it */\n fanotify_mark(fanotify_fd,\n FAN_MARK_REMOVE,\n event_mask,\n AT_FDCWD,\n monitors[i].path);\n free(monitors[i].path);\n }\n free(monitors);\n close(fanotify_fd);\n}\n\nstatic int\ninitialize_fanotify(int argc,\n const char **argv)\n{\n int i;\n int fanotify_fd;\n\n /* Create new fanotify device */\n if ((fanotify_fd = fanotify_init(FAN_CLASS_CONTENT | FAN_UNLIMITED_QUEUE | FAN_UNLIMITED_MARKS,\n O_RDONLY | O_LARGEFILE)) < 0)\n {\n fprintf(stderr,\n \"Couldn't setup new fanotify device: %s\\n\",\n strerror(errno));\n return -1;\n }\n\n /* Allocate array of monitor setups */\n n_monitors = argc - 1;\n monitors = malloc(n_monitors * sizeof(monitored_t));\n\n /* Loop all input directories, setting up marks */\n for (i = 0; i < n_monitors; ++i)\n {\n monitors[i].path = strdup(argv[i + 1]);\n /* Add new fanotify mark */\n if (fanotify_mark(fanotify_fd,\n FAN_MARK_ADD | FAN_MARK_MOUNT,\n event_mask,\n AT_FDCWD,\n monitors[i].path) < 0)\n {\n fprintf(stderr,\n \"Couldn't add monitor in directory '%s': '%s'\\n\",\n monitors[i].path,\n strerror(errno));\n return -1;\n }\n\n printf(\"Started monitoring directory '%s'...\\n\",\n monitors[i].path);\n }\n\n return fanotify_fd;\n}\n\nstatic void\nshutdown_signals(int signal_fd)\n{\n close(signal_fd);\n}\n\nstatic int\ninitialize_signals(void)\n{\n int signal_fd;\n sigset_t sigmask;\n\n /* We want to handle SIGINT and SIGTERM in the signal_fd, so we block them. */\n sigemptyset(&sigmask);\n sigaddset(&sigmask, SIGINT);\n sigaddset(&sigmask, SIGTERM);\n\n if (sigprocmask(SIG_BLOCK, &sigmask, NULL) < 0)\n {\n fprintf(stderr,\n \"Couldn't block signals: '%s'\\n\",\n strerror(errno));\n return -1;\n }\n\n /* Get new FD to read signals from it */\n if ((signal_fd = signalfd(-1, &sigmask, 0)) < 0)\n {\n fprintf(stderr,\n \"Couldn't setup signal FD: '%s'\\n\",\n strerror(errno));\n return -1;\n }\n\n return signal_fd;\n}\n\nint main(int argc,\n const char **argv)\n{\n int signal_fd;\n int fanotify_fd;\n struct pollfd fds[FD_POLL_MAX];\n\n /* Input arguments... */\n if (argc < 2)\n {\n fprintf(stderr, \"Usage: %s directory1 [directory2 ...]\\n\", argv[0]);\n exit(EXIT_FAILURE);\n }\n\n /* Initialize signals FD */\n if ((signal_fd = initialize_signals()) < 0)\n {\n fprintf(stderr, \"Couldn't initialize signals\\n\");\n exit(EXIT_FAILURE);\n }\n\n /* Initialize fanotify FD and the marks */\n if ((fanotify_fd = initialize_fanotify(argc, argv)) < 0)\n {\n fprintf(stderr, \"Couldn't initialize fanotify\\n\");\n exit(EXIT_FAILURE);\n }\n\n /* Setup polling */\n fds[FD_POLL_SIGNAL].fd = signal_fd;\n fds[FD_POLL_SIGNAL].events = POLLIN;\n fds[FD_POLL_FANOTIFY].fd = fanotify_fd;\n fds[FD_POLL_FANOTIFY].events = POLLIN;\n\n /* Now loop */\n for (;;)\n {\n /* Block until there is something to be read */\n if (poll(fds, FD_POLL_MAX, -1) < 0)\n {\n fprintf(stderr,\n \"Couldn't poll(): '%s'\\n\",\n strerror(errno));\n exit(EXIT_FAILURE);\n }\n\n /* Signal received? */\n if (fds[FD_POLL_SIGNAL].revents & POLLIN)\n {\n struct signalfd_siginfo fdsi;\n\n if (read(fds[FD_POLL_SIGNAL].fd, &fdsi, sizeof(fdsi)) != sizeof(fdsi))\n {\n fprintf(stderr, \"Couldn't read signal, wrong size read\\n\");\n exit(EXIT_FAILURE);\n }\n\n /* Break loop if we got the expected signal */\n if (fdsi.ssi_signo == SIGINT || fdsi.ssi_signo == SIGTERM)\n {\n break;\n }\n\n fprintf(stderr, \"Received unexpected signal\\n\");\n }\n\n /* fanotify event received? */\n if (fds[FD_POLL_FANOTIFY].revents & POLLIN)\n {\n char buffer[FANOTIFY_BUFFER_SIZE];\n ssize_t length;\n\n /* Read from the FD. It will read all events available up to\n * the given buffer size. */\n if ((length = read(fds[FD_POLL_FANOTIFY].fd, buffer, FANOTIFY_BUFFER_SIZE)) > 0)\n {\n struct fanotify_event_metadata *metadata;\n\n metadata = (struct fanotify_event_metadata *)buffer;\n while (FAN_EVENT_OK(metadata, length))\n {\n event_process(metadata);\n if (metadata->fd > 0)\n close(metadata->fd);\n metadata = FAN_EVENT_NEXT(metadata, length);\n }\n }\n }\n }\n\n /* Clean exit */\n shutdown_fanotify(fanotify_fd);\n shutdown_signals(signal_fd);\n\n printf(\"Exiting fanotify example...\\n\");\n\n return EXIT_SUCCESS;\n}\n\nI will not go into a detailed explanation of the sample above because it is not the main point here, but it initializes fanotify with settings that are almost the same as ClamAV's, as shown below.\n\n``` c\n/* Setup fanotify notifications (FAN) mask. All these defined in fanotify.h. */\nstatic uint64_t event_mask =\n (FAN_ACCESS | /* File accessed */\n FAN_MODIFY | /* File modified */\n FAN_CLOSE_WRITE | /* Writtable file closed */\n FAN_CLOSE_NOWRITE | /* Unwrittable file closed */\n FAN_OPEN | /* File was opened */\n FAN_ONDIR | /* We want to be reported of events in the directory */\n FAN_EVENT_ON_CHILD); /* We want to be reported of events in files of the directory */\n\nfanotify_init(FAN_CLASS_CONTENT | FAN_UNLIMITED_QUEUE | FAN_UNLIMITED_MARKS, O_RDONLY | O_LARGEFILE)\n \nfanotify_mark(fanotify_fd,\n FAN_MARK_ADD | FAN_MARK_MOUNT,\n event_mask,\n AT_FDCWD,\n monitors[i].path)\n\nIf you build this source code and run the resulting program with a mount point as the argument, you can receive fanotify notifications when directory or file accesses occur within that mount point.\n\n![image-20241027211958055](../../static/media/2024-10-23-clamav-onaccess-scanning/image-20241027211958055.png)\n\nOne especially confusing part here was how `FAN_MARK_MOUNT` behaves.\n\nWhen `FAN_MARK_MOUNT` is specified in the `fanotify_mark` function, fanotify appears to monitor all directories and files inside the \"mount point\" received via the path argument.\n\nIn other words, the object being monitored here seems to be the mount point itself, not a \"directory\" in the same sense as a Windows folder.\n\nIn the environment where I first tested this, the `/home` directory existed under the same mount point as directories such as `/usr`, so even if I specified `/home/user` as the monitor target, I still received access events for every file in that same mount point, such as `/usr/file`.\n\nIn practice, after following the steps in the article below to move `/home` to a separate partition and then editing `/etc/fstab` to assign `/home` its own mount point, I was able to monitor only accesses to directories and files under `/home` with fanotify.\n\nReference: [Moving an in-use home directory to another partition on Ubuntu (no LiveUSB required) - kamocyc’s blog](https://kamocyc.hatenablog.com/entry/2019/10/26/132015)\n\nIf you want to monitor operations only on a specific directory or file, it seems better to specify just `FAN_MARK_ADD` rather than `FAN_MARK_MOUNT`.\n\n### Denying operations on a specific file\n\nOnce I could receive filesystem events with fanotify, I next rewrote the code so that only operations on a specific file would be denied.\n\nThe number of changes is small, but I will include the full source code below.\n\n``` c\n/* Define _GNU_SOURCE, Otherwise we don't get O_LARGEFILE */\n#define _GNU_SOURCE\n\n#include <stdio.h>\n#include <signal.h>\n#include <string.h>\n#include <unistd.h>\n#include <stdlib.h>\n#include <poll.h>\n#include <errno.h>\n#include <limits.h>\n#include <sys/stat.h>\n#include <sys/signalfd.h>\n#include <fcntl.h>\n\n#include <sys/fanotify.h>\n\n/* Structure to keep track of monitored directories */\ntypedef struct\n{\n /* Path of the directory */\n char *path;\n} monitored_t;\n\n/* Size of buffer to use when reading fanotify events */\n#define FANOTIFY_BUFFER_SIZE 8192\n\n/* Enumerate list of FDs to poll */\nenum\n{\n FD_POLL_SIGNAL = 0,\n FD_POLL_FANOTIFY,\n FD_POLL_MAX\n};\n\n/* Setup fanotify notifications (FAN) mask. All these defined in fanotify.h. */\nstatic uint64_t event_mask =\n (FAN_OPEN_PERM |\n FAN_ACCESS | /* File accessed */\n FAN_MODIFY | /* File modified */\n FAN_CLOSE_WRITE | /* Writtable file closed */\n FAN_CLOSE_NOWRITE | /* Unwrittable file closed */\n FAN_OPEN | /* File was opened */\n FAN_ONDIR | /* We want to be reported of events in the directory */\n FAN_EVENT_ON_CHILD); /* We want to be reported of events in files of the directory */\n\n/* Array of directories being monitored */\nstatic monitored_t *monitors;\nstatic int n_monitors;\n\nstatic char *\nget_program_name_from_pid(int pid,\n char *buffer,\n size_t buffer_size)\n{\n int fd;\n ssize_t len;\n char *aux;\n\n /* Try to get program name by PID */\n sprintf(buffer, \"/proc/%d/cmdline\", pid);\n if ((fd = open(buffer, O_RDONLY)) < 0)\n return NULL;\n\n /* Read file contents into buffer */\n if ((len = read(fd, buffer, buffer_size - 1)) <= 0)\n {\n close(fd);\n return NULL;\n }\n close(fd);\n\n buffer[len] = '\\0';\n aux = strstr(buffer, \"^@\");\n if (aux)\n *aux = '\\0';\n\n return buffer;\n}\n\nstatic char *\nget_file_path_from_fd(int fd,\n char *buffer,\n size_t buffer_size)\n{\n ssize_t len;\n\n if (fd <= 0)\n return NULL;\n\n sprintf(buffer, \"/proc/self/fd/%d\", fd);\n if ((len = readlink(buffer, buffer, buffer_size - 1)) < 0)\n return NULL;\n\n buffer[len] = '\\0';\n return buffer;\n}\n\nstatic void event_process(int fanotify_fd, struct fanotify_event_metadata *event)\n{\n char path[PATH_MAX];\n\n printf(\"Received event in path '%s'\",\n get_file_path_from_fd(event->fd,\n path,\n PATH_MAX)\n ? path\n : \"unknown\");\n printf(\" pid=%d (%s): \\n\",\n event->pid,\n (get_program_name_from_pid(event->pid,\n path,\n PATH_MAX)\n ? path\n : \"unknown\"));\n\n if (event->mask & FAN_OPEN)\n printf(\"\\tFAN_OPEN\\n\");\n if (event->mask & FAN_ACCESS)\n printf(\"\\tFAN_ACCESS\\n\");\n if (event->mask & FAN_MODIFY)\n printf(\"\\tFAN_MODIFY\\n\");\n if (event->mask & FAN_CLOSE_WRITE)\n printf(\"\\tFAN_CLOSE_WRITE\\n\");\n if (event->mask & FAN_CLOSE_NOWRITE)\n printf(\"\\tFAN_CLOSE_NOWRITE\\n\");\n fflush(stdout);\n\n struct fanotify_response response;\n response.fd = event->fd;\n\n if (strcmp(get_file_path_from_fd(event->fd,\n path,\n PATH_MAX),\n \"/home/rana/eicar\") == 0)\n {\n response.response = FAN_DENY;\n }\n else\n {\n response.response = FAN_ALLOW;\n }\n\n write(fanotify_fd, &response, sizeof(response));\n\n close(event->fd);\n}\n\nstatic void\nshutdown_fanotify(int fanotify_fd)\n{\n int i;\n\n for (i = 0; i < n_monitors; ++i)\n {\n /* Remove the mark, using same event mask as when creating it */\n fanotify_mark(fanotify_fd,\n FAN_MARK_REMOVE,\n event_mask,\n AT_FDCWD,\n monitors[i].path);\n free(monitors[i].path);\n }\n free(monitors);\n close(fanotify_fd);\n}\n\nstatic int\ninitialize_fanotify(int argc,\n const char **argv)\n{\n int i;\n int fanotify_fd;\n\n /* Create new fanotify device */\n if ((fanotify_fd = fanotify_init(FAN_CLASS_CONTENT | FAN_UNLIMITED_QUEUE | FAN_UNLIMITED_MARKS,\n O_RDONLY | O_LARGEFILE)) < 0)\n {\n fprintf(stderr,\n \"Couldn't setup new fanotify device: %s\\n\",\n strerror(errno));\n return -1;\n }\n\n /* Allocate array of monitor setups */\n n_monitors = argc - 1;\n monitors = malloc(n_monitors * sizeof(monitored_t));\n\n /* Loop all input directories, setting up marks */\n for (i = 0; i < n_monitors; ++i)\n {\n monitors[i].path = strdup(argv[i + 1]);\n /* Add new fanotify mark */\n if (fanotify_mark(fanotify_fd,\n FAN_MARK_ADD | FAN_MARK_MOUNT,\n event_mask,\n AT_FDCWD,\n monitors[i].path) < 0)\n {\n fprintf(stderr,\n \"Couldn't add monitor in directory '%s': '%s'\\n\",\n monitors[i].path,\n strerror(errno));\n return -1;\n }\n\n printf(\"Started monitoring directory '%s'...\\n\",\n monitors[i].path);\n }\n\n return fanotify_fd;\n}\n\nstatic void\nshutdown_signals(int signal_fd)\n{\n close(signal_fd);\n}\n\nstatic int\ninitialize_signals(void)\n{\n int signal_fd;\n sigset_t sigmask;\n\n /* We want to handle SIGINT and SIGTERM in the signal_fd, so we block them. */\n sigemptyset(&sigmask);\n sigaddset(&sigmask, SIGINT);\n sigaddset(&sigmask, SIGTERM);\n\n if (sigprocmask(SIG_BLOCK, &sigmask, NULL) < 0)\n {\n fprintf(stderr,\n \"Couldn't block signals: '%s'\\n\",\n strerror(errno));\n return -1;\n }\n\n /* Get new FD to read signals from it */\n if ((signal_fd = signalfd(-1, &sigmask, 0)) < 0)\n {\n fprintf(stderr,\n \"Couldn't setup signal FD: '%s'\\n\",\n strerror(errno));\n return -1;\n }\n\n return signal_fd;\n}\n\nint main(int argc,\n const char **argv)\n{\n int signal_fd;\n int fanotify_fd;\n struct pollfd fds[FD_POLL_MAX];\n\n /* Input arguments... */\n if (argc < 2)\n {\n fprintf(stderr, \"Usage: %s directory1 [directory2 ...]\\n\", argv[0]);\n exit(EXIT_FAILURE);\n }\n\n /* Initialize signals FD */\n if ((signal_fd = initialize_signals()) < 0)\n {\n fprintf(stderr, \"Couldn't initialize signals\\n\");\n exit(EXIT_FAILURE);\n }\n\n /* Initialize fanotify FD and the marks */\n if ((fanotify_fd = initialize_fanotify(argc, argv)) < 0)\n {\n fprintf(stderr, \"Couldn't initialize fanotify\\n\");\n exit(EXIT_FAILURE);\n }\n\n /* Setup polling */\n fds[FD_POLL_SIGNAL].fd = signal_fd;\n fds[FD_POLL_SIGNAL].events = POLLIN;\n fds[FD_POLL_FANOTIFY].fd = fanotify_fd;\n fds[FD_POLL_FANOTIFY].events = POLLIN;\n\n /* Now loop */\n for (;;)\n {\n /* Block until there is something to be read */\n if (poll(fds, FD_POLL_MAX, -1) < 0)\n {\n fprintf(stderr,\n \"Couldn't poll(): '%s'\\n\",\n strerror(errno));\n exit(EXIT_FAILURE);\n }\n\n /* Signal received? */\n if (fds[FD_POLL_SIGNAL].revents & POLLIN)\n {\n struct signalfd_siginfo fdsi;\n\n if (read(fds[FD_POLL_SIGNAL].fd, &fdsi, sizeof(fdsi)) != sizeof(fdsi))\n {\n fprintf(stderr, \"Couldn't read signal, wrong size read\\n\");\n exit(EXIT_FAILURE);\n }\n\n /* Break loop if we got the expected signal */\n if (fdsi.ssi_signo == SIGINT || fdsi.ssi_signo == SIGTERM)\n {\n break;\n }\n\n fprintf(stderr, \"Received unexpected signal\\n\");\n }\n\n /* fanotify event received? */\n if (fds[FD_POLL_FANOTIFY].revents & POLLIN)\n {\n char buffer[FANOTIFY_BUFFER_SIZE];\n ssize_t length;\n\n /* Read from the FD. It will read all events available up to\n * the given buffer size. */\n if ((length = read(fds[FD_POLL_FANOTIFY].fd, buffer, FANOTIFY_BUFFER_SIZE)) > 0)\n {\n struct fanotify_event_metadata *metadata;\n\n metadata = (struct fanotify_event_metadata *)buffer;\n while (FAN_EVENT_OK(metadata, length))\n {\n event_process(fanotify_fd, metadata);\n if (metadata->fd > 0)\n close(metadata->fd);\n metadata = FAN_EVENT_NEXT(metadata, length);\n }\n }\n }\n }\n\n /* Clean exit */\n shutdown_fanotify(fanotify_fd);\n shutdown_signals(signal_fd);\n\n printf(\"Exiting fanotify example...\\n\");\n\n return EXIT_SUCCESS;\n}\n\nThe first key point is that the `FAN_OPEN_PERM` bit is added to the `event_mask` used by the `fanotify_mark` function.\n\n``` c\nstatic uint64_t event_mask =\n (FAN_OPEN_PERM |\n FAN_ACCESS | /* File accessed */\n FAN_MODIFY | /* File modified */\n FAN_CLOSE_WRITE | /* Writtable file closed */\n FAN_CLOSE_NOWRITE | /* Unwrittable file closed */\n FAN_OPEN | /* File was opened */\n FAN_ONDIR | /* We want to be reported of events in the directory */\n FAN_EVENT_ON_CHILD); /* We want to be reported of events in files of the directory */\n

Once you add this, fanotify suspends the target operation until it receives a notification that allows or denies the operation through the file descriptor created by fanotify_init. (Apparently the default timeout is 5 seconds.)

\n

After that, when a filesystem event is received from fanotify, the code checks whether the target file is /home/rana/eicar, and only if that specific file was accessed does it set the response member of the fanotify_response structure to FAN_DENY.

\n
struct fanotify_response response;\nresponse.fd = event->fd;\n\nif (strcmp(get_file_path_from_fd(event->fd,\n                                 path,\n                                 PATH_MAX),\n                                 \"/home/rana/eicar\") == 0)\n{\n    response.response = FAN_DENY;\n}\nelse\n{\n    response.response = FAN_ALLOW;\n}\n\nwrite(fanotify_fd, &response, sizeof(response));
\n

When you run this program, accesses are denied only when a file at the hard-coded path below is touched.

\n

\n \n , (unsigned long int)size);\n return NULL;\n } else\n return alloc;\n}\n\nThe `onas_context` structure allocated here contains a variety of information related to scanning, but in the current version it does not seem to be used that heavily.\n\n``` c\nstruct optstruct {\n char *name;\n char *cmd;\n char *strarg;\n long long numarg;\n int enabled;\n int active;\n int flags;\n int idx;\n struct optstruct *nextarg;\n struct optstruct *next;\n\n char **filename; /* cmdline */\n};\n\nstruct onas_context {\n const struct optstruct *opts;\n const struct optstruct *clamdopts;\n\n int printinfected;\n int maxstream;\n\n uint32_t ddd_enabled;\n\n int fan_fd;\n uint64_t fan_mask;\n uint8_t retry_on_error;\n uint8_t retry_attempts;\n uint8_t deny_on_error;\n\n uint64_t sizelimit;\n uint64_t extinfo;\n\n int scantype;\n int isremote;\n int session;\n int timeout;\n\n int64_t portnum;\n\n int32_t maxthreads;\n} __attribute__((packed));\n\n### Getting command-line arguments\n\nThe next few lines parse the command-line arguments for `clamonacc`.\n\nThe command-line arguments obtained here are stored in the `opts` member of the context, and the information parsed by the `optparse` function is stored in the `clamdopts` member.\n\n``` c\n/* Parse out all our command line options */\nopts = optparse(NULL, argc, argv, 1, OPT_CLAMONACC, OPT_CLAMSCAN, NULL);\nif (opts == NULL) {\n logg(\"!Clamonacc: can't parse command line options\\n\");\n return 2;\n}\nctx->opts = opts;\n\nif (optget(opts, \"verbose\")->enabled) {\n mprintf_verbose = 1;\n logg_verbose = 1;\n}\n\n/* And our config file options */\nclamdopts = optparse(optget(opts, \"config-file\")->strarg, 0, NULL, 1, OPT_CLAMD, 0, NULL);\nif (clamdopts == NULL) {\n logg(\"!Clamonacc: can't parse clamd configuration file %s\\n\", optget(opts, \"config-file\")->strarg);\n optfree((struct optstruct *)opts);\n return 2;\n}\nctx->clamdopts = clamdopts;\n\nBoth of these are pointers to `optstruct` structures and are managed as linked lists.\n\n![image-20241025221022858](../../static/media/2024-10-23-clamav-onaccess-scanning/image-20241025221022858.png)\n\n### Registering fanotify\n\nNext comes the startup check performed by the `startup_checks` function.\n\nIf this check returns any meaningful value, execution appears to jump to the `done` section and the process exits after cleanup.\n\n``` c\n/* Make sure we're good to begin spinup */\nret = startup_checks(ctx);\nif (ret) {\n if (ret == (int)CL_BREAK) {\n ret = 0;\n }\n goto done;\n}\n\nInside the `startup_checks` function, fanotify is registered.\n\n#if defined(_GNU_SOURCE)\nctx->fan_fd = fanotify_init(FAN_CLASS_CONTENT | FAN_UNLIMITED_QUEUE | FAN_UNLIMITED_MARKS, O_LARGEFILE | O_RDONLY);\n#else\nctx->fan_fd = fanotify_init(FAN_CLASS_CONTENT | FAN_UNLIMITED_QUEUE | FAN_UNLIMITED_MARKS, O_RDONLY);\n#endif\nif (ctx->fan_fd < 0) {\n logg(\"!Clamonacc: fanotify_init failed: %s\\n\", cli_strerror(errno, faerr, sizeof(faerr)));\n if (errno == EPERM) {\n logg(\"!Clamonacc: clamonacc must have elevated permissions ... exiting ...\\n\");\n }\n ret = 2;\n goto done;\n}\n\nRegistration with fanotify is performed by the `fanotify_init` function.\n\nWhen I debugged this in my local environment, I confirmed that the `fanotify_init` function was called with the arguments in `fanotify_init(FAN_CLASS_CONTENT | FAN_UNLIMITED_QUEUE | FAN_UNLIMITED_MARKS, O_LARGEFILE | O_RDONLY);`.\n\n![image-20241025225143323](../../static/media/2024-10-23-clamav-onaccess-scanning/image-20241025225143323.png)\n\nThis function creates and initializes a fanotify group.\n\nAs its return value, `fanotify_init` returns the file descriptor for the event queue associated with the group it created.\n\nIn `clamonacc`, this return value appears to be stored in the `fan_fd` member of the context.\n\nReference: [fanotify_init(2) - Linux manual page](https://man7.org/linux/man-pages/man2/fanotify_init.2.html)\n\nThe `flag` value passed as the first argument to `fanotify_init` includes the notification class configuration.\n\nIn `clamonacc`, it registers `FAN_CLASS_CONTENT`, which is generally used by AntiVirus software.\n\nThis class can receive both \"events that notify you when a file access has occurred\" and \"events used to decide whether access to that file should be permitted.\"\n\nIt also specifies `FAN_UNLIMITED_QUEUE` and `FAN_UNLIMITED_MARKS`, which remove the limits on the number of fanotify marks and queued events.\n\nReference: [fanotify(7) - Linux manual page](https://man7.org/linux/man-pages/man7/fanotify.7.html)\n\nThe second argument also includes `O_LARGEFILE | O_RDONLY`.\n\n`O_LARGEFILE` supports monitoring files larger than 2 GB, and `O_RDONLY` appears to configure read-only access.\n\nAfter calling `fanotify_init`, the monitoring targets are registered via the `fanotify_mark` function.\n\nIn `clamonacc`, there are several branches that call `fanotify_mark` depending on the `clamd` configuration. But when a mount point is specified with the `OnAccessMountPath` option, the following code in `fanotif.c`, called from `onas_setup_fanotif`, appears to run.\n\n![image-20241101223410446](../../static/media/2024-10-23-clamav-onaccess-scanning/image-20241101223410446.png)\n\nHere, `fanotify_mark(onas_fan_fd, FAN_MARK_ADD | FAN_MARK_MOUNT, (*ctx)->fan_mask, (*ctx)->fan_fd, pt->strarg)` is executed, and the path specified by `OnAccessMountPath` is passed in the `pt->strarg` argument.\n\nNote that ClamAV cannot use the `OnAccessMountPath` option together with `OnAccessPrevention`, which blocks file access with fanotify.\n\n> The OnAccessMountPath option uses a different fanotify api configuration which makes it incompatible with OnAccessIncludePath and the DDD System. Therefore, inotify watch-point limitations will not be a concern when using this option. Unfortunately, this also means that the following options cannot be used in conjunction with OnAccessMountPath:\n>\n> OnAccessExtraScanning - is built around catching inotify events.\n> OnAccessExcludePath - is built upon the DDD System.\n> OnAccessPrevention - would lock up the system if / was selected for OnAccessMountPath. If you need OnAccessPrevention, you should use OnAccessIncludePath instead of OnAccessMountPath.\n\nReference: [On-Access Scanning - ClamAV Documentation](https://docs.clamav.net/manual/OnAccess.html)\n\nThat means if you specify `OnAccessMountPath` rather than `OnAccessIncludePath`, access itself will not be blocked even if a file is detected.\n\nIn fact, when you read the `clamonacc` source code, you can confirm that when `OnAccessMountPath` is enabled, the fanotify mask uses `FAN_OPEN` rather than `FAN_OPEN_PERM`.\n\nHowever, for testing purposes, I modified the source code as shown below so that file access would still be blocked even when `OnAccessMountPath` was enabled.\n\n![image-20241103155744015](../../static/media/2024-10-23-clamav-onaccess-scanning/image-20241103155744015.png)\n\nOnce the processing in `onas_setup_fanotif` described above finishes, `onas_handle_signals` and `onas_start_eloop` are called, and monitoring for On-Access scanning begins.\n\n``` c\n/* Setup fanotify */\nswitch (onas_setup_fanotif(&ctx)) {\n case CL_SUCCESS:\n break;\n case CL_BREAK:\n ret = 0;\n goto done;\n break;\n case CL_EARG:\n default:\n mprintf(\"!Clamonacc: can't setup fanotify\\n\");\n ret = 2;\n goto done;\n break;\n}\n\n**\n \n/* Setup signal handling */\ng_ctx = ctx;\nonas_handle_signals();\n\nlogg(\"*Clamonacc: beginning event loops\\n\");\n/* Kick off event loop(s) */\nret = onas_start_eloop(&ctx);\n

Setting up signal handling

\n

The onas_handle_signals function sets up signal handling with the code below.

\n
static void onas_handle_signals()\n{\n    sigset_t sigset;\n    struct sigaction act;\n\n    /* ignore all signals except SIGUSR1 */\n    sigfillset(&sigset);\n    sigdelset(&sigset, SIGUSR1);\n    sigdelset(&sigset, SIGUSR2);\n    /* The behavior of a process is undefined after it ignores a\n\t * SIGFPE, SIGILL, SIGSEGV, or SIGBUS signal */\n    sigdelset(&sigset, SIGFPE);\n    sigdelset(&sigset, SIGILL);\n    sigdelset(&sigset, SIGSEGV);\n    sigdelset(&sigset, SIGINT);\n    sigdelset(&sigset, SIGTERM);\n#ifdef SIGBUS\n    sigdelset(&sigset, SIGBUS);\n#endif\n    pthread_sigmask(SIG_SETMASK, &sigset, NULL);\n    memset(&act, 0, sizeof(struct sigaction));\n    act.sa_handler = onas_clamonacc_exit;\n    sigfillset(&(act.sa_mask));\n    sigaction(SIGUSR2, &act, NULL);\n    sigaction(SIGTERM, &act, NULL);\n    sigaction(SIGSEGV, &act, NULL);\n    sigaction(SIGINT, &act, NULL);\n}\n\nAfter initializing the signal set so that it includes all signals with the `sigfillset` function, the code removes some of those signals from the set with `sigdelset`.\n\nAfter that, it uses the newly prepared `sigaction` structure named `act` to associate signals such as `SIGTERM` with the `onas_clamonacc_exit` function.\n\nReference: [sigfillset(3) man page](https://nxmnpg.lemoda.net/ja/3/sigfillset)\n\nWhen I actually debugged what happened after issuing `SIGTERM` with the `kill` command, I confirmed that `onas_clamonacc_exit` was called and the process terminated.\n\n![image-20241101230336454](../../static/media/2024-10-23-clamav-onaccess-scanning/image-20241101230336454.png)\n\n### Waiting for scan events\n\nIf execution reaches this point, the `onas_start_eloop` function is finally called to trigger the event loop.\n\nInside that function, `onas_fan_eloop` is executed in turn.\n\nA partial implementation of that function is shown below.\n\n``` c\ntime_t start = time(NULL) - 30;\n\nwhile (((bread = read((*ctx)->fan_fd, buf, sizeof(buf))) > 0) || (errno == EOVERFLOW || errno == EMFILE || errno == EACCES)) {\n\n    switch (errno) {\n        ***\n    }\n\n    fmd = (struct fanotify_event_metadata *)buf;\n    while (FAN_EVENT_OK(fmd, bread)) {\n        \n        ***\n\n        scan = 1;\n\n        ***\n    }\n}\n\nJust like in the sample code used earlier in this article, `fanotify_event_metadata` is read into `buf` from the file descriptor registered with fanotify, the `FAN_EVENT_OK` macro is used to validate the event, and then the `scan` flag is set to 1.\n\nAfter several additional checks, a variable of type `onas_scan_event` is initialized and populated.\n\nThe `onas_scan_event` structure stores information such as the file name obtained with the `readlink` function.\n\n``` c\nstruct onas_scan_event {\n    const char *tcpaddr;\n    int64_t portnum;\n    char *pathname;\n    int fan_fd;\n#if defined(HAVE_SYS_FANOTIFY_H)\n    struct fanotify_event_metadata *fmd;\n#endif\n    uint8_t retry_attempts;\n    uint64_t sizelimit;\n    int32_t scantype;\n    int64_t maxstream;\n    int64_t timeout;\n    uint8_t bool_opts;\n} __attribute((packed));\n\n\nif (scan) {\n    struct onas_scan_event *event_data;\n\n    event_data = cli_calloc(1, sizeof(struct onas_scan_event));\n    \n    ***\n\n    /* general mapping */\n    onas_map_context_info_to_event_data(*ctx, &event_data);\n    scan ? event_data->bool_opts |= ONAS_SCTH_B_SCAN : scan;\n\n    /* fanotify specific stuffs */\n    event_data->bool_opts |= ONAS_SCTH_B_FANOTIFY;\n    event_data->fmd = cli_malloc(sizeof(struct fanotify_event_metadata));\n    \n    ***\n           \n    memcpy(event_data->fmd, fmd, sizeof(struct fanotify_event_metadata));\n    event_data->pathname = cli_strdup(fname);\n    \n    ***\n\n    logg(\"*ClamFanotif: attempting to feed consumer queue\\n\");\n\n    /* feed consumer queue */\n    if (CL_SUCCESS != onas_queue_event(event_data)) {\n        close(fmd->fd);\n        free(event_data->pathname);\n        free(event_data->fmd);\n        free(event_data);\n        logg(\"!ClamFanotif: error occurred while feeding consumer queue ... \\n\");\n        if ((*ctx)->retry_on_error) {\n            err_cnt++;\n            if (err_cnt < (*ctx)->retry_attempts) {\n                logg(\"ClamFanotif: ... recovering ...\\n\");\n                fmd = FAN_EVENT_NEXT(fmd, bread);\n                continue;\n            }\n        }\n        return 2;\n    }\n}
\n

The event_data variable created here, which is a value of type onas_scan_event, is ultimately passed to the onas_queue_event function.

\n

Inside this function, it first acquires a lock using the pthread_mutex_t variable onas_queue_lock, which is defined as a global variable.

\n

It then appends a node to the queue list managed around the global variable g_onas_event_queue_tail and writes the event_data received as an argument into that node.

\n
cl_error_t onas_queue_event(struct onas_scan_event *event_data)\n{\n    struct onas_event_queue_node *node = NULL;\n    if (CL_EMEM == onas_new_event_queue_node(&node))\n        return CL_EMEM;\n\n    pthread_mutex_lock(&onas_queue_lock);\n    node->next                                                            = g_onas_event_queue_tail;\n    node->prev                                                            = g_onas_event_queue_tail->prev;\n    ((struct onas_event_queue_node *)g_onas_event_queue_tail->prev)->next = node;\n    g_onas_event_queue_tail->prev                                         = node;\n\n    node->data = event_data;\n\n    g_onas_event_queue.size++;\n\n    pthread_cond_signal(&onas_scan_queue_empty_cond);\n    pthread_mutex_unlock(&onas_queue_lock);\n\n    return CL_SUCCESS;\n}\n\nSo this appears to be the point where data containing information about the scan target is added to the queue.\n\n### Monitoring the scan queue\n\nAlthough the order is a bit reversed in this explanation, the following code is executed in the `main` function of `clamonacc.c` before `onas_setup_fanotif` performs the fanotify registration.\n\n/* Setup our event queue */\nctx->maxthreads = optget(ctx->clamdopts, \"OnAccessMaxThreads\")->numarg;\n\nswitch (onas_scan_queue_start(&ctx)) {\n    case CL_SUCCESS:\n        break;\n    case CL_BREAK:\n    case CL_EARG:\n    case CL_ECREAT:\n    default:\n        ret = 2;\n        logg(\"!Clamonacc: can't setup event consumer queue\\n\");\n        goto done;\n        break;\n}\n\nThe `onas_scan_queue_start` function called here starts a new thread with the `pthread_create` function.\n\nAt that time, the `onas_scan_queue_th` function is set as the thread's `start_routine`.\n\ncl_error_t onas_scan_queue_start(struct onas_context **ctx)\n{\n\n    pthread_attr_t scan_queue_attr;\n    int32_t thread_started = 1;\n\n    if (!ctx || !*ctx) {\n        logg(\"*ClamScanQueue: unable to start clamonacc. (bad context)\\n\");\n        return CL_EARG;\n    }\n\n    if (pthread_attr_init(&scan_queue_attr)) {\n        return CL_BREAK;\n    }\n    pthread_attr_setdetachstate(&scan_queue_attr, PTHREAD_CREATE_JOINABLE);\n    thread_started = pthread_create(&scan_queue_pid, &scan_queue_attr, onas_scan_queue_th, *ctx);\n\n    if (0 != thread_started) {\n        /* Failed to create thread */\n        logg(\"*ClamScanQueue: Unable to start event consumer queue thread ... \\n\");\n        return CL_ECREAT;\n    }\n\n    return CL_SUCCESS;\n}\n\nAs shown above, inside the `onas_scan_queue_th` function, signal handling is configured with `sigfillset` and `sigdelset`.\n\nThis seems to overlap partially with the behavior of the `onas_handle_signals` function introduced earlier. But I do not fully understand this area, so I do not know why `sigfillset` is also used on the `onas_scan_queue_th` side.\n\nWhen I attached a debugger, the call order of `onas_handle_signals` and `onas_scan_queue_th` appeared inconsistent, and in some cases `onas_handle_signals` seemed to be called first, so I am not entirely sure whether they interfere with each other.\n\nIf I learn the reason for this implementation later, I will add a note.\n\nAfter configuring signal handling, the `onas_init_event_queue` function initializes the `g_onas_event_queue` list of type `onas_event_queue` with size 0, and then the `onas_consume_event` function is executed in a loop.\n\n``` c\nvoid *onas_scan_queue_th(void *arg)\n{\n\n    /* not a ton of use for context right now, but perhaps in the future we can pass in more options */\n    struct onas_context *ctx = (struct onas_context *)arg;\n    sigset_t sigset;\n    int ret;\n\n    /* ignore all signals except SIGUSR2 */\n    sigfillset(&sigset);\n    sigdelset(&sigset, SIGUSR2);\n    /* The behavior of a process is undefined after it ignores a\n\t * SIGFPE, SIGILL, SIGSEGV, or SIGBUS signal */\n    sigdelset(&sigset, SIGFPE);\n    sigdelset(&sigset, SIGILL);\n    sigdelset(&sigset, SIGSEGV);\n    sigdelset(&sigset, SIGTERM);\n    sigdelset(&sigset, SIGINT);\n#ifdef SIGBUS\n    sigdelset(&sigset, SIGBUS);\n#endif\n\n    logg(\"*ClamScanQueue: initializing event queue consumer ... (%d) threads in thread pool\\n\", ctx->maxthreads);\n    onas_init_event_queue();\n    threadpool thpool = thpool_init(ctx->maxthreads);\n    g_thpool          = thpool;\n\n    /* loop w/ onas_consume_event until we die */\n    pthread_cleanup_push(onas_scan_queue_exit, NULL);\n    logg(\"*ClamScanQueue: waiting to consume events ...\\n\");\n    do {\n        onas_consume_event(thpool);\n    } while (1);\n\n    pthread_cleanup_pop(1);\n}\n\nThe `onas_consume_event` function pops an element from the `g_onas_event_queue` queue and passes it to the thread pool together with the `onas_scan_worker` task by using the `thpool_add_work` function.\n\nReference: [Pithikos/C-Thread-Pool: A minimal but powerful thread pool in ANSI C](https://github.com/Pithikos/C-Thread-Pool/tree/master)\n\n``` c\nstatic int onas_queue_is_b_empty()\n{\n\n    if (g_onas_event_queue.head->next == g_onas_event_queue.tail) {\n        return 1;\n    }\n\n    return 0;\n}\n\n\nstatic int onas_consume_event(threadpool thpool)\n{\n    pthread_mutex_lock(&onas_queue_lock);\n\n    while (onas_queue_is_b_empty()) {\n        pthread_cond_wait(&onas_scan_queue_empty_cond, &onas_queue_lock);\n    }\n\n    struct onas_event_queue_node *popped_node = g_onas_event_queue_head->next;\n    g_onas_event_queue_head->next             = g_onas_event_queue_head->next->next;\n    g_onas_event_queue_head->next->prev       = g_onas_event_queue_head;\n    g_onas_event_queue.size--;\n\n    pthread_mutex_unlock(&onas_queue_lock);\n\n    thpool_add_work(thpool, (void *)onas_scan_worker, (void *)popped_node->data);\n    onas_destroy_event_queue_node(popped_node);\n\n    return 1;\n}\n\nThe `onas_scan_worker` function performs the scan job after several conditional branches.\n\nIn the environment I am using for testing this time, it passes the event information retrieved from the queue to the `onas_scan_thread_handle_file` function.\n\n![image-20241102181444683](../../static/media/2024-10-23-clamav-onaccess-scanning/image-20241102181444683.png)\n\nAfter doing some simple checks and obtaining file information, the `onas_scan_thread_handle_file` function passes the initialized `infected` variable and related values to the `onas_scan_thread_scanfile` function.\n\n``` c\nret = onas_scan_thread_scanfile(event_data, curr->fts_path, sb, &infected, &err, &ret_code);
\n

The onas_scan_thread_scanfile function then calls onas_scan -> onas_scan_safe -> onas_client_scan, and eventually executes the onas_dsresult function, which issues the scan request to clamd and obtains the scan result.

\n
onas_scan(event_data, fname, sb, infected, err, ret_code);\n↓\n    \nonas_scan_safe(event_data, fname, sb, infected, err, ret_code);\n\n↓\n    \nonas_client_scan(event_data->tcpaddr, event_data->portnum, event_data->scantype, event_data->maxstream,fname, fd, event_data->timeout, sb, infected, err, ret_code);\n\n↓\n    \nif ((ret = onas_dsresult(curl, scantype, maxstream, fname, fd, timeout, &ret, err, ret_code)) >= 0) {\n    *infected = ret;\n}
\n

Inside the onas_scan_thread_scanfile function, the final decision about whether the target file should be accessible is made based on the scan result received from clamd.

\n

If the scan determines that the target file is malware, the following code sets the response member of the fanotify_response structure to FAN_DENY.

\n
if (b_fanotify) {\n    if ((*err && *ret_code && b_deny_on_error) || *infected) {\n        res.response = FAN_DENY;\n    }\n}
\n

With that, if the target file is detected, fanotify blocks access to the file.

\n

By the way, if the fanotify access mask is left as FAN_OPEN_PERM, I cannot make much progress when debugging fanotify itself, so this time I modified the code to use print-based debugging instead.

\n

\n \n \n \n \n \n \n \n \n

\n

When I actually tested detection of Eicar with On-Access scanning in my test environment, the code above executed as shown below, and I confirmed that access was denied via FAN_DENY.

\n

\n \n