Home

PySandboxes documentation

PySandboxes runs a Python program under a deny-by-default policy kept in a readable .py-sandboxes file, with an optional Linux kernel boundary around it. This index is organized around reader tasks. Pick a reading path first.

Reading paths

5 minutes: what is it, does it fit?

1. README: the demo, the quick start, the limits at a glance.
2. Use cases: which scenario, which protection level.

30 minutes: try it and decide

1. Run the quick demo: learn a policy, then see it refuse an attack.
2. Usage: complete mode or partial mode.
3. Configuration files: read and lock a .py-sandboxes.
4. Provider comparison: choose the OS layer.
5. Alternatives: how it compares with containers, microVMs and hosted services.

Security review: what exactly does it hold?

1. Security model: the layers and the filters.
2. Weaknesses: known limits and residual risks.
3. Python-layer assessment and eval-* assessment: attack by attack.
4. Test coverage map: what is exercised, and what is not.
5. SECURITY.md: what counts as a vulnerability, and how to report one.

Get started and configure

• README: run an application in complete mode, with the limits at a glance.
• Usage: complete mode, partial mode, @sandbox, init_fn, learning.
• Configuration files: locate .py-sandboxes, compose files with include, and configure a module.
• FAQ: answers to common usage and troubleshooting questions.
• Samples: framework integrations and instructions for running the sample projects.
• Integrating with the MCP SDK: configure a sandbox for an MCP server.
• Database: use the database-backed data table.

Understand the security model

• Security model: why, the layers, the risks addressed and the filters.
• Weaknesses: known limits and residual risks of the Python layer.
• Security assessment of the Python layer: attacks, mechanisms, regression tests, and open paths.
• Security assessment of dynamically evaluated code: the eval-* guard's behavior and limits.
• Dynamically evaluated code: configuration reference for the eval-* rules.
• Transport unpickle guard: validation of objects received from the sandbox child.
• Native guard study: the native-extension approach considered and the decision made.
• Related CVEs: published vulnerabilities in adjacent agent frameworks.

Choose and operate an OS provider

• Provider comparison: which provider for which situation, enforcement mechanisms, prerequisites, compatibility, and trade-offs.
• Landlock
• Bubblewrap (bwrap)
• Firejail
• Unshare
• QEMU
• DNS and network filtering: DNS resolution and iptables behavior.
• Docker Hub images: pull and run published provider images.

Compare and evaluate

• Alternative sandboxes: comparison with other sandboxes, frameworks, and hosted services.
• Use cases: threat scenarios and suitable isolation levels.
• Test coverage map: test suites, provider matrix, skipped scenarios, and approximate counts.
• Learning from tests: use full or partial test runs to discover and review sandbox permissions.

Maintain and explore the project

• Implementation: framework architecture and execution flow.
• Coding-agent skills and plugin: learn and review rules from tests with a human approval gate.
• Roadmap: planned work and project direction.
• Releasing: release and publication process for maintainers.
• Confining Python by observation: research background for the policy-learning approach.