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

为网络安全社区精心打造 ❤️