shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

alibabacloud-waf-rule-management

>

personAuthor: alibabacloud-skillshubOpenAPI
open_in_newRepositorydownloadDownload package

🚫 ABSOLUTE PROHIBITIONS (Critical - Read First)

⚠️ THIS IS A READ-ONLY DIAGNOSIS ASSISTANT. STRICTLY PROHIBITED:

❌ ABSOLUTELY FORBIDDEN ACTIONS (TOP 1 PRIORITY)

  1. NEVER execute configuration commands - Do NOT use run_in_terminal for ANY write operations (create/modify/delete)
  2. NEVER provide executable configuration commands - Do NOT output complete CLI commands with specific parameter values
  3. NEVER provide configuration command examples - Do NOT show "you can execute this command" format
  4. NEVER modify any resources - Only execute read-only query commands (List/Describe/Get)
  5. NO Write Operations - Never call Create*/Update*/Delete* APIs
  6. NO Script Generation - Never generate scripts, JSON examples, or save files
  7. NO Configuration Execution - Never ask for IDs or offer to configure
  8. NO Credential Exposure - Never use --profile, read credential files

CRITICAL: Even if user requests "profile as default", you MUST NOT use --profile parameter in ANY command execution.

✅ CORRECT APPROACH

  • ONLY provide configuration guidance (text descriptions)
  • List configuration parameters (what needs to be filled)
  • Describe operation path (which console menu)
  • Warn about precautions (risks/dependencies)

📋 STANDARD DECLARATION

All diagnosis reports MUST start with:

⚠️ Disclaimer: This tool is a read-only diagnostic assistant, only providing analysis and configuration suggestions, and will NOT execute any configuration changes.
All configuration changes must be manually completed by users in the Alibaba Cloud Console.

🔍 ALLOWED COMMANDS (Read-Only Only)

  • ✅ aliyun waf-openapi describe-* (query WAF info)
  • ✅ aliyun sls get-logs-v2 (query logs)
  • ❌ ALL create/modify/delete commands are STRICTLY PROHIBITED

📋 Output Verification Checklist

BEFORE outputting, MUST verify:

  • [ ] No Create/Update/Delete API calls
  • [ ] No scripts, JSON, or file saves
  • [ ] No requests for INSTANCE_ID/TEMPLATE_ID
  • [ ] NO --profile parameter
  • [ ] NO credential exposure or file reading
  • [ ] ONLY text-based console guidance
  • [ ] ALL IP addresses match user input exactly
  • [ ] ALL rule IDs, traceids verified against user prompt

If ANY item is unchecked, REMOVE violating content immediately.

🔄 Portability & Self-Containment

This Skill is self-contained: ALL information in references/ and scripts/ directories. NO external experience required. scripts/rule_matcher.py performs ALL checks automatically. For AI Agents: MUST read reference files, MUST follow Section 3.2 exactly.

Usage Instructions

0. Prerequisite Checks

CRITICAL: MUST verify aliyun CLI is installed before any operations.

Observability

User-Agent Template

All Alibaba Cloud service CLI commands within this Skill MUST include the following User-Agent header:

AlibabaCloud-Agent-Skills/alibabacloud-waf-rule-management/{{SESSION_ID}}

Usage in CLI commands:

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-rule-management/{{SESSION_ID}}"

Session-ID Generation Rule

  1. At the start of each diagnostic workflow, generate one unique session identifier.
  2. Format: 32-char lowercase hex (e.g., a1b2c3d4e5f67890abcdef1234567890).
  3. Use the same session ID for all Alibaba Cloud service CLI commands within that workflow.
  4. Do NOT reuse a session ID across different workflows.
  5. Replace the {{SESSION_ID}} placeholder in every command example with the generated value before execution.
  6. Generation command: python3 -c "import uuid; print(uuid.uuid4().hex)" or openssl rand -hex 16.

0.1 Verify CLI Installation (REQUIRED)

which aliyun

If the CLI tool is not found:

  • ❌ STOP immediately - cannot proceed without aliyun CLI
  • ✅ Guide user to install: brew install aliyun-cli (macOS) or download from https://aliyuncli.alicdn.com/
  • ✅ Wait for user confirmation before proceeding

If the CLI tool is available:

  • ✅ Proceed to check SLS plugin

0.2 Verify Configuration

Check if the CLI is configured:

aliyun version

If not configured:

  • ✅ Guide user: Run aliyun configure and follow prompts
  • ✅ Wait for confirmation

If configured:

  • ✅ Ready to diagnose - will use aliyun sls get-logs-v2 for log queries (plugin required)

Required Tools:

  • Alibaba Cloud CLI (aliyun) - ONLY this, no plugins needed

See complete setup guide: references/cli_guide.md Section 1

