qualys-mcp

Qualys MCP

あらゆる MCP 対応クライアント（Claude、その他の MCP ホスト）で VMDR、Policy Compliance、WAS、Cloud Agent、Container Security、TotalCloud、Patch Management、CSAM/GAV、EASM および管理機能を利用できる、Qualys ポータル全体を管理する Model Context Protocol サーバーです。

Qualys コンソールごとに 1 つのプロセスを実行します（契約数に応じて複数実行できます）。FastMCP を基盤とし、Qualys の 3 種類すべての API に対応する単一クライアントを備えています。厳格な読み取り／書き込み／破壊的操作の安全モデルを採用し、認証情報がチャットや平文に触れることはありません。

---

特長

• 幅広い機能範囲 — 自動検出される 59 の機能モジュールが、ポータル全体をカバーします。VMDR、PC、WAS、Cloud Agent、Container Security、TotalCloud/CloudView、Patch Management、CSAM/GAV、EASM、FIM、EDR、PCRS、および管理機能が含まれます。
• 約 400 のツール — list_hosts、list_host_detections、launch_scan、search_was_findings、list_knowledgebase、get_cs_image_vulnerabilities など、数百のツールを提供します。それぞれが、文書化された Qualys API 操作に 1 対 1 で対応しています。
• 3 種類の API に 1 つのクライアントで対応 — 従来の「FO」XML API、QPS REST API、JWT 認証の Gateway を、すべて self._fo／self._qps／self._gateway の背後で処理します。
• 安全性の段階分けを厳格に適用 — すべてのツールに読み取り専用、書き込み、破壊的操作のいずれかが指定されています。破壊的操作（削除／パージ／無効化）を行うツールは、コンソールごとに有効化しない限り登録すらされません。さらに、呼び出しごとに確認トークンが必要です。
• 遅延認証 — インポート時にも構築時にもネットワーク呼び出しを行いません。--check は認証情報なしで完全にオフラインで実行できます。
• シークレットを安全に保持 — Windows では認証情報を DPAPI 暗号化されたデータとしてのみ保存します。どの OS でも、環境変数を使って認証情報を設定できます。リポジトリに書き込まれることはありません。

3 種類の API

種別	ベースパス	認証	ペイロード
従来型「FO」	/api/2.0/fo/、/msp/	Basic ＋ X-Requested-With ヘッダー	フォーム → XML
QPS REST	/qps/rest/	Basic	XML <ServiceRequest>／JSON
Gateway	gateway.<pod>.apps.qualys.com	Bearer JWT（/auth から取得）	JSON

アーキテクチャ

