Container Sandbox

Container-MCP

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

A secure, container-based implementation of the Model Context Protocol (MCP) for executing tools on behalf of large language models.

Overview

Container-MCP provides a sandboxed environment for safely executing code, running commands, accessing files, and performing web operations requested by large language models. It implements the MCP protocol to expose these capabilities as tools that can be discovered and called by AI systems in a secure manner.

The architecture uses a domain-specific manager pattern with multi-layered security to ensure tools execute in isolated environments with appropriate restrictions, protecting the host system from potentially harmful operations.

Key Features

**Multi-layered Security** - Container isolation using Podman/Docker - AppArmor profiles for restricting access - Firejail sandboxing for additional isolation - Resource limits (CPU, memory, execution time) - Path traversal prevention - Allowed extension restrictions

**MCP Protocol Implementation** - Standardized tool discovery and execution - Resource management - Async execution support

**Domain-Specific Managers** - `BashManager`: Secure command execution - `PythonManager`: Sandboxed Python code execution - `FileManager`: Safe file operations - `WebManager`: Secure web browsing and scraping

**Configurable Environment** - Extensive configuration via environment variables - Custom environment support - Development and production modes

Available Tools

System Operations

`system_run_command`

Executes bash commands in a secure sandbox environment.

**Parameters**: - `command` (string, required): The bash command to execute - `working_dir` (string, optional): Working directory (ignored in sandbox)

**Returns**: - `stdout` (string): Command standard output - `stderr` (string): Command standard error - `exit_code` (integer): Command exit code - `success` (boolean): Whether command completed successfully

`system_run_python`

Executes Python code in a secure sandbox environment.

**Parameters**: - `code` (string, required): Python code to execute - `working_dir` (string, optional): Working directory (ignored in sandbox)

**Returns**: - `output` (string): Print output from the code - `error` (string): Error output from the code - `result` (any): Optional return value (available if code sets `_` variable) - `success` (boolean): Whether code executed successfully

`system_env_var`

Gets environment variable values.

**Parameters**: - `var_name` (string, optional): Specific variable to retrieve

**Returns**: - `variables` (object): Dictionary of environment variables - `requested_var` (string): Value of the requested variable (if var_name provided)

File Operations

`file_read`

Reads file contents safely.

**Parameters**: - `path` (string, required): Path to the file (relative to sandbox root) - `encoding` (string, optional): File encoding (default: "utf-8")

**Returns**: - `content` (string): File content - `size` (integer): File size in bytes - `modified` (float): Last modified timestamp - `success` (boolean): Whether the read was successful

`file_write`

Writes content to a file safely.

**Parameters**: - `path` (string, required): Path to the file (relative to sandbox root) - `content` (string, required): Content to write - `encoding` (string, optional): File encoding (default: "utf-8")

**Returns**: - `success` (boolean): Whether the write was successful - `path` (string): Path to the written file

`file_list`

Lists contents of a directory safely.

**Parameters**: - `path` (string, optional): Path to the directory (default: "/") - `pattern` (string, optional): Glob pattern to filter files

**Returns**: - `entries` (array): List of directory entries with metadata - `path` (string): The listed directory path - `success` (boolean): Whether the listing was successful

`file_delete`

Deletes a file safely.

**Parameters**: - `path` (string, required): Path of the file to delete

**Returns**: - `success` (boolean): Whether the deletion was successful - `path` (string): Path to the deleted file

`file_move`

Moves or renames a file safely.

**Parameters**: - `source` (string, required): Source file path - `destination` (string, required): Destination file path

**Returns**: - `success` (boolean): Whether the move was successful - `source` (string): Original file path - `destination` (string): New file path

Web Operations

`web_search`

Uses a search engine to find information on the web.

**Parameters**: - `query` (string, required): The query to search for

**Returns**: - `results` (array): List of search results - `query` (string): The original query

`web_scrape`

Scrapes a specific URL and returns the content.

**Parameters**: - `url` (string, required): The URL to scrape - `selector` (string, optional): CSS selector to target specific content

**Returns**: - `content` (string): Scraped content - `url` (string): The URL that was scraped - `title` (string): Page title - `success` (boolean): Whether the scrape was successful - `error` (string): Error message if scrape failed

`web_browse`

Interactively browses a website using Playwright.

**Parameters**: - `url` (string, required): Starting URL for browsing session

**Returns**: - `content` (string): Page HTML content - `url` (string): The final URL after any redirects - `title` (string): Page title - `success` (boolean): Whether the browsing was successful - `error` (string): Error message if browsing failed

Execution Environment

Container-MCP provides isolated execution environments for different types of operations, each with its own security measures and resource constraints.

Container Environment

The main Container-MCP service runs inside a container (using Podman or Docker) providing the first layer of isolation:

**Base Image**: Ubuntu 24.04

**User**: Non-root ubuntu user

**Python**: 3.12

**Network**: Limited to localhost binding only

**Filesystem**: Volume mounts for configuration, data, and logs

**Security**: AppArmor, Seccomp, and capability restrictions

Bash Execution Environment

The Bash execution environment is configured with multiple isolation layers:

**Allowed Commands**: Restricted to safe commands configured in `BASH_ALLOWED_COMMANDS`

**Firejail Sandbox**: Process isolation with restricted filesystem access

**AppArmor Profile**: Fine-grained access control

**Resource Limits**: - Execution timeout (default: 30s, max: 120s) - Limited directory access to sandbox only

**Network**: No network access

**File System**: Read-only access to data, read-write to sandbox

Example allowed commands:

Python Execution Environment

The Python execution environment is designed for secure code execution:

**Python Version**: 3.12

**Memory Limit**: Configurable memory ceiling (default: 256MB)

**Execution Timeout**: Configurable time limit (default: 30s, max: 120s)

**AppArmor Profile**: Restricts access to system resources

**Firejail Sandbox**: Process isolation

**Capabilities**: All capabilities dropped

**Network**: No network access

**Available Libraries**: Only standard library

**Output Capturing**: stdout/stderr redirected and sanitized

**Resource Controls**: CPU and memory limits enforced

File System Environment

The file system environment controls access to files within the sandbox:

**Base Directory**: All operations restricted to sandbox root

**Path Validation**: All paths normalized and checked for traversal attempts

**Size Limits**: Maximum file size enforced (default: 10MB)

**Extension Control**: Only allowed extensions permitted (default: txt, md, csv, json, py)

**Permission Control**: Appropriate read/write permissions enforced

**Isolation**: No access to host file system

Web Environment

The web environment provides controlled access to external resources:

**Domain Control**: Optional whitelisting of allowed domains

**Timeout Control**: Configurable timeouts for operations

**Browser Control**: Headless browser via Playwright for full rendering

**Scraping Control**: Simple scraping via requests/BeautifulSoup

**Content Sanitization**: All content parsed and sanitized

**Network Isolation**: Separate network namespace via container

Architecture

The project follows a modular architecture:

Each manager follows consistent design patterns:

`.from_env()` class method for environment-based initialization

Async execution methods for non-blocking operations

Strong input validation and error handling

Security-first approach to all operations

Security Measures

Container-MCP implements multiple layers of security:

**Container Isolation**: Uses Podman/Docker for container isolation

**AppArmor Profiles**: Fine-grained access control for bash and Python execution

**Firejail Sandboxing**: Additional process isolation

**Resource Limits**: Memory, CPU, and execution time limits

**Path Traversal Prevention**: Validates and normalizes all file paths

**Allowed Extension Restrictions**: Controls what file types can be accessed

**Network Restrictions**: Controls what domains can be accessed

**Least Privilege**: Components run with minimal necessary permissions

Installation

Prerequisites

Linux system with Podman or Docker

Python 3.12+

Firejail (`apt install firejail` or `dnf install firejail`)

AppArmor (`apt install apparmor apparmor-utils` or `dnf install apparmor apparmor-utils`)

Quick Start

The quickest way to get started is to use the all-in-one script:

Step-by-Step Installation

You can also perform the installation steps individually:

**Initialize the project**: ```bash ./bin/01-init.sh ```

**Build the container**: ```bash ./bin/02-build-container.sh ```

**Set up the environment**: ```bash ./bin/03-setup-environment.sh ```

**Run the container**: ```bash ./bin/04-run-container.sh ```

**Run tests** (optional): ```bash ./bin/05-run-tests.sh ```

Usage

Once the container is running, you can connect to it using any MCP client implementation. The server will be available at `http://localhost:8000` or the port specified in your configuration.

**Important:** When configuring your MCP client, you must set the endpoint URL to `http://127.0.0.1:<port>/sse` (where `<port>` is 8000 by default or the port you've configured). The `/sse` path is required for proper server-sent events communication.

Example Python Client

Configuration

Container-MCP can be configured through environment variables, which can be set in `volume/config/custom.env`:

Server Configuration

Bash Manager Configuration

Python Manager Configuration

File Manager Configuration

Web Manager Configuration

Development

Setting Up a Development Environment

Create a Python virtual environment: ```bash python3.12 -m venv .venv source .venv/bin/activate ```

Install dependencies: ```bash pip install -r requirements-dev.txt ```

Install the package in development mode: ```bash pip install -e . ```

Running Tests

Development Server

To run the MCP server in development mode:

License

This project is licensed under the Apache License 2.0.

Author

Martin Bukowski