DEV Community

Onkar Singh Pawar
Onkar Singh Pawar

Posted on Fully Autonomous

AegisExec: a Linux action broker for untrusted AI agents

#opensource #python #security #ai

An AI agent does not need a sophisticated exploit to cause damage. A tool request that reads outside its workspace, exposes credentials, or starts an unbounded process can be enough. Prompt instructions alone are not an operating-system security boundary.

AegisExec is my experimental defensive project for exploring that boundary: a Linux CLI that evaluates structured action requests before reading workspace files or running Python.

Built by onkar-cybersec. The project was built with AI assistance, followed by source review, fixes, and independent regression testing. It is not a production-certified sandbox or a general detector of AI-generated attacks.

Source code and installation instructions

The idea: mediate the action

The flow is deliberately small:

Untrusted agent request
        |
        v
Strict schema + trusted policy
        |
        +--> DENIED: stop and record a metadata-only event
        |
        v
Bounded file operation OR isolated Python worker
Enter fullscreen mode Exit fullscreen mode

The broker accepts three operations: read_text, list_dir, and run_python. A client submits a versioned JSON request. The operator controls the policy and workspace.

This only works when the agent's operations go through the broker. An agent with a separate host shell can bypass it.

Five defensive controls

  1. Workspace boundaries. File access uses descriptor-relative resolution. Absolute paths, raw .., symlinks, hardlink aliases, special files and common credential filenames are rejected. For Python, the broker creates a bounded snapshot of admitted workspace files.
  2. Network isolation. Python runs through Linux Bubblewrap in a network namespace without host interfaces or outbound connectivity.
  3. Restricted host actions. The broker offers fixed operations rather than arbitrary host executable or shell requests. Python can still launch installed runtime binaries inside its sandbox; this is not a Python-language allowlist.
  4. Execution limits. The sandbox drops capabilities and mounts the snapshot read-only. The host bounds combined stdout/stderr bytes and execution time. The worker also sets resource limits. Missing prerequisites fail closed.
  5. Manifest drift review. An operator can pin a canonical SHA-256 baseline and compare later tool descriptions and capabilities. This is trust-on-first-use change detection, not proof that a tool is safe. It is a separate review step, not an automatic prerequisite for every run request.

Audit records exclude raw code, file contents, paths and approval tokens, and hash request identifiers. JSON and escaped HTML reports provide a decision summary. Approval-required operations remain disabled in v0.1; a client-supplied token cannot authorize them.

A small example

After installing the package and running aegisexec doctor, create a new demo directory:

aegisexec init --dir ./demo
aegisexec run demo/requests/valid_read.json --policy demo/policy.json
Enter fullscreen mode Exit fullscreen mode

The generated traversal example must be denied:

aegisexec run demo/requests/attack_traversal.json --policy demo/policy.json
# Expected exit status: 2
Enter fullscreen mode Exit fullscreen mode

A calculation request can look like this:

{
  "schema_version": "1.0",
  "request_id": "calc-1",
  "operation": "run_python",
  "parameters": {
    "code": "print(sum(range(10)))"
  }
}
Enter fullscreen mode Exit fullscreen mode

Save it as demo/requests/calc.json, then run:

aegisexec run demo/requests/calc.json --policy demo/policy.json
Enter fullscreen mode Exit fullscreen mode

What was tested

The reviewed source passed 69 tests with no skips in Ubuntu 22.04 CI using Python 3.10 and distro Bubblewrap. Those include 17 actual sandbox execution tests. The CLI smoke workflow also passed.

The suite checks traversal and symlink swaps, nested allowlists, hardlinks and special files, audit privacy, report escaping, manifest drift, outside-file access, environment scrubbing, network denial, read-only mounts, output flooding and timeouts.

One independent regression checks that a detached subprocess actually exists while the sandbox runs and disappears after timeout. That tests cleanup rather than merely checking a returned timeout status.

Linux CI evidence

Actual Linux regression results

The browser interface is a simulation

The repository also includes a React policy explorer with synthetic request scenarios and manifest comparisons. It illustrates decisions; it does not execute Python or enforce Linux confinement. The CLI is the authoritative implementation.

Policy explorer showing a simulated traversal denial

Where the boundary ends

Use a dedicated workspace containing only data safe to expose to untrusted code. Filename filters cannot identify every secret. System runtime directories remain readable inside the sandbox, and there is no seccomp allowlist.

The resource limits are not cgroup aggregate memory, process or temporary-disk budgets. For strongly hostile workloads, use an additional VM or container boundary. The kernel, Bubblewrap, interpreter, broker, policy, baseline and audit directory are trusted components.

The installation guide targets Kali, Parrot, Debian and Ubuntu, but the tested environment is Ubuntu 22.04. Windows and macOS cannot run the Linux sandbox.

Feedback welcome

I would especially appreciate feedback on filesystem race handling, sandbox resource boundaries and practical integration with agent tool calls. Please use synthetic data when experimenting.

Explore AegisExec on GitHub. The project is MIT licensed.

Top comments (0)