{"id":13693165,"url":"https://github.com/cisco-open/camblet-driver","last_synced_at":"2025-05-02T21:31:37.757Z","repository":{"id":155966348,"uuid":"627920949","full_name":"cisco-open/camblet-driver","owner":"cisco-open","description":"Linux Kernel module providing TLS, identity and running WASM","archived":true,"fork":false,"pushed_at":"2024-08-12T10:09:22.000Z","size":8967,"stargazers_count":76,"open_issues_count":21,"forks_count":6,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-30T16:02:22.443Z","etag":null,"topics":["camblet","kernel","tls"],"latest_commit_sha":null,"homepage":"https://camblet.io","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cisco-open.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-04-14T13:47:21.000Z","updated_at":"2025-02-15T22:27:59.000Z","dependencies_parsed_at":"2024-01-28T15:29:12.114Z","dependency_job_id":"8c41e77d-1e3b-4a73-a290-7a775a28ac82","html_url":"https://github.com/cisco-open/camblet-driver","commit_stats":null,"previous_names":["cisco-open/nasp-kernel-module","cisco-open/wasm-kernel-module"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fcamblet-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fcamblet-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fcamblet-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisco-open%2Fcamblet-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cisco-open","download_url":"https://codeload.github.com/cisco-open/camblet-driver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252108816,"owners_count":21696143,"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":["camblet","kernel","tls"],"created_at":"2024-08-02T17:01:06.422Z","updated_at":"2025-05-02T21:31:36.751Z","avatar_url":"https://github.com/cisco-open.png","language":"C","funding_links":[],"categories":["优秀项目与工具"],"sub_categories":["CNCF WASM Working Group"],"readme":"# camblet-driver\n\n[![Makefile CI](https://github.com/cisco-open/camblet-driver/actions/workflows/build.yml/badge.svg)](https://github.com/cisco-open/camblet-driver/actions/workflows/build.yml)\n\n## Introduction\n\nThe *camblet-driver* is the supporting Linux kernel module for the [Camblet](https://github.com/cisco-open/camblet) system. It is capable of enhancing plain old TCP sockets in a frictionless way so that application developers can focus on their business logic instead of dealing with the complexity of TLS, mTLS, and other security-related concerns. It is doing this seamlessly, no code changes or re-compilations or re-deployments are required.\n\nThe features are the following:\n\n- providing zero-trust identity for UNIX TCP sockets through mTLS\n- access control, authorization and authentication (through OPA)\n- providing frictionless TLS termination for those TCP sockets\n- supporting every Linux-based machine (bare-metal, vanilla VM, Kubernetes, etc... you name it)\n\n### Presentations\n\nThe early incarnation of this project was presented on KubeCon 2023 Amsterdam, Wasm Day, you can find the recording [here](https://www.youtube.com/watch?v=JSKNch6piyY). By that time the module was capable of running OPA -\u003e Wasm compiled policies in the Kernel and those were exposed as an eBPF function from the kernel module.\n\n## Which Wasm runtime?\n\nThe [wasm3](https://github.com/wasm3/wasm3) runtime was chosen since it is written in C and has minimal dependencies (except a C library) and it is extremely portable. In kernel space, there is no libc, but we maintain a fork of wasm3 which can run in kernel space as well (check the `third-party/wasm3/` submodule).\n\nCurrent restrictions for kernel-space wasm3:\n\n- no floating point support [can be soft-emulated if needed]\n- no WASI support\n\n## Development environment\n\nCheckout the code before you start:\n\n```bash\ngit clone --recurse-submodules https://github.com/cisco-open/camblet-driver.git\ncd camblet-driver\n```\n\n### Lima\n\nOur primary development environment is [Lima](https://lima-vm.io) since it supports x86_64 and ARM as well. The module was tested on Ubuntu and Arch Linux and requires kernel version 5.15 and upwards.\n\nInstall Lima itself, for example on macOS using `brew`:\n\n```bash\nbrew install lima\n```\n\nLaunch the default VM which is an Ubuntu and matches the host's architecture by default:\n\n```bash\nlimactl start\n\n# You may also start the VM with your user home mounted as writable with this one-liner:\nlimactl start --set '.mounts[0].writable=true' --tty=false\n```\n\nSetup the required dependencies in the VM:\n\n```bash\nlima # enter the VM\nsudo apt update \u0026\u0026 sudo apt install make\nmake setup-vm\n```\n\n### Coding\n\nWe are using VSCode for development and the project ships with a `c_cpp_properties.json` file which contains the required paths for the kernel headers. The file is ARM specific from include path point-of-view so if you happen to run on x86_64 please replace the paths accordingly (arm64 -\u003e x86, aarch64 -\u003e x86_64).\n\nWe are respecting your `c_cpp_properties.json` file by not overriding it. Please copy the required parts to your file, if it is already present.\n\nYou will also need a Linux source bundle, to have full navigation in the source code. The easiest way is to run the `setup-dev-env` target after you already have created a working and configured VM in Lima (with `lima make setup-vm`). This target installs the necessary GCC cross-compilers for IntelliSense, clones the Linux repo, and configures the VSCode workspace accordingly:\n\n```bash\n# Start the VM if you haven't already\nlimactl start\n\n# Setup the development environment\nmake setup-dev-env\n```\n\n## Build and run\n\n*This assumes that you have created a development environment according to the previous section.*\n\nBuild the kernel modules(BearSSL and Camblet):\n\n```bash\n# Enter the VM\nlima\n\n# Build on all CPU cores parallelly\nmake -j$(nproc)\n```\n\nLoad the kernel modules(BearSSL and Camblet):\n\n```bash\nmake insmod\n```\n\nUnload the kernel modules(BearSSL and Camblet):\n\n```bash\nmake rmmod\n```\n\nFollow the kernel logs:\n\n```bash\nmake logs\n```\n\nInstall the [CLI](https://github.com/cisco-open/camblet) for the kernel module:\n\n```bash\n# You can build the module on your workstation\ngit clone https://github.com/cisco-open/camblet.git\ncd camblet\nGOOS=linux make build\n\n# But you need to run it in the VM, where the device is exposed\nlima sudo build/camblet agent --policies-path $(pwd)/camblet.d/policies --services-path $(pwd)/camblet.d/services\n```\n\nThen follow the instructions [here](https://github.com/cisco-open/camblet#cli).\n\n## TLS Termination\n\nThe kernel module can terminate TLS connections for ordinary TCP sockets (IPv4 or IPv6), and forward the plaintext traffic to a user space application.\n\nBetween two applications - both of them intercepted by this module - the traffic is always encrypted by [kTLS](https://docs.kernel.org/networking/tls-offload.html). If one of them is not intercepted by the module but supports the ChaCha20-Poly1305 AEAD - kTLS is used. Otherwise, the traffic is encrypted by BearSSL.\n\n## Debugging\n\n### Logging\n\nMost of the logs of this module are on the debug level and can be shown using the [dynamic debug](https://www.kernel.org/doc/html/latest/admin-guide/dynamic-debug-howto.html) feature of the Linux kernel.\n\nUse the following command to turn on debug-level logging for the module:\n\n```bash\necho -n '-p; module camblet file opa.c  +pftl' | sudo tee /proc/dynamic_debug/control \u003e /dev/null\n```\n\n### Kernel debugging environment\n\nThe kernel module can be traced for memory leaks and other issues with the help of fine tools, like [KASAN](https://www.kernel.org/doc/html/latest/dev-tools/kasan.html) and [Kmemleak](https://www.kernel.org/doc/html/latest/dev-tools/kmemleak.html).\n\nTo create a kernel debugging environment on Fedora, follow these steps:\n\n```bash\nlimactl start --name fedora-debug template://fedora --vm-type vz --set '.mounts[0].writable=true'\n\n# Enter the VM\nlimactl shell fedora-debug\n\nsudo dnf update\nsudo dnf install kernel-debug kernel-debug-devel\n\n# Check the current debug kernel version, and set it as default (ls /boot/)\nCURRENT_DEBUG_KERNEL=vmlinuz-6.8.7-200.fc39.aarch64+debug\n\nsudo grubby --set-default ${CURRENT_DEBUG_KERNEL}\nsudo grubby --update-kernel=${CURRENT_DEBUG_KERNEL} --args kmemleak=on kasan=on\nsudo reboot\n```\n\n### Test mTLS\n\nThe kernel module offers TLS termination on certain ports selected by an [OPA](https://www.openpolicyagent.org) rule-set:\n\n```bash\n# Edit the rule-set\nvim socket.rego\n\n# Build and insert the module, then follow the logs\nmake\nmake insmod\nmake logs\n\n# In another terminal start a server\nlima python3 -m http.server --protocol HTTP/1.1\n\n# In another terminal connect to the server (over plaintext, will be TLS terminated by the kernel)\nlima curl -v http://localhost:8000\n```\n\n## Installation\n\nIt is also possible to manually install the kernel module with [DKMS](https://github.com/dell/dkms).\n\n### DKMS Support\n\nLinux kernel modules need to be built against a specified kernel version, this is when dynamic kernel module support, [DKMS](https://github.com/dell/dkms) comes in handy. The DKMS framework enables you to automatically re-build kernel modules into the current kernel tree as you upgrade your kernel, so you don't need to re-build them manually every time.\n\n#### Install DKMS\n\nEnsure that DKMS is installed on your system. You can typically install it using your distribution's package manager.\n\nFor example, on Debian-based systems:\n\n```bash\nsudo apt install dkms\n```\n\nOn Red Hat compatible systems:\n\n```bash\nsudo dnf install --enablerepo epel dkms\n```\n\nOn Amazon Linux:\n\n```bash\nsudo dnf install dkms\n```\n\n#### Prepare the Camblet kernel module\n\nThe Camblet can be installed with DKMS in the following way currently:\n\n```bash\nsudo git clone --recurse-submodule https://github.com/cisco-open/camblet-driver.git /usr/src/camblet-0.8.0/\n\n# Add the kernel module to the DKMS source control\nsudo dkms add -m camblet -v 0.8.0\n\n# Build and install the kernel module against the current kernel version\nsudo dkms install -m camblet -v 0.8.0\n\n# Load the kernel module\nsudo modprobe camblet\n\n# Check the logs that the module got loaded\nsudo dmesg -T\n```\n\nUn-installation is very simple as well:\n\n```bash\n# Unload the kernel module\nsudo modprobe -r camblet\n\n# Remove the kernel module from DKMS source control\nsudo dkms uninstall -m camblet -v 0.8.0\nsudo dkms remove -m camblet -v 0.8.0\n```\n\n### Debian package\n\nThe kernel module can be packaged into a Debian package with DKMS support, so kernel module re-builds are handled automatically.\n\n#### Building the package for yourself\n\nPrepare the build environment, if you want to build the package on your workstation:\n\n```bash\nsudo apt install debhelper\n```\n\nThe package can be built with the following command:\n\n```bash\nmake deb\n```\n\nThe package can be installed with the following command:\n\n```bash\nsudo apt install ../camblet-driver_0.7.1-1_all.deb\n```\n\n### RPM package\n\nThe kernel module can be packaged into an RPM package with DKMS support, so kernel module re-builds are handled automatically.\n\n#### Building the package for yourself\n\nPrepare the build environment, if you want to build the package on your workstation:\n\n```bash\nsudo dnf install rpm-build\n```\n\nThe package can be built with the following command:\n\n```bash\nmake rpm\n```\n\nThe package can be installed with the following command:\n\n```bash\nsudo dnf install ../camblet-driver-0.7.1-1.noarch.rpm\n```\n\n## Testing\n\nWe are using [bats-core](https://bats-core.readthedocs.io/en/stable/index.html) for running our tests.\n\n```bash\nmake tests\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisco-open%2Fcamblet-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcisco-open%2Fcamblet-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisco-open%2Fcamblet-driver/lists"}