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