Htb MCP Server

🚀 HackTheBox MCP Server

HackTheBox MCP Serverは、AIアシスタントがHackTheBoxプラットフォームの機能にプログラムからアクセスできるようにするModel Context Protocol (MCP) サーバーです。このサーバーを使用することで、HackTheBox上の様々な機能を自動化して利用することができます。

✨ 主な機能

HTB MCP Serverは、HackTheBoxプラットフォームとやり取りするための12の包括的なツールを公開しています。

チャレンジ管理

• 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 Profile Settingsにアクセスします。
   • アプリトークンを生成します。
   • 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エンドポイント

サーバーはstdioトランスポートを介してMCPプロトコルを実装しています。すべての通信はJSON-RPC 2.0仕様に従っています。

コアMCPメソッド

• initialize - MCPセッションを初期化します。
• tools/list - 利用可能なツールをリストします。
• tools/call - 特定のツールを実行します。

HTB API統合

サーバーはHackTheBox API v4と統合されています。

• ベースURL: https://labs.hackthebox.com/api/v4
• 認証: ベアラートークン (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) {
       // Implementation
   }
   

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%のリクエストで500ms未満
• キャッシュ: インテリジェントなキャッシュによりAPI呼び出しが削減されます。
• 並行性: 複数の同時ツール実行をサポートします。
• サーキットブレーカー: HTB APIの障害から保護します。

トラブルシューティング

一般的な問題

1. "HTB token appears invalid or expired"

   • トークンが正しく、期限切れでないことを確認します。
   • トークンが適切なJWT形式 (ドットで区切られた3つの部分) であることを確認します。
   • HTBプロファイル設定でトークンの権限を確認します。

2. "Connection refused"

   • labs.hackthebox.comへのネットワーク接続を確認します。
   • 企業のファイアウォールがHTB APIアクセスをブロックしていないか確認します。

3. "Rate limit exceeded"

   • リクエスト頻度を減らします。
   • 必要に応じて 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を提供してくれたことに感謝します。
• Model Context Protocolコミュニティが仕様を提供してくれたことに感謝します。
• Goコミュニティが優れたツールとライブラリを提供してくれたことに感謝します。

🗺️ ロードマップ

フェーズ2の機能

• リアルタイムのマシンステータス通知
• 高度な分析とレポート
• チームコラボレーション機能
• カスタムチャレンジ作成ツール

長期的な目標

• モバイルアプリケーションのサポート
• 他のセキュリティプラットフォームとの統合
• 高度な自動化機能
• 機械学習による推奨機能

🆘 サポート

• 問題報告: GitHub Issues
• ドキュメント: Wiki

Built with ❤️ for the cybersecurity community