Htb Mcp Server

安全 Go

🚀 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 格式）。

安装步骤

克隆仓库：

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

构建二进制文件：

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

获取 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/                     # 文档

添加新工具

创建一个新的工具结构体，实现 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) {
// 实现代码
}

在 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 中断。

故障排除

常见问题

“HTB 令牌无效或已过期”
- 验证你的令牌是否正确且未过期。
- 确保令牌具有正确的 JWT 格式（由点分隔的三部分）。
- 检查 HTB 个人资料设置中的令牌权限。
“连接被拒绝”
- 验证与 labs.hackthebox.com 的网络连接。
- 检查企业防火墙是否阻止了 HTB API 访问。
“速率限制已超出”
- 降低请求频率。
- 如有需要，增加 RATE_LIMIT_PER_MINUTE。

调试模式

启用调试日志：

export LOG_LEVEL=DEBUG
./htb-mcp-server

健康检查

测试服务器连接：

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

🤝 贡献说明

分叉仓库。
创建功能分支。
进行更改。
为新功能添加测试。
提交拉取请求。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

HackTheBox 团队提供了 API。
模型上下文协议社区提供了规范。
Go 社区提供了优秀的工具和库。

🚧 路线图

第二阶段功能

实时机器状态通知。
高级分析和报告。
团队协作功能。
自定义挑战创建工具。

长期目标

支持移动应用程序。
与其他安全平台集成。
高级自动化功能。
基于机器学习的推荐。

🛠️ 支持

问题反馈：GitHub 问题
文档参考：Wiki

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

0 条评论
分类：安全