Tunnel Manager

隧道管理器-A2A|AG-UI|MCP

*版本：1.10.0*

概述

该项目提供了一个基于Python的 Tunnel 用于安全SSH连接和文件传输的类，与FastMCP服务器集成(mcp_server.py)将这些功能作为人工智能驱动的工作流程的工具。该实现支持标准SSH（例如，用于本地网络）和Teleport的安全访问平台，利用 paramiko SSH操作库。

特性

隧道等级

• 目的：为单个或多个主机提供安全的SSH连接、文件传输和密钥管理。
• 关键功能:

- 运行远程命令：在远程主机上执行shell命令并检索输出。 - 文件上传/下载：使用SFTP向单个主机或清单组中的所有主机传输文件。 - 无密码SSH设置：配置基于密钥的身份验证，以实现安全、无密码的访问，并支持RSA和Ed25519密钥类型。 - SSH配置管理：将本地SSH配置文件复制到远程主机。 - 密钥轮换：生成和部署新的SSH密钥对（RSA或Ed25519），更新 authorized_keys. - 库存支持：在Ansible风格的YAML清单中定义的多个主机上操作。， all, homelab, poweredge). - 远程传输支持：与Teleport的基于证书的身份验证和代理无缝集成。 - 配置灵活性：从加载SSH设置 ~/.ssh/config 默认情况下，对用户名、密码、身份文件、证书和代理命令进行可选覆盖。 - 日志记录：用于调试和审核的可选基于文件的日志记录。 - 并行执行：支持跨多个主机的并行操作，具有可配置的线程限制。 - 密钥类型支持：在身份验证、生成和轮换中明确支持RSA和Ed25519密钥，以增强安全性和兼容性。 - 主机管理：通过以下方式管理主机库存 HostManager 用于存储和检索主机配置的类。

FastMCP服务器

• 目的：暴露 Tunnel 类功能作为FastMCP服务器，使AI工具能够以编程方式执行远程操作。
• 提供的工具:

- 主机管理工具: - list_hosts：列出清单中的所有托管主机 - add_host：将新主机添加到受管库存 - remove_host：从受管库存中删除主机 - 单主机操作: - run_command_on_remote_host：在单个远程主机上运行shell命令 - send_file_to_remote_host：通过SFTP将文件上传到单个远程主机 - receive_file_from_remote_host：通过SFTP从单个远程主机下载文件 - check_ssh_server：检查SSH服务器是否正在运行并配置为基于密钥的身份验证 - test_key_auth：测试主机的基于密钥的身份验证 - setup_passwordless_ssh：为单个主机设置无密码SSH - copy_ssh_config：将SSH配置文件复制到单个远程主机 - rotate_ssh_key：旋转单个主机的SSH密钥 - remove_host_key：从本地删除主机的密钥 known_hosts 文件 - 库存操作: - configure_key_auth_on_inventory：为清单组中的所有主机设置无密码SSH - run_command_on_inventory：在清单组中的所有主机上运行命令 - copy_ssh_config_on_inventory：将SSH配置文件复制到清单组中的所有主机 - rotate_ssh_key_on_inventory：轮换清单组中所有主机的SSH密钥 - send_file_to_inventory：通过SFTP将文件上传到清单组中的所有主机 - receive_file_from_inventory：通过SFTP从清单组中的所有主机下载文件 - 运营管理工具: - start_operation：通过进度跟踪启动新操作 - get_operation_progress：获取正在运行的操作的进度 - cancel_operation：取消正在运行的操作 - get_resource_metrics：在操作过程中获取资源指标 - list_active_sessions：列出活动SSH会话 - 系统智能工具: - get_system_info：获取全面的系统信息（操作系统、硬件、软件包、正常运行时间） - discover_services：发现正在运行的服务、进程和开放端口 - analyze_logs：分析指定模式的日志文件 - network_topology：映射网络接口、路由和活动连接 - 高级文件操作工具: - recursive_file_operations：执行递归目录操作（复制、移动、删除、列表、chmod、chown） - file_content_search：跨目录搜索文件内容 - file_watch_monitor：监控文件/目录的实时更改 - file_diff_compare：比较两个不同主机上的文件 - smart_backup：使用版本控制和压缩创建自动备份 - 安全审计工具: - security_audit：进行全面的安全评估 - compliance_check：检查是否符合安全标准（CIS、PCI DSS、HIPAA） - vulnerability_scan：扫描已知漏洞 - access_control_audit：审核访问控制和权限