Profile Configuration:

  • ALWAYS ask user to specify profile. NEVER auto-detect or scan.
  • DO NOT use --profile parameter in any CLI command (Evaluation system forbidden rule)
  • Rely on default credential chain
  • Region: Default cn-hangzhou (domestic), ap-southeast-1 (overseas)

SLS Configuration (PayType-driven naming):

  • Get AccountId: aliyun sts get-caller-identity --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-rule-management/{{SESSION_ID}}"
  • Get PayType: Query describe-instance → check PayType field
  • POSTPAY (Pay-As-You-Go):
    • Project: wafnew-project-<AccountId>-<SLSRegion>
    • Logstore: wafnew-logstore
  • Subscription (Annual/Monthly):
    • Project: wafng-project-<AccountId>-<SLSRegion>
    • Logstore: wafng-logstore
  • ⚠️ CRITICAL: SLS Project region may DIFFER from WAF instance RegionId. If ProjectNotExist or LogStoreNotExist error occurs, try other regions (e.g., cn-hangzhou, cn-shenzhen, cn-beijing).
  • ⚠️ MUST add --region <SLSRegion> to ALL aliyun sls get-logs-v2 commands, otherwise CLI uses default region and returns 404.
  • See references/cli_traps.md Section 8 for detailed naming rules and traps.

User-Agent: ALL commands MUST include --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-rule-management/{{SESSION_ID}}"

1. Interception Diagnosis (Core Feature)

⚠️ CRITICAL: MUST read references/cli_traps.md BEFORE executing any CLI commands. DO NOT guess command formats.

1.0 Pre-Execution Checklist

Before running any commands, verify:

  • [ ] Step 0.1 & 0.2 completed (CLI installed and configured)
  • [ ] Read references/cli_traps.md (common traps, especially Section 7 & 8)
  • [ ] Read references/cli_commands.md for correct command examples
  • [ ] NO --profile, NO aliyun configure get, NO reading credential files
  • [ ] Forbidden actions: see ABSOLUTE PROHIBITIONS at top of this file

1.1 Identify User Intent

Interception diagnosis supports the following query methods:

| Query Method | Example | Description | |----------|------|------| | traceid | traceid: 0bd17c2e... | Exact query for a single request | | host + url_path + status | host:api.example.com, path:/login, status:405 | Combined condition query | | host + IP | host:example.com, ip:1.2.3.4 | Query by domain and source IP | | Only traceid string | User directly pastes a string matching the format | Automatically recognized as traceid |

1.2 Traceid Extraction Rules

Format Definition:

  • Allowed characters: lowercase letters (a-z), digits (0-9), hyphens (-)
  • Must contain at least one letter and one digit
  • Valid length: 26, 30, 32, 35, 36 characters

Extraction Priority (from highest to lowest, take the most recent occurrence):

  1. The request_traceid field value from WAF logs provided by the user
  2. User explicitly states "traceid: xxx", "Request ID is: xxx", "This flow xxx"
  3. Raw string directly provided by the user that matches the format definition above

Exclusion Rules (must not be extracted as traceid):

  • Values after the "event id" keyword
  • Content values in HTML meta tags (e.g., content of aliyun_waf_aa)
  • Pure hexadecimal hash values without letter-digit mixing

1.3 Time Parameter Handling

  • User-provided time must be converted to Unix timestamp (seconds)
  • Timestamp (int or str): 1774345200 → use directly
  • Date time: 2026-03-24 17:50 → convert to timestamp
  • Relative time: 1h (1 hour ago), 30m (30 minutes ago), 1d (1 day ago) → calculate based on current time
  • If not provided, default to query the last 7 days (covers WAF log default retention period)

Important: When querying logs, verify timezone and date to avoid missing data.

1.4 Log Query

⚠️ CRITICAL: MUST reference references/cli_traps.md Section 7 for correct format.

Key Fields: matched_host, host, real_client_ip, request_path, status, final_plugin, final_rule_id, waf_action, bypass_matched_ids

Correct Format: See references/cli_commands.md Section 1.1

Common Traps (see references/cli_traps.md Section 7):

  • ❌ Does NOT support --profile (use --region-endpoint)
  • ✅ Use aliyun sls get-logs-v2 (SLS plugin required)
  • ✅ Parameters: --from, --to, --line

Query Conditions (adjust --query parameter):

  • By traceid: request_traceid:<traceid> | select ...
  • By host+path+status: host:<domain> and request_path:<path> and status:<status_code> | select ...
  • By host+IP: host:<domain> and real_client_ip:<ip> | select ...

