secimport

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

• Background
  • Technical Blogs
  • The problem
  • How it works
  • Who is it for?
• Getting Started
  • Example Sandboxes
  • Using Docker
  • Without Docker
• Command Line Usage
  • Stop on violation
  • Kill on violation
• Quickstart: trace, build, run.
• Advanced
  • Python API
  • seccomp-bpf support using nsjail
  • Changelog
  • Contributing

Background

Technical Blogs

• secimport + Dtrace
• secimprt + eBPF + PyTorch
• secimport + eBPF + FastAPI

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.

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.
  • Run your application while enforcing syscalls per module.
    • Upon violation of the policy, it can log, stop, or kill the process.
• Protect yourself from RCE:
  • secimport makes 1day attacks less of an issue, because it prevents the code form running. If you are using a vulnerable package and someone exploited it, your policy will not allow this exploit's syscalls and it will be handled as you wish.
  • Avoid incidents like log4shell. A logging library requires very few syscalls, and it should never run command using fork, execve or spawn.
    • The syscalls that "fastapi", "numpy" or "requests" use are very different.
• Load AI Models from Insecure Sources
  • Models from unsafe source (huggingface, torch hub, and pytorch pickled models) can be limited to run only a set of syscalls. RCE like 'import os;os.system(...)' somewhere deep in the code will be catched by secimport.
• Minimal Performance Impact
  • Has negligible performance impact and is production-ready thanks to eBPF. Check out the Performance 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.

Getting Started

Example Sandboxes

The Sandbox Examples page contains basic and advanced real-world examples.

Using Docker

The quickest way to evaluate secimport is to use our Docker container, 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:

  cd docker/ && ./build.sh && ./run.sh
  

  A temporary container will be created, and you will be logged in as the root user.

Without Docker

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.

1. Install python with USDT probes by configuring it with '--dtrace'
2. Install one of the backends: eBPF or DTrace.
3. Install secimport

• Install from pypi

  • python3 -m pip install secimport
    

• Install from source

  • git clone https://github.com/avilum/secimport.git && cd secimport
    python3 -m pip install poetry && python3 -m poetry install
    

Command Line Usage

To sandbox your program using the CLI, start a bpftrace program that logs all the syscalls for all the modules in your application into a file with the secimport trace command. Once you have covered the logic you would like to sandbox, hit CTRL+C or CTRL+D, or wait for the program to finish. Then, build a sandbox from the trace using the secimport build command, and run the sandbox with the secimport run command.

NAME
    secimport - is a comprehensive toolkit designed to enable the tracing, construction, and execution of secure Python runtimes. It leverages USDT probes and eBPF/DTrace technologies to enhance the overall security measures.

SYNOPSIS
    secimport COMMAND

DESCRIPTION
    https://github.com/avilum/secimport/wiki/Command-Line-Usage

    WORKFLOW:
            1. secimport trace / secimport shell
            2. secimport build
            3. secimport run

    QUICKSTART:
            $ secimport interactive

    EXAMPLES:
        1. trace:
            $  secimport trace
            $  secimport trace -h
            $  secimport trace_pid 123
            $  secimport trace_pid -h
        2. build:
            # secimport build
            $ secimport build -h
        3. run:
            $  secimport run
            $  secimport run --entrypoint my_custom_main.py
            $  secimport run --entrypoint my_custom_main.py --stop_on_violation=true
            $  secimport run --entrypoint my_custom_main.py --kill_on_violation=true
            $  secimport run --sandbox_executable /path/to/my_sandbox.bt --pid 2884
            $  secimport run --sandbox_executable /path/to/my_sandbox.bt --sandbox_logfile my_log.log
            $  secimport run -h

COMMANDS
    COMMAND is one of the following:

     build
       Compiles a trace log (trace.log). Creates the sandbox executable (instrumentation script) for each supported backend It uses `create_profile_from_trace ...` and `sandbox_from_profile`.

     compile_sandbox_from_profile
       Generates a tailor-made sandbox that will enforce a given yaml profile/policy in runtime.

     interactive

     run
       Run a python process inside the sandbox.

     shell
       Alternative syntax for secimport "trace".

     trace
       Traces a python process using an entrypoint or interactive interpreter. It might require sudo privilleges on some hosts.

     trace_pid
       Traces a running process by pid. It might require sudo privilleges on some hosts.

Stop on violation

root@1bc0531d91d0:/workspace# secimport run  --stop_on_violation=true
 >>> secimport run
[WARNING]: This sandbox will send SIGSTOP to the program upon violation.
 RUNNING SANDBOX... ['./sandbox.bt', '--unsafe', ' -c ', '/workspace/Python-3.11.8/python', 'STOP']
Attaching 4 probes...
Python 3.11.8 (default, Apr 28 2023, 11:32:40) [GCC 9.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.system('ps')
[SECURITY PROFILE VIOLATED]: <stdin> called syscall 56 at depth 8022

^^^ STOPPING PROCESS 85918 DUE TO SYSCALL VIOLATION ^^^
		PROCESS 85918 STOPPED.

Kill on violation

root@ee4bc99bb011:/workspace# secimport run --kill_on_violation
 >>> secimport run
[WARNING]: This sandbox will send SIGKILL to the program upon violation.
 RUNNING SANDBOX... ['./sandbox.bt', '--unsafe', ' -c ', '/workspace/Python-3.11.8/python', 'KILL']
import os
oAttaching 4 probes...
sPython 3.11.8 (default, Apr 28 2023, 11:32:40) [GCC 9.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.system('ps')
[SECURITY PROFILE VIOLATED]: <stdin> called syscall 56 at depth 8022

^^^ KILLING PROCESS 86466 DUE TO SYSCALL VIOLATION ^^^
		KILLED.
 SANDBOX EXITED;

Quickstart: trace, build, run.

root@1fa3d6f09989:/workspace# secimport interactive

Let's create our first tailor-made sandbox with secimport!
- A python shell will be opened
- The behavior will be recorded.

OK? (y): y
 >>> secimport trace

TRACING: ['/workspace/secimport/profiles/trace.bt', '-c', '/workspace/Python-3.11.8/python', '-o', 'trace.log']

                        Press CTRL+D to stop the trace;

Python 3.11.8 (default, Mar 19 2023, 08:34:46) [GCC 9.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import this
>>>
 TRACING DONE;
 >>> secimport build

SECIMPORT COMPILING...

CREATED JSON TEMPLATE:  policy.json
CREATED YAML TEMPLATE:  policy.yaml
compiling template policy.yaml
DTRACE SANDBOX:  sandbox.d
BPFTRCE SANDBOX:  sandbox.bt

Now, let's run the sandbox!

- Run the same commands as before, they should run without any problem;.
- Do something new in the shell; e.g:   >>> __import__("os").system("ps")

        OK? (y): y
 >>> secimport run
 RUNNING SANDBOX... ['./sandbox.bt', '--unsafe', ' -c ', '/workspace/Python-3.11.8/python']
Attaching 5 probes...
REGISTERING SYSCALLS...
STARTED
Python 3.11.8 (default, Mar 19 2023, 08:34:46) [GCC 9.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import this
>>> import os
[SECIMPORT VIOLATION]: <stdin> called syscall ioctl at depth 0
[SECIMPORT VIOLATION]: <stdin> called syscall ioctl at depth 0

For more detailed usage instructions, see the Command-Line Usage page.

Advanced

Python API

See the 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.

Changelog

See the Changelog for development progress and existing features.

Contributing

For information on how to contribute to secimport, see the Contributing guide.