comments; sanity

Co-authored-by: anurag <[email protected]>

Author: kanurag94

README.md

@@ -3,15 +3,21 @@
 ebpf based Filemonitoring
 
 ```
-usage: filemonitor.py [-h] [-f FILE]
+usage: filemonitor.py [-h] [-f FILE] [-r] [-w] [-p] [-c] [-d]
 
 Monitors file actions
 
 optional arguments:
   -h, --help            show this help message and exit
   -f FILE, --file FILE  give config filepath
+  -r, --read            trace read events
+  -w, --write           trace write events
+  -p, --rename          trace rename events
+  -c, --create          trace create events
+  -d, --delete          trace delete events
 
-Usage:
-    ./filemonitor                       # traces /var/log/syslog
-    ./filemonitor -f /path/to/config    # pass a file with new line separated filepaths to monitor 
+Example:
+    ./filemonitor -r                         # traces read of /var/log/syslog
+    ./filemonitor -f /path/to/config         # traces filepaths in path for all events
+    ./filemonitor -f /path/to/config -d      # traces filepaths in path for delete events
 ```

cli.py

@@ -1,6 +1,7 @@
 import argparse
 from distutils.command.config import config
 
+# sample_config traces /var/log/syslog
 sample_config = "config.txt"
 
 try:
@@ -9,12 +10,24 @@
 except:
     pass
 
