stackhawk

StackHawk MCP Server

現在のバージョン：1.2.5 Python 3.10 以降が必要です

StackHawk のセキュリティスキャンプラットフォームと連携するための Model Context Protocol（MCP）サーバーです。開発者が StackHawk をセットアップし、セキュリティスキャンを実行し、検出結果をトリアージして脆弱性を修正できるよう支援します。すべて LLM を活用した IDE またはチャット内で実行できます。

---

目次

• 機能
• インストール
• 使用方法
• 設定
• 利用可能なツール
• テストと開発
• 設定例
• LLM と IDE との連携
• コントリビューション
• ライセンス

---

機能

• セットアップ： プロジェクトを検出し、StackHawk アプリケーションを作成して、すぐにスキャンできる stackhawk.yml を生成します
• スキャン： IDE またはチャットから StackHawk のスキャンを直接実行します（CLI がない場合はインストールを支援します）
• トリアージ： 修正に向けて、失敗しきい値以上の対応可能な検出結果を取得します
• 検証： YAML 設定を公式スキーマと照合し、フィールドパスを検証してハルシネーションを防ぎます
• カスタム User-Agent： すべての API 呼び出しにバージョン付きの User-Agent ヘッダーを含めます

---

インストール

1. pip でインストールします（現在の Python 環境への書き込み権限があることを確認してください）：

   > pip install stackhawk-mcp
   # Requires Python 3.10 or higher
   

または、仮想環境で pip を使ってインストールします：

> python3 -m venv ~/.virtualenvs/mcp
> source ~/.virtualenvs/mcp/bin/activate
> (mcp) pip install stackhawk-mcp
# Requires Python 3.10 or higher

または、pyenv を使って pip でインストールします：

> pyenv shell 3.10.11
> pip install stackhawk-mcp
# Requires Python 3.10 or higher

または、このリポジトリからローカルにインストールします：

> pip install --user .
# Run this command from the root of the cloned repository

2. StackHawk API キーを設定します：

   > export STACKHAWK_API_KEY="your-api-key-here"
   

---

使用方法

MCP サーバーの実行

python -m stackhawk_mcp.server

HTTP サーバー（FastAPI）の実行

python -m stackhawk_mcp.http_server

テストの実行

pytest

LLM と IDE との連携

StackHawk MCP は、AI コーディングアシスタントや LLM を活用した開発環境のツールプロバイダーとして使用できます。ワークフロー内でセキュリティスキャンのセットアップ、YAML の検証、脆弱性のトリアージを直接実行できます。

Cursor（AI コーディングエディター）

• セットアップ：
  • 上記のインストール手順に従って、Python 環境に stackhawk-mcp をインストールします。
  • Cursor で Cursor Settings->Tools & Integrations->MCP Tools に移動します
  • 環境に応じて、以下の json を指定して「New MCP Server」を追加します：
    • ~/.virtualenvs/mcp の仮想環境を使用する場合：

      {
        "mcpServers": {
          "stackhawk": {
            "command": "/home/bobby/.virtualenvs/mcp/bin/python",
            "args": ["-m", "stackhawk_mcp.server"],
            "env": {
              "STACKHAWK_API_KEY": "${env:STACKHAWK_API_KEY}"
            },
            "disabled": false
          }
        }
      }
      

    • pyenv を使用する場合：

      {
        "mcpServers": {
          "stackhawk": {
            "command": "/home/bobby/.pyenv/versions/3.10.11/bin/python3",
            "args": ["-m", "stackhawk_mcp.server"],
            "env": {
              "STACKHAWK_API_KEY": "${env:STACKHAWK_API_KEY}"
            },
            "disabled": false
          }
        }
      }
      

    • または、python を直接使用します：

      {
        "mcpServers": {
          "stackhawk": {
            "command": "python3",
            "args": ["-m", "stackhawk_mcp.server"],
            "env": {
              "STACKHAWK_API_KEY": "${env:STACKHAWK_API_KEY}"
            }
          }
        }
      }
      

    • 次に、「stackhawk」MCP Tool が有効になっていることを確認します
• 使用方法：
  • Cursor のツール呼び出しを使って、StackHawk MCP ツール（例：脆弱性の検索、YAML の検証）を呼び出します。
  • プロンプトの例：Validate this StackHawk YAML config for errors.

OpenAI、Anthropic、その他の LLM

• セットアップ：
  • MCP HTTP サーバーをデプロイし、LLM システム（ローカルまたはクラウド）からアクセスできるようにします。
  • LLM のツール呼び出し API または関数呼び出し API を使用して、MCP エンドポイントに接続します。
  • ツールのスキーマで指定されている必須の引数（例：org_id、yaml_content）を渡します。
• API 呼び出しの例：

  {
    "method": "tools/call",
    "params": {
      "name": "validate_stackhawk_config",
      "arguments": {"yaml_content": "..."}
    }
  }
  

• ベストプラクティス：
  • ハルシネーション防止ツールを使用して、フィールド名とスキーマへの準拠を検証します。
  • ツールの出力を必ず確認し、警告や提案がないか確認します。

Windsurf などの IDE

• セットアップ：
  • IDE にツールプロバイダーまたは拡張機能として StackHawk MCP を追加し、ローカルまたはリモートの MCP サーバーエンドポイントを指定します。
  • 必要に応じて環境変数を設定します。
• 使用方法：
  • IDE のコマンドパレットまたはツール統合パネルから、セットアップ、スキャン、検証、トリアージのツールを直接呼び出します。

全般的なヒント

• MCP サーバーが実行中で、LLM または IDE 環境からアクセスできることを確認します。
• サポートされている操作については、使用可能なツールと API セクションを確認してください。
• 高度な統合については、この README のツール使用例を参照するか、コードベースを調べてカスタムワークフローを確認してください。

GitHub Copilot エージェント

StackHawk は、MCP サーバーとして、または独自の GitHub カスタムエージェントとして GitHub コーディングエージェントに追加できます。

GitHub コーディングエージェントへの追加

StackHawk MCP を GitHub Copilot コーディングエージェントに追加できます。これにより、エージェントはすべての stackhawk/ ツールを利用できるようになります。

コーディングエージェントへの StackHawk MCP のインストール

GitHub の一般的な手順

StackHawk MCP の場合、MCP Configuration JSON は次のようになります。

{
  "mcpServers": {
    "stackhawk": {
      "type": "local",
      "tools": [
        "*"
      ],
      "command": "uvx",
      "args": [
        "stackhawk-mcp"
      ],
      "env": {
        "STACKHAWK_API_KEY": "COPILOT_MCP_STACKHAWK_API_KEY"
      }
    }
  }
}

次に、リポジトリの Settings->Environments->copilot->Environment Secrets で、StackHawk API キーを使用して COPILOT_MCP_STACKHAWK_API_KEY を追加します。

インストールの確認手順

GitHub Copilot カスタムエージェントとしての StackHawk オンボーディングエージェント

StackHawk オンボーディングエージェントは、GitHub のエンタープライズ、組織、またはリポジトリのレベルでカスタムエージェントとして追加できます。追加すると、StackHawk オンボーディングエージェントが Copilot エージェントチャットで選択可能なオプションになり、オンボーディングを支援するコンテキストを提供します。また、stackhawk-mcp がインストールされ、エージェントはそのすべてのツールを利用できるようになります。

StackHawk オンボーディングエージェントのインストール

基本的な手順は、StackHawk オンボーディングエージェントの定義を取得し、GitHub 上の目的のリポジトリ、エンタープライズ、または組織に適用することです。

• GitHub のリポジトリにインストールする手順
• GitHub のエンタープライズにインストールする手順
• GitHub の組織にインストールする手順

StackHawk オンボーディングエージェントの定義にある mcp-servers ブロックでは、COPILOT_MCP_STACKHAWK_API_KEY という環境変数を参照していることに注意してください。リポジトリの Settings->Environments->copilot->Environment Secrets に移動し、StackHawk API キーを使用して COPILOT_MCP_STACKHAWK_API_KEY を追加します。

---

設定

• すべての HTTP リクエストには、カスタムの User-Agent ヘッダーが含まれます。

  User-Agent: StackHawk-MCP/{version}
  

• バージョンは stackhawk_mcp/server.py の STACKHAWK_MCP_VERSION で設定します。
• STACKHAWK_API_KEY 環境変数を使用して API キーを設定します。

---

利用可能なツール

MCP サーバーは、開発者のワークフローに沿って整理された7つのツールを公開します。

フェーズ	ツール	説明
検出	get_organization_info	組織の詳細、チーム、アプリケーションを取得します
検出	list_applications	組織内のアプリケーションを一覧表示します
セットアップ	setup_stackhawk_for_project	言語を検出し、アプリを検索または作成して、stackhawk.yml を生成します
検証	validate_stackhawk_config	YAML を StackHawk の公式スキーマに照らして検証します
検証	validate_field_exists	スキーマ内でフィールドパスが有効かどうかを確認します（ハルシネーション防止）
スキャン	run_stackhawk_scan	CLI で StackHawk スキャンを実行します（CLI が見つからない場合はインストール方法を返します）
トリアージ	get_app_findings_for_triage	設定された失敗しきい値以上の検出結果を取得します

ツールの使用例

# Set up StackHawk for a project
result = await server.call_tool("setup_stackhawk_for_project", {"host": "http://localhost:3000"})

# Validate a YAML config
result = await server.call_tool("validate_stackhawk_config", {"yaml_content": "..."})

# Run a scan
result = await server.call_tool("run_stackhawk_scan", {})

# Get findings to triage
result = await server.call_tool("get_app_findings_for_triage", {})

公式スキーマ URL： https://download.stackhawk.com/hawk/jsonschema/hawkconfig.json

---

テストと開発

すべてのテストを実行する

pytest

個別のテストを実行する

pytest tests/test_ux_improvements.py
pytest tests/test_user_scenarios.py

コードのフォーマット

black stackhawk_mcp/

型チェック

mypy stackhawk_mcp/

---

設定例

基本設定

app:
  applicationId: "12345678-1234-1234-1234-123456789012"
  env: "dev"
  host: "http://localhost:3000"
  name: "Development App"
  description: "Local development environment"

認証を使用する本番環境向け設定

app:
  applicationId: "87654321-4321-4321-4321-210987654321"
  env: "prod"
  host: "https://myapp.com"
  name: "Production App"
  description: "Production environment"
  authentication:
    type: "form"
    username: "your-username"
    password: "your-password"
    loginUrl: "https://myapp.com/login"
    usernameField: "username"
    passwordField: "password"

hawk:
  spider:
    base: true
    ajax: false
    maxDurationMinutes: 30
  scan:
    maxDurationMinutes: 60
    threads: 10
  startupTimeoutMinutes: 5
  failureThreshold: "high"

tags:
  - name: "environment"
    value: "production"
  - name: "application"
    value: "myapp"

---

コントリビューション

コントリビューションを歓迎します。バグ修正、新機能、ドキュメントの改善について、イシューまたはプルリクエストを作成してください。

---

ライセンス

Apache License 2.0。詳細は LICENSE を参照してください。

リリースとバージョンの更新

バージョンの更新は、「Prepare Release」GitHub Actions ワークフローで管理されます。 このワークフローを実行する際に、マイナーバージョンまたはメジャーバージョンのどちらを更新するか選択できます。 ワークフローはバージョンファイルを自動的に更新し、変更をコミットして main にプッシュします。

注： このワークフローでは、自動バージョン更新コミットによって無限ループが発生しないよう保護されています。

GitHub Actions の認証

すべての CI/CD の Git 操作では、認証に GitHub App トークンを使用します。 Git ユーザーとメールアドレスは、リポジトリシークレット HAWKY_APP_USER および HAWKY_APP_USER_EMAIL から設定されます。

ワークフローの保護

最新のコミットが自動バージョン更新である場合、ジョブをスキップするようワークフローが設計されており、ワークフローのループを防止します。

リリースを実行する方法

1. GitHub の「Actions」タブに移動します。
2. 「Prepare Release」ワークフローを選択します。
3. 「Run workflow」をクリックし、希望する更新種別（マイナーまたはメジャー）を選択します。
4. あとはワークフローが処理します！