{"id":13840309,"url":"https://github.com/linux-lock/bpflock","last_synced_at":"2025-04-12T02:50:32.181Z","repository":{"id":43831585,"uuid":"393625888","full_name":"linux-lock/bpflock","owner":"linux-lock","description":"bpflock - eBPF driven security for locking and auditing Linux machines","archived":false,"fork":false,"pushed_at":"2022-02-16T21:30:06.000Z","size":5216,"stargazers_count":146,"open_issues_count":3,"forks_count":14,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-25T22:22:45.971Z","etag":null,"topics":["bpf","containers","ebpf","iot","iot-security","kernel","kubernetes","lsm","security"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linux-lock.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}},"created_at":"2021-08-07T08:29:04.000Z","updated_at":"2025-03-05T21:08:14.000Z","dependencies_parsed_at":"2022-08-12T10:50:30.714Z","dependency_job_id":null,"html_url":"https://github.com/linux-lock/bpflock","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-lock%2Fbpflock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-lock%2Fbpflock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-lock%2Fbpflock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linux-lock%2Fbpflock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linux-lock","download_url":"https://codeload.github.com/linux-lock/bpflock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248509152,"owners_count":21115951,"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":["bpf","containers","ebpf","iot","iot-security","kernel","kubernetes","lsm","security"],"created_at":"2024-08-04T17:00:45.539Z","updated_at":"2025-04-12T02:50:32.155Z","avatar_url":"https://github.com/linux-lock.png","language":"C","funding_links":[],"categories":["Projects Related to eBPF","eBPF 相关项目","C"],"sub_categories":["Security","安全"],"readme":"# bpflock - Lock Linux machines\n\n![Bpflock Logo](docs/images/bpflock-logo-small.png)\n\nbpflock - eBPF driven security for locking and auditing Linux machines.\n\nNote: bpflock is currently in **experimental stage**, it may break, options and security semantics may change, some BPF programs will be updated to use [Cilium ebpf library](https://github.com/cilium/ebpf/).\n\n## Sections\n\n* [1. Introduction](https://github.com/linux-lock/bpflock#1-introduction)\n* [2. Functionality Overview](https://github.com/linux-lock/bpflock#2-functionality-overview)\n  - [2.1 Security features](https://github.com/linux-lock/bpflock#21-security-features)\n  - [2.2 Semantics](https://github.com/linux-lock/bpflock#12-semantics)\n* [3. Deployment](https://github.com/linux-lock/bpflock#2-deployment)\n* [4. Documentation](https://github.com/linux-lock/bpflock#3-documentation)\n* [5. Build](https://github.com/linux-lock/bpflock#3-build)\n\n## 1. Introduction\n\nbpflock uses [eBPF](https://ebpf.io/) to strength Linux security. By restricting access to a various range of Linux features, bpflock is able to reduce the attack surface and block some well known attack techniques.\n\nOnly programs like container managers, systemd and other containers/programs that run in the host [pid and network namespaces](https://man7.org/linux/man-pages/man7/namespaces.7.html) are allowed access to full\nLinux features, containers and applications that run on their own namespace will be restricted.\nIf bpflock bpf programs run under the `restricted` profile then all programs/containers including privileged\nones will have their access denied.\n\nbpflock protects Linux machines by taking advantage of multiple security features including [Linux Security Modules + BPF](https://docs.kernel.org/bpf/prog_lsm.html).\n\nArchitecture and Security design notes:\n- bpflock is not a mandatory access control labeling solution, and it does not intent to replace\n[AppArmor](https://apparmor.net/), [SELinux](https://github.com/SELinuxProject/selinux), and other MAC solutions.\nbpflock uses a simple declarative security profile.\n- bpflock offers multiple small bpf programs that can be reused in multiple contexts from Cloud Native deployments to Linux IoT devices.\n- bpflock is able to restrict root from accessing certain Linux features, however it does not protect against evil root.\n\n## 2. Functionality Overview\n\n### 2.1 Security features\n\nbpflock offer multiple security protections that can be classified as:\n\n* [Memory Protections](https://github.com/linux-lock/bpflock/tree/main/docs/memory-protections.md)\n  - [Kernel Image Lock-down](https://github.com/linux-lock/bpflock/tree/main/docs/memory-protections.md#1-kernel-image-lock-down)\n  - [Kernel Modules Protection](https://github.com/linux-lock/bpflock/tree/main/docs/memory-protections.md#2-kernel-modules-protection)\n  - [BPF Protection](https://github.com/linux-lock/bpflock/tree/main/docs/memory-protections.md#3-bpf-protection)\n\n* [Process Protections](https://github.com/linux-lock/bpflock/tree/main/docs/process-protections.md)\n  - [Fileless Memory Execution](https://github.com/linux-lock/bpflock/tree/main/docs/process-protections.md#fileless-memory-execution)\n  - Namespaces protection\n\n* [Hardware Addition Attacks](https://github.com/linux-lock/bpflock/tree/main/docs/hardware-additions.md)\n  - [USB Additions Protection](https://github.com/linux-lock/bpflock/tree/main/docs/hardware-additions.md#1-usb-additions-protection)\n\n* [System and Application tracing](https://github.com/linux-lock/bpflock/tree/main/docs/system-and-application-tracing.md)\n  - [Trace Application Execution](https://github.com/linux-lock/bpflock/tree/main/docs/system-and-application-tracing.md#trace-application-execution)\n  - Trace Privileged System Operations\n\n* Filesystem Protections\n  - Read-only root filesystem protection\n  - sysfs protection\n\n* Network protections\n\n  - bpflock may include in future a simple network protection that can be used in single machine workload or Linux-IoT, but will not include a Cloud Native protection. [Cilium](https://github.com/cilium/cilium) and other kubernetes CNI related solutions are by far better.\n\n### 2.2 Semantics\n\nbpflock keeps the security semantics simple. It support three **global** profiles to broadly cover the security sepctrum, and restrict access to specific Linux features.\n\n* `profile`: this is the global profile that can be applied per bpf program, it takes one of the followings:\n  - `allow|none|privileged` : they are the same, they define the least secure profile. In this profile access is logged and allowed for all processes. Useful to log security events.\n  - `baseline` : restrictive profile where access is denied for all processes, except privileged applications and containers that run in the host namespaces, or per cgroup allowed profiles in the `bpflock_cgroupmap` bpf map.\n  - `restricted` : heavily restricted profile where access is denied for all processes.\n\n* `Allowed` or `blocked` operations/commands:\n\n  Under the `allow|privileged` or `baseline` profiles, a list of allowed or blocked commands can be specified and will be applied.\n  - `--protection-allow` : comma-separated list of allowed operations. Valid under `baseline` profile, this is useful for applications that are too specific and perform privileged operations. It will reduce the use of the `allow | privileged` profile, so instead of using the `privileged` profile, we can specify the `baseline` one and add a set of allowed commands to offer a case-by-case definition for such applications.\n  - `--protection-block` : comma-separated list of blocked operations. Valid under `allow|privileged` and `baseline` profiles, it allows to restrict access to some features without using the full `restricted` profile that might break some specific applications. Using `baseline` or `privileged` profiles opens the gate to access most Linux features, but with the `--protection-block` option some of this access can be blocked.\n\nFor bpf security examples check [bpflock configuration examples](https://github.com/linux-lock/bpflock/tree/main/deploy/configs/)\n\n\n## 3. Deployment\n\n### 3.1 Prerequisites\n\nbpflock needs the following:\n\n* Linux kernel version \u003e= 5.13 with the following configuration:\n\n  ```code\n  CONFIG_BPF_SYSCALL=y\n  CONFIG_DEBUG_INFO=y\n  CONFIG_DEBUG_INFO_BTF=y\n  CONFIG_KPROBES=y\n  CONFIG_LSM=\"...,bpf\"\n  CONFIG_BPF_LSM=y\n  ```\n\n* Obviously a BTF enabled kernel.\n\n#### Enable BPF LSM support\n\nIf your kernel was compiled with `CONFIG_BPF_LSM=y` check the `/boot/config-*` to confirm, but when running bpflock it fails with:\n\n```\nmust have a kernel with 'CONFIG_BPF_LSM=y' 'CONFIG_LSM=\\\"...,bpf\\\"'\"\n```\n\nThen to enable BPF LSM as an example on Ubuntu:\n\n  1. Open the /etc/default/grub file as privileged of course.\n  2. Append the following to the `GRUB_CMDLINE_LINUX` variable and save.\n     ```\n     \"lsm=lockdown,capability,yama,apparmor,bpf\"\n     ```\n     or\n     ```\n     GRUB_CMDLINE_LINUX=\"lsm=lockdown,capability,yama,apparmor,bpf\"\n     ```\n  3. Update grub config with:\n     ```bash\n     sudo update-grub2\n     ```\n  4. Reboot into your kernel.\n\n\n### 3.2 Docker deployment\n\nTo run using the default `allow` or `privileged` profile (the least secure profile):\n```bash\ndocker run --name bpflock -it --rm --cgroupns=host \\\n  --pid=host --privileged \\\n  -v /sys/kernel/:/sys/kernel/ \\\n  -v /sys/fs/bpf:/sys/fs/bpf linuxlock/bpflock\n```\n\n#### Fileless Binary Execution\n\nTo log and restict [fileless binary execution](https://github.com/linux-lock/bpflock/tree/main/docs/process-protections.md#fileless-memory-execution) run with:\n\n```bash\ndocker run --name bpflock -it --rm --cgroupns=host --pid=host --privileged \\\n  -e \"BPFLOCK_FILELESSLOCK_PROFILE=restricted\" \\\n  -v /sys/kernel/:/sys/kernel/ \\\n  -v /sys/fs/bpf:/sys/fs/bpf linuxlock/bpflock\n```\n\nWhen running under `restricted` profile, the container logs will display:\n```\ntime=\"2022-02-04T14:54:33Z\" level=info msg=\"event=syscall_execve tgid=1833 pid=1833 ppid=1671 uid=1000 cgroupid=8821 comm=loader pcomm=bash filename=./loader retval=0\" bpfprog=execsnoop subsys=bpf\n\ntime=\"2022-02-04T14:54:33Z\" level=info msg=\"event=lsm_bprm_creds_from_file tgid=1833 pid=1833 ppid=1671 uid=1000 cgroupid=8821 comm=loader pcomm=bash filename=memfd:memfd-test retval=-1 reason=denied (restricted)\" bpfprog=filelesslock subsys=bpf\n\ntime=\"2022-02-04T14:54:33Z\" level=info msg=\"event=syscall_execve tgid=1833 pid=1833 ppid=0 uid=1000 cgroupid=8821 comm= pcomm= filename=/proc/self/fd/3 retval=-1\" bpfprog=execsnoop subsys=bpf\n```\n\nRunning under the `restricted` profile may break things, this is why the default profile is `allow`.\n\n#### Kernel Modules Protection\n\nTo apply [Kernel Modules Protection](https://github.com/linux-lock/bpflock/tree/main/docs/memory-protections.md#2-kernel-modules-protection)\nrun with environment variable `BPFLOCK_KMODLOCK_PROFILE=baseline` or `BPFLOCK_KMODLOCK_PROFILE=restricted`:\n```bash\ndocker run --name bpflock -it --rm --cgroupns=host --pid=host --privileged \\\n  -e \"BPFLOCK_KMODLOCK_PROFILE=restricted\" \\\n  -v /sys/kernel/:/sys/kernel/ \\\n  -v /sys/fs/bpf:/sys/fs/bpf linuxlock/bpflock\n```\n\nExample:\n```bash\n$ sudo unshare -p -n -f\n# modprobe xfs\nmodprobe: ERROR: could not insert 'xfs': Operation not permitted\n```\n\n```\ntime=\"2022-02-07T06:50:25+01:00\" level=info msg=\"event=syscall_execve tgid=52323 pid=52323 ppid=52288 uid=0 cgroupid=7014 comm=modprobe pcomm=bash filename=/usr/sbin/modprobe retval=0\" bpfprog=execsnoop subsys=bpf\n\ntime=\"2022-02-07T06:50:25+01:00\" level=info msg=\"event=lsm_kernel_read_file operation=loading module tgid=52323 pid=52323 ppid=52288 uid=0 cgroupid=7014 comm=modprobe pcomm=bash filename=xfs.ko retval=-1 reason=denied (restricted)\" bpfprog=kmodlock subsys=bpf\n```\n\n#### Kernel Image Lock-down\n\nTo apply [Kernel Image Lock-down](https://github.com/linux-lock/bpflock/tree/main/docs/memory-protections.md#1-kernel-image-lock-down) run with environment variable `BPFLOCK_KIMGLOCK_PROFILE=baseline`:\n```bash\ndocker run --name bpflock -it --rm --cgroupns=host --pid=host --privileged \\\n  -e \"BPFLOCK_KIMGLOCK_PROFILE=baseline\" \\\n  -v /sys/kernel/:/sys/kernel/ \\\n  -v /sys/fs/bpf:/sys/fs/bpf linuxlock/bpflock\n```\n\n```bash\n$ sudo unshare -f -p -n bash\n# head -c 1 /dev/mem\nhead: cannot open '/dev/mem' for reading: Operation not permitted\n```\n\n```\ntime=\"2022-02-07T06:57:22+01:00\" level=info msg=\"event=syscall_execve tgid=52428 pid=52428 ppid=52288 uid=0 cgroupid=7014 comm=head pcomm=bash filename=/usr/bin/head retval=0\" bpfprog=execsnoop subsys=bpf\n\ntime=\"2022-02-07T06:57:22+01:00\" level=info msg=\"event=lsm_locked_down operation=/dev/mem,kmem,port tgid=52428 pid=52428 ppid=52288 uid=0 cgroupid=7014 comm=head pcomm=bash retval=-1 reason=denied (baseline)\" bpfprog=kimglock subsys=bpf\n```\n\n#### BPF Protection\n\nTo apply [bpf restriction](https://github.com/linux-lock/bpflock/tree/main/docs/memory-protections.md#3-bpf-protection) run with environment variable `BPFLOCK_BPFRESTRICT_PROFILE=baseline` or `BPFLOCK_BPFRESTRICT_PROFILE=restricted`:\n```bash\ndocker run --name bpflock -it --rm --cgroupns=host --pid=host --privileged \\\n  -e \"BPFLOCK_BPFRESTRICT_PROFILE=baseline\" \\\n  -v /sys/kernel/:/sys/kernel/ \\\n  -v /sys/fs/bpf:/sys/fs/bpf linuxlock/bpflock\n```\n\nExample running in a different pid and network namespaces and using [bpftool](https://github.com/libbpf/bpftool):\n```bash\n$ sudo unshare -f -p -n bash\n# bpftool prog\nError: can't get next program: Operation not permitted\n```\n\n```\ntime=\"2022-02-04T15:40:56Z\" level=info msg=\"event=lsm_bpf tgid=2378 pid=2378 ppid=2364 uid=0 cgroupid=9458 comm=bpftool pcomm=bash filename= retval=-1 reason=baseline\" bpfprog=bpfrestrict subsys=bpf\n\ntime=\"2022-02-04T15:40:56Z\" level=info msg=\"event=lsm_bpf tgid=2378 pid=2378 ppid=2364 uid=0 cgroupid=9458 comm=bpftool pcomm=bash filename= retval=-1 reason=baseline\" bpfprog=bpfrestrict subsys=bpf\n```\n\nRunning with the `-e \"BPFLOCK_BPFRESTRICT_PROFILE=restricted\"` profile will deny bpf for all:\n```\ntime=\"2022-02-04T15:44:13Z\" level=info msg=\"event=syscall_execve tgid=2500 pid=2500 ppid=2499 uid=0 cgroupid=9458 comm=bpftool pcomm=sudo filename=./tools/amd64/bpftool retval=0\" bpfprog=execsnoop subsys=bpf\n\ntime=\"2022-02-04T15:44:13Z\" level=info msg=\"event=lsm_bpf tgid=2500 pid=2500 ppid=2499 uid=0 cgroupid=9458 comm=bpftool pcomm=sudo filename= retval=-1 reason=denied (restricted)\" bpfprog=bpfrestrict subsys=bpf\n\ntime=\"2022-02-04T15:44:13Z\" level=info msg=\"event=lsm_bpf tgid=2500 pid=2500 ppid=2499 uid=0 cgroupid=9458 comm=bpftool pcomm=sudo filename= retval=-1 reason=denied (restricted)\" bpfprog=bpfrestrict subsys=bpf\n```\n\n### 3.3 Configuration and Environment file\n\nPassing configuration as bind mounts can be achieved using the following command.\n\nAssuming [bpflock.yaml](https://github.com/linux-lock/bpflock/blob/main/deploy/configs/bpflock/bpflock.yaml) and [bpf.d profiles](https://github.com/linux-lock/bpflock/blob/main/deploy/configs/bpflock/bpf.d/) configs are in current directory inside `bpflock` directory, then we can just use:\n\n```bash\nls bpflock/\n  bpf.d  bpflock.d  bpflock.yaml\n```\n```bash\ndocker run --name bpflock -it --rm --cgroupns=host --pid=host --privileged \\\n  -v $(pwd)/bpflock/:/etc/bpflock \\\n  -v /sys/kernel/:/sys/kernel/ \\\n  -v /sys/fs/bpf:/sys/fs/bpf linuxlock/bpflock\n```\n\nPassing environment variables can also be done with files using `--env-file`. All parameters can be passed as environment variables using the `BPFLOCK_$VARIABLE_NAME=VALUE` format.\n\nExample run with environment variables in a file:\n```bash\ndocker run --name bpflock -it --rm --cgroupns=host --pid=host --privileged \\\n  --env-file bpflock.env.list \\\n  -v /sys/kernel/:/sys/kernel/ \\\n  -v /sys/fs/bpf:/sys/fs/bpf linuxlock/bpflock\n```\n\n## 4. Documentation\n\nDocumentation files can be found [here](https://github.com/linux-lock/bpflock/tree/main/docs/).\n\n## 5. Build\n\nbpflock uses [docker BuildKit](https://docs.docker.com/develop/develop-images/build_enhancements/) to build and\n[Golang](https://go.dev/doc/install) to make some checks and run tests. bpflock is built inside Ubuntu container that\ndownloads the standard golang package.\n\nRun the following to build the bpflock docker container:\n```bash\ngit submodule update --init --recursive\nmake\n```\n\nBpf programs are built using libbpf. The docker image used is Ubuntu.\n\nIf you want to only build the bpf programs directly without using docker, then on Ubuntu:\n```bash\nsudo apt install -y pkg-config bison binutils-dev build-essential \\\n        flex libc6-dev clang-12 libllvm12 llvm-12-dev libclang-12-dev \\\n        zlib1g-dev libelf-dev libfl-dev gcc-multilib zlib1g-dev \\\n        libcap-dev libiberty-dev libbfd-dev\n```\n\nThen run:\n```bash\nmake bpf-programs\n```\n\nIn this case the generated programs will be inside the ./bpf/build/... directory.\n\n## Credits\n\nbpflock uses lot of resources including source code from the [Cilium](https://github.com/cilium/cilium) and\n[bcc](https://github.com/iovisor/bcc) projects.\n\n## License\n\nThe bpflock user space components are licensed under the [Apache License, Version 2.0](https://github.com/linux-lock/bpflock/blob/main/LICENSE). The BPF code where it is noted is licensed under the [General Public License, Version 2.0](https://github.com/linux-lock/bpflock/blob/main/src/COPYING).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-lock%2Fbpflock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinux-lock%2Fbpflock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinux-lock%2Fbpflock/lists"}