ScanMalware.com URL Scanner

scanmalware-mcp

公開 ScanMalware.com API をラップする、最小構成の Python MCP サーバーです。

操作

デプロイ、TLS、ログ記録、セキュリティメンテナンス、および DigitalOcean droplet への接続方法については、運用手順書を参照してください。

ローカルで実行する（Streamable HTTP）

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install .

export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8000

scanmalware-mcp

Docker で実行する

docker build -t scanmalware-mcp .
docker run --rm -p 127.0.0.1:8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  scanmalware-mcp

任意：HTTP トランスポートで Authorization: Bearer <MCP_AUTH_TOKEN> を必須にするには、MCP_AUTH_TOKEN を設定します。

任意の認証環境変数（認証が必要なエンドポイントでのみ必要です）：

• SCANMALWARE_BEARER_TOKEN

その他の環境変数：

• SCANMALWARE_BASE_URL（デフォルト：https://scanmalware.com）
• SCANMALWARE_ALLOW_HTTP（デフォルト：false）
• SCANMALWARE_TIMEOUT_S（デフォルト：30）
• SCANMALWARE_SLOW_QUERY_TIMEOUT_S（デフォルト：90。ファビコンとテクノロジー統計、OCR テキスト検索、JS フィンガープリントの類似性カウント、振る舞いシグネチャ検索に適用）
• SCANMALWARE_MAX_DOWNLOAD_BYTES（デフォルト：10485760）
• SCANMALWARE_ALLOW_PRIVATE_TARGETS（デフォルト：false）
• SCANMALWARE_CA_CERT（任意。SSL バンプ用 CA バンドルのパス）

MCP サーバーのセキュリティ環境変数：

• MCP_AUTH_TOKEN（設定すると、HTTP トランスポートで Authorization: Bearer <token> が必須になります）
• MCP_RESOURCE_SERVER_URL / MCP_ISSUER_URL（任意。MCP_AUTH_TOKEN が設定されている場合にのみ使用されます）

トランスポートに関する注意：HTTP トランスポートはステートレスで実行されるため（stateless_http=True）、レスポンスに mcp-session-id ヘッダーは含まれません。クライアントはこのヘッダーを必須としてはなりません。これにより、セッションごとの状態、 つまりメモリ使用量を一定に保ちます。2 世代の MCP プロトコルに対応しています：initialize （2024-11-05 から 2025-11-25）および server/discover（2026-07-28）。リクエストには POST を使用します。 サーバーは単独の SSE ストリームを提供しないため、/mcp への GET は 405 を返します。

SSE トランスポート：MCP_TRANSPORT=sse を設定します。また、パスプレフィックス配下で提供する場合は MCP_SSE_MOUNT_PATH も任意で設定します。

ツールに関する注意：submit_scan は /api/v1/csrf-token を呼び出しません。CSRF トークン用のツールはありません。 ツールに関する注意：上流の一部のエンドポイントは無効化されており、ツール一覧から除外されています（例：get_improvements、find_screenshot_duplicates、get_ai_stats、search_js_fingerprinter2_code_hash、search_js_segments_by_tlsh）。 フィルター：すべての検索ツールはデフォルト値で呼び出せます。 search_js_fingerprint_patterns は、API がパターンフィルターを必須としているため、パターンフィルターが指定されていない場合は has_eval=true を適用します。search_js_obfuscation と search_js_malware_families は、API 独自のデフォルト値にフォールバックします。スコアフィルターには API のスケールが使われ、リクエスト前に検証されます：AI リスクスコアは 0～10、AI 信頼度は 0～100、JS 難読化スコアは 0～1、ランタイム JS リスク スコアは 0～100 です。OCR 検索には、前後の空白を除去した後で最低 3 文字が必要です。 ライブラリ検索では get_js_library_inventory から検出された識別子を使用します。 search_js_fingerprint_by_library では、検出された識別子 nextjs のエイリアスとして Next.js を使用できます。

スキャンの公開範囲

submit_scan では scan_type が必須で、デフォルト値はありません。public スキャンでは、対象 URL とスキャン結果が ScanMalware の公開フィードに掲載され、ほかのユーザーや検索エンジンから閲覧できるようになります。クライアントの対象、機密性の高い URL、セキュリティ関連の業務では、公開範囲を慎重に選択してください。

