secimport
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.
- 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.
- Control the execution or third-party and open-source packages you can't fully control.
- Avoid incidents like log4shell.
- Prevent 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.
- Has negligible performance impact and is production-ready thanks to eBPF. Check out the Performance benchmarks.
Installation
Tested on Ubuntu, Debian, Rocky (Linux x86/AMD/ARM) and MacOS in (x86/M1).
With Docker
For quicker evaluation, we recommend using the Docker image instead of self-installing.
- Build and run the Docker container with a custom kernel that matches your existing OS kernel version:
A temporary container will be created, and you will be logged in as the root user.
cd docker/ && ./build.sh && ./run.sh
Without Docker
- Install python with USDT probes by configuring it with '--dtrace'
- Install one of the backends: eBPF or DTrace.
- 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
-
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 - A toolkit for Tracing and Securing Python Runtime using USDT probes and eBPF/DTrace
SYNOPSIS
cli.py COMMAND
DESCRIPTION
QUICK START:
>>> 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
interactive
run
Run a python process inside the sandbox.
trace
Traces
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.10.0/python', 'STOP']
Attaching 4 probes...
Python 3.10.0 (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.10.0/python', 'KILL']
import os
oAttaching 4 probes...
sPython 3.10.0 (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;
Dynamic profiling - trace, build sandbox, 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.10.0/python', '-o', 'trace.log']
Press CTRL+D to stop the trace;
Python 3.10.0 (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: traced_modules.json
CREATED YAML TEMPLATE: traced_modules.yaml
compiling template traced_modules.yaml
DTRACE SANDBOX: traced_modules.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.10.0/python']
Attaching 5 probes...
REGISTERING SYSCALLS...
STARTED
Python 3.10.0 (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.
Python API
You can also use secimport
by replacing import
with secimport.secure_import
for selected modules. See the Python Imports example for more details.
Docker
The quickest way to evaluate secimport
is to use our Docker container, which includes bpftrace
(ebpf
) and other plug-and-play examples.
Examples
The Sandbox Examples page contains basic and advanced real-world examples.
Contributing
For information on how to contribute to secimport
, see the Contributing guide.
Roadmap
See the Roadmap for the planned features and development milestones.
Changelog
See the Changelog for development progress and existing features.