Cmd Line MCP

🚀 命令行工具安全系统文档

本系统提供了强大的命令行工具安全机制，通过严格的目录访问控制和命令分类管理保障系统安全。它支持三种目录访问模式，还允许用户自定义命令分类和权限。

🚀 快速开始

基本配置示例

# 启动服务时启用审计功能
$ tool --audit enable

# 设置白名单目录
$ tool --config directory.add "/home/user/documents"

# 添加自定义命令到读取类别
$ tool --config command.read "awk, jq"

✨ 主要特性

• 提供三种目录安全模式，满足不同场景的安全需求。
• 支持目录白名单配置和审批流程，严格控制目录访问。
• 使用命令分类控制访问权限，对不同类型的命令进行差异化管理。
• 基于令牌的会话管理，保障命令执行的安全性。
• 详细的日志记录和审计功能，方便进行安全审查。
• 完善的错误处理机制，记录详细的错误信息。

📦 安装指南

文档未提及安装步骤，故跳过此章节。

💻 使用示例

基础用法

获取新的令牌

$ tool --generate-token

使用令牌执行命令

$ tool --token <your_token> --command "ls -a"

高级用法

示例错误输出

$ tool --token invalid_token --command "ls -a"

Command execution failed: Invalid token or session timeout
For more details, check the audit logs.

📚 详细文档

目录安全系统

目录安全模式

系统支持以下三种目录安全模式：

白名单目录配置

"security": {
  "whitelisted_directories": [
    "/home",                  // 系统目录
    "/tmp",
    "~",                      // 用户主目录
    "~/Documents"             // 常用用户目录
  ],
  "auto_approve_directories_in_desktop_mode": false  // 设置为true以启用便利性功能
}

目录审批流程

1. 命令请求在一个特定目录下执行
2. 系统检查：
   • 该目录是否在全局白名单中？ → 允许
   • 该目录是否在当前会话的已批准列表中？ → 允许
   • 两者都不是？ → 请求审批
3. 审批通过后，该目录在整个会话期间内保持批准状态

支持的路径格式

• 绝对路径： /home/user/documents
• 主目录： ~（扩展为用户的主目录）
• 用户子目录： ~/Downloads

命令定制系统

本系统使用命令分类来控制访问权限：

定制方法

// 在config.json中
{
  "commands": {
    "read": ["ls", "cat", "grep", "awk", "jq"],
    "write": ["mkdir", "touch", "rm"],
    "system": ["ping", "ifconfig", "kubectl"],
    "blocked": ["sudo", "bash", "eval"]
  }
}

环境变量方法：

# 在现有列表中添加，而不是覆盖（逗号分隔）
export CMD_LINE_TOOL_COMMANDS_READ="ls,cat,grep"
export CMD_LINE_TOOL_COMMANDS_WRITE="mkdir,touch,rm"
export CMD_LINE_TOOL_COMMANDS_SYSTEM="ping/ifconfig/kubectl"
export CMD_LINE_TOOL_COMMANDS_BLOCKED="sudo/bash/eval"

会话管理

系统支持基于令牌的访问控制，用户可以通过令牌认证来执行命令。每个会话都有独立的令牌，并且会在超时后自动失效。

安全审计

系统提供详细的日志记录和审计功能，所有执行的命令及其结果都会被记录下来，便于后续的安全审查。

日志格式示例：

{
  "timestamp": "2024-01-20T15:30:45.123Z",
  "user": "admin",
  "command": "ls -a",
  "directory": "/home/admin",
  "status": "success",
  "output": [
    "file1.txt",
    "file2.png",
    ".hidden"
  ]
}

错误处理

系统提供详细的错误报告机制，所有执行失败的命令都会记录详细的错误信息。

🔧 技术细节

附录

环境变量参考

• CMD_LINE_TOOL_API_KEY：用于身份验证的API密钥
• CMD_LINE_TOOL_LOG_LEVEL：设置日志记录级别（debug/info/warning/error/critical）
• CMD_LINE_TOOL_SESSION_TIMEOUT：设置会话超时时间（单位：秒）

错误代码参考

• 101: Invalid token or session timeout
• 102: Directory access denied
• 103: Command execution failed
• 104: Configuration error
• 105: Unauthorized command