• public：スキャンを公開します。公開することについて明示的な承認を得た場合に限り、これらの対象に使用してください。
• unlisted：公開リストには掲載されませんが、直接リンクを知っている人なら誰でもアクセスできます。
• private：結果は認証済みの ScanMalware アカウントに制限されます。 MCP サーバーに有効な SCANMALWARE_BEARER_TOKEN を設定する必要があります。 MCP_AUTH_TOKEN は MCP サーバーへのアクセスのみを制御するもので、ScanMalware の認証には使用できません。

これらの対象について公開範囲が指定されていない場合は、送信前にユーザーに unlisted または private を選んでもらってください。送信に失敗した場合、制限の緩い公開範囲に変更して再試行しないでください。これらのモードはスキャンの公開範囲を制御します。リクエストは引き続き ScanMalware に送信され、サーバーログに記録される場合があります（MCP のプライバシーポリシーを参照）。ScanMalware は、公開範囲のオプションをプライバシーポリシーで説明しています。

プロンプトの例

フィッシングのトリアージ（送信 → 待機 → 要約）：

Submit an unlisted scan for https://example-login-update.com, wait for completion, and
return status, risk_score, and the top indicators. If high risk, include the
AI analysis and screenshot resource.

ブランドの不正利用の監視：

Search scans for "acme login" (limit 5). For each result, list scan_id,
status, risk_score, and URL. Highlight anything marked high risk.

TLS／証明書の検査：

For scan_id 1234...abcd, fetch TLS details and the certificate PEM download.
Summarize issuer, subject, validity dates, and SANs; flag mismatches.

DigitalOcean にデプロイする（Debian + Docker + Nginx）

デプロイ用バンドルは deploy/ にあり、次の 3 つのコンテナを実行します。

• mcp（このサーバー。ポート 8000 でストリーミング可能な HTTP を提供）
• nginx（ポート 80/443 のフロントエンド。HTTP を HTTPS にリダイレクトし、/mcp を MCP サーバーにプロキシします）
• proxy（mitmproxy。ScanMalware の宛先を確認し、上流の HTTP トラフィックをログに記録します）

前提条件

• doctl の認証が完了していること（doctl auth init）
• DigitalOcean に SSH キーをアップロード済みであること（doctl compute droplet create で使用します）
• Nginx の起動前に、HTTPS / TLS に記載されているパスに DNS と Let's Encrypt 証明書を用意すること

ドイツ（フランクフルト）に小規模な Droplet を作成する

DROPLET_NAME=scanmalware-mcp-small
REGION=fra1
SIZE=s-1vcpu-2gb
IMAGE=debian-12-x64
SSH_KEYS=$(doctl compute ssh-key list --format ID --no-header | paste -sd, -)

doctl compute droplet create "$DROPLET_NAME" \
  --region "$REGION" \
  --size "$SIZE" \
  --image "$IMAGE" \
  --ssh-keys "$SSH_KEYS" \
  --tag-name scanmalware-mcp \
  --wait

ファイアウォール（公開 HTTP/HTTPS + SSH）

doctl compute firewall create \
  --name scanmalware-mcp-fw \
  --inbound-rules "protocol:tcp,ports:22,address:0.0.0.0/0,address:::0/0" \
  --inbound-rules "protocol:tcp,ports:80,address:0.0.0.0/0,address:::0/0" \
  --inbound-rules "protocol:tcp,ports:443,address:0.0.0.0/0,address:::0/0" \
  --outbound-rules "protocol:icmp,ports:0,address:0.0.0.0/0,address:::0/0" \
  --outbound-rules "protocol:tcp,ports:0,address:0.0.0.0/0,address:::0/0" \
  --outbound-rules "protocol:udp,ports:0,address:0.0.0.0/0,address:::0/0" \
  --droplet-ids <droplet-id>

Droplet に Docker + Compose をインストールする

Docker 公式の apt リポジトリから Docker Engine と Compose プラグインをインストールしてください。docker compose を使用してください。旧式の Python 製 docker-compose クライアントは、現在の Docker Engine と互換性がありません。

ビルドのバージョン固定とメンテナンス時の確認項目については、運用手順書を参照してください。

アップロードして実行する

