alibabacloud-waf-bot-management

WAF Bot Management 自動構成アシスタント

前提条件

Alibaba Cloud CLI

Alibaba Cloud CLI（aliyun）をインストールし、設定しておく必要があります。認証情報はデフォルトの認証情報チェーンを通じて取得する必要があります。スクリプトに AK/SK をハードコーディングすることは禁止されています。

# Verify CLI is available
aliyun version
# Verify credentials are valid
aliyun waf-openapi describe-instance --region cn-hangzhou \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

CLI がインストールされていない場合、または認証情報が無効な場合は、次のページを案内してください：https://help.aliyun.com/zh/waf/web-application-firewall-3-0/developer-reference/cli-integration-example-v3

WAF インスタンス

WAF 3.0 インスタンス（Enterprise エディション以上）を購入済みで、Bot Management モジュールが有効になっている必要があります（Bot Management は WAF の追加モジュールであり、別途購入する必要があります）。

AI モードの構成

このスキルでは、すべての操作に aliyun CLI を使用します。AI モードのライフサイクル管理コマンド：

# Enable AI-Mode
aliyun configure ai-mode enable

# Set User-Agent
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# Disable AI-Mode
aliyun configure ai-mode disable

# Update plugin
aliyun plugin update

現在の状態：aliyun waf-openapi コマンドを実行する前に、AI モードを有効にする必要があります。以下の業務用 CLI コマンドには、トレーサビリティ確保のため --user-agent フラグが含まれています。システムコマンド（例：--help、configure）では user-agent を設定しません。

---

入力情報の収集

AskUserQuestion を使用して、以下の情報を収集してください。不足している項目があれば、追加で確認する必要があります。

必須項目

1. 業界シナリオ：LLM/API サービス | 小売 E コマース／プロモーション | 一般的なクローリング対策 | 学術研究プラットフォーム
2. 保護対象ドメイン：保護が必要なドメインを少なくとも 1 つ
3. アクセス方式：CNAME | ALB クラウド製品アクセス | ハイブリッドクラウド | 不明（API で照会可能）

シナリオ固有の追加質問

• LLM シナリオ：API エンドポイントのパスプレフィックス（例：/api/v1/）、モバイルアプリの有無、1 日あたりの API 呼び出しの平均件数
• 小売シナリオ：プロモーション期間（日時＋時間帯）の有無、アプリ／ミニプログラムの有無、フラッシュセール／秒殺シナリオの有無
• 学術研究シナリオ：ユーザーがクラウドプロバイダーの VM からアクセスするか、Python／スクリプトベースの API 呼び出しが許可されているか
• 一般シナリオ：現在の攻撃症状（帯域幅の飽和／データスクレイピング／SMS 爆撃／その他）

任意項目

• WAF インスタンスのリージョン（デフォルト：cn-hangzhou）
• コンプライアンス上の制約の有無（例：CAPTCHA を表示できない、リージョン単位でブロックできない）
• 特定の正規クローラーを保護する必要があるか（例：検索エンジンのクローラー）

---

実行ワークフロー

ステップ 1：現状評価（CLI による自動化）

API を使用して現在の WAF インスタンスと Bot Management の設定状況を照会し、評価レポートを出力します。

# 1.1 Query WAF instance information
aliyun waf-openapi describe-instance --region {region} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 1.2 Query existing protection template list
aliyun waf-openapi describe-defense-templates --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 1.3 Query Bot Management rule label information
aliyun waf-openapi describe-bot-rule-labels --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 1.4 Query log service status
aliyun waf-openapi describe-user-waf-log-status --region {region} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 1.5 Query protected object list
aliyun waf-openapi describe-defense-resources --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 1.6 Query CNAME access domain list (confirm protected domains are onboarded)
aliyun waf-openapi describe-domains --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

評価チェックリストの出力（各項目を確認してください）：

• WAF インスタンスが正常な状態で、Bot Management モジュールが有効になっている
• 保護対象のドメインが WAF に登録されている（CNAME またはクラウド製品経由でアクセス可能）
• 保護対象が作成され、関連付けられている
• ログサービスが有効になっている（後続の検証に必要）
• Bot の収集フィールドがログに追加され、インデックス作成が有効になっている

Bot モジュールが有効でない場合や、ドメインが登録されていない場合は、運用手順を提示して処理を一時停止します。ユーザーが完了を確認するまで、続行しないでください。

実行時のエラー処理（すべての CLI 呼び出しに適用）：

ステップ 1／3／4 で CLI コマンドを実行する際は、次のようにエラーを処理します。

