From 88e1728977e6a4e25afae6a3f8d18a45b99c4669 Mon Sep 17 00:00:00 2001 From: mvle Date: Thu, 16 Apr 2026 10:56:10 -0500 Subject: [PATCH 1/3] update to docs addressing #14 Signed-off-by: mvle --- README.md | 187 ++++++++++++++++++++-------------------------- docs/analysis.rst | 18 +++-- docs/arch.rst | 4 +- docs/seccomp.rst | 14 ++++ 4 files changed, 109 insertions(+), 114 deletions(-) create mode 100644 docs/seccomp.rst diff --git a/README.md b/README.md index b08de60..a932a0c 100644 --- a/README.md +++ b/README.md @@ -4,33 +4,19 @@ 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. -## Quick start - -To install the library, choose one of the following methods: - -``` -pip install guardx +[Design](docs/arch.rst) +[Static Code Analysis](docs/analysis.rst) +[Sandbox via seccomp](docs/seccomp.rst) -``` - -## Dev: Create a python virtual env +## Quick start -This is recommended. +### Create a python virtual env ```bash python -m venv .venv source .venv/bin/activate ``` - -### Initialization - -The library container images must be built before importing and using the library. - -```bash -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. @@ -42,81 +28,13 @@ podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}' export DOCKER_HOST=unix:// ``` -### Test using provided example - -```bash -python example.py --file example_gen_code.py -``` - -### Library Usage - -Here is an example of how to use this library in your code. - -```python -from guardx import Guardx -from guardx.analysis import AnalysisType - -python_code = """""" - -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) +### Method 1: via CLI -# 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) ``` +pip install guardx -#### 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 - -```python -# 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 - -## Development - -## Install from a branch - **git+https** (using a [github personal access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/)): ```bash pip install git+https://github.com/ibm/guardx.git@{branch/tag} @@ -128,18 +46,20 @@ pip install git+https://github.com/ibm/guardx.git@{branch/tag} pip install git+ssh://git@github.com/ibm/guardx.git@${branch/tag} ``` -## Setting up the development environment +The library container images must be built before importing and using the library. -**git clone**: +```bash +guardx init +``` +#### Test using provided example ```bash -git clone git@github.com:ibm/guardx.git -make -C guardx init -make -C guardx install +python example.py --file example_gen_code.py ``` +### Method 2: for development -### Install pre-requisites +#### Install pre-requisites ```bash git clone git@github.com:ibm/guardx.git @@ -148,7 +68,7 @@ make init ``` **Note:** This installs Poetry. Make sure to configure your PATH to access poetry. -### Install dependencies +#### Install dependencies To install the dev dependencies (editable mode): @@ -158,7 +78,7 @@ make install/dev **Note:** To add additional dependencies, use `poetry add "package"`. For help, `poetry add -h`. -### Build the library container images +#### Build the library container images ```bash make containers/docker @@ -171,7 +91,7 @@ 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 +#### Testing Test modules are created under the `tests` directory. @@ -183,7 +103,7 @@ make test **Note:** To enable logging, set `log_cli = true` in `tests/pytest.ini`. -### Code Linting +#### Code Linting Before checking in any code for the project, please lint the code. This can be done using: @@ -202,14 +122,67 @@ cd docs make html ``` -## Seccomp policy category +## Library Usage -Set the seccomp policy category in `resources/config.yaml`. -Categories description below: +Here is an example of how to use this library in your code. + +```python +from guardx import Guardx +from guardx.analysis import AnalysisType + +python_code = """""" + +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) +``` -- 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 +### 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 + +```python +# 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 diff --git a/docs/analysis.rst b/docs/analysis.rst index b23d733..9b04715 100644 --- a/docs/analysis.rst +++ b/docs/analysis.rst @@ -1,7 +1,19 @@ Security Analysis ================= -GuardX uses `Bandit `_ for static security analysis of Python code and identify security issues before execution. +GuardX provides a common interface for statically scanning Python code for safety and security issues. + +Analysis can be invoked like so:: + result = guardx.Guardx().analyze(python_code, {AnalysisType.UNSAFE_CODE, AnalysisType.DETECT_SECRET}) + +AnalysisType.UNSAFE_CODE: +Runs `Bandit `_ for static security analysis of Python code and identify security issues before execution. + +AnalysisType.DETECT_SECRET: +Runs `detect-secrets `_ checks for *secrets* in code. + +By default, all tests in Bandit and detect-secrets are run. Details of the tests are listed below +and can be found on the respective project's website. Bandit Tests `ref `_ --------------------------------------------------------------------------------- @@ -74,10 +86,6 @@ Bandit supports YAML configuration files: Detect-Secrets ============== - -`detect-secrets `_ checks for the following *secrets* in code - - **Secret Types** * API keys and tokens * Private keys (RSA, SSH, PGP) diff --git a/docs/arch.rst b/docs/arch.rst index 74d824c..2712e26 100644 --- a/docs/arch.rst +++ b/docs/arch.rst @@ -52,8 +52,8 @@ GuardX analyzes AI generated code snippets using: * Intent profiles Based on syscall analysis of "similar code", GuardX will try to match the required permissions of the generated code snippet to a set of predefined intents -1. Execution +2. Execution ------------ -Execution of AI generated code poses a high security risk for application users and data owners. To enable this GuardX orchestrates sand boxed containers or VMs (future). Containers can be sand boxed with seccomp policies which are derived from intent profiles. GuardX takes care of instantiating the execution environment, applying appropriate security profiles and verifying the output. +Execution of AI generated code poses a high security risk for application users and data owners. To enable this, GuardX uses sandboxed containers or VMs (future). AI generated code is run inside the sandboxed container. Inside the container, the process used to execute the AI generated code is further sandboxed using seccomp policies. These seccomp policies are derived from intent profiles of the code or selected from a list of seccomp profiles such as `no network,` `strict,` and `memory only.` GuardX takes care of instantiating the execution environment, applying appropriate security profiles and verifying the output. diff --git a/docs/seccomp.rst b/docs/seccomp.rst new file mode 100644 index 0000000..82d24f0 --- /dev/null +++ b/docs/seccomp.rst @@ -0,0 +1,14 @@ +## Seccomp policy category + +The process (Python) running the AI code inside the container is further constrained with seccomp. + +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. +- strict: allows read(), write(), _exit(), and sigreturn() +- log: logs all syscalls to auditd.log +- unconfined: no seccomp + From 27530bd91e7fa4f491c841dc1e9d4a3809c23573 Mon Sep 17 00:00:00 2001 From: mvle Date: Thu, 16 Apr 2026 11:00:58 -0500 Subject: [PATCH 2/3] fix docs Signed-off-by: mvle --- README.md | 2 ++ docs/analysis.rst | 8 +++++--- docs/seccomp.rst | 3 ++- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a932a0c..6b264aa 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,9 @@ 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](docs/arch.rst) + [Static Code Analysis](docs/analysis.rst) + [Sandbox via seccomp](docs/seccomp.rst) ## Quick start diff --git a/docs/analysis.rst b/docs/analysis.rst index 9b04715..ffb4d68 100644 --- a/docs/analysis.rst +++ b/docs/analysis.rst @@ -3,13 +3,15 @@ Security Analysis GuardX provides a common interface for statically scanning Python code for safety and security issues. -Analysis can be invoked like so:: +Analysis can be invoked like so: + +.. code-block:: python result = guardx.Guardx().analyze(python_code, {AnalysisType.UNSAFE_CODE, AnalysisType.DETECT_SECRET}) -AnalysisType.UNSAFE_CODE: +**AnalysisType.UNSAFE_CODE:** Runs `Bandit `_ for static security analysis of Python code and identify security issues before execution. -AnalysisType.DETECT_SECRET: +**AnalysisType.DETECT_SECRET:** Runs `detect-secrets `_ checks for *secrets* in code. By default, all tests in Bandit and detect-secrets are run. Details of the tests are listed below diff --git a/docs/seccomp.rst b/docs/seccomp.rst index 82d24f0..0fc1621 100644 --- a/docs/seccomp.rst +++ b/docs/seccomp.rst @@ -1,4 +1,5 @@ -## Seccomp policy category +Seccomp policy category +======================= The process (Python) running the AI code inside the container is further constrained with seccomp. From 31ea854b7d2384095950e29d252ff13a0152e417 Mon Sep 17 00:00:00 2001 From: mvle Date: Thu, 16 Apr 2026 11:05:43 -0500 Subject: [PATCH 3/3] fix doc Signed-off-by: mvle --- docs/analysis.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/analysis.rst b/docs/analysis.rst index ffb4d68..d616baa 100644 --- a/docs/analysis.rst +++ b/docs/analysis.rst @@ -3,9 +3,8 @@ Security Analysis GuardX provides a common interface for statically scanning Python code for safety and security issues. -Analysis can be invoked like so: +Analysis can be invoked like so:: -.. code-block:: python result = guardx.Guardx().analyze(python_code, {AnalysisType.UNSAFE_CODE, AnalysisType.DETECT_SECRET}) **AnalysisType.UNSAFE_CODE:** @@ -18,7 +17,7 @@ By default, all tests in Bandit and detect-secrets are run. Details of the tests and can be found on the respective project's website. Bandit Tests `ref `_ ---------------------------------------------------------------------------------- +================================================================================ Bandit includes tests for various security vulnerabilities. Full list `here `_