• 运输选项：支持 stdio （用于本地脚本）， http，以及 sse 运输方式。
• 进度报告：与FastMCP集成 Context 用于在操作过程中更新进度。
• 日志记录：全面记录文件或控制台输出。
• 错误处理：使用一致的错误响应 ResponseBuilder 对于所有工具。

增强代理框架的功能

隧道管理器现在包括专门为人工智能驱动的工作流程设计的高级功能：

运营管理

• 通过流式进度更新跟踪长时间运行的操作
• 监控操作过程中的CPU、内存和磁盘使用情况
• 维护持久SSH连接池以提高效率
• 优雅地取消正在进行的操作
• 工具：开始操作、获取操作进度、取消操作、获取资源信息、列表活动会话

系统智能与发现

• 收集全面的系统信息（操作系统、硬件、软件包、正常运行时间）
• 发现正在运行的服务、进程和开放端口
• 分析日志文件中的模式和安全事件
• 映射网络拓扑（接口、路由、DNS、连接）
• 工具：get_system_info、发现服务、分析日志、网络拓扑

高级文件操作

• 执行递归目录操作（复制、移动、删除、chmod、chown）
• 使用类似grep的功能在多个目录中搜索文件内容
• 监控文件/目录的实时更改
• 比较不同主机上的文件
• 使用压缩和版本控制创建自动备份
• 工具：递归file_operations、file_content_search、file_watch_monitor、file_diff_compare、smart_backup

安全与合规自动化

• 进行全面的安全评估，评分（0-100）
• 检查是否符合行业标准（CIS基准、PCI DSS、HIPAA）
• 扫描包和配置中的已知漏洞
• 审核访问控制、用户权限、sudo配置和SSH设置
• 工具：安全审计、合规检查、漏洞扫描、访问控制审计

测试基础设施

• 综合测试套件：212项测试，涵盖核心功能和增强功能（通过率98.6%）
• 测试覆盖率:

- tunnel_manager.py：74%的覆盖率 - agent_server.py：96%的覆盖率 - __init__.py：89%的覆盖率 - operation_manager.py：全测试覆盖率（37次测试） - system_intelligence.py：全面测试覆盖（27次测试） - advanced_file_manager.py：全面测试覆盖（32次测试） - security_auditor.py：全面测试覆盖（28次测试）

• 测试类别:

- 单元测试 HostManager 类 - 单元测试 Tunnel 类（SSH操作、文件传输、密钥管理） - MCP服务器助手功能的单元测试 - 代理服务器功能的单元测试 - SSH操作的集成测试 - 通过进度跟踪增强运营管理的测试 - 系统智能和发现测试 - 高级文件操作测试 - 安全和合规审计测试

• 测试框架：pytest和pytest-asyncio用于异步测试

用法

命令行界面

备注

其中一个命令(setup-all, run-command, copy-config, rotate-key, send-file, receive-file)必须指定为的第一个参数 tunnel_manager.py。每个命令都有必需的参数，必须用标志指定：

• setup-all：需要 --inventory.
• run-command：需要 --inventory 和 --remote-command.
• copy-config：需要 --inventory 和 --local-config-path.
• rotate-key：需要 --inventory.
• send-file：需要 --inventory, --local-path，以及 --remote-path.
• receive-file：需要 --inventory, --remote-path，以及 --local-path-prefix.

附加说明