エラーコード	意味	解決方法
command not found	CLI がインストールされていません	ワークフローを一時停止します。CLI をインストールするには、https://help.aliyun.com/zh/waf/web-application-firewall-3-0/developer-reference/cli-integration-example-v3 を参照するようユーザーに案内するか、brew install aliyun-cli（macOS）を実行してもらいます
InvalidAccessKeyId / Forbidden.RAM	権限が不足しています	ワークフローを一時停止します。RAM ポリシーに AliyunWAFReadWriteAccess が含まれていることを確認するようユーザーに依頼します
InvalidSecurityToken.Expired	STS トークンの有効期限が切れています	認証情報を更新して再試行するため、aliyun configure を実行するようユーザーに依頼します
Throttling / Throttling.User	API の呼び出し頻度が制限されています	5 秒待って再試行します。間隔を延ばしながら最大 3 回まで再試行します（5 秒／10 秒／15 秒）
InternalError	サーバー側のエラーです	10 秒待ってから 1 回再試行します。それでも失敗する場合は、一時停止して完了したステップを報告します
InvalidParameter	パラメーターエラーです	InstanceId とリージョンが正しいことを確認します。自動で再試行しないでください

ロールバック戦略：ステップ 3 で一部のルールの作成に失敗しても、正常に作成されたルールは自動的にはロールバックされません。作成済みのルール ID の一覧を出力し、ユーザーに delete-defense-rule を手動で実行して削除するよう案内します。または、すべてのルールが確認されるまで待ってからテンプレートを有効にします（ステップ 3.4 は最後に実行されます）。

SDK 統合チェックリスト（事前に注意を促すべき重要な落とし穴が 3 つあります）：

1. Web クライアントには Web SDK の統合が必要です。統合されていない場合、4 種類のソフトブロックアクション（JS チャレンジ、動的トークン、スライダー、厳格なスライダー）はすべて失敗します
2. 静的ファイル（js/css/images）には Web SDK を挿入できません。組み込みの Bot 検知ルールとスライダーのみを使用できます
3. APP と Web が同じドメインを共有する場合、APP には SDK の統合が必要です。統合されていないと、JS 環境がないため JS チャレンジが失敗し、ビジネスに影響します

SDK の詳しい統合手順については、references/sdk-integration-guide.md を参照してください。

---

ステップ 2：シナリオに基づくルールの推奨

ユーザーが選択したシナリオに基づいて、対応する設定プランを読み込みます。

シナリオ	参照ドキュメント	主な保護対象
LLM／API サービス	references/scene-llm-api.md	LLM API エンドポイント
小売 E コマース／プロモーション	references/scene-retail-promotion.md	ログインページ／注文ページ／商品ページ／価格設定 API
一般的なクローリング対策	references/scene-anti-crawl.md	すべての Web ページ
学術研究プラットフォーム	references/scene-academic.md	API エンドポイント＋Web ページ

各シナリオのドキュメントには、有効化を推奨するルールラベル、有効化を推奨しないルールとその理由、アクションの選択、レート制限のしきい値の参考値、特別な考慮事項が含まれています。

共通ルール：すべてのシナリオで references/rules-blacklist.md（有効化を推奨しないルールの一覧）と references/attack-level-matrix.md（攻撃レベルの対応マトリックス）を参照してください。

---

ステップ 3：CLI による設定の自動化

ステップ 2 のシナリオ別の推奨事項に基づき、CLI を使用して保護テンプレートとルールを自動作成します。

3.0 ホワイトリストの設定（最初に実行）

保護ルールを作成する前に、内部監視や正規サービスの誤検知を避けるため、信頼できる IP をホワイトリストに追加します。

# Query existing address books
aliyun waf-openapi describe-addresses --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# Add trusted IPs to whitelist (can be executed multiple times)
aliyun waf-openapi add-address \
  --region {region} \
  --InstanceId {instance_id} \
  --AddressList '["{trusted_ip_1}","{trusted_ip_2}"]' \
  --AddressType "ipv4" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

ホワイトリストに登録する IP の情報源：ユーザーから提供された内部監視 IP、CI/CD の送信元 IP、パートナーの固定 IP、顧客が所有するクラウドリソースの IP 範囲。

3.1 保護テンプレートの作成

aliyun waf-openapi create-defense-template \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateName "{scenario_name}_Bot_Protection" \
  --DefenseScene "antibot" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

3.2 保護ルールの作成

シナリオごとに推奨されるルールラベルに基づいて、ルールを 1 つずつ作成します。各ルールでは、以下が必要です。