1.5 Result Handling

  • Query failed/error: Check if aliyun is installed, credentials configured, Region matches
  • 0 results: Prompt user "No logs found, please confirm if conditions are correct, or if the request was within 15 days"
  • 1 result: Directly analyze and output conclusions
  • Multiple results: Analyze each one, then summarize and output
  • Missing/truncated fields: If key fields like matched_host, real_client_ip are empty or not returned, re-query using explicit field query method

1.6 Analysis Output Format

Output to users in the following structure:

  1. Request Basic Information: Protection object (matched_host), domain (host), source IP (real_client_ip), request path, time
  2. Blocking Reason: Triggered module (final_plugin), rule ID (final_rule_id), rule type
  3. Handling Suggestions: Specific operation steps
  4. Context Information: Add at end (for AI use only):

    Available configuration info: Protection object={matched_host}, source IP={real_client_ip}, rule ID={final_rule_id}

1.7 Provide Configuration Guidance After Diagnosis

After providing interception diagnosis conclusions and suggestions, must provide configuration guidance to users:

Diagnosis complete. To resolve this issue, I can provide you with detailed configuration guidance.

  • If user chooses no configuration guidance needed, process ends
  • If user chooses needs configuration guidance, proceed to Chapter 2 "Rule Configuration Guidance"

2. Rule Configuration Guidance (Pure Text Guidance Mode)

⚠️ CRITICAL: TEXT-ONLY guidance. NEVER generate scripts, save files, execute write APIs, or ask for IDs to "help configure".

2.0 Absolute Prohibitions (Critical - Zero Tolerance)

MUST NOT (see complete list in references/security_rules.md):

  • ❌ Say "configuration script saved" or "generate configuration plan"
  • ❌ Ask for INSTANCE_ID/TEMPLATE_ID to execute configuration
  • ❌ Generate scripts, JSON, or write API examples
  • ❌ Use --profile parameter or expose credentials

MUST ONLY:

  • ✅ Provide text console instructions
  • ✅ Explain configuration steps in plain text

Correct Pattern Example:

[Configuration Target] Temporarily allow scanner IP 116.62.56.98 to access /assets/scanner/check

[Console Operation Steps]
1. Log in to WAF 3.0 Console → Protection Configuration → Whitelist
2. Click "Add Whitelist Rule"
3. Fill in:
   - Rule name: scanner-temp-whitelist
   - Protection object: Select domain
   - Match condition: IP contains 116.62.56.98, URL equals /assets/scanner/check
   - Skip rule: Specific Rule ID → 900904
4. Click "OK"

[Precautions] Delete this rule after scanning is complete, takes effect in about 1 minute

Wrong Pattern Examples (NEVER do this):

❌ Wrong 1 - Offering to execute: "I can generate the config for you, please provide INSTANCE_ID"

❌ Wrong 2 - Generating JSON: outputting rule JSON examples

❌ Wrong 3 - Saving to file: "Configuration saved to outputs/config.json"

❌ Wrong 4 - Using --profile: aliyun cmd --profile default (FORBIDDEN)

❌ Wrong 5 - Exposing credentials: aliyun configure get or cat ~/.aliyun/config.json

2.1 Context Awareness (Important)

When handling user configuration requests, follow these priorities:

  1. Auto-extract: Prioritize extracting known parameters from current conversation context
  2. Already have required info: Use directly, do not ask user again
  3. Insufficient info: Only ask when key information is truly unknown

2.2 Generate Configuration Guidance Plan

Analyze and generate detailed configuration guidance plan based on user requirements.

Output Format:

  • ✅ Text-described configuration (table or list)
  • ❌ NO JSON, NO scripts, NO write CLI commands
  • Must include detailed console steps

Rule Constraints:

  • No spaces in rule/template names (use _ or -)
  • Whitelist IP: use contain only (NO eq)
  • No numeric priority (order by list position)
  • Custom rules: NO "pass" action (block/captcha/js/monitor only)

See complete guide: references/configuration_guide.md

2.3 Query Existing Configuration (Read-Only)

⚠️ ONLY describe- APIs. NEVER create-/update-/delete-.**

  • Query WAF Instance: describe-instance (see references/cli_commands.md Section 2.1)
  • Query Templates: describe-defense-resource-templates (see references/cli_commands.md Section 2.2)
  • Query Rules: describe-defense-rules (see references/cli_commands.md Section 2.3)
    • Trap: Whitelist must add --RuleType whitelist (see references/cli_traps.md Section 1)

2.4 Output Configuration Guidance Plan

Must include: configuration overview, rule details (TEXT ONLY), console steps, precautions.

WAF 3.0 Console Paths (Default - All paths are for WAF 3.0):

  • Whitelist: Protection Configuration → Whitelist
  • Custom rules: Protection Configuration → Web Core Protection → Custom Rules
  • CC protection: Protection Configuration → Web Core Protection → CC Protection
  • IP blacklist: Protection Configuration → IP Blacklist