# Package exactly one commit; a tar of the working tree also picks up untracked
# files (.tools/, caches, egg-info) and uncommitted edits.
git archive --format=tar.gz -o /tmp/scanmalware-mcp.tar.gz origin/main
scp -i /path/to/key /tmp/scanmalware-mcp.tar.gz root@<droplet-ip>:/tmp/
ssh -i /path/to/key root@<droplet-ip> \
  "mkdir -p /opt/scanmalware-mcp && tar -xzf /tmp/scanmalware-mcp.tar.gz -C /opt/scanmalware-mcp"

新しいホストでは、MCP と Nginx を起動する前に、TLS 検査に従ってプロキシをビルドし、その CA を生成してください。ホストのセットアップの一環として、送信ルールと Docker 起動フックおよびログローテーションを設定してください。

確認する

curl -I https://mcp.scanmalware.com/
curl -sS -o /dev/null -w '%{http_code}\n' https://mcp.scanmalware.com/mcp

/ は Nginx から 200 を返すはずです。/mcp は GET に対して 405 を返しますが、これは想定どおりです。このサーバーは単独の SSE ストリームを提供しないため、MCP リクエストには POST を使用します。

スモークテスト（MCP の initialize + tools/list）

python - <<'PY'
import json
import httpx

URL = "https://mcp.scanmalware.com/mcp"
HEADERS = {
    "accept": "application/json, text/event-stream",
    "content-type": "application/json",
}

init_payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2025-06-18",
        "capabilities": {},
        "clientInfo": {"name": "mcp-smoke-test", "version": "0.1.0"},
    },
}

with httpx.Client(timeout=10) as client:
    init_resp = client.post(URL, headers=HEADERS, json=init_payload)
    init_resp.raise_for_status()
    # Stateless deployments return no session header.
    session_id = init_resp.headers.get("mcp-session-id")

    def extract_sse_data(text: str) -> dict:
        for line in text.splitlines():
            if line.startswith("data: "):
                return json.loads(line[len("data: "):])
        raise ValueError("No SSE data line found")

    init_message = extract_sse_data(init_resp.text)
    protocol_version = init_message["result"]["protocolVersion"]

    headers = {**HEADERS, "mcp-protocol-version": protocol_version}
    if session_id:
        headers["mcp-session-id"] = session_id

    # Send initialized notification
    client.post(
        URL,
        headers=headers,
        json={"jsonrpc": "2.0", "method": "notifications/initialized"},
    )

    tools_resp = client.post(
        URL,
        headers=headers,
        json={"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
    )
    tools_resp.raise_for_status()
    tools_message = extract_sse_data(tools_resp.text)
    tool_names = [tool["name"] for tool in tools_message["result"]["tools"]]

print("protocol_version:", protocol_version)
print("tool_count:", len(tool_names))
print("tools:", ", ".join(tool_names))
PY

再デプロイ／新規デプロイ

よくある手順は 2 つあります。

1. インプレース更新（同じ Droplet）

# Package exactly one commit; a tar of the working tree also picks up untracked
# files (.tools/, caches, egg-info) and uncommitted edits.
git archive --format=tar.gz -o /tmp/scanmalware-mcp.tar.gz origin/main
scp -i /path/to/key /tmp/scanmalware-mcp.tar.gz root@<droplet-ip>:/tmp/
ssh -i /path/to/key root@<droplet-ip> \
  "bash /opt/scanmalware-mcp/deploy/redeploy.sh /tmp/scanmalware-mcp.tar.gz"

再デプロイスクリプトは 3 つのコンテナをすべて停止してファイルを置き換え、すべてのイメージを再ビルドして再起動します（docker compose up -d --build）。mitmproxy の CA は保持されます。git にない Droplet 上のファイルは削除されます（logs/ の外にあるすべてのファイル）。Droplet にまだスクリプトがない場合は、レガシーの tar + docker compose コマンドを一度実行してインストールしてください。

リポジトリのルートから実行できる任意のワンショットヘルパー（コミットではなく、未コミットの変更も含む作業ツリーをパッケージ化します）：

./deploy/push-redeploy.sh root@<droplet-ip> /path/to/key

数秒のダウンタイムで MCP サーバーのみを更新する方法については、MCP サーバーのみを更新するを参照してください。

2. ローリングデプロイ（新しい Droplet）

• 新しい Droplet を作成する（上記の手順）
• 同じバンドルをデプロイする
• DNS を新しい IP に切り替える
• 準備ができたら古い Droplet を破棄する

doctl compute droplet delete <old-droplet-id> --force