cede

cede /siːd/ (Container Escape Detection Engine) is an eBPF-based security monitor for detecting suspicious container activity at the kernel level.

Goal

This project is a security monitoring system that detects potential container escape attempts. It works by hooking into low-level Linux kernel events using eBPF, correlating those events with their container context, and generating alerts.

The primary threat this tool guards against is a compromised or malicious container attempting to break out of its isolation and gain access to the underlying host system.

Core Concepts

To understand how this tool works, it's important to be familiar with the core technologies it's built upon:

• eBPF: The foundation of the project. eBPF allows us to run sandboxed programs within the Linux kernel to observe system behavior safely and efficiently.
• Container Isolation: An overview of the Linux namespaces and cgroups that create the "walls" of a container, which this tool is designed to protect.
• Threat Model: A breakdown of the specific container escape techniques we aim to detect.

Current Status

The project has successfully completed the initial implementation and debugging phases for its first detection capability.

• Working: The core detection pipeline for monitoring mount syscalls is functional.
• Mechanism: A Go-based userspace agent successfully loads, attaches, and listens for events from an eBPF program.
• eBPF Hook: The eBPF program uses a kprobe to reliably hook the __x64_sys_mount kernel function, which is the entry point for the mount syscall. This ensures we capture all mount attempts, including those from within containers.
• Container Context: When an event is received, the agent enriches it by parsing /proc/<pid>/cgroup to determine if the process is running inside a container and extracts the container ID.
• Output: The agent prints formatted alerts to the console, distinguishing between actions happening on the host versus inside a container.

Getting Started

Prerequisites

• A Linux host (tested on Arch Linux).
• Go (v1.18+).
• Clang/LLVM toolchain (for compiling the eBPF C code).
• Docker (for running test containers).
• bpftool (usually part of the kernel tools package).
• make.

1. Setup

First, clone the repository.

git clone <your-repo-url>
cd <your-repo-name>

The eBPF program needs kernel-specific type information to compile correctly. You must generate a vmlinux.h header file from your running kernel's BTF data.

bpftool btf dump file /sys/kernel/btf/vmlinux format c > detector/vmlinux.h

2. Build

Two Makefiles are provided to compile both the eBPF program and the Go agent.

cd detector/ && make
cd .. && make run

This will create detector/detector.bpf.o and the agent binary in the root directory.

3. Run

The agent requires elevated privileges to load eBPF programs into the kernel.

sudo ./agent

Or, using the Makefile

make run

You should see a message indicating the kprobe was attached successfully, and the agent is "Listening for eBPF events...".

How to Test

You can test the detector by simulating a common escape technique: mounting a sensitive host directory from within a privileged container.

1. In one terminal, run the agent (make run).
2. In a second terminal, start a privileged container:

   docker run -it --rm --privileged archlinux bash

3. Inside the container, attempt to mount the host's /dev directory:

   # Inside the container shell
   mkdir /tmp/host_dev
   mount --bind /dev /tmp/host_dev

4. (Don't) observe the output in your agent's terminal. You will see a high-fidelity alert for this action:

   ALERT: PID=54321, Comm=mount, Reason=1, Path=/dev, Context=container (c26c26ea543b...)
   

Note: 4th step isn't quite there yet.

Project Plan & Roadmap

• Phase 1: Building the eBPF Kernel Probe
  • Choose initial hook point (mount syscall).
  • Write the eBPF program (detector.bpf.c) to capture the syscall.
  • Send event data from kernel to userspace via a ring buffer.
  • Next: Implement hooks for unshare and openat syscalls.
• Phase 2: Building the Go Security Agent
  • Scaffold the Go application (main.go).
  • Implement eBPF program loading and attaching.
  • Listen for events from the kernel ring buffer.
  • Enrich events with container context from /proc.
  • Implement basic alerting to the console.
• Phase 3: Deployment & Automation
  • Containerize the agent with a Dockerfile.
  • Create a Kubernetes DaemonSet manifest.
  • Write an Ansible playbook to automate deployment.
• Phase 4: Testing & Demo
  • Deploy the DaemonSet to a minikube cluster.
  • Create a vulnerable test Pod.
  • Simulate and record an escape attempt.

Technology Stack

• Go: Core agent logic, eBPF management, container runtime interaction.
• eBPF (C): Kernel-level tracing and event collection.
• Low-Level Linux: Deep knowledge of syscalls, kprobes, namespaces, cgroups, and the /proc filesystem.
• Docker: For containerizing the agent and providing a test environment.
• (Upcoming) Kubernetes: For deploying the agent as a DaemonSet for cluster-wide coverage.
• (Upcoming) Ansible: For automating the build and deployment pipeline.