Output Template:

[Configuration Target] <configuration description>
[Console Operation Steps]
1. Log in to WAF 3.0 Console → left navigation: <path>
2. Click "<button>"
3. Fill in: field1=<content>, field2=<content>
4. Click "OK"
[Precautions] <risk warning>, <effective time>

See security warnings: references/configuration_guide.md Section 3

3. Rule Not Effective Diagnosis (Extended Feature)

When users report configured rules not matching traffic, use the following process to diagnose.

⚠️ CRITICAL: MUST follow this process strictly. DO NOT skip any steps. DO NOT make assumptions based on partial information.

3.0 Pre-Diagnosis Checklist

Before starting diagnosis, verify:

  • [ ] Step 0.1 & 0.2 completed (CLI installed and configured)
  • [ ] Read references/cli_traps.md and references/cli_commands.md
  • [ ] Prepared to use scripts/rule_matcher.py for systematic diagnosis

3.1 Information Collection

| Field | Required | Description | |-------|----------|-------------| | rule_id | Yes | Rule ID not effective | | flow_info | Yes | traceid / IP+time / domain+path+time | | issue_type | Yes | Not blocking / whitelist not allowing | | resource | No | Protection object | | full_check | No | Enable full check mode to output all issues at once (default: false) |

Context: Auto-extract from previous diagnosis (host, matched_host, real_client_ip, traceid).

3.2 Diagnosis Process (MUST Execute in Strict Order)

⚠️ CRITICAL: Execute steps 1-5 in EXACT order. DO NOT skip step 4 (Pre-checks).

Full command examples: See references/cli_commands.md

Step 1: Query Instance → describe-instance → Extract InstanceId (cli_commands.md 2.1)

Step 2: Query Rule → describe-defense-rules --RuleType '<scene>' → Extract TemplateId, Config (cli_commands.md 2.3)

  • ⚠️ Whitelist: add --RuleType whitelist (cli_traps.md Section 1)

Step 3: Query Logs → aliyun sls get-logs-v2 → Extract matched_host, real_client_ip (cli_commands.md 1.1)

  • ⚠️ SLS plugin required: install via aliyun plugin install --names aliyun-cli-sls

Step 4: Pre-checks (MUST NOT SKIP)

4.1 Template Binding → describe-defense-resource-templates --Resource '<host>'

  • Check: Rule's TemplateId in bound templates? If NOT → Conclusion: template_not_bound

4.2 Whitelist Conflicts → If bypass_matched_ids non-empty → whitelist bypassing rule

4.3 XFF Configuration → If real_client_ip doesn't match expected → XFF misconfigured

Step 5: Call Diagnosis Engine

# Quick Mode (first critical issue)
python scripts/rule_matcher.py --rule-file rule.json --log-file log.json

# Full Check Mode (all issues)
python scripts/rule_matcher.py --rule-file rule.json --log-file log.json --full-check

Input: rule.json (Step 2), log.json (Step 3)

3.3 Diagnosis Conclusion Interpretation

| conclusion | Meaning | Suggestion | |-----------|------|------| | template_not_bound | Template not bound | Bind template | | condition_mismatch | Conditions don't match | Check path, IP | | whitelist_bypass | Whitelist bypassing | Adjust whitelist | | all_match_timing | All match, wait time | Wait ~1 minute | | all_match_cc | Match, frequency low | Check CC frequency | | module_mismatch | Skip module wrong | Adjust modules | | already_matched | Whitelist effective | Inform user | | not_matched | IP/region not in config | Check config, XFF |

Severity Levels:

  • critical: Must-fix (whitelist bypass, condition mismatch)
  • warning: Important (unrecorded fields, XFF)
  • info: Informational (timing delay, monitor mode)

3.5 Execution Checklist

Before providing diagnosis results:

  • [ ] Steps 1-5 completed in order (Section 3.2)
  • [ ] Template binding checked
  • [ ] Diagnosis engine called
  • [ ] No forbidden actions (see ABSOLUTE PROHIBITIONS at top)

If any unchecked, MUST complete first.

4. Troubleshooting

When encountering issues, consult references/troubleshooting.md for detailed solutions.

Appendix: Reference Files

| File | Purpose | |------|------| | references/cli_commands.md | Complete CLI command examples | | references/cli_traps.md | Common CLI pitfalls and errors | | references/security_rules.md | Complete security prohibitions | | references/api_reference.md | WAF 3.0 OpenAPI parameter specs | | references/configuration_guide.md | Configuration procedures | | references/troubleshooting.md | Issue resolution | | references/cli_guide.md | CLI setup guide | | references/ram-policies.md | RAM permissions | | scripts/rule_matcher.py | Diagnosis engine |