┌───────────────────────┐      ┌───────────────────────────┐      ┌─────────────────────┐
│  AI Assistant (Claude │ ───▶ │  ubuntu-mcp-server        │ ───▶ │  Ubuntu System      │
│  Desktop, custom      │ MCP  │  stdio/stdin-stream       │ safe │  files · commands ·  │
│  clients)             │      │  SecurityChecker │Audit   │      │  packages · system   │
└───────────────────────┘      └───────────────────────────┘      └─────────────────────┘

# 1. Clone & enter
git clone https://github.com/Serp3n7/secure-ubuntu-mcp.git && cd secure-ubuntu-mcp

# 2. Interactive setup (venv + deps + tests + Claude config) — recommended
python3 setup.py

# --- or, manually ---
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. Verify
python main.py --test
python main.py --security-test

python main.py --policy secure   # 🔐 production default
python main.py --policy dev      # 🧪 more permissive, for development

usage: main.py [options]

--policy secure|dev    Security policy to use                          [default: secure]
--test                 Run functionality tests
--security-test        Run the comprehensive security validation suite
--log-level LEVEL      Logging level: INFO, DEBUG, WARNING, ERROR      [default: INFO]

wget https://github.com/aaddrick/claude-desktop-debian/releases/latest/download/claude-desktop_latest_amd64.deb
sudo dpkg -i claude-desktop_latest_amd64.deb
sudo apt-get install -f

{
  "mcpServers": {
    "secure-ubuntu": {
      "command": "/path/to/ubuntu_mcp_server/.venv/bin/python3",
      "args": ["/path/to/ubuntu_mcp_server/main.py", "--policy", "secure"],
      "env": { "MCP_LOG_LEVEL": "INFO" }
    }
  }
}

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def example():
    params = StdioServerParameters(command="python3", args=["main.py"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            # ... call tools ...

asyncio.run(example())

from main import SecurityPolicy, SecureUbuntuController

policy = SecurityPolicy(
    allowed_paths=["/your/custom/paths"],
    forbidden_paths=["/sensitive/areas"],
    allowed_commands=["safe", "commands"],
    forbidden_commands=["dangerous", "commands"],
    command_whitelist_mode=True,   # True = deny-by-default
    max_command_timeout=30,
    allow_sudo=False,              # use with extreme caution
    audit_actions=True,
    resolve_symlinks=True,         # always on for security
    use_path_cache=False,          # off by default (TOCTOU-safe)
    use_shell_exec=False,          # off by default
)

controller = SecureUbuntuController(policy)

{
  "server": {
    "name": "ubuntu-controller",
    "version": "1.0.0",
    "description": "MCP Server for Ubuntu System Control",
    "log_level": "INFO"
  },
  "security": {
    "policy_name": "safe",
    "allowed_paths": ["~/", "/tmp", "/var/tmp"],
    "forbidden_paths": ["/etc/passwd", "/etc/shadow", "/root", "/boot", "/sys", "/proc"],
    "allowed_commands": ["ls", "cat", "echo", "pwd", "whoami", "date", "grep", "find", "which", "file", "head", "tail", "apt", "git", "python3", "pip3"],
    "forbidden_commands": ["rm", "rmdir", "dd", "mkfs", "shutdown", "reboot", "mount", "umount", "chmod", "chown"],
    "max_command_timeout": 30,
    "allow_sudo": false
  }
}

../../../etc/passwd        → SecurityViolation
/etc/passwd                → SecurityViolation
/tmp/../etc/passwd         → SecurityViolation
symlink_to_/etc/passwd     → SecurityViolation  (symlinks fully resolved)

echo hello; rm -rf /     → SecurityViolation
echo `cat /etc/passwd`   → SecurityViolation
echo $(whoami)           → SecurityViolation
ls | rm -rf /            → SecurityViolation

COMMAND_ATTEMPT: user=serp3n7 cmd='ls -la' cwd=default
FILE_READ:       user=serp3n7 path='/home/serp3n7/foo' status=SUCCESS
SECURITY_VIOLATION: user=serp3n7 violation='COMMAND_BLOCKED' details='Command not in whitelist: nmap'

./run_tests.sh          # full suite: controller, MCP client, policies, files, packages
python main.py --test   # functionality tests
python main.py --security-test   # attack-surface validation
python test_client.py             # end-to-end MCP protocol client
python test_client.py --simple    # controller-level smoke test

# systemd service install
sudo python3 install.py
sudo systemctl enable --now ubuntu-mcp

from main import create_secure_policy, SecureUbuntuController

controller = SecureUbuntuController(create_secure_policy())

@mcp.tool("your_tool_name")
async def your_tool(param: str) -> str:
    try:
        result = controller.safe_operation(param)
        return json.dumps(result, indent=2)
    except Exception as e:
        return json.dumps({"error": str(e)}, indent=2)

def create_custom_policy() -> SecurityPolicy:
    return SecurityPolicy(
        allowed_paths=["/your/paths"],
        forbidden_commands=["dangerous", "commands"],
        # ...
    )

python main.py --log-level DEBUG --policy secure
tail -f /tmp/ubuntu_mcp_audit.log