From 3bec290c4f547785d6ce7163bf67c387092dedfb Mon Sep 17 00:00:00 2001 From: Avi Lumelsky Date: Sun, 19 May 2024 16:43:15 +0300 Subject: [PATCH 1/2] Updated README and FAQ --- README.md | 178 +++++++++++++++++++++------------------------------- docs/FAQ.md | 1 + 2 files changed, 72 insertions(+), 107 deletions(-) diff --git a/README.md b/README.md index 0fd7c67..d778748 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,67 @@ +# secimport +[![Upload Python Package](https://github.com/avilum/secimport/actions/workflows/python-publish.yml/badge.svg)](https://github.com/avilum/secimport/actions/workflows/python-publish.yml) +![](https://img.shields.io/badge/Test_Coverage-90%-blue) + +A Tailor-Made Sandbox for Your Python Applications.
+secimport is eBPF-based sandbox toolkit for Python, that enforces specific syscalls per module in yoyr code.
+1. It traces your python code +2. It creates a security profile for your application
+3. Use the profile by applying it to running processes, or to run a new python process with supervision. + +secimport for python is like seccomp-bpf for linux but per module in your code. + **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* -- [secimport](#secimport) - - [The Tailor-Made Sandbox for Your Application](#the-tailor-made-sandbox-for-your-application) - - [The problem](#the-problem) - - [The solution](#the-solution) - - [Installation](#installation) - - [With Docker](#with-docker) +- [Background](#background) + - [Technical Blogs](#technical-blogs) + - [The problem](#the-problem) + - [How it works](#how-it-works) + - [Who is it for?](#who-is-it-for) +- [Getting Started](#getting-started) + - [Example Sandboxes](#example-sandboxes) + - [Using Docker](#using-docker) - [Without Docker](#without-docker) - - [Usage](#usage) - - [Stop on violation](#stop-on-violation) - - [Kill on violation](#kill-on-violation) - - [Dynamic profiling - trace, build sandbox, run.](#dynamic-profiling---trace-build-sandbox-run) - - [nsjail support (seccomp)](#nsjail-support-seccomp) +- [Command Line Usage](#command-line-usage) + - [Stop on violation](#stop-on-violation) + - [Kill on violation](#kill-on-violation) +- [Quickstart: trace, build, run.](#quickstart-trace-build-run) +- [Advanced](#advanced) - [Python API](#python-api) - - [Docker](#docker) - - [Examples](#examples) - - [Contributing](#contributing) - - [Roadmap](#roadmap) + - [seccomp-bpf support using nsjail](#seccomp-bpf-support-using-nsjail) - [Changelog](#changelog) + - [Contributing](#contributing) -# secimport -[![Upload Python Package](https://github.com/avilum/secimport/actions/workflows/python-publish.yml/badge.svg)](https://github.com/avilum/secimport/actions/workflows/python-publish.yml) -![](https://img.shields.io/badge/Test_Coverage-90%-blue) +# Background +## Technical Blogs +- secimport + Dtrace +- secimprt + eBPF + PyTorch +- secimport + eBPF + FastAPI - -## The Tailor-Made Sandbox for Your Application -secimport is production-oriented sandbox toolkit.
-It traces your code, and runs an executable that allows only the same syscalls, per module. - -Technical Blogs (Free Reading): -1. secimport + Dtrace -2. secimprt + eBPF + PyTorch -3. secimport + eBPF + FastAPI - -### The problem +## The problem Traditional tools like seccomp or AppArmor enforce syscalls for the entire process.
Something like `allowed_syscalls=["read","openat","bind","write"]`, which is great, but not enough for python's attack surface.
-### The solution -`secimport` is able to trace which syscalls each module in your code uses (by package name).
-After tracing, secimport creates a JSON/YAML policy for your code. It compiles it into a high-performance eBPF instrumentation script (smaller then 512 bytes overall), that looks like this. -``` -modules: - requests: - destructive: true # when true, secimport will kill on vilation instead of logging. - syscall_allowlist: - - fchmod - - getentropy - - getpgrp - - getrlimit -... -``` -You can also use JSON instaead of YAML, and even confine builtin python modules.
-An example policy that uses logging, multiprocessing, os and filesystem will look approximately like this: -``` -... - "/workspace/Python-3.11.8/Lib/logging/__init__.py": [ - " clock_gettime", - " getpid", - " write" - ], - "/workspace/Python-3.11.8/Lib/multiprocessing/process.py": [ - " getcwd", - " getpid", - " getrandom" - ], - "/workspace/Python-3.11.8/Lib/multiprocessing/util.py": [ - " prlimit64" - ], - "/workspace/Python-3.11.8/Lib/os.py": [ - " read" - ], - "/workspace/Python-3.11.8/Lib/platform.py": [ - " uname" - ], - "/workspace/Python-3.11.8/Lib/posixpath.py": [ - " close", - " fstat", - " getcwd", - " getdents64", - " openat" - ], - "/workspace/Python-3.11.8/Lib/random.py": [ - " getrandom" - ], -... -``` -It was created by tracing the code. secimport automatically finds these per-module syscalls for you. - -Finally, you convert this policy into an sandbox (eBPF instrumentation script) to run the python process in production. Running the sandbox will enfore python to obey any given policy. - +## How it works +1. `secimport` is able to trace which syscalls each module in your code uses (by package name).
+2. After tracing, secimport creates a JSON/YAML policy for your code. It compiles it into a high-performance eBPF instrumentation script (smaller then 512 bytes overall), that looks like this. + ``` + modules: + requests: + destructive: true # when true, secimport will kill on vilation instead of logging. + syscall_allowlist: + - fchmod + - getentropy + - getpgrp + - getrlimit + ... + ``` + You can also use JSON instaead of YAML, and even confine builtin python modules.
+3. Finally, you convert this policy into an sandbox (eBPF instrumentation script) to run the python process in production. Running the sandbox will enfore python to obey any given policy. + +## Who is it for? `secimport` is great for... - Preventing Code Execution: reduce the risk of supply chain attacks. - Trace the syscalls flow of your application at the user-space/os/kernel level and per module. @@ -108,14 +77,14 @@ Finally, you convert this policy into an sandbox (eBPF instrumentation script) t - Has negligible performance impact and is production-ready thanks to eBPF. Check out the [Performance](https://github.com/avilum/secimport/wiki/Performance-Benchmarks) benchmarks. - Trace which syscalls are called by each module in your code. - secimport uses USDT (Userland Statically Defined Tracing) together with kernel probes in the runtime using eBPF or dtrace instrumentation scripts. -## Installation -Tested on Ubuntu, Debian, Rocky (Linux x86/AMD/ARM) and MacOS in (x86/M1). If you run on MacOS you will need to disable SIP for dtrace. -## Examples -The [Sandbox Examples](https://github.com/avilum/secimport/wiki/Sandbox-Examples) page contains basic and advanced real-world examples. +# Getting Started +## Example Sandboxes -## With Docker +The [Sandbox Examples](https://github.com/avilum/secimport/wiki/Sandbox-Examples) page contains basic and advanced real-world examples. +## Using Docker +The quickest way to evaluate `secimport` is to use our [Docker container](docker/README.md), which includes `bpftrace` (`ebpf`) and other plug-and-play examples. For quicker evaluation, we recommend using the Secimport Docker Image instead of self-installing.
- Build and run the Docker container with a custom kernel that matches your existing OS kernel version: ``` @@ -124,6 +93,8 @@ For quicker evaluation, we recommend using the disable SIP for dtrace. + 1. Install python with USDT probes by configuring it with '--dtrace' 2. Install one of the backends: eBPF or DTrace. 3. Install secimport @@ -138,7 +109,7 @@ For quicker evaluation, we recommend using the >> secimport run @@ -237,7 +208,7 @@ Type "help", "copyright", "credits" or "license" for more information. SANDBOX EXITED; ``` -## Dynamic profiling - trace, build sandbox, run. +# Quickstart: trace, build, run. ```shell root@1fa3d6f09989:/workspace# secimport interactive @@ -289,27 +260,20 @@ Type "help", "copyright", "credits" or "license" for more information. For more detailed usage instructions, see the [Command-Line Usage](https://github.com/avilum/secimport/wiki/Command-Line-Usage) page. -## nsjail support (seccomp) +# Advanced + +## Python API +See the [Python Imports](examples/python_imports/) example for more details.
+You can use secimport directly from python, instead of the CLI.
you can replace `import` with `secimport.secure_import` for selected modules, and have them supervised in real time.
+ +## seccomp-bpf support using nsjail Beside the sandbox that secimport builds,
The `secimport build` command creates an nsjail sandbox with seccomp profile for your traced code.
`nsjail` enables namespace sandboxing with seccomp on linux
`secimport` automatically generates seccomp profiles to use with `nsjail` as executable bash script. It can be used to limit the syscalls of the entire python process, as another layer of defence. -## Python API - -Instead of CLI, you can also use `secimport` by replacing "`import`" with "`secimport.secure_import`" for selected modules. See the [Python Imports](examples/python_imports/) example for more details. - -## Docker -The quickest way to evaluate `secimport` is to use our [Docker container](docker/README.md), which includes `bpftrace` (`ebpf`) and other plug-and-play examples. +## Changelog +See the [Changelog](https://github.com/avilum/secimport/blob/master/docs/CHANGELOG.md) for development progress and existing features. ## Contributing - For information on how to contribute to `secimport`, see the [Contributing](https://github.com/avilum/secimport/blob/master/docs/CONTRIBUTING.md) guide. - -## Roadmap - -See the [Roadmap](https://github.com/avilum/secimport/blob/master/docs/ROADMAP.md) for the planned features and development milestones. - -## Changelog - -See the [Changelog](https://github.com/avilum/secimport/blob/master/docs/CHANGELOG.md) for development progress and existing features. diff --git a/docs/FAQ.md b/docs/FAQ.md index df1d032..f2421f1 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -5,6 +5,7 @@ - [Is it safe to use in production?](#is-it-safe-to-use-in-production) - [Should I use dtrace or bpftrace backend?](#should-i-use-dtrace-or-bpftrace-backend) - [What are the tradeoffs? How does it change they way I code?](#what-are-the-tradeoffs-how-does-it-change-they-way-i-code) +- [On Ubuntu, I get the error message `ERROR: Could not resolve symbol: /proc/self/exe:BEGIN_trigger`](#on-ubuntu-i-get-the-error-message-error-could-not-resolve-symbol-procselfexebegin_trigger) - [What are the performance impacts?](#what-are-the-performance-impacts) From 3bff442c27a964992d276d8daa903c965db53546 Mon Sep 17 00:00:00 2001 From: Avi Lumelsky Date: Sun, 19 May 2024 17:54:06 +0300 Subject: [PATCH 2/2] Fixed Dockerfile for Apple Silicon M3 --- docker/docker/Dockerfile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docker/docker/Dockerfile b/docker/docker/Dockerfile index 87be96c..e1a4cf4 100755 --- a/docker/docker/Dockerfile +++ b/docker/docker/Dockerfile @@ -2,7 +2,8 @@ ARG KERNEL_VERSION #FROM --platform=linux/amd64 linuxkit/kernel:${KERNEL_VERSION} as ksrc FROM docker/for-desktop-kernel:5.10.25-6594e668feec68f102a58011bb42bd5dc07a7a9b as ksrc -FROM --platform=linux/amd64 ubuntu:latest AS build +# FROM --platform=linux/amd64 ubuntu:latest AS build +FROM ubuntu:latest AS build ARG BPFTRACE_VERSION ARG PYTHON_VERSION