• DefenseScene：保護シナリオ（antibot）
• RuleName：ルール名
• RuleContent：一致条件（ラベル、レート制限のしきい値など）
• Action：処置アクション（block/captcha/captcha_strict/js/sigchl/monitor/bypass）

# Example: Create crawler client detection rule (action = block)
aliyun waf-openapi create-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --DefenseScene "antibot" \
  --RuleName "Crawler_Client_Block" \
  --RuleContent '{"bot_labels":["malicious_crawler_python","malicious_crawler_java"],"action":"block"}' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# Example: Create IP rate-limit rule (requests > 30 in 60 seconds -> JS challenge)
aliyun waf-openapi create-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --DefenseScene "antibot" \
  --RuleName "IP_High_Frequency_Rate_Limit" \
  --RuleContent '{"stat_object":"ip","interval":60,"threshold":30,"action":"js","rule_type":"frequency"}' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

3.3 保護対象オブジェクトのバインド

aliyun waf-openapi modify-template-resources \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --ResourceMode "bind" \
  --ResourceList '["{resource_id_1}","{resource_id_2}"]' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

resource_id を取得するには、ステップ 1.5 の describe-defense-resources の応答から ResourceId フィールドを抽出します。ステップ 1 で保護対象オブジェクトが見つからなかった場合は、まず create-defense-resource を使用して作成してください。

3.4 保護テンプレートの有効化

aliyun waf-openapi modify-defense-template-status \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --Status "enabled" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

カナリアデプロイの推奨事項：初期設定では、すべての処置アクションを monitor（監視のみ、ブロックなし）に設定します。一定期間運用してヒットデータを確認し、誤検知がないことを確認してから、正式な処置アクションに切り替えてください。シナリオ別の推奨カナリア期間は、LLM／小売シナリオで 24～48 時間、一般的なスクレイピング対策で 24～48 時間、学術研究シナリオで 7～14 日です（ユーザーの行動パターンが多様なため、より長い観察期間が必要です）。

カナリア切り替え SOP（monitor → 正式なアクション）：

1. describe-rule-hits-top-rule-id と describe-rule-hits-top-client-ip を使用して、カナリア期間中のヒットデータを確認します
2. フラグが付けられた上位 IP／UA が正規ユーザーかどうかを確認します（SLS ログと照合します）
3. 誤検知がないことを確認してから、ルールのアクションを 1 つずつ変更します。

# Switch a single rule from monitor to formal action (e.g., captcha)
aliyun waf-openapi modify-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --RuleId {rule_id} \
  --Action "captcha" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

4. 各ルールの切り替え後、4 時間観察します。次のルールに切り替える前に、異常がないことを確認してください
5. 目標のアクションが block の場合は、まず captcha に切り替えて 4 時間観察してから block に引き上げることを推奨します。

# captcha -> block upgrade (execute only after confirming captcha has no false positives)
aliyun waf-openapi modify-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --RuleId {rule_id} \
  --Action "block" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

6. すべての切り替えが完了したら、describe-defense-rules ですべてのルールのステータスを確認します

3.5 設定の検証

ルールを作成するたびに、クエリを実行して確認します。

aliyun waf-openapi describe-defense-rules \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

---

ステップ 4：CLI による自動検証

設定が完了し、一定期間運用した後（1 時間以上を推奨）、API を通じて保護効果を確認します。

# 4.1 Query Top 10 rule hits
aliyun waf-openapi describe-rule-hits-top-rule-id \
  --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 4.2 Query Top 10 attack source IPs
aliyun waf-openapi describe-rule-hits-top-client-ip \
  --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 4.3 Query attack traffic time series
aliyun waf-openapi describe-security-event-time-series-metric \
  --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 4.4 Query Top traffic URLs
aliyun waf-openapi describe-flow-top-url \
  --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 4.5 Query Top UAs hitting rules
aliyun waf-openapi describe-rule-hits-top-ua \
  --region {region} --InstanceId {instance_id} \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

より詳細なログ分析（例：単一デバイスによる複数アカウントの切り替え検出）には、SLS クエリを使用します。テンプレートは references/sls-query-templates.md にあります。

---

ステップ 5：効果の評価と調整

ステップ 4 のデータに基づいて、評価レポートを作成します。

ブロック率の評価：

• 目標ブロック率は 85% 超（実用上の目安：85%～95%）です
• ブロック率が低すぎる場合は、ルールが主な攻撃シグネチャを網羅しているか確認します
• ブロック率が高すぎる場合（98% 超）は、誤検知がないか確認します

誤検知リスクの評価：

• ブロックされた上位 IP／UA に正規ユーザーが含まれていないか確認します
• references/rules-blacklist.md を参照し、有効にすべきでないルールが有効になっていないことを確認します

