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.

Design

Static Code Analysis

Sandbox via seccomp

Quick start

Create a python virtual env

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

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>

Method 1: via CLI

pip install guardx

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

pip install git+https://github.com/ibm/guardx.git@{branch/tag}

git+ssh:

pip install git+ssh://git@github.com/ibm/guardx.git@${branch/tag}

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

guardx init

Test using provided example

python example.py --file example_gen_code.py

Method 2: for development

Install pre-requisites

git clone git@github.com: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

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)

# To execute code with global variables passed into the sandbox
globals_dict = {"x": 10, "y": 20}
result = g.execute(python_code, globals=globals_dict).get_docker_result()
print(result)

Passing Global Variables to Sandbox Execution

You can pass global variables into the sandbox execution environment using the globals parameter. This is useful for:

• Providing prior execution state
• Passing configuration or context data
• Simulating stateful execution across multiple code snippets

# Example: Using globals for stateful execution
code1 = "counter = 1"
result1 = g.execute(code1)

# Continue with prior state
code2 = "counter += 1; print(counter)"
result2 = g.execute(code2, globals={"counter": 1})

# Example: Passing complex data structures
code = "result = sum(numbers) * multiplier"
globals_dict = {
    "numbers": [1, 2, 3, 4, 5],
    "multiplier": 2
}
result = g.execute(code, globals=globals_dict)

# Example: Passing configuration
code = "result = data['value'] * config['multiplier']"
globals_dict = {
    "data": {"value": 100},
    "config": {"multiplier": 2.5, "threshold": 10}
}
result = g.execute(code, globals=globals_dict)

Important Notes:

• Global variables must be JSON-serializable (strings, numbers, lists, dicts, booleans, None)
• Do NOT include __builtins__ - it is automatically provided by the executor
• Non-serializable objects (functions, classes, modules, file handles) will be automatically filtered out with a warning
• Only the serializable values will be passed to the sandbox