命令行工具安全系统文档

概述

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

目录安全系统

目录安全模式

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

白名单目录配置

"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"

会话管理

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

# 获取新的令牌
$ tool --generate-token

# 使用令牌执行命令
$ tool --token <your_token> --command "ls -a"

安全审计

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

日志格式示例：

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

配置示例

基本配置

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

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

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

错误处理

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

示例错误输出：

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

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

附录

环境变量参考

• 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