Cmd Line MCP

🚀 Command Line Tool Security System Documentation

This system provides a robust security mechanism for command-line tools. It aims to safeguard system security through strict directory access control and command classification management. The system supports three different directory access modes and allows users to customize command classification and permissions.

🚀 Quick Start

Directory Security System

The system offers three directory security modes to ensure different levels of security and user convenience.

✨ Features

Directory Security Modes

The system supports the following three directory security modes:

Whitelisted Directory Configuration

"security": {
  "whitelisted_directories": [
    "/home",                  // System directory
    "/tmp",
    "~",                      // User home directory
    "~/Documents"             // Common user directory
  ],
  "auto_approve_directories_in_desktop_mode": false  // Set to true to enable convenience feature
}

Directory Approval Process

1. A command requests to execute in a specific directory.
2. The system checks:
   • Is the directory in the global whitelist? → Allow
   • Is the directory in the approved list of the current session? → Allow
   • Neither? → Request approval
3. Once approved, the directory remains approved for the entire session.

Supported Path Formats

• Absolute path: /home/user/documents
• Home directory: ~ (expanded to the user's home directory)
• User subdirectory: ~/Downloads

Command Customization System

The system uses command classification to control access permissions:

Customization Methods

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

Environment Variable Method:

# Add to the existing list instead of overwriting (comma-separated)
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"

Session Management

The system supports token-based access control. Users can authenticate with tokens to execute commands. Each session has an independent token, which expires automatically after a timeout.

# Get a new token
$ tool --generate-token

# Execute a command with a token
$ tool --token <your_token> --command "ls -a"

Security Audit

The system provides detailed logging and auditing functions. All executed commands and their results are recorded for subsequent security reviews.

Log Format Example

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

Configuration Examples

Basic Configuration

# Enable audit function when starting the service
$ tool --audit enable

# Set whitelisted directories
$ tool --config directory.add "/home/user/documents"

# Add custom commands to the read category
$ tool --config command.read "awk, jq"

Error Handling

The system provides a detailed error reporting mechanism. All failed commands record detailed error information.

Example Error Output

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

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

Appendix

Environment Variable Reference

• CMD_LINE_TOOL_API_KEY: API key for authentication
• CMD_LINE_TOOL_LOG_LEVEL: Set the logging level (debug/info/warning/error/critical)
• CMD_LINE_TOOL_SESSION_TIMEOUT: Set the session timeout (in seconds)

Error Code Reference

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