Metadata-Version: 2.4
Name: hermetic-seal
Version: 1.0.0
Summary: User-space sandbox runner for Python console scripts
Project-URL: Repository, https://gitlab.com/matthewdeanmartin/hermetic
Project-URL: Documentation, https://hermetic.readthedocs.io/en/latest/
Project-URL: Changelog, https://gitlab.com/matthewdeanmartin/hermetic/blob/main/CHANGELOG.md
Project-URL: homepage, https://gitlab.com/matthewdeanmartin/hermetic
Project-URL: issues, https://gitlab.com/matthewdeanmartin/hermetic/issues/
Author: Matthew Dean Martin
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Requires-Dist: typing-extensions; python_version < '3.11'
Description-Content-Type: text/markdown

# hermetic

This is lightweight sandboxing for semi-trusted code or for disabling APIs in unit tests. What is semi-trusted code?
Things like pluggy plugins, LLM generated code. Unit test code is trusted, but as design decision, you may want to
avoid accidentally creating integration tests.

Run a python tool, or your application with certain APIs disabled, such as network or subprocess.

The previously safe library you depend on was hijacked and will be sending your password files to a remote server.
Or you installed this and the malicious hackers didn't include evasive code to defeat this fig leaf of a security
feature and the day is saved.

If Alice and Bob know about your application and specifically are targeting this, this tool won't help. See docs for
a discussion of how to defeat hermetic-seal.

## Usage

### Programmatic API

You can use `hermetic` directly in your Python code via the `hermetic_blocker` context manager or the `@with_hermetic`
decorator.

#### Decorator

The `@with_hermetic` decorator is the easiest way to apply guards to an entire function.

```python
from hermetic import with_hermetic
import requests


@with_hermetic(block_network=True, allow_domains=["api.internal.com"])
def process_data():
    # This will fail because all network access is blocked by default.
    # requests.get("https://example.com") # --> raises PolicyViolation

    # This is allowed because the domain is on the allow-list.
    return requests.get("https://api.internal.com/data")


process_data()
```

#### Context Manager

For more granular control, use the `hermetic_blocker` context manager.

```python
from hermetic import hermetic_blocker
import os


def check_system():
    # Subprocesses are allowed here
    os.system("echo 'Checking system...'")

    with hermetic_blocker(block_subprocess=True):
        # Inside this block, os.system() would raise a PolicyViolation
        print("Running in a sandboxed context.")
        os.system("echo 'This will fail.'")  # --> raises PolicyViolation

    # Subprocesses are allowed again
    os.system("echo 'Exited sandbox.'")


check_system()
```

## Where could this work?

There are APIs you don't need but an application or 3rd party library you depend on needs. So you block them.

The 3rd party library must be unaware of hermetic or monkeypatching. Import order is important, hermetic must run
early enough to intercept all imports to the banned API. Then use of the banned API is blocked and the whole app stops.

This already works in unit testing where there isn't an adversarial relationship between the developers testing the code
and writing the code under test, where you block network traffic to guarantee a unit test is pure of network side
effects.

## Is this defeatable?

Yes, by many routes. Native code, import order tricks, undoing a monkey patch, bringing along a vendorized copy of APIs,
and so on.

This is "envelope instead of postcard" level security. This is "lock your door with standard key that can be picked with
a $5 purchase on Ebay" level security.

Real sandboxing is running your code in a docker container.

## Prior Art

This technique of monkey-patching for isolation is well-established, particularly in the testing ecosystem.

- [pytest-socket](https://pypi.org/project/pytest-socket/): Disables sockets during tests.
- [pytest-network](https://pypi.org/project/pytest-network/): Disables networking during tests.

For stronger sandboxing, consider:

- [pysandbox](https://github.com/vstinner/pysandbox): Uses Linux `seccomp` for kernel-level syscall filtering.
- [RestrictedPython](https://pypi.org/project/RestrictedPython/): Rewrites Python AST to enforce constraints.
- [Docker](https://www.docker.com/): OS-level virtualization.

### Command-Line Interface

Use the `hermetic` command to run any Python console script, separating its arguments with `--`.

**Syntax**: `hermetic [flags] -- <command> [command_args]`

#### Common Flags:

- `--no-network`: Disable all network activity.
- `--allow-localhost`: Allows network connections to localhost (used with `--no-network`).
- `--allow-domain <domain>`: Allows connections to a specific domain (repeatable).
- `--no-subprocess`: Disable creating new processes.
- `--fs-readonly[=/path/to/root]`: Make the filesystem read-only. Optionally, restrict all reads to be within the
  specified root directory.
- `--no-environment`: Disable environment variable reads and mutations.
- `--no-code-exec`: Disable `eval`, `exec`, `compile`, and `runpy` execution helpers.
- `--deny-import <module>`: Deny importing a module or package prefix (repeatable).
- `--no-interpreter-mutation`: Disable `sys.path`, `cwd`, and `site` mutation surfaces.
- `--block-native`: Block imports of native C extensions.
- `--profile <name>`: Apply a pre-configured profile (e.g., `block-all`).
- `--trace`: Print a message to stderr when an action is blocked.

#### CLI Examples:

**Block network access for the `httpie` tool:**

```bash
$ hermetic --no-network -- http [https://example.com](https://example.com)

hermetic: blocked action: network disabled: DNS(example.com)
```

**Run a script in a read-only filesystem where it can only read from `./sandbox`:**

```bash
$ hermetic --fs-readonly=./sandbox -- python my_script.py

# my_script.py will raise PolicyViolation if it tries to read outside ./sandbox
# or write anywhere.
```

**Apply the `block-all` profile to completely lock down a script:**

```bash
$ hermetic --profile block-all -- my_analyzer.py --input data.csv
```

## Project Links

- [GitHub](https://github.com/matthewdeanmartin/hermetic)
- [PyPI](https://pypi.org/project/hermetic-seal/)
- [Documentation](https://hermetic.readthedocs.io/en/latest/)
- [Bug Tracker](https://github.com/matthewdeanmartin/hermetic/issues)
- [Change Log](https://github.com/matthewdeanmartin/hermetic/blob/main/CHANGELOG.md)