-examples = """Usage:
-    ./filemonitor                       # traces /var/log/syslog
-    ./filemonitor -f /path/to/config    # pass a file with new line separated filepaths to monitor 
+examples = """
+Example:
+    ./filemonitor -r                         # traces read of /var/log/syslog
+    ./filemonitor -f /path/to/config         # traces filepaths in path for all events
+    ./filemonitor -f /path/to/config -d      # traces filepaths in path for delete events
 """
 parser = argparse.ArgumentParser(
     description="Monitors file actions",
     formatter_class=argparse.RawDescriptionHelpFormatter,
     epilog=examples)
-parser.add_argument("-f", "--file", default=sample_config, help="give config filepath")
+parser.add_argument("-f", "--file", default=sample_config, help="give config filepath")
+parser.add_argument("-r", "--read", action="store_true", help="trace read events")
+parser.add_argument("-w", "--write", action="store_true", help="trace write events")
+parser.add_argument("-p", "--rename", action="store_true", help="trace rename events")
+parser.add_argument("-c", "--create", action="store_true", help="trace create events")
+parser.add_argument("-d", "--delete", action="store_true", help="trace delete events")
+
+def noflags(args):
+    if(args.read or args.write or args.rename or args.create or args.delete):
+        return False
+    return True

filemonitor.c

@@ -15,6 +15,8 @@ struct data_t {
 BPF_HASH(inodemap, u32, u32);
 BPF_PERF_OUTPUT(events);
 
+// common function takes dentry and operation name as arguments
+// looks up if inode exists in "inodemap" then trace and send event update
 static int common(struct pt_regs *ctx, struct dentry *de, char *OPRN) {
     if (de->d_name.len == 0) return 0;
 
@@ -45,7 +47,8 @@ static int common(struct pt_regs *ctx, struct dentry *de, char *OPRN) {
         return 0;
 }
 
-
+// trace_read function takes file, buffer and size as arguments
+// this is attached to file read (vfs_read) events
 int trace_read(struct pt_regs *ctx, struct file *file,
     char __user *buf, size_t count)
 {
@@ -55,6 +58,8 @@ int trace_read(struct pt_regs *ctx, struct file *file,
     return common(ctx, file->f_path.dentry, OPRN);
 }
 
+// trace_write function takes file, buffer and size as arguments
+// this is attached to file write (vfs_read) events
 int trace_write(struct pt_regs *ctx, struct file *file,
     char __user *buf, size_t count)
 {
@@ -64,6 +69,9 @@ int trace_write(struct pt_regs *ctx, struct file *file,
     return common(ctx, file->f_path.dentry, OPRN);
 }
 
+// trace_rename function takes old directory inode,
+// old dentry, new directory inode, new dentry as arguments
+// this is attached to file rename (vfs_rename) events
 int trace_rename(struct pt_regs *ctx, struct inode *old_dir,
  struct dentry *old_dentry, struct inode *new_dir,
  struct dentry *new_dentry)
@@ -72,21 +80,27 @@ int trace_rename(struct pt_regs *ctx, struct inode *old_dir,
     return common(ctx, old_dentry, OPRN);
 }
 
+// trace_write function takes old directory inode, dentry as arguments
+// this is attached to file create (security_inode_create) events
+// vfs_create is not fired by kernel > 4.8
 int trace_create(struct pt_regs *ctx, struct inode *dir, struct dentry *dentry)
 {
     char OPRN[10] = "CREATE";
     return common(ctx, dentry, OPRN);
 };
 
+// trace_write function takes old directory inode, dentry as arguments
+// this is attached to file unlinking(vfs_unlink) events to trace before deletion
 int trace_delete(struct pt_regs *ctx, struct inode *dir, struct dentry *dentry)
 {
     char OPRN[10] = "DELETE";
     return common(ctx, dentry, OPRN);
 }
 
 /*
-// KRETFUNC_PROBE function is triggered on process creation
+// KRETFUNC_PROBE probe is triggered on process creation
 // Linking it with file operation is hackish
+// TODO: Link with file events
 KRETFUNC_PROBE(__x64_sys_openat, struct pt_regs *regs, int ret)
 {
     struct data_t data = {};
@@ -101,4 +115,4 @@ KRETFUNC_PROBE(__x64_sys_openat, struct pt_regs *regs, int ret)
     events.perf_submit(ctx, &data, sizeof(data));
     return 0;
 }
-*/
+*/

filemonitor.py

@@ -1,6 +1,7 @@
 #!/usr/bin/python
 
 from __future__ import print_function
+import json
 from bcc import BPF
 from ctypes import c_uint32
 
@@ -12,6 +13,7 @@
 
 BPF_C_PROG = "filemonitor.c"
 
+# initialize global variables
 def init():
     global BPF_C_PROG
     try:
@@ -20,6 +22,8 @@ def init():
     except:
         pass
 
+# update_inodemap function takes BPFHASH inodemap, config file as arguments
+# reads config file, finds the inode and updates inodemap
 def update_inodemap(inodemap, config_file):
     if not config_file:
         raise FileNotFoundError
@@ -30,9 +34,12 @@ def update_inodemap(inodemap, config_file):
         inode_id = get_inode_from_filepath(filepath.strip())
         if inode_id != "":
             inodemap[c_uint32(int(inode_id))] = c_uint32(int(inode_id))
-          
+
+# main function reads args and attaches bpf program
+# prints output of bpf events
 def main():
     args = cli.parser.parse_args()
+    noflags = cli.noflags(args)
 
     try:
         # initialize bpf program
@@ -43,11 +50,16 @@ def main():
         update_inodemap(b["inodemap"], args.file)
 
         # attach probes
-        b.attach_kprobe(event="vfs_read", fn_name="trace_read")
-        b.attach_kprobe(event="vfs_write", fn_name="trace_write")
-        b.attach_kprobe(event="vfs_rename", fn_name="trace_rename")
-        b.attach_kprobe(event="security_inode_create", fn_name="trace_create")
-        b.attach_kprobe(event="vfs_unlink", fn_name="trace_delete")
+        if noflags or args.read:
+            b.attach_kprobe(event="vfs_read", fn_name="trace_read")
+        if noflags or args.write:
+            b.attach_kprobe(event="vfs_write", fn_name="trace_write")
+        if noflags or args.rename:
+            b.attach_kprobe(event="vfs_rename", fn_name="trace_rename")
+        if noflags or args.create:
+            b.attach_kprobe(event="security_inode_create", fn_name="trace_create")
+        if noflags or args.delete:
+            b.attach_kprobe(event="vfs_unlink", fn_name="trace_delete")
 
         # header
         print("%-6s %-4s %-4s %-32s %-32s %-32s %-4s" % ("PID", "UID", "CPU", "PROC", "FPATH", "COMM", "OPRN"))
@@ -70,7 +82,8 @@ def print_event(cpu, data, size):
     except Exception as e:
         print("Exception occured, Are you root? Is BPF installed?", e)
 
-
+# get_inode_from_filepath takes a filepath as argument
+# and returns inode associated with that file path
 def get_inode_from_filepath(filepath):
   cmd = f'ls {filepath} 2>&1 1>/dev/null && ls -i {filepath}'
   cmd += ' | awk \'{print $1}\''
@@ -81,6 +94,7 @@ def get_inode_from_filepath(filepath):
   except:
       return ""
 
+# starts program
 if __name__ == "__main__":
     init()
     main()