調整操作（CLI コマンド）：

# 5.1 Adjust rule disposition action (e.g., if a rule has a high false positive rate, switch to observe mode)
aliyun waf-openapi modify-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --RuleId {rule_id} \
  --Action "monitor" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 5.2 Disable false-positive rule
aliyun waf-openapi modify-defense-rule-status \
  --region {region} \
  --InstanceId {instance_id} \
  --RuleId {rule_id} \
  --Status "disabled" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 5.3 Add targeted rule (based on newly discovered attack signatures)
aliyun waf-openapi create-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --TemplateId {template_id} \
  --DefenseScene "antibot" \
  --RuleName "{new_rule_name}" \
  --RuleContent '{...}' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

# 5.4 Adjust rate-limit threshold (modify existing frequency control rule)
aliyun waf-openapi modify-defense-rule \
  --region {region} \
  --InstanceId {instance_id} \
  --RuleId {rule_id} \
  --RuleContent '{"stat_object":"ip","interval":60,"threshold":50,"action":"captcha","rule_type":"frequency"}' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-bot-management"

調整に関する推奨事項：

• しきい値の調整：通常のビジネスベースラインに基づいて、レート制限のしきい値を調整します
• アクションの調整：観察中に誤検知が確認されたルールは、monitor に切り替えるか無効にします
• 新しいルール：新たに発見された攻撃シグネチャに基づいて、対象を絞ったポリシーを追加します
• SDK のデプロイ：SDK がまだデプロイされていない場合は、最適な保護を実現するため、デプロイを強く推奨します

---

アクション選択の原則（共通）

ルールの種類	推奨アクション	理由
IDC Intelligence / Request Sequence / Threat Intelligence	captcha（スライダー）	正規のユーザーは認証を通過できます
AI Crawlers / Forged Spiders / Known Malicious Tools	block	明らかに悪意のあるアクセスのため、認証を提示する必要はありません
スクリプトクライアント（Python/Java/Go など）	block または captcha	シナリオによって異なります。学術プラットフォームでは正規のスクリプトが使われる場合があります
IP／デバイス／アカウントの高頻度アクセス制限	js（JS チャレンジ）または captcha	通常のブラウザーなら自動的に通過できます
デバイス偽装の検出	captcha	正規のユーザーを誤検知するのを防ぎます
ブラウザープローブ	captcha	開発者ツールやエミュレーターを検出します

スライダーの種類の違い：

• 標準スライダー（captcha）：認証を通過すると、30 分間は再認証されません（Cookie ベース）。ログインページに適しています
• 厳格なスライダー（captcha_strict）：毎回認証します。注文ページや決済ページなど、重要な操作に適しています

---

出力形式

実行後、毎回次の項目を含む Markdown レポートを出力します。

1. 現在の状態の評価概要：インスタンスの状態、設定済みルール数、SDK のデプロイ状況
2. 設定変更ログ：このセッションで作成／変更したルールの一覧（ルール名、適用アクション、有効範囲）
3. 保護効果のデータ：ブロック率、ヒット数上位のルール、攻撃元 IP 上位
4. チューニングの推奨事項：次の最適化に向けた提案
5. 重要な注意事項：SDK デプロイ時の注意、無効化が推奨されるルール

---

参考ドキュメント一覧

ファイル	内容	使用シナリオ
references/bot2-rules-reference.md	BOT2.0 のルールラベル完全リファレンス	ルール設定時にラベル名とデフォルト状態を確認
references/sdk-integration-guide.md	Web／App SDK 統合ガイド	ステップ 1：SDK のデプロイ確認
references/scene-llm-api.md	LLM API シナリオ設定マニュアル	ステップ 2：シナリオの推奨
references/scene-retail-promotion.md	小売プロモーションのシナリオ設定マニュアル	ステップ 2：シナリオの推奨
references/scene-anti-crawl.md	一般的なクローリング対策シナリオの設定マニュアル	ステップ 2：シナリオの推奨
references/scene-academic.md	学術研究シナリオの設定マニュアル	ステップ 2：シナリオの推奨
references/sls-query-templates.md	SLS クエリテンプレートライブラリ	ステップ 4：詳細なログ分析
references/attack-level-matrix.md	攻撃レベルと保護戦略のマトリクス	ステップ 2：攻撃レベルの評価
references/rules-blacklist.md	有効化が推奨されないルール	ステップ 2／3：ルールの絞り込み
references/openapi-reference.md	WAF Bot Management OpenAPI クイックリファレンス	ステップ 3：CLI による設定