Htb MCP Server

🚀 HackTheBox MCP 服務器

HackTheBox MCP 服務器是一個基於模型上下文協議（MCP）的服務器，它為 AI 助手提供了對 HackTheBox 平臺功能的編程訪問能力，極大地提升了用戶與平臺交互的便捷性和效率。

✨ 主要特性

HTB MCP 服務器提供了 12 種全面的工具，用於與 HackTheBox 平臺進行交互：

挑戰管理

• list_challenges - 獲取帶有過濾功能的分頁挑戰列表。
• start_challenge - 初始化挑戰環境。
• submit_challenge_flag - 提交挑戰標誌以進行驗證。

機器管理

• list_machines - 獲取帶有狀態信息的活躍/退役機器列表。
• start_machine - 啟動機器並獲取連接詳情。
• get_machine_ip - 獲取活躍機器的 IP 地址。
• submit_user_flag - 提交機器的用戶標誌。
• submit_root_flag - 提交機器的根標誌。

用戶管理

• get_user_profile - 獲取用戶資料和統計信息。
• get_user_progress - 獲取完成狀態和成就信息。

搜索與實用工具

• search_content - 對挑戰、機器和用戶進行高級搜索。
• get_server_status - 進行健康檢查並獲取服務器信息。

📦 安裝指南

前提條件

• Go 1.21 或更高版本。
• 具有 API 訪問權限的有效 HackTheBox 賬戶。
• HTB API 令牌（JWT 格式）。

安裝步驟

1. 克隆倉庫：

git clone https://github.com/NoASLR/htb-mcp-server.git
cd htb-mcp-server

2. 構建二進制文件：

go build -o htb-mcp-server main.go

3. 獲取 HTB API 令牌：
   • 訪問 HackTheBox 個人資料設置。
   • 生成應用令牌。
   • 複製 JWT 令牌（格式：xxx.yyy.zzz）。

🔧 配置說明

服務器通過環境變量進行配置：

必需配置

• HTB_TOKEN - 你的 HackTheBox API 令牌（JWT 格式）。

可選配置

• SERVER_PORT - 服務器端口（默認：3000）。
• LOG_LEVEL - 日誌級別：DEBUG、INFO、WARN、ERROR（默認：INFO）。
• RATE_LIMIT_PER_MINUTE - API 速率限制（默認：100）。
• CACHE_TTL_SECONDS - 響應緩存的生存時間（默認：300）。
• REQUEST_TIMEOUT_SECONDS - HTTP 請求超時時間（默認：30）。

💻 使用示例

獨立模式

export HTB_TOKEN="your.jwt.token.here"
./htb-mcp-server

Docker 模式

docker build -t htb-mcp-server .
docker run -e HTB_TOKEN="your.jwt.token.here" htb-mcp-server

MCP 客戶端集成

將以下內容添加到你的 MCP 客戶端配置（例如，Claude Desktop）中：

{
  "mcpServers": {
    "htb": {
      "command": "/path/to/htb-mcp-server",
      "env": {
        "HTB_TOKEN": "your.jwt.token.here"
      }
    }
  }
}

示例用法

連接成功後，你可以通過 AI 助手使用這些工具：

# 列出活躍挑戰
"Can you show me the available Web challenges on HackTheBox?"

# 啟動一臺機器
"Please start machine ID 123 and get its IP address"

# 提交標誌
"Submit the user flag 'HTB{example_flag}' for machine 123"

# 搜索內容
"Search for machines related to 'Active Directory'"

# 檢查服務器狀態
"What's the current status of the HTB MCP server?"

📚 詳細文檔

API 端點

服務器通過標準輸入輸出傳輸實現了 MCP 協議。所有通信都遵循 JSON-RPC 2.0 規範。

核心 MCP 方法

• initialize - 初始化 MCP 會話。
• tools/list - 列出可用工具。
• tools/call - 執行特定工具。

HTB API 集成

服務器與 HackTheBox API v4 集成：

• 基礎 URL：https://labs.hackthebox.com/api/v4。
• 認證方式：Bearer 令牌（JWT）。
• 速率限制：遵循 HTB API 限制。

開發說明

項目結構

htb-mcp-server/
├── main.go                    # 入口點
├── pkg/
│   ├── config/               # 配置管理
│   ├── htb/                  # HTB API 客戶端
│   └── mcp/                  # MCP 協議實現
├── internal/
│   ├── server/               # MCP 服務器核心
│   └── tools/                # 工具實現
├── tests/                    # 測試文件
└── docs/                     # 文檔

添加新工具

1. 創建一個新的工具結構體，實現 Tool 接口：

type MyTool struct {
    client *htb.Client
}

func (t *MyTool) Name() string { return "my_tool" }
func (t *MyTool) Description() string { return "Description" }
func (t *MyTool) Schema() mcp.ToolSchema { /* schema */ }
func (t *MyTool) Execute(ctx context.Context, args map[string]interface{}) (*mcp.CallToolResponse, error) {
    // 實現代碼
}

2. 在 registry.go 中註冊工具：

r.RegisterTool(NewMyTool(r.htbClient))

測試

# 運行單元測試
go test ./...

# 運行帶覆蓋率的測試
go test -cover ./...

# 運行集成測試（需要 HTB_TOKEN）
HTB_TOKEN="your.token" go test -tags=integration ./...

🔧 技術細節

安全考慮

• 令牌安全：切勿將你的 HTB 令牌提交到版本控制中。
• 速率限制：服務器實現了速率限制，以防止 API 濫用。
• 輸入驗證：所有用戶輸入在進行 API 調用之前都會進行驗證。
• 錯誤處理：錯誤消息中不會暴露敏感信息。

性能表現

• 響應時間：95% 的請求響應時間小於 500 毫秒。
• 緩存機制：智能緩存減少了 API 調用次數。
• 併發處理：支持多個工具的併發執行。
• 熔斷機制：防止 HTB API 中斷。

故障排除

常見問題

1. “HTB 令牌無效或已過期”
   • 驗證你的令牌是否正確且未過期。
   • 確保令牌具有正確的 JWT 格式（由點分隔的三部分）。
   • 檢查 HTB 個人資料設置中的令牌權限。
2. “連接被拒絕”
   • 驗證與 labs.hackthebox.com 的網絡連接。
   • 檢查企業防火牆是否阻止了 HTB API 訪問。
3. “速率限制已超出”
   • 降低請求頻率。
   • 如有需要，增加 RATE_LIMIT_PER_MINUTE。

調試模式

啟用調試日誌：

export LOG_LEVEL=DEBUG
./htb-mcp-server

健康檢查

測試服務器連接：

curl -X POST http://localhost:3000/health

🤝 貢獻說明

1. 分叉倉庫。
2. 創建功能分支。
3. 進行更改。
4. 為新功能添加測試。
5. 提交拉取請求。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

• HackTheBox 團隊提供了 API。
• 模型上下文協議社區提供了規範。
• Go 社區提供了優秀的工具和庫。

🚧 路線圖

第二階段功能

• 即時機器狀態通知。
• 高級分析和報告。
• 團隊協作功能。
• 自定義挑戰創建工具。

長期目標

• 支持移動應用程序。
• 與其他安全平臺集成。
• 高級自動化功能。
• 基於機器學習的推薦。

🛠️ 支持

• 問題反饋：GitHub 問題
• 文檔參考：Wiki

為網絡安全社區精心打造 ❤️