• 确保 ansible_host 值在 inventory.yml 是可解析的IP或主机名。
• 更新 ansible_ssh_private_key_file 在运行后的库存中 rotate-key.
• 使用 --log-file 用于基于文件的日志记录，或省略控制台输出。
• 这 --parallel 选项加快了操作速度，但可能会使资源过载；调整 --max-threads 根据需要。
• 这 receive-file 命令将文件保存到 local_path_prefix// 以保留原始文件名并避免冲突。
• 建议使用Ed25519密钥，以获得比RSA更好的安全性和性能，但支持RSA是为了与旧系统兼容。

1.设置无密码SSH

为清单中的主机设置无密码SSH，分发共享密钥。使用 --key-type 指定RSA或Ed25519（默认值：Ed25519）。

• 目标 all 组（顺序，Ed25519）:

  tunnel-manager setup-all --inventory inventory.yml --shared-key-path ~/.ssh/id_shared --key-type ed25519

• 目标 homelab 组（并行，3线程，RSA）:

  tunnel-manager setup-all --inventory inventory.yml --shared-key-path ~/.ssh/id_shared_rsa --key-type rsa --group homelab --parallel --max-threads 3

• 目标 poweredge 组（顺序，Ed25519）:

  tunnel-manager --log-file setup_poweredge.log setup-all --inventory inventory.yml --shared-key-path ~/.ssh/id_shared --key-type ed25519 --group poweredge

2.运行命令

在指定组中的所有主机上执行shell命令。

• 跑 uptime 上 all 组（顺序）:

  tunnel-manager run-command --inventory inventory.yml --remote-command "uptime"

• 跑 df -h 上 homelab 组（平行，5线程）:

  tunnel-manager run-command --inventory inventory.yml --remote-command "df -h" --group homelab --parallel --max-threads 5

• 跑 whoami 上 poweredge 组（顺序）:

  tunnel-manager run-command --inventory inventory.yml --remote-command "whoami" --group poweredge

3.复制SSH配置

将本地SSH配置文件复制到远程主机 ~/.ssh/config.

• 复制到 all 组（顺序）:

  tunnel-manager copy-config --inventory inventory.yml --local-config-path ~/.ssh/config

• 复制到 homelab 组（平行，4线程）:

  tunnel-manager copy-config --inventory inventory.yml --local-config-path ~/.ssh/config --group homelab --parallel --max-threads 4

• 复制到 poweredge 具有自定义远程路径的组:

  tunnel-manager --log-file copy_config.log copy-config --inventory inventory.yml --local-config-path ~/.ssh/config --remote-config-path ~/.ssh/custom_config --group poweredge

4.旋转SSH密钥

旋转主机的SSH密钥，生成带有前缀的新密钥。使用 --key-type 指定RSA或Ed25519（默认值：Ed25519）。

• 旋转按键 all 组（顺序，Ed25519）:

  tunnel-manager rotate-key --inventory inventory.yml --key-prefix ~/.ssh/id_ --key-type ed25519

• 旋转按键 homelab 组（并行，3线程，RSA）:

  tunnel-manager rotate-key --inventory inventory.yml --key-prefix ~/.ssh/id_rsa_ --key-type rsa --group homelab --parallel --max-threads 3

• 旋转按键 poweredge 组（顺序，Ed25519）:

  tunnel-manager --log-file rotate.log rotate-key --inventory inventory.yml --key-prefix ~/.ssh/id_ --key-type ed25519 --group poweredge

5.上传文件

将本地文件上载到指定组中的所有主机。

• 上传到 all 组（顺序）:

  tunnel-manager send-file --inventory inventory.yml --local-path ./myfile.txt --remote-path /home/user/myfile.txt

• 上传到 homelab 组（平行，3线程）:

  tunnel-manager send-file --inventory inventory.yml --local-path ./myfile.txt --remote-path /home/user/myfile.txt --group homelab --parallel --max-threads 3

• 上传到 poweredge 组（顺序）:

  tunnel-manager --log-file upload_poweredge.log send-file --inventory inventory.yml --local-path ./myfile.txt --remote-path /home/user/myfile.txt --group poweredge

6.下载文件

从指定组中的所有主机下载文件。， downloads/R510/myfile.txt).

• 下载自 all 组（顺序）:

  tunnel-manager receive-file --inventory inventory.yml --remote-path /home/user/myfile.txt --local-path-prefix ./downloads

• 下载自 homelab 组（平行，3线程）:

  tunnel-manager receive-file --inventory inventory.yml --remote-path /home/user/myfile.txt --local-path-prefix ./downloads --group homelab --parallel --max-threads 3

• 下载自 poweredge 组（顺序）:

  tunnel-manager --log-file download_poweredge.log receive-file --inventory inventory.yml --remote-path /home/user/myfile.txt --local-path-prefix ./downloads --group poweredge

隧道经理库存

库存文件示例(inventory.yml):

all:
  hosts:
    r510:
      ansible_host: 192.168.1.10
      ansible_user: admin
      ansible_ssh_private_key_file: "~/.ssh/id_ed25519"
    r710:
      ansible_host: 192.168.1.11
      ansible_user: admin
      ansible_ssh_pass: mypassword
    gr1080:
      ansible_host: 192.168.1.14
      ansible_user: admin
      ansible_ssh_private_key_file: "~/.ssh/id_rsa"
homelab:
  hosts:
    r510:
      ansible_host: 192.168.1.10
      ansible_user: admin
      ansible_ssh_private_key_file: "~/.ssh/id_ed25519"
    r710:
      ansible_host: 192.168.1.11
      ansible_user: admin
      ansible_ssh_pass: mypassword
    gr1080:
      ansible_host: 192.168.1.14
      ansible_user: admin
      ansible_ssh_private_key_file: "~/.ssh/id_rsa"
poweredge:
  hosts:
    r510:
      ansible_host: 192.168.1.10
      ansible_user: admin
      ansible_ssh_private_key_file: "~/.ssh/id_ed25519"
    r710:
      ansible_host: 192.168.1.11
      ansible_user: admin
      ansible_ssh_pass: mypassword

用实际值替换IP、用户名和密码。

MCP-CLI

用作MCP服务器

MCP服务器可以在两种模式下运行： stdio （用于本地测试）或 http （用于网络访问）。要启动服务器，请使用以下命令：

A2A-CLI

端点

• Web 用户界面: http://localhost:8000/ （如果启用）
• A2A: http://localhost:8000/a2a （发现： /a2a/.well-known/agent.json)
• AG-UI: http://localhost:8000/ag-ui （职位）

在stdio模式下运行（默认）：

tunnel-manager-mcp --transport "stdio"

在HTTP模式下运行：

tunnel-manager-mcp --transport "http"  --host "0.0.0.0"  --port "8000"

隧道等级

这 Tunnel 类可以独立用于SSH操作。示例：

使用RSA密钥

from tunnel_manager.tunnel_manager import Tunnel

# Initialize with a remote host (assumes ~/.ssh/config or explicit params)
tunnel = Tunnel(
    remote_host="192.168.1.10",
    username="admin",
    password="mypassword",
    identity_file="/path/to/id_rsa",
    certificate_file="/path/to/cert",  # Optional for Teleport
    proxy_command="tsh proxy ssh %h",  # Optional for Teleport
    ssh_config_file="~/.ssh/config",
)

# Connect and run a command
tunnel.connect()
out, err = tunnel.run_command("ls -la /tmp")
print(f"Output: {out}\nError: {err}")

# Upload a file
tunnel.send_file("/local/file.txt", "/remote/file.txt")

# Download a file
tunnel.receive_file("/remote/file.txt", "/local/downloaded.txt")

# Setup passwordless SSH with RSA
tunnel.setup_passwordless_ssh(local_key_path="~/.ssh/id_rsa", key_type="rsa")

# Copy SSH config
tunnel.copy_ssh_config("/local/ssh_config", "~/.ssh/config")

# Rotate SSH key with RSA
tunnel.rotate_ssh_key("/path/to/new_rsa_key", key_type="rsa")

# Close the connection
tunnel.close()

使用Ed25519密钥

from tunnel_manager.tunnel_manager import Tunnel

# Initialize with a remote host (assumes ~/.ssh/config or explicit params)
tunnel = Tunnel(
    remote_host="192.168.1.10",
    username="admin",
    password="mypassword",
    identity_file="/path/to/id_ed25519",
    certificate_file="/path/to/cert",  # Optional for Teleport
    proxy_command="tsh proxy ssh %h",  # Optional for Teleport
    ssh_config_file="~/.ssh/config",
)

# Connect and run a command
tunnel.connect()
out, err = tunnel.run_command("ls -la /tmp")
print(f"Output: {out}\nError: {err}")

# Upload a file
tunnel.send_file("/local/file.txt", "/remote/file.txt")

# Download a file
tunnel.receive_file("/remote/file.txt", "/local/downloaded.txt")

# Setup passwordless SSH with Ed25519
tunnel.setup_passwordless_ssh(local_key_path="~/.ssh/id_ed25519", key_type="ed25519")

# Copy SSH config
tunnel.copy_ssh_config("/local/ssh_config", "~/.ssh/config")

# Rotate SSH key with Ed25519
tunnel.rotate_ssh_key("/path/to/new_ed25519_key", key_type="ed25519")

# Close the connection
tunnel.close()

将MCP服务器部署为服务

MCP服务器可以使用Docker部署，具有可配置的身份验证、中间件和Eunomia授权。

使用Docker运行

docker pull knucklessg1/tunnel-manager:latest

docker run -d \
  --name tunnel-manager-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=http \
  -e AUTH_TYPE=none \
  -e EUNOMIA_TYPE=none \
  knucklessg1/tunnel-manager:latest

对于高级身份验证（例如JWT、OAuth代理、OIDC代理、远程OAuth）或Eunomia，添加相关的环境变量：

docker run -d \
  --name tunnel-manager-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=http \
  -e AUTH_TYPE=oidc-proxy \
  -e OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration \
  -e OIDC_CLIENT_ID=your-client-id \
  -e OIDC_CLIENT_SECRET=your-client-secret \
  -e OIDC_BASE_URL=https://your-server.com \
  -e ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/* \
  -e EUNOMIA_TYPE=embedded \
  -e EUNOMIA_POLICY_FILE=/app/mcp_policies.json \
  knucklessg1/tunnel-manager:latest

使用Docker Compose

创建一个 docker-compose.yml 文件：

services:
  tunnel-manager-mcp:
    image: knucklessg1/tunnel-manager:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8004
      - TRANSPORT=http
      - AUTH_TYPE=none
      - EUNOMIA_TYPE=none
    ports:
      - 8004:8004

对于具有身份验证和Eunomia的高级设置：

services:
  tunnel-manager-mcp:
    image: knucklessg1/tunnel-manager:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8004
      - TRANSPORT=http
      - AUTH_TYPE=oidc-proxy
      - OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration
      - OIDC_CLIENT_ID=your-client-id
      - OIDC_CLIENT_SECRET=your-client-secret
      - OIDC_BASE_URL=https://your-server.com
      - ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/*
      - EUNOMIA_TYPE=embedded
      - EUNOMIA_POLICY_FILE=/app/mcp_policies.json
    ports:
      - 8004:8004
    volumes:
      - ./mcp_policies.json:/app/mcp_policies.json

运行服务：

docker-compose up -d

配置 mcp.json AI集成

{
  "mcpServers": {
    "tunnel_manager": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "tunnel-manager",
        "tunnel_manager_mcp"
      ],
      "env": {
        "TUNNEL_REMOTE_HOST": "192.168.1.12",      // Optional
        "TUNNEL_USERNAME": "admin",                // Optional
        "TUNNEL_PASSWORD": "",                     // Optional
        "TUNNEL_REMOTE_PORT": "22",                // Optional
        "TUNNEL_IDENTITY_FILE": "",                // Optional
        "TUNNEL_INVENTORY": "~/inventory.yaml",    // Optional
        "TUNNEL_INVENTORY_GROUP": "all",           // Optional
        "TUNNEL_PARALLEL": "true",                 // Optional
        "TUNNEL_CERTIFICATE": "",                  // Optional
        "TUNNEL_PROXY_COMMAND": "",                // Optional
        "TUNNEL_LOG_FILE": "~/tunnel_log.txt",     // Optional
        "TUNNEL_MAX_THREADS": "6"                  // Optional
      },
      "timeout": 200000
    }
  }
}

安装Python包

python -m pip install tunnel-manager

或

uv pip install --upgrade tunnel-manager

存储库所有者

MCP配置示例

1.标准IO（stdio）部署

{
  "mcpServers": {
    "tunnel-manager": {
      "command": "uv",
      "args": [
        "run",
        "tunnel-manager-mcp"
      ],
      "env": {
        "ADVANCED_FILE_OPERATIONSTOOL": "True",
        "AGENT_DESCRIPTION": "",
        "AGENT_SYSTEM_PROMPT": "",
        "DEFAULT_AGENT_NAME": "",
        "HOST_MANAGEMENTTOOL": "True",
        "LLM_API_KEY": "",
        "LLM_BASE_URL": "",
        "MCP_URL": "",
        "MISCTOOL": "True",
        "MODEL_ID": "",
        "OPERATION_MANAGEMENTTOOL": "True",
        "REMOTE_ACCESSTOOL": "True",
        "SECURITY_AUDITINGTOOL": "True",
        "SYSTEM_INTELLIGENCETOOL": "True",
        "TUNNEL_CERTIFICATE": "",
        "TUNNEL_IDENTITY_FILE": "",
        "TUNNEL_INVENTORY": "",
        "TUNNEL_INVENTORY_GROUP": "",
        "TUNNEL_LOG_FILE": "",
        "TUNNEL_MAX_THREADS": "",
        "TUNNEL_PARALLEL": "",
        "TUNNEL_PASSWORD": "",
        "TUNNEL_PROXY_COMMAND": "",
        "TUNNEL_REMOTE_HOST": "",
        "TUNNEL_REMOTE_PORT": "",
        "TUNNEL_USERNAME": ""
      }
    }
  }
}

2.流式HTTP（SSE）部署

{
  "mcpServers": {
    "tunnel-manager": {
      "command": "uv",
      "args": [
        "run",
        "tunnel-manager-mcp",
        "--transport",
        "http",
        "--host",
        "0.0.0.0",
        "--port",
        "8000"
      ],
      "env": {
        "ADVANCED_FILE_OPERATIONSTOOL": "True",
        "AGENT_DESCRIPTION": "",
        "AGENT_SYSTEM_PROMPT": "",
        "DEFAULT_AGENT_NAME": "",
        "HOST_MANAGEMENTTOOL": "True",
        "LLM_API_KEY": "",
        "LLM_BASE_URL": "",
        "MCP_URL": "",
        "MISCTOOL": "True",
        "MODEL_ID": "",
        "OPERATION_MANAGEMENTTOOL": "True",
        "REMOTE_ACCESSTOOL": "True",
        "SECURITY_AUDITINGTOOL": "True",
        "SYSTEM_INTELLIGENCETOOL": "True",
        "TUNNEL_CERTIFICATE": "",
        "TUNNEL_IDENTITY_FILE": "",
        "TUNNEL_INVENTORY": "",
        "TUNNEL_INVENTORY_GROUP": "",
        "TUNNEL_LOG_FILE": "",
        "TUNNEL_MAX_THREADS": "",
        "TUNNEL_PARALLEL": "",
        "TUNNEL_PASSWORD": "",
        "TUNNEL_PROXY_COMMAND": "",
        "TUNNEL_REMOTE_HOST": "",
        "TUNNEL_REMOTE_PORT": "",
        "TUNNEL_USERNAME": ""
      }
    }
  }
}