qualys_mcp/
  server.py     FastMCP server; lazy auth; --check offline validation
  registry.py   auto-discovers modules/*.py
  client.py     one client, three API regimes (FO / QPS / Gateway-JWT)
  config.py     per-console config + platform (POD) -> URL map
  common/       auth (HTTP mw), errors, logging, rate_limit, utils, xml
  modules/      base.py + one file per feature module (the bulk of the surface)

機能を追加するには、qualys_mcp/modules/ にファイルを追加するだけです。docs/MODULE_BUILD_GUIDE.md を参照してください。

クイックスタート

1. インストール

python -m venv .venv
# Windows:      .\.venv\Scripts\pip install -e .
# macOS/Linux:  ./.venv/bin/pip install -e .

2. オフラインの動作確認（認証情報は不要）

python -m qualys_mcp --check

検出されたすべてのモジュールについて、ツール数を一覧表示して終了します。最初のスモークテストに適しています。

3. 認証情報を設定

Qualys の API ユーザーと、プラットフォーム／POD コード（例：US1、US2、EU1）が必要です。コンソールの URL、または Help → About で確認できます。

すべての OS — 環境変数：

export QUALYS_USERNAME='api-user'
export QUALYS_PASSWORD='api-pass'
export QUALYS_PLATFORM='US2'          # or set QUALYS_API_URL / QUALYS_GATEWAY_URL
python -m qualys_mcp --transport streamable-http --host 127.0.0.1 --port 8781 --console-label consulting

Windows — DPAPI 暗号化データ（継続的な運用におすすめ）：

# Encrypt once per console; the blob is user-scoped and stored under .secrets/
.\encrypt-qualys-creds.ps1 -Console consulting -Platform US2
.\encrypt-qualys-creds.ps1 -Console cloud      -Platform US2

# Launch one instance per console (:8781, :8782)
.\start-qualys-mcp.ps1
#   ...opt into destructive tools for a console only when you mean it:
.\start-qualys-mcp.ps1 -EnableDestructive cloud

# Optional: keep both alive across reboots via a Scheduled Task watchdog
.\register-qualys-mcp-task.ps1

すべての QUALYS_* 設定については .env.example を参照してください。

4. MCP クライアントを接続

Claude Code 用の、すぐに使える .mcp.json が含まれています。

{
  "mcpServers": {
    "qualys-consulting": { "type": "http", "url": "http://localhost:8781/mcp" },
    "qualys-cloud":      { "type": "http", "url": "http://localhost:8782/mcp" }
  }
}

scripts/register_mcp_clients.py では、同じローカル HTTP サーバーを複数の MCP クライアントに一括登録する方法を紹介しています。

安全モデル

• ツールには、読み取り専用、書き込み、破壊的操作のいずれかが注記されています。
• 破壊的操作を行うツール（削除、消去、無効化、アンインストール）は、コンソールが QUALYS_ENABLE_DESTRUCTIVE=true で実行されない限り、登録されません。
• 有効にした場合でも、破壊的操作を行うツールが動作するには、一致する confirm=<id> 引数が必要です。したがって、単一のプロンプトから誤って破壊的な呼び出しが行われることはありません。

各ティアの詳細については、docs/SAFETY_AUDIT.md をご覧ください。

モジュールとツールの一覧

• qualys_mcp/modules/ から 59 個のモジュールが自動検出されます。
• デフォルトで 約 360 個のツールが登録され、QUALYS_ENABLE_DESTRUCTIVE=true の場合は 約 400 個になります（追加される約 40 個は、通常は非表示の、保護された破壊的操作ツールです）。
• 3 つの API 体系にまたがっており、2 つの体系を扱うモジュールもいくつかあります。

モジュールごとの完全な表（レジストリ名、API ファミリー、ツール数、簡単な説明）は docs/MODULE_INDEX.md に、エンドポイント → ツール → アクションの完全な内訳は docs/ENDPOINTS_TOOLS_ACTIONS.md にあります。

設定リファレンス

変数	用途
QUALYS_USERNAME / QUALYS_PASSWORD	API ユーザーの認証情報
QUALYS_PLATFORM	POD コード（US1…KSA1）。API URL とゲートウェイ URL が自動入力されます
QUALYS_API_URL / QUALYS_GATEWAY_URL	一覧にない POD 向けの明示的な上書き
QUALYS_CONSOLE_LABEL	ログとサーバー名に表示するコンソール名
QUALYS_ENABLE_DESTRUCTIVE	破壊的操作のティアを登録する場合は true
QUALYS_MCP_MODULES	コンソールの対象をライセンス済みモジュールに限定する、カンマ区切りの許可リスト
QUALYS_MCP_API_KEY	HTTP トランスポート用の任意の共有シークレット

開発

pip install -e ".[dev]"
python -m qualys_mcp --check   # offline validation
pytest                          # unit tests (no network)
ruff check .                    # lint

コントリビューションを歓迎します。CONTRIBUTING.md をご覧ください。

免責事項

これは独立したコミュニティプロジェクトです。Qualys, Inc. とは提携、推奨、サポートの関係にありません。「Qualys」および製品名は、それぞれの所有者の商標です。ご自身のサブスクリプションに対し、Qualys のライセンスおよび API 利用規約に従って使用してください。本ソフトウェアは「現状有姿」で提供されます（LICENSE を参照）。ご自身の環境に対して実行する内容については、特に破壊的操作のティアに関して、ユーザーご自身が責任を負います。

スター履歴

ライセンス

MIT © 2026 Rijul Sharma