Metadata-Version: 2.4
Name: zachos-agent-sandbox-sdk
Version: 0.1.0
Summary: Sandboxed execution environments for AI agents with permission management and audit logging
Author-email: Agent Sandbox SDK <dev@agentsandbox.dev>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/agent-sandbox-sdk
Project-URL: Documentation, https://agent-sandbox-sdk.readthedocs.io
Project-URL: Repository, https://github.com/yourusername/agent-sandbox-sdk
Keywords: ai,agents,sandbox,security,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: websockets>=12.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.6.0; extra == "dev"
Provides-Extra: dashboard
Requires-Dist: jinja2>=3.1.0; extra == "dashboard"

# agent-sandbox-sdk

Give AI agents controlled system access without the security nightmares or container overhead.

## What is this?

**agent-sandbox-sdk** is a Python SDK that wraps AI agent functions in isolated execution environments with fine-grained permission controls, resource limits, and comprehensive audit logging. Instead of giving LLMs unrestricted system access or wrestling with Docker containers, you get a simple decorator-based API that makes sandboxing as easy as `@sandbox(permissions=[...])`.

Perfect for LangChain tools, CrewAI agents, or any AI system that needs to touch the filesystem, network, or spawn processes safely.

## Features

- **Decorator-based API** – Wrap any function with `@sandbox()` for instant isolation
- **Fine-grained permissions** – Whitelist specific filesystem paths, network domains, and process types
- **Resource limits** – Cap CPU time, memory usage, and disk writes per execution
- **Comprehensive audit logging** – Track every action with timestamps, results, and resource consumption
- **Real-time monitoring** – Built-in dashboard for observing agent behavior across sessions
- **Framework integrations** – Drop-in support for LangChain, CrewAI, and AutoGPT
- **Webhook support** – Get notified on permission violations or resource threshold breaches
- **Cross-platform** – Works on Linux, macOS, and Windows

## Quick Start

### Installation

```bash
pip install agent-sandbox-sdk
```

### Basic Usage

```python
from agent_sandbox import sandbox, FileSystemPermission, NetworkPermission

@sandbox(
    permissions=[
        FileSystemPermission(read=["/data"], write=["/tmp/output"]),
        NetworkPermission(domains=["api.example.com"])
    ],
    max_execution_time=30,  # seconds
    max_memory_mb=512
)
def agent_task(query: str):
    # Agent code runs in isolated environment
    with open("/data/docs.txt") as f:
        content = f.read()
    
    # Network access only to whitelisted domains
    response = requests.get("https://api.example.com/search")
    
    return process_results(content, response.json())

# Execute safely
result = agent_task("analyze sales data")
```

### LangChain Integration

```python
from langchain.agents import Tool
from agent_sandbox.integrations.langchain import SandboxedTool

# Wrap any LangChain tool with sandbox protection
safe_tool = SandboxedTool(
    tool=Tool(
        name="file_reader",
        func=read_file,
        description="Read files from disk"
    ),
    permissions=[FileSystemPermission(read=["/safe/path"])],
    max_execution_time=10
)

agent = initialize_agent([safe_tool], llm, agent="zero-shot-react-description")
```

### Monitoring Dashboard

```bash
# Start the monitoring dashboard
agent-sandbox dashboard --port 8080
```

Access at `http://localhost:8080` to view:
- Real-time agent execution logs
- Resource usage graphs
- Permission violation alerts
- Audit trail exports

## Usage Examples

### Resource Monitoring

```python
from agent_sandbox import sandbox, get_execution_stats

@sandbox(max_memory_mb=256, max_execution_time=60)
def data_processor(files: list):
    results = []
    for file in files:
        results.append(process_file(file))
    return results

result = data_processor(["data1.csv", "data2.csv"])
stats = get_execution_stats()

print(f"Peak memory: {stats.peak_memory_mb}MB")
print(f"Execution time: {stats.execution_time}s")
print(f"Files accessed: {stats.files_accessed}")
```

### Audit Logging

```python
from agent_sandbox import sandbox, AuditLogger

# Configure audit logger with webhook
logger = AuditLogger(
    log_file="/var/log/agents/audit.jsonl",
    webhook_url="https://your-server.com/audit-webhook",
    alert_on_violation=True
)

@sandbox(
    permissions=[NetworkPermission(domains=["safe-api.com"])],
    audit_logger=logger
)
def agent_action():
    # All actions logged automatically
    response = requests.get("https://safe-api.com/data")
    return response.json()
```

### CrewAI Integration

```python
from crewai import Agent, Task, Crew
from agent_sandbox.integrations.crewai import SandboxedAgent

# Create sandboxed CrewAI agent
analyst = SandboxedAgent(
    role="Data Analyst",
    goal="Analyze sales data",
    backstory="Expert in data analysis",
    permissions=[
        FileSystemPermission(read=["/data/sales"]),
        NetworkPermission(domains=["api.salesforce.com"])
    ],
    max_execution_time=120
)

crew = Crew(agents=[analyst], tasks=[...])
```

## Tech Stack

- **Core**: Python 3.8+ with asyncio for concurrent execution
- **Isolation**: Platform-specific syscall monitoring (seccomp on Linux, Seatbelt on macOS)
- **Dashboard**: FastAPI backend with React frontend
- **Audit Storage**: SQLite for local logging with optional PostgreSQL support
- **Monitoring**: Prometheus metrics export for production observability

## Configuration

Create `sandbox_config.yaml`:

```yaml
default_permissions:
  filesystem:
    read: ["/data/public"]
    write: ["/tmp"]
  network:
    domains: ["*.safe-api.com"]
  
resource_limits:
  max_execution_time: 60
  max_memory_mb: 512
  max_disk_write_mb: 100

audit:
  enabled: true
  log_file: "/var/log/agent_sandbox/audit.log"
  webhook_url: "https://monitoring.example.com/webhook"
  
dashboard:
  port: 8080
  auth_required: true
```

## CLI Commands

```bash
# Start monitoring dashboard
agent-sandbox dashboard

# View audit logs
agent-sandbox logs --tail 100 --filter "violation"

# Export audit report
agent-sandbox export --format json --output report.json

# Validate permissions config
agent-sandbox validate config.yaml
```

## License

MIT License - see LICENSE file for details.

---

**Security Note**: This SDK provides defense-in-depth for AI agent execution but should not be the only security measure. Always follow the principle of least privilege and conduct security reviews of agent code.
