🚀 命令行工具安全系统文档
本系统提供了强大的命令行工具安全机制，通过严格的目录访问控制与命令分类管理，保障系统安全。它支持三种目录访问模式，还允许用户自定义命令分类和权限。
🚀 快速开始
本系统提供了强大的命令行工具安全机制，通过严格的目录访问控制与命令分类管理，保障系统安全。它支持三种目录访问模式，还允许用户自定义命令分类和权限。
✨ 主要特性
- 提供三种不同的目录访问模式，满足不同场景下的安全需求。
- 支持用户自定义命令的分类和权限，灵活控制访问。
- 基于令牌的访问控制，保障会话安全。
- 详细的日志记录和审计功能，便于安全审查。
- 完善的错误报告机制，记录执行失败命令的详细信息。
📦 安装指南
文档未提及安装步骤，故跳过此章节。
💻 使用示例
基础用法
获取新的令牌
# 获取新的令牌
$ tool --generate-token
使用令牌执行命令
# 使用令牌执行命令
$ tool --token --command "ls -a"
高级用法
启动服务时启用审计功能
# 启动服务时启用审计功能
$ tool --audit enable
设置白名单目录
# 设置白名单目录
$ tool --config directory.add "/home/user/documents"
添加自定义命令到读取类别
# 添加自定义命令到读取类别
$ tool --config command.read "awk, jq"
📚 详细文档
目录安全系统
目录安全模式
系统支持以下三种目录安全模式：
| 模式 | 描述 | 最适合 | 配置 |
|---|---|---|---|
| 严格模式 | 仅允许全局白名单中的目录访问 | 最大化安全性 | auto_approve_directories_in_desktop_mode: false |
| 审批模式 | 非白名单目录需要显式审批 | 交互式使用 | 默认行为适用于标准客户端 |
| 自动审批模式 | 自动批准目录访问（针对Claude Desktop） | 使用便利性 | auto_approve_directories_in_desktop_mode: true |
白名单目录配置
"security": {
"whitelisted_directories": [
"/home", // 系统目录
"/tmp",
"~", // 用户主目录
"~/Documents" // 常用用户目录
],
"auto_approve_directories_in_desktop_mode": false // 设置为true以启用便利性功能
}
目录审批流程
- 命令请求在一个特定目录下执行
- 系统检查：
- 该目录是否在全局白名单中？ → 允许
- 该目录是否在当前会话的已批准列表中？ → 允许
- 两者都不是？ → 请求审批
- 审批通过后，该目录在整个会话期间内保持批准状态
支持的路径格式
- 绝对路径：
/home/user/documents - 主目录：
~（扩展为用户的主目录） - 用户子目录：
~/Downloads
命令定制系统
本系统使用命令分类来控制访问权限：
| 类别 | 描述 | 示例命令 | 是否需要审批 |
|---|---|---|---|
| 读取 | 安全操作 | ls, cat, find | 否 |
| 写入 | 数据修改 | mkdir, touch, rm | 是 |
| 系统 | 系统操作 | ping, ifconfig, kubectl | 是 |
| 阻止 | 危险命令 | sudo, bash, eval | 总是拒绝 |
定制方法
// 在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"
]
}
错误处理
系统提供详细的错误报告机制，所有执行失败的命令都会记录详细的错误信息。
示例错误输出：
$ 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
🔧 技术细节
本系统通过严格的目录访问控制和命令分类管理来保障系统的安全性。在目录安全系统方面，支持三种不同的目录访问模式，通过白名单目录配置和目录审批流程来控制目录访问权限。在命令定制系统方面，使用命令分类来控制访问权限，用户可以自定义命令的分类和权限。同时，系统还支持基于令牌的会话管理，以及详细的日志记录和审计功能，便于安全审查和错误处理。
📄 许可证
文档未提及许可证信息，故跳过此章节。