guardx 0.2.0

A Python library for code analysis and sandboxing

GuardX

A Python package for code analysis and sandbox.

This library can be used to create pipelines that filter code generated by GenAI code models, and for guarding the execution of generated code.

Create a python virtual env

This is recommended.

python -m venv .venv
source .venv/bin/activate

Quick start

To install the library, choose one of the following methods:

git+https (using a github personal access token):

pip install guardx@git+https://${GITHUB_TOKEN}@https://github.com/ibm/guardx.git@${GUARDX_VERSION}

git+ssh:

pip install guardx@git+ssh://[e-mail]/ibm/guardx.git@${GUARDX_VERSION}

git clone:

git clone [e-mail]:ibm/guardx.git
make -C guardx init
make -C guardx install

Initialization

The library container images must be built before importing and using the library.

guardx init

Note: Depending on your system, you may need to run as sudo .venv/bin/guardx init.

Podman: GuardX uses the docker python package to communicate with containers. Hence, if you are using Podman, you will need to set the env variable DOCKER_HOST to point to the unix socket used by Podman. See docs/container.rst.

podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}'
export DOCKER_HOST=unix://<your_podman_socket_location>

Test using provided example

python example.py --file example_gen_code.py

Library Usage

Here is an example of how to use this library in your code.

from guardx import Guardx
from guardx.analysis import AnalysisType

python_code = """<your code here>"""

g = Guardx(config_path="./resources/config.yaml")

# To analyze code
result = g.analyze(python_code, {AnalysisType.DETECT_SECRET, AnalysisType.UNSAFE_CODE})
print(result)

# To execute code in sandbox with a default security policy
result = g.execute(python_code).get_docker_result()
print(result)

Setting up the development environment

Install pre-requisites

git clone [e-mail]:ibm/guardx.git
cd guardx
make init

Note: This installs Poetry. Make sure to configure your PATH to access poetry.

Install dependencies

To install the dev dependencies (editable mode):

make install/dev

Note: To add additional dependencies, use poetry add "package". For help, poetry add -h.

Build the library container images

make containers/docker

OR

make containers/podman

Note: Fresh build takes 5-10 minutes. Make sure to update the GuardX config file in resources/config.yaml to match built image name and tag.

Testing

Test modules are created under the tests directory.

To run all tests, use the following command:

make test

Note: To enable logging, set log_cli = true in tests/pytest.ini.

Code Linting

Before checking in any code for the project, please lint the code. This can be done using:

make lint

Precommit Hooks

We are currently using detect-secrets in our precommit hooks. Refer to this repo for configuration instructions

Docs config & build

cd docs
make html

Seccomp policy category

Set the seccomp policy category in resources/config.yaml. Categories description below:

• memory: only allow rt_sigaction, exit_group, munmap, read stdin, write stdout, write stderr
• nonet: disallow network related syscalls
• crit_syscalls: disallow syscalls associated with known CVEs or used as launchpad to carry out attacks.
• log: logs all syscalls to auditd.log
• unconfined: no seccomp