🔐 SSH-MCP Secure

High-Security SSH MCP Server - Enterprise-grade SSH management with AI intelligence and military-grade security

🌟 Core Features

🔒 Enterprise-Grade Security

• AES-256-GCM Encryption - Military-grade encryption protecting all credentials

• Multi-Factor Authentication (MFA) - TOTP + backup codes support

• SSH Key Authentication - Supports ED25519 and RSA-4096

• Role-Based Access Control (RBAC) - Fine-grained permission management

• Circuit Breaker Protection - 8 resilient circuits protecting critical services

• Comprehensive Audit Logs - Full compliance reporting

🤖 AI Intelligence

• Context-Aware Assistance - Real-time command suggestions based on current context

• Tech Stack Detection - Automatic project stack identification and recommendations

• Pattern Recognition - ML-driven command history learning

• GitHub Intelligence - Community pattern mining and best practice discovery

• Predictive Operations - Trend analysis to predict issues

📊 Monitoring & Compliance

• Prometheus Metrics - Real-time performance monitoring

• Grafana Dashboard - Visualize system health

• Compliance Framework - SOC2, GDPR, NIST, HIPAA, PCI-DSS, ISO 27001

• Error Analysis - Intelligent error diagnosis

• Alert Management - Proactive alerts and auto-remediation

📋 Table of Contents

• Installation

• Quick Start

• Configuration

• Security Features

• API Reference

• Compliance

• Contributing

• License

🛠️ Installation

Prerequisites

• Node.js 18+ and npm/yarn

• Claude Code CLI (optional, for MCP integration)

• SSH access to target servers

• Git

Installation Steps

# Clone 倉庫
git clone https://github.com/your-org/ssh-mcp-secure.git
cd ssh-mcp-secure

# 安裝依賴
npm install

# 構建項目
npm run build

# 配置環境變量
cp .env.example .env
# 編輯 .env 文件填入實際配置

# 測試安裝
npm run security:audit

🚀 Quick Start

1. Configure Server Credentials

Create a .env file:

# 服務器配置
MY_SERVER_HOST=example.com
MY_SERVER_PORT=22
MY_SERVER_USERNAME=myuser
MY_SERVER_PRIVATE_KEY_PATH=/path/to/private_key
MY_SERVER_DEFAULT_DIR=/home/myuser
MY_SERVER_DESCRIPTION=Production Server

# 安全設置
SSH_ALLOW_PASSWORD_AUTH=false
SSH_REQUIRE_KEY_AUTH=true
SSH_MAX_AUTH_RETRIES=3
SSH_LOCKOUT_DURATION=300

# MFA 設置
MFA_ENABLED=true
MFA_REQUIRED_FOR_PRODUCTION=true

# 加密設置
ENCRYPTION_ALGORITHM=AES-256-GCM
ENCRYPTION_KEY_ROTATION_DAYS=90

# 審計日誌
AUDIT_ENABLED=true
AUDIT_LOG_PATH=/var/log/ssh-mcp/audit.log

2. Generate SSH Keys

# 生成 ED25519 密鑰 (推薦)
ssh-keygen -t ed25519 -a 100 -C "your_email@example.com"

# 或生成 RSA-4096 密鑰
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# 設置正確的權限
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

3. Configure MFA

On first connection, the system automatically generates MFA settings:

# 啟動服務器
npm start

# 掃描 QR 碼配置 TOTP
# 使用 Google Authenticator 或 Authy

4. Connect and Execute

// 安全連接
const session = await secureConnect({
  serverName: "my-server",
  requireMFA: true
});

// 執行命令
const result = await secureExecute({
  sessionId: session.sessionId,
  command: "ls -la"
});

console.log(result.stdout);

⚙️ Configuration

Environment Variables

Server Configuration

# 命名規範：SERVERNAME_PROPERTY
SERVERNAME_HOST=hostname.com
SERVERNAME_PORT=22
SERVERNAME_USERNAME=username
SERVERNAME_PASSWORD=password        # 可選 (不推薦)
SERVERNAME_PRIVATE_KEY_PATH=/path   # 推薦
SERVERNAME_PASSPHRASE=passphrase    # 可選 (加密密鑰)
SERVERNAME_DEFAULT_DIR=/home/user   # 可選
SERVERNAME_DESCRIPTION=Description   # 可選

Security Settings

# 認證安全
SSH_ALLOW_PASSWORD_AUTH=false      # 生產環境禁用密碼
SSH_REQUIRE_KEY_AUTH=true          # 要求密鑰認證
SSH_MAX_AUTH_RETRIES=3             # 最大認證嘗試
SSH_LOCKOUT_DURATION=300           # 鎖定時長 (秒)

# SSH 密鑰安全
SSH_KEY_TYPE=ed25519               # 推薦：ed25519
SSH_KEY_MIN_BITS=4096              # 最小 RSA 密鑰位數
SSH_KEY_PASSPHRASE_REQUIRED=true   # 要求密鑰短語

# 連接安全
SSH_MAX_RETRIES=3
SSH_RETRY_DELAY=2000
SSH_CONNECTION_TIMEOUT=20000
SSH_STRICT_HOST_KEY_CHECKING=true

MFA Settings

MFA_ENABLED=true
MFA_REQUIRED_FOR_PRODUCTION=true
MFA_TOTP_ISSUER=SSH-MCP-Secure
MFA_TOTP_DIGITS=6
MFA_TOTP_PERIOD=30
MFA_BACKUP_CODES_COUNT=10

Encryption Settings

ENCRYPTION_ALGORITHM=AES-256-GCM
ENCRYPTION_KEY_LENGTH=256
ENCRYPTION_KEY_ROTATION_DAYS=90
ENCRYPTION_MASTER_KEY=<your-64-char-hex-key>

Audit Logs

AUDIT_ENABLED=true
AUDIT_LOG_PATH=/var/log/ssh-mcp/audit.log
AUDIT_RETENTION_DAYS=90
AUDIT_LOG_FORMAT=json
AUDIT_AUTH_EVENTS=true
AUDIT_COMMAND_EXECUTION=true
AUDIT_FILE_OPERATIONS=true

🔒 Security Features

1. Encryption

• AES-256-GCM encrypts all credentials

• TLS 1.3 for external communication

• SSH Protocol 2 for all SSH connections

• Key Rotation automatically rotates every 90 days

2. Authentication

• Multi-Factor Authentication (MFA) - TOTP + backup codes

• SSH Key Authentication - ED25519/RSA-4096

• Password Authentication - Optional (recommended disabled in production)

• Session Timeout - Auto-expires after 1 hour

3. Access Control

• Role-Based Access Control (RBAC)

  • admin - Full access

  • operator - Operational permissions

  • developer - Development permissions

  • viewer - Read-only permissions

• Principle of Least Privilege - Deny all access by default

• Audit All Permission Checks - Full audit trail

4. Audit & Compliance

• Comprehensive Audit Logs

  • All authentication events

  • All command executions

  • All file operations

  • All session events

  • All permission changes

  • All credential access

• Compliance Framework Support

  • SOC2 Type II

  • GDPR

  • NIST Cybersecurity Framework

  • HIPAA (configurable)

  • PCI-DSS (configurable)

  • ISO 27001 (configurable)

5. Resilience Protection

• Circuit Breaker - Protects critical services

  • SSH connections

  • Redis cache

  • Authentication service

  • MFA verification

  • Encryption service

• Automatic Retry - Exponential backoff

• Health Checks - Connection pool health monitoring

📊 Monitoring

Prometheus Metrics

# SSH 連接
ssh_connections_active
ssh_commands_total
ssh_errors_total
ssh_command_duration_seconds

# 認證
auth_failures_total
mfa_verifications_total

# 緩存
cache_hits_total
cache_misses_total
cache_hit_rate

# 電路斷路器
circuit_breaker_trips_total
circuit_breaker_state

Grafana Dashboard

Access http://localhost:3000 to view the Grafana dashboard.

Alerts

Configure alert notifications:

ALERTING_ENABLED=true
ALERT_EMAIL=admin@example.com
ALERT_WEBHOOK_URL=https://hooks.slack.com/xxx
ALERT_THRESHOLD_CRITICAL=5
ALERT_THRESHOLD_WARNING=10

🔍 Security Best Practices

1. Environment Variables

# 永遠不要提交 .env 文件
echo ".env*" >> .gitignore

# 使用強密碼
export ENCRYPTION_MASTER_KEY=$(openssl rand -hex 32)

# 限制文件權限
chmod 600 .env

2. SSH Keys

# 生成安全密鑰
ssh-keygen -t ed25519 -a 100

# 設置正確權限
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

3. Credential Management

• Use credential rotation (90-day default)

• Enable MFA for production environments

• Regularly audit credential access

• Use separate credentials for each environment

4. Network Security

• Whitelist IP addresses whenever possible

• Use jump hosts for sensitive servers

• Enable SSH rate limiting

• Monitor for suspicious activity

📚 API Reference

Connection Management

// 安全連接到預定義服務器
secureConnect(params: {
  serverName: string
  requireMFA?: boolean
}): Promise<{
  sessionId: string
  sessionToken: string
  expiresAt: number
  mfaVerified: boolean
}>

// 列出配置的服務器
listPredefinedServers(): Promise<Record<string, ServerInfo>>

Command Execution

// 執行遠程命令
secureExecute(params: {
  sessionId: string
  command: string
  timeout?: number
}): Promise<{
  success: boolean
  stdout: string
  stderr: string
  exitCode: number
  audited: true
}>

File Operations

// 智能文件編輯
smartFileEdit(params: {
  sessionId: string
  filePath: string
  operations: EditOperation[]
  strategy?: EditStrategy
}): Promise<EditResult>

Compliance Reports

// 生成合規報告
generateComplianceReport(params: {
  framework: 'soc2' | 'gdpr' | 'nist'
  startDate: string
  endDate: string
}): Promise<ComplianceReport>

🤝 Contributing

We welcome contributions! Please check out our Contributing Guide.

Development Setup

# Clone 和安裝
git clone https://github.com/your-org/ssh-mcp-secure.git
cd ssh-mcp-secure
npm install

# 運行測試
npm test

# 構建
npm run build

# 監聽模式
npm run watch

# 代碼檢查
npm run lint

# 安全審計
npm run security:audit

📄 License

MIT License - See the LICENSE file

📞 Contact

• Security issues: security@example.com

• General support: support@example.com

• Documentation: https://github.com/your-org/ssh-mcp-secure/wiki

Remember: Security is everyone's responsibility. When in doubt, ask!

🔐 Security Checklist

Before deployment:

• Configure a complete .gitignore

• Set up a credential rotation schedule

• Enable MFA for production access

• Configure compliance monitoring

• Regularly review audit logs

• Set ENCRYPTION_MASTER_KEY

• Disable password authentication

• Configure firewall rules

• Set up monitoring and alerts

• Document emergency procedures