{"id":23359865,"url":"https://github.com/ait-aecid/rootkit-detection-ebpf-time-trace","last_synced_at":"2025-04-10T10:32:06.384Z","repository":{"id":263406196,"uuid":"877895022","full_name":"ait-aecid/rootkit-detection-ebpf-time-trace","owner":"ait-aecid","description":"Detection of rootkit file hiding activities through analysis of shifts in kernel function execution times.","archived":false,"fork":false,"pushed_at":"2025-03-07T14:34:27.000Z","size":186,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T09:21:10.861Z","etag":null,"topics":["anomaly","anomaly-detection","ebpf","hids","intrusion-detection","kernel-tracing","machine-learning","rootkit-detection","rootkits","semi-supervised"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ait-aecid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-24T12:33:42.000Z","updated_at":"2025-03-07T14:34:31.000Z","dependencies_parsed_at":"2024-11-18T11:57:17.248Z","dependency_job_id":"6cd77356-022c-493e-a826-5fcca6ef89dd","html_url":"https://github.com/ait-aecid/rootkit-detection-ebpf-time-trace","commit_stats":null,"previous_names":["ait-aecid/rootkit-detection-ebpf-time-trace"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ait-aecid%2Frootkit-detection-ebpf-time-trace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ait-aecid%2Frootkit-detection-ebpf-time-trace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ait-aecid%2Frootkit-detection-ebpf-time-trace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ait-aecid%2Frootkit-detection-ebpf-time-trace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ait-aecid","download_url":"https://codeload.github.com/ait-aecid/rootkit-detection-ebpf-time-trace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248199136,"owners_count":21063641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anomaly","anomaly-detection","ebpf","hids","intrusion-detection","kernel-tracing","machine-learning","rootkit-detection","rootkits","semi-supervised"],"created_at":"2024-12-21T11:12:12.014Z","updated_at":"2025-04-10T10:32:06.377Z","avatar_url":"https://github.com/ait-aecid.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rootkit Detection with eBPF Time Tracing\n\nThis repository contains code to collect time measurements of kernel functions that are manipulated by rootkits when they hide files, as well as a semi-supervised detection method that analyzes shifts of kernel function execution times. This implementation relies on the open-source rootkit [CARAXES](https://github.com/ait-aecid/caraxes), which wraps the filldir function to manipulate the outcomes of file enumerations, e.g., when executing the `ls` command. Time measurements are taken from several functions in the getdents system call (including filldir) using eBPF probes. For detection we apply a simple machine learning model based on statistical testing. We refer to the following publication for detailed explanations of data collection and anomaly detection mechanisms. If you use any of the resources provided in this repository, please cite the following publication:\n* Landauer, M., Alton, L., Lindorfer, M., Skopik, F., Wurzenberger, M., \u0026 Hotwagner, W. (2025). Trace of the Times: Rootkit Detection through Temporal Anomalies in Kernel Activity. Under Review.\n\n## Rootkit and eBPF probing\n\nThe following steps setup up the rootkit and explain how to collect time measurements from kernel functions. In case that you are only interested in the detection of anomalies and want to use our public data sets, you can skip this section.\n\n### Setup\n\nThe rootkit and probing has been tested on Linux kernels 5.15-6.11 and Python 3.10. To run the tools, download this repository and install the following dependencies required to run the rootkit and probing mechanism.\n\n```sh\nubuntu@ubuntu:~$ git clone https://github.com/ait-aecid/rootkit-detection-ebpf-time-trace.git\nubuntu@ubuntu:~$ cd rootkit-detection-ebpf-time-trace\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ sudo apt update\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ sudo apt install python3-bpfcc make gcc flex bison python3-pip linux-headers-$(uname -r)\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ pip install -r requirements.txt\n```\n\nSome scenarios require additional resources. Specifically, the ls-basic scenario requires to compile the ls-basic script and the system load scenario requires to install stress-ng. If you do not want to use these scenarios, you can skip the following dependencies.\n\n```sh\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ gcc -o ls-basic ls-basic.c\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ sudo apt install stress-ng\n```\n\nThe following commands are mandatory, because the rootkit manipulates the getdents system call by default, however, only manipulation of filldir is currently supported for probing. Download the rootkit, replace `hooks.h` with the file provided in this repository (this ensures that filldir is hooked rather than getdents), and compile the rootkit.\n\n```sh\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ cd ..\nubuntu@ubuntu:~$ git clone https://github.com/ait-aecid/caraxes.git\nubuntu@ubuntu:~$ cd caraxes/\nubuntu@ubuntu:~/caraxes$ cp ../rootkit-detection-ebpf-time-trace/hooks.h .\nubuntu@ubuntu:~/caraxes$ sudo make\n```\n\nIf you have troubles installing the rootkit or want to test if it works as expected, check out the ReadMe on the [CARAXES](https://github.com/ait-aecid/caraxes) github page.\n\nAfterwards, return to this repository and open `linux.py` to edit the variable `KERNEL_OBJECT_PATH` so that it points to the caraxes folder that you just cloned; the default path is `\"/home/ubuntu/caraxes/\"`.\n\n```sh\nubuntu@ubuntu:~/caraxes$ cd ../rootkit-detection-ebpf-time-trace\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ vim linux.py\n```\n\n### Measurement of kernel function timings\n\nNow you are ready to run the probing mechanism that will automatically inject probes into the kernel, start the rootkit, store time measurement data into a file, and stop the rootkit. To trigger system calls, the script thereby creates a directory with files to be hidden and executes `ls` 100 times (can be modified with the `-i` flag) while polling the probes. The script allows to collect measurments with the rootkit (`--rootkit` flag), without the rootkit (`--normal` flag), or both, and supports several scenarios. Run the default scenario with the following command:\n\n```sh\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ sudo python3 probing.py --normal --rootkit\ncompiling eBPF probes...\nprobes compiled!\n\nattached bpf probes:\niterate_dir-enter\niterate_dir-return\ndcache_readdir-enter\ndcache_readdir-return\nfilldir64-enter\nfilldir64-return\nverify_dirent_name-enter\nverify_dirent_name-return\ntouch_atime-enter\ntouch_atime-return\n\nRunning experiment with ls for 100 times.\nIteration 0...\ndetection_PID: 70133\nIteration 1...\ndetection_PID: 70134\n...\nIteration 99...\ndetection_PID: 70338\npolled 40 times!\ndone with the \"rootkit version\"\nExperiment finished, saving output.\nSaved data to events/events_2025-01-17T09:59:52.183801_rootkit.json.gz\n412K    events/events_2025-01-17T09:59:52.183801_rootkit.json.gz\n```\n\nMeasurements are stored in the `events` directory. Check out the help page with `python3 probing.py -h` to learn about other parameters that allow to set up data collection in other scenarios (e.g., using `ls-basic` instead of `ls` or simulating system load) and assign names to different runs (`--description`). Check out `repeat_seq.sh` for some parameterized commands; in fact, we used this script to collect our public data sets. Note that we only consider some of the available kernel functions from the getdents system call. To specify which functions the probing mechanism should attach probes to, open `probing.py` and add or remove function names in the `probe_points` list in the beginning of the file. \n\n## Anomaly detection\n\nRunning the anomaly detection algorithm only requires to install the python dependencies. If you have not done so already in the previous step, run the following command to install the requirements with pip.\n\n```sh\nubuntu@ubuntu:~$ git clone https://github.com/ait-aecid/rootkit-detection-ebpf-time-trace.git\nubuntu@ubuntu:~$ cd rootkit-detection-ebpf-time-trace\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ pip install -r requirements.txt\n```\n\nThen, download and extract the data set we provide on [Zenodo](https://zenodo.org/records/14679675). If you generated your own data in the previous step and want to use it, skip this step.\n\n```sh\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ wget https://zenodo.org/records/14679675/files/events.zip\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ unzip events.zip\n```\n\nNow you are ready to run the anomaly detection as follows. Specify the directory containing measurement data (`-d`), the fration of normal data used for training (`-t`), the mode of operation (`-m`) and the grouping function (`-g`). The script will load all files from the specified directory, split them into training and testing data (summarized in the output), compute and print detection metrics, and plot a confusion matrix.\n\n```sh\nubuntu@ubuntu:~/rootkit-detection-ebpf-time-trace$ python3 evaluate.py -d events -t 0.333 -m offline -g fun\n100%|█████████████████████████████████████████████| 1250/1250 [02:47\u003c00:00,  7.45it/s]\nProcessed all files from events\n\nNormal batches: 750\n  Normal batches for training: 250\n    default: 50\n    file_count: 50\n    system_load: 50\n    ls_basic: 50\n    filename_length: 50\n  Normal batches for testing: 500\n    default: 100\n    file_count: 100\n    system_load: 100\n    ls_basic: 100\n    filename_length: 100\nAnomalous batches: 500\n  default: 100\n  file_count: 100\n  system_load: 100\n  ls_basic: 100\n  filename_length: 100\n\nResults (Run 1)\n Threshold=3.5111917342151415e-16\n Time=0.0027740001678466797\n TP=499\n FP=9\n TN=491\n FN=1\n TPR=R=0.998\n FPR=0.018\n TNR=0.982\n P=0.9822834645669292\n F1=0.9900793650793651\n ACC=0.99\n MCC=0.9801254640896192\n\nConfusion Matrix (Run 1)\nPredicted\ndefault     file_count  system_load ls_basic    filename_length\nPos   Neg   Pos   Neg   Pos   Neg   Pos   Neg   Pos   Neg\n100   0     100   0     100   0     100   0     100   0      Pos - Actual default\n3     97    100   0     99    1     100   0     2     98     Neg - Actual default\n100   0     100   0     100   0     100   0     100   0      Pos - Actual file_count\n100   0     0     100   100   0     100   0     100   0      Neg - Actual file_count\n100   0     100   0     100   0     100   0     100   0      Pos - Actual system_load\n100   0     100   0     4     96    100   0     100   0      Neg - Actual system_load\n100   0     100   0     100   0     99    1     100   0      Pos - Actual ls_basic\n100   0     100   0     100   0     2     98    100   0      Neg - Actual ls_basic\n99    1     100   0     100   0     100   0     100   0      Pos - Actual filename_length\n3     97    100   0     99    1     100   0     0     100    Neg - Actual filename_length\n```\n\nCheck out the manual using `python3 evaluate.py -h` to learn more about available parameters of this script. Also, have a look at `demo.sh` to see the parameterized commands that we used for the evaluation in our paper.\n\n# Citation\n\nIf you use any of the resources provided in this repository, please cite the following publication:\n* Landauer, M., Alton, L., Lindorfer, M., Skopik, F., Wurzenberger, M., \u0026 Hotwagner, W. (2025). Trace of the Times: Rootkit Detection through Temporal Anomalies in Kernel Activity. Under Review.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fait-aecid%2Frootkit-detection-ebpf-time-trace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fait-aecid%2Frootkit-detection-ebpf-time-trace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fait-aecid%2Frootkit-detection-ebpf-time-trace/lists"}