huawei-cloud-waf-log-analysis

Analyze Huawei Cloud WAF security event logs to identify attack patterns, top sources, targeted assets, and provide actionable protection rule recommendations. Use when the user asks about recent attacks, WAF alert investigation, security posture review, attack trend analysis, or needs guidance on configuring protection rules based on observed threats. Triggers include "analyze WAF logs", "WAF attack analysis", "security event report", "what attacks happened", "WAF alert investigation", "recommend protection rules", "attack source analysis", "WAF安全日志分析", "攻击事件分析", "防护规则推荐".

Huawei Cloud WAF Security Event Log Analysis

Overview

This skill provides read-only analysis of Huawei Cloud WAF (Web Application Firewall) security event logs. It queries attack event data through hcloud CLI, performs multi-dimensional aggregation and analysis, and generates actionable protection rule recommendations based on observed attack patterns.

Key Capabilities:

• Query and filter security events by attack type, source IP, target domain/URL, time range, and geography
• Aggregate statistics by attack category, source IP frequency, geographic distribution, and time trends
• Recommend specific WAF protection rules (precise access control, CC protection, IP blacklist/whitelist, geo-blocking) based on analyzed attack characteristics

Applicable Scenarios:

• Daily security patrol and attack posture review
• Incident response after receiving WAF alerts
• Periodic security reports (weekly/monthly attack trends)
• Anomaly investigation when suspicious activity is detected
• Protection hardening decisions after attack events

⚠️ Read-Only Principle — STRICTLY ENFORCED

This skill is a READ-ONLY analysis skill. The agent must follow these rules without exception:

Action	Allowed?	Explanation
Query events (ListEvent, ShowEvent)	✅ YES	Read-only data retrieval
Query policies/hosts (ListPolicy, ShowPolicy, ListHost)	✅ YES	Read-only data retrieval
Aggregate and analyze event data	✅ YES	Core analysis work
Output recommended hcloud commands	✅ YES	Provide copy-paste ready commands for the user
Execute Create* / Update* / Delete* commands	❌ NEVER	These modify production resources; the user decides when and whether to run them
Auto-execute any write operation based on analysis findings	❌ NEVER	Even if the recommendation seems obvious, do NOT run it

What the agent MUST do:

1. Perform read-only queries and analysis
2. Generate a structured report with prioritized recommendations
3. For each recommendation, output the exact, copy-paste ready hcloud command that the user can execute themselves
4. Clearly label each command with its purpose and expected effect

What the agent MUST NOT do:

1. Execute any command that creates, modifies, or deletes WAF resources
2. Ask the user "should I execute this for you?" — just present the command and let the user decide
3. Proceed to execute recommendations after presenting them — stop after the report is delivered

Prerequisites

Requirement	Description
hcloud CLI	v7.2+ installed and configured with AK/SK, region, and project ID
Project ID	Valid project ID (configured via hcloud configure set --cli-project-id=<id>)
IAM Permissions	See references/iam-policies.md for least-privilege policy
Network	Accessible network path to Huawei Cloud API endpoints

⚠️ Windows PowerShell Compatibility — STRICTLY ENFORCED

This skill runs on Windows PowerShell. The agent MUST NOT use Linux/Unix shell commands. Use PowerShell-native equivalents at all times.

❌ Linux command (NEVER use)	✅ PowerShell equivalent	Example
head -N	Select-Object -First N	... | Select-Object -First 30
tail -N	Select-Object -Last N	... | Select-Object -Last 30
grep "pattern"	Select-String "pattern"	... | Select-String "error"
wc -l	(... ).Count or (Measure-Object -Line).Lines	$items.Count
sort	Sort-Object	... | Sort-Object Count -Descending
uniq	Get-Unique or Group-Object	... | Group-Object
awk '{print $1}'	ForEach-Object { $_.field }	$items | ForEach-Object { $_.sip }
cut -d: -f1	Split-Path, -split, or Substring	($_ -split ':')[0]
sed 's/a/b/'	-replace operator	'text' -replace 'a','b'
cat file	Get-Content file	Get-Content "$env:TEMP\data.json" -Raw
echo "text"	Write-Host "text"	Write-Host "Processing..."
export VAR=value	$env:VAR="value"	$env:HTTP_PROXY="http://127.0.0.1:3128"
sleep N	Start-Sleep -Seconds N	Start-Sleep -Seconds 2

Additional rules:

• Always use Out-File -Encoding utf8 instead of > file for redirecting output (avoids encoding issues)
• Use double quotes " around variable expansions inside strings: "Total: $($items.Count)"
• Pipe hcloud JSON output to ConvertFrom-Json for structured analysis: hcloud WAF ListEvent ... \| ConvertFrom-Json

Workflow

Step 1: Clarify Analysis Scope

Ask the user for the following parameters (defaults provided):

Parameter	Default	Options
Time range	today	today, yesterday, 3days, 1week, 1month
Domain filter	All domains	Specific domain name or leave empty
Attack type filter	All types	sqli, xss, cc, botm, cmdi, robot, etc.
Analysis focus	General overview	Attack type stats, IP analysis, target analysis, time trends, rule recommendation
Data volume	First page (100)	See options below

Data Volume Options:

Option	Description	When to use
first_page (default)	Query first 100 events only, fastest	Quick glance at recent activity
sample_pages	Query N pages of events; N must be explicitly specified by the user — agent has NO default	Balanced speed vs coverage
all_pages	Paginate through ALL results up to 10,000	Comprehensive analysis, may take several minutes
by_attack_type	First query to discover attack types, then query top N types separately (each gets its own first page)	Best attack-type diversity, avoids single-type bias

⚠️ IMPORTANT — Data Volume Selection (STRICTLY ENFORCED):

• The agent MUST ask the user which data volume option to use. Do NOT silently default to any option.
• If user chooses sample_pages, the agent MUST ask the user how many pages (N) to fetch. There is NO default value for N. The agent must NOT assume or default to any number (e.g., 5). Ask explicitly: "你想采样多少页？（每页100条事件）"
• If total events > 100 and user chose first_page, warn them that the sample may not represent the full picture.

Step 2: Query Security Events

Step 2a: Get Total Count First

Always start with a single lightweight query to determine total event count:

bash

hcloud WAF ListEvent --recent={time_range} --pagesize=1 --page=1

Read the total field from the response. This tells you how much data exists before committing to a fetching strategy.

Step 2b: Fetch Data Based on User's Choice

Based on the user's data volume selection, execute the corresponding strategy:

Strategy: first_page (default)

Fetch one page of 100 events:

bash

hcloud WAF ListEvent --recent={time_range} --pagesize=100 --page=1 --sort_key=attack

Save result to file:

powershell

hcloud WAF ListEvent --recent={time_range} --pagesize=100 --page=1 --sort_key=attack | Out-File -Encoding utf8 "$env:TEMP\waf_events.json"

If total > 100, display a warning to the user:

"Total events: {total}. This analysis is based on 100 events (1%). Results may not represent the full picture."

Strategy: sample_pages (user specifies N)

Loop through N pages, appending each page's items to a combined file:

powershell

$pages = {N}   # e.g., 5
for ($p = 1; $p -le $pages; $p++) {
    hcloud WAF ListEvent --recent={time_range} --pagesize=100 --page=$p --sort_key=attack | Out-File -Encoding utf8 "$env:TEMP\waf_events_page$p.json"
}

# Merge all pages into one file for unified analysis
$allItems = @()
for ($p = 1; $p -le $pages; $p++) {
    $raw = Get-Content "$env:TEMP\waf_events_page$p.json" -Raw
    $data = $raw | ConvertFrom-Json
    $allItems += $data.items
}
$merged = @{ total = $data.total; items = $allItems } | ConvertTo-Json -Depth 10
$merged | Out-File -Encoding utf8 "$env:TEMP\waf_events_all.json"
Write-Host "Merged $($allItems.Count) events from $pages pages"

Strategy: all_pages

Keep paginating until all events are fetched or 10,000 cap reached:

powershell

$allItems = @()
$page = 1
$total = 0
do {
    $raw = hcloud WAF ListEvent --recent={time_range} --pagesize=100 --page=$page --sort_key=attack
    $data = $raw | ConvertFrom-Json
    $total = $data.total
    $allItems += $data.items
    Write-Host "Fetched page $page / $([math]::Ceiling($total / 100)) ($($allItems.Count) / $total events)"
    $page++
} while ($data.items.Count -eq 100 -and $allItems.Count -lt 10000)

$merged = @{ total = $total; items = $allItems } | ConvertTo-Json -Depth 10
$merged | Out-File -Encoding utf8 "$env:TEMP\waf_events_all.json"
Write-Host "Total fetched: $($allItems.Count) events"

⚠️ With 10,000 events this requires ~100 API calls and may take 5-10 minutes. Consider using by_attack_type instead for faster diverse coverage.

Strategy: by_attack_type

Step 1 — Discover attack types by querying first page sorted by attack:

powershell

$raw = hcloud WAF ListEvent --recent={time_range} --pagesize=100 --page=1 --sort_key=attack
$data = $raw | ConvertFrom-Json
$attackTypes = $data.items | Group-Object attack | Sort-Object Count -Descending
$attackTypes | ForEach-Object { Write-Host ("{0,-30} {1}" -f $_.Name, $_.Count) }

Step 2 — For the top N attack types discovered (default N=5), query each separately:

powershell

foreach ($atk in $attackTypes | Select-Object -First {N}) {
    $type = $atk.Name
    hcloud WAF ListEvent --recent={time_range} --attacks.1=$type --pagesize=100 --page=1 | Out-File -Encoding utf8 "$env:TEMP\waf_events_attack_$type.json"
    Write-Host "Fetched 100 events for attack type: $type"
}

Step 3 — Merge all per-type files into one combined dataset:

powershell

# Clean up old attack type files to avoid mixing with previous runs
Remove-Item "$env:TEMP\waf_events_attack_*.json" -ErrorAction SilentlyContinue

$allItems = @()
foreach ($file in Get-ChildItem "$env:TEMP\waf_events_attack_*.json") {
    $raw = Get-Content $file.FullName -Raw
    $data = $raw | ConvertFrom-Json
    if ($data.items) { $allItems += $data.items }
}
$merged = @{ total = "multi-type-sample"; items = $allItems } | ConvertTo-Json -Depth 10
$merged | Out-File -Encoding utf8 "$env:TEMP\waf_events_all.json"
Write-Host "Combined dataset: $($allItems.Count) events across multiple attack types"

Common Query Examples

bash

# Filter by source IP
hcloud WAF ListEvent --recent={time_range} --sip={source_ip} --pagesize=100

# ⚠️ WARNING: --domain conflicts with KooCLI system parameter and will prompt interactively
# DO NOT use --domain in automated scripts; see workaround below
# hcloud WAF ListEvent --recent={time_range} --domain={domain} --pagesize=100

# Sort by different dimensions
hcloud WAF ListEvent --recent={time_range} --sort_key=sort_ip --pagesize=100
hcloud WAF ListEvent --recent={time_range} --sort_key=attack --pagesize=100

⚠️ --domain Parameter Conflict: The --domain parameter name conflicts with KooCLI's system parameter. Using it directly triggers an interactive prompt asking to choose between system/API parameter, which hangs non-interactive environments (e.g., Bash tool, automation scripts).

Solution — Use --cli-jsonInput to bypass the conflict:

powershell

# Step 1: Create a JSON file with query parameters
$jsonContent = @'
{
  "path": {
    "project_id": "{project_id}"
  },
  "query": {
    "recent": "today",
    "domain": "{domain}",
    "pagesize": 100,
    "page": 1
  }
}
'@
$jsonContent | Out-File -FilePath "$env:TEMP\listevent_domain.json" -Encoding ASCII

# Step 2: Execute with --cli-jsonInput
hcloud WAF ListEvent --cli-jsonInput="$env:TEMP\listevent_domain.json" | Out-File -Encoding utf8 "$env:TEMP\domain_result.json"

# Step 3: Parse result (skip hcloud's warning message)
$raw = Get-Content "$env:TEMP\domain_result.json" -Raw
$jsonStart = $raw.IndexOf('{')
$data = $raw.Substring($jsonStart) | ConvertFrom-Json
Write-Host "Filtered $($data.items.Count) events for domain: {domain}"

Note: project_id can be obtained from hcloud configure list or from previous API responses. hcloud outputs a warning message before JSON when using --cli-jsonInput, so use file redirect and skip to the first { character when parsing.

Important:

• Maximum 10,000 records per query; narrow time range if exceeded
• --pagesize parameter: Valid range is [0, total_data]. Default to 100 if user doesn't specify. Use user's value when provided. If API returns error WAF.00011011: pageOrPageSize.illegal, inform the user that their pagesize value is too large and ask them to enter a smaller value within the valid range
• Paginate through results if total count > pagesize (use multiple queries with --page=1, --page=2, etc.)
• Use --from and --to (millisecond timestamps) for custom time ranges (max 30 days)
• Always save multi-page results to a merged file before analysis to avoid PowerShell variable scope issues

Step 3: Multi-Dimensional Analysis

⚠️ PowerShell Variable Scope Warning: Each Bash tool invocation runs in an isolated session — variables do NOT persist across calls. You MUST either:

• Load and analyze data in the same command block, OR
• Save query results to a file first, then reload from file in subsequent analysis commands

powershell

# ❌ WRONG - Variables don't persist across Bash calls
# Call 1: $items = hcloud WAF ListEvent ... | ConvertFrom-Json
# Call 2: $items | Group-Object attack  # ERROR: $items is empty!

# ✅ CORRECT Option 1 - Single command block
$items = (hcloud WAF ListEvent --recent=today --pagesize=100 --page=1).items | ConvertFrom-Json
$items | Group-Object attack | Sort-Object Count -Descending | Select-Object Count, Name

# ✅ CORRECT Option 2 - Save to file, reload later
# Call 1: hcloud WAF ListEvent ... | Out-File -Encoding utf8 "$env:TEMP\waf_events.json"
# Call 2: $items = (Get-Content "$env:TEMP\waf_events.json" -Raw | ConvertFrom-Json).items
#         $items | Group-Object attack

Aggregate the queried events across the following dimensions:

3a. Attack Type Distribution

Count events by attack field. Map attack codes to human-readable names:

Code	Name	Recommended Rule Type
sqli	SQL Injection	CreateCustomRule / UpdatePolicy --options.webattack=true
xss	XSS Attack	CreateCustomRule / UpdatePolicy --options.webattack=true
cc	CC Attack	CreateCcRule
botm	BOT Attack	CreateAnticrawlerRule (需先调用 UpdateAnticrawlerRuleType) / UpdatePolicy --options.bot_enable=true + enable specific detectors: crawler_scanner, crawler_script, crawler_engine, crawler_other
cmdi	Command Injection	CreateCustomRule / UpdatePolicy --options.webattack=true
rfi	Remote File Inclusion	CreateCustomRule / UpdatePolicy --options.webattack=true
rce	Remote Code Execution	CreateCustomRule / UpdatePolicy --options.webattack=true
lfi	Local File Inclusion	CreateCustomRule / UpdatePolicy --options.webattack=true
ptr	Directory Traversal	CreateCustomRule (match ../ payload) / UpdatePolicy --options.webattack=true
robot	Malicious Crawler	CreateAnticrawlerRule (需先调用 UpdateAnticrawlerRuleType) / UpdatePolicy --options.bot_enable=true + --options.crawler_scanner=true + --options.crawler_script=true + --options.crawler_engine=true + --options.crawler_other=true
webshell	Webshell	UpdatePolicy --options.webshell=true / CreateCustomRule
vuln	Other Vulnerability	UpdatePolicy --options.webattack=true / CreateCustomRule
custom_whiteblackip	IP Blacklist/Whitelist	Already using CreateWhiteblackipRule
custom_geoip	Geo Access Control	Already using CreateGeoipRule
custom_custom	Precise Protection	Already using CreateCustomRule
iprank	IP Reputation	CreateIpReputationRule
antiscan_high_freq_scan	High-frequency Scan	CreateCcRule / UpdatePolicy --options.modulex_enabled=true --modulex_options.global_rate_enabled=true
antitamper	Anti-tamper	CreateAntiTamperRule + UpdatePolicy --options.antitamper=true
anticrawler	Anti-crawler	CreateAnticrawlerRule + UpdatePolicy --options.anticrawler=true
followed_action	Attack Punishment	CreatePunishmentRule + UpdatePolicy --options.followed_action=true
antileakage	Sensitive Data Leakage	CreateAntileakageRule + UpdatePolicy --options.antileakage=true
custom_robot	Scanner Crawler	CreateCustomRule (User-Agent matching) / CreateAnticrawlerRule
advanced_bot	Advanced BOT	UpdatePolicy --options.bot_enable=true + CreateAnticrawlerRule

3b. Source IP Analysis

Group by sip (source IP) field, sorted by frequency:

• Identify top attacking IPs (>5 hits in analysis period)
• Cross-reference with ip_countries and ip_regions for geographic distribution
• Flag IPs from unexpected countries

3c. Target Asset Analysis

Group by host (domain) and url fields:

• Identify most-targeted domains
• Identify most-targeted URL paths
• Correlate attack types with specific URLs

3d. Time Trend Analysis

The time field in API responses is a Unix millisecond timestamp (e.g., 1789696805000). It MUST be converted using [DateTimeOffset]::FromUnixTimeMilliseconds():

powershell

# CORRECT - Convert Unix millisecond timestamp to local time
$items | ForEach-Object {
    [DateTimeOffset]::FromUnixTimeMilliseconds([long]$_.time).LocalDateTime.ToString("yyyy-MM-dd HH")
} | Group-Object | Sort-Object Name | Select-Object Count, Name

# WRONG - FromFileTimeUtc expects Windows FILETIME (epoch 1601-01-01),
#         passing a Unix timestamp will produce dates around year 1601
[DateTime]::FromFileTimeUtc($_.time)

Aggregate the converted timestamps by hour:

• Identify peak attack periods
• Determine if attacks are sustained or burst-type
• Compare with normal traffic baseline if available

3e. Action Distribution

Group by action field (protection action taken):

• Count events by action type: block, pass, log, captcha, cache, mask, js_challenge, advanced_captcha, abort_response, desensitize
• Calculate block rate vs pass rate to assess protection effectiveness
• Identify rules that are in "log only" mode and should be escalated to "block"

Step 4: View Detailed Events (if needed)

For deeper investigation of specific events:

bash

hcloud WAF ShowEvent --eventid={event_id}

The detail view includes: full request headers, payload content, matched rule ID, and action taken.

⚠️ Timeout Warning: ShowEvent may fail with [USE_ERROR]调用API超时 if:

• The event is old and data retrieval is slow
• The API endpoint is under heavy load

Troubleshooting steps:

1. Increase read timeout: hcloud configure set --cli-read-timeout=60
2. Try a more recent event ID (older events may have been archived)
3. If timeout persists, the detailed event data can often be found in the original ListEvent response's response_body, headers, and other fields — use that as a fallback

Step 5: Generate Protection Rule Recommendations

Based on the analysis results, recommend specific WAF protection rules with executable hcloud commands. See references/rule-recommendation-guide.md for detailed mapping logic and full command reference.

Quick Reference — Attack Pattern → Rule Recommendation → hcloud Command:

Observed Pattern	Recommended Action	Rule Type
High-volume requests from single IP to same URL	CC protection rule (rate limiting by IP + URL)	CreateCcRule
SQL injection attempts targeting specific URL	Precise access control rule (URL contains + block sqli payload pattern)	CreateCustomRule
Attacks from specific country IPs	Geo access control rule (block specific countries)	CreateGeoipRule
Repeated attacks from known malicious IPs	IP blacklist rule	CreateWhiteblackipRule
BOT/scanner user-agent patterns	Precise access control rule (User-Agent matching)	CreateCustomRule
Attacks on admin/api paths	Precise access control rule (URL path restriction)	CreateCustomRule
Multiple attack types from same IP subnet	IP group blacklist rule	CreateWhiteblackipRule
Malicious crawler/scanner traffic (robot)	JS anti-crawler rule (User-Agent matching)	CreateAnticrawlerRule
IDC datacenter malicious IP (iprank)	IP reputation rule (threat intelligence)	CreateIpReputationRule
Web content tampering (antitamper)	Anti-tamper rule (URL protection)	CreateAntiTamperRule
Persistent attacker blocking (followed_action)	Punishment rule (auto-block after threshold)	CreatePunishmentRule
Sensitive data in responses	Anti-leakage rule (filter phone/id_card/email)	CreateAntileakageRule
Webshell upload/access (webshell)	Enable webshell detection module	UpdatePolicy --options.webshell=true
Directory traversal (ptr) / Other vuln (vuln)	Enable basic protection + custom rule for payload	UpdatePolicy --options.webattack=true
High-frequency scan (antiscan_high_freq_scan)	CC protection or modulex scan protection	CreateCcRule / UpdatePolicy

After determining the recommendation, output the corresponding hcloud command as a code block for the user to copy and execute themselves. Do NOT execute the command. Use the policy_id extracted from the event data (the policyid field). See below for command templates per pattern:

5a. IP Blacklist — Block Malicious Source IP

bash

hcloud WAF CreateWhiteblackipRule   --policy_id={policy_id} \
  --name={rule_name} \
  --addr={source_ip} \
  --white=0

Parameters:

• --white=0 → blacklist (block), --white=1 → whitelist (allow), --white=2 → log only
• --addr supports single IP or CIDR (e.g., 203.0.113.0/24)
• Verify: hcloud WAF ListWhiteblackipRule --policy_id={policy_id} --page=1 --pagesize=10

5b. CC Protection — Rate Limiting

⚠️ --mode conflicts with KooCLI system parameter. Must use --cli-jsonInput.

Create a temporary JSON file (e.g., cc-rule.json):

json

{
  "path": {
    "project_id": "{project_id}",
    "policy_id": "{policy_id}"
  },
  "query": {},
  "body": {
    "name": "{rule_name}",
    "mode": 1,
    "tag_type": "ip",
    "limit_num": 100,
    "limit_period": 60,
    "lock_time": 300,
    "action": {
      "category": "block"
    }
  }
}

Note: {project_id} is the same one configured in hcloud CLI (via hcloud configure set --cli-project-id=<id>). Check current value with hcloud configure list.

Then execute:

bash

hcloud WAF CreateCcRule --cli-jsonInput=cc-rule.json

Parameters:

• tag_type: ip (by source IP), url (by URL path), cookie (by cookie), header (by header)
• limit_num / limit_period: threshold count within time window (seconds)
• lock_time: block duration (seconds) after threshold exceeded
• action.category: block, captcha, redirect
• Verify: hcloud WAF ListCcRules --policy_id={policy_id}

5c. Precise Access Control — Custom Rule

bash

hcloud WAF CreateCustomRule   --policy_id={policy_id} \
  --name={rule_name} \
  --action.category=block \
  --conditions.1.category={field_category} \
  --conditions.1.logic_operation={logic_op} \
  --conditions.1.contents.1={match_value} \
  --priority=50 \
  --time=false

Common condition configurations:

Scenario	category	index (if needed)	logic_operation	contents.1
Match URL path	url	—	contain	/admin
Match User-Agent	user-agent	—	contain	python-requests
Match Header value	header	X-Custom-Header	equal	malicious-value
Match Cookie	cookie	session_id	contain	value
Match IP source	ip	—	equal	203.0.113.1
Match request method	method	—	equal	POST
Match payload	params	—	contain	<script>

Additional parameters:

• --conditions.N.index={field_name} — Required when category is header, cookie; NOT field
• --time=false — Immediate effect; do NOT use --status
• --priority=N — Range 0~65535, lower = higher priority
• Multi-condition AND: add --conditions.2.category=... etc.
• Logic operations: contain, not_contain, equal, not_equal, prefix, suffix, regex, none
• Verify: hcloud WAF ListCustomRules --policy_id={policy_id}

5d. Geo Access Control — Block by Country

bash

hcloud WAF CreateGeoipRule   --policy_id={policy_id} \
  --name={rule_name} \
  --geoip={country_code} \
  --white=0

Parameters:

• --geoip — ISO 3166-1 alpha-2 country code (e.g., KP, IR, CU)
• --white=0 → block traffic from this country
• Caution: Always confirm with user that no legitimate business traffic comes from the blocked countries before recommending geo-blocking
• Verify: hcloud WAF ListGeoipRule --policy_id={policy_id}

5e. Update Basic Protection Policy — Change Action from Log to Block

If events show action=log for attack types that should be blocked:

bash

# View current policy settings
hcloud WAF ShowPolicy --policy_id={policy_id}

# Change protection action to block
hcloud WAF UpdatePolicy   --policy_id={policy_id} \
  --action.category=block

# Or raise protection level (1=loose, 2=medium, 3=strict)
hcloud WAF UpdatePolicy   --policy_id={policy_id} \
  --level=3

Note: UpdatePolicy can also enable/disable built-in protection modules via --options.* parameters (see 5k below).

5f. Anticrawler Rule — Block Malicious Crawlers (robot / anticrawler)

⚠️ Must call UpdateAnticrawlerRuleType to set protection mode before creating anticrawler rules.

bash

# Step 1: Set anticrawler protection mode (required prerequisite)
hcloud WAF UpdateAnticrawlerRuleType   --policy_id={policy_id} \
  --anticrawler_type=anticrawler_except_url

# Step 2: Create anticrawler rule
hcloud WAF CreateAnticrawlerRule   --policy_id={policy_id} \
  --name={rule_name} \
  --type=anticrawler_except_url \
  --conditions.1.category=user-agent \
  --conditions.1.logic_operation=contain \
  --conditions.1.contents.1={scanner_signature} \
  --priority=20

Parameters (verified via --help):

• --anticrawler_type / --type: anticrawler_except_url (protect all paths, rule = exclusion) or anticrawler_specific_url (protect specified paths only)
• --conditions.N.category: url or user-agent
• --conditions.N.logic_operation: contain, not_contain, equal, prefix, suffix, regular_match, etc.
• --priority: 0~65535, lower = higher priority
• Verify: hcloud WAF ListAnticrawlerRules --policy_id={policy_id} --page=1 --pagesize=10

5g. IP Reputation Rule — Block Malicious IP Sources (iprank)

bash

hcloud WAF CreateIpReputationRule   --policy_id={policy_id} \
  --name={rule_name} \
  --type=idc \
  --action.category=block \
  --tags.1={threat_tag}

Parameters (verified via --help):

• --type: Currently only supports idc (IDC data center IP)
• --action.category: block (拦截), log (仅记录), pass (放行)
• --tags.N: Threat intelligence tags (obtain from ListIpReputationRules or threat intel console)
• Verify: hcloud WAF ListIpReputationRules --policy_id={policy_id} --page=1 --pagesize=10

5h. Anti-Tamper Rule — Protect Web Content (antitamper)

bash

hcloud WAF CreateAntiTamperRule   --policy_id={policy_id} \
  --hostname={protected_domain} \
  --url={protected_url} \
  --description={rule_description}

Parameters (verified via --help):

• --hostname: Protected domain (from ListHost response hostname field)
• --url: Protected URL path, e.g., /admin/index.html or /static/* (* suffix = prefix match)
• --description: Optional rule description
• Verify: hcloud WAF ListAntitamperRule --policy_id={policy_id} --page=1 --pagesize=10
• Note: Must also enable the module: hcloud WAF UpdatePolicy --policy_id={policy_id} --options.antitamper=true

5i. Punishment Rule — Block Persistent Attackers (followed_action)

bash

hcloud WAF CreatePunishmentRule   --policy_id={policy_id} \
  --category={punishment_category} \
  --block_time={block_seconds} \
  --time_unit={time_unit} \
  --description={rule_description}

Parameters (verified via --help):

• --category: One of:
  • short_ip_block / short_cookie_block / short_params_block / short_header_block — short-term punishment
  • long_ip_block / long_cookie_block / long_params_block / long_header_block — long-term punishment
• --block_time: Block duration (range depends on category and time_unit):
  • short_* + SECOND: [1, 300]
  • long_* + SECOND: [301, 7776000]
  • long_* + MINUTE: [6, 129600]
  • long_* + HOUR: [1, 2160]
  • long_* + DAY: [1, 90]
  • long_* + MONTH: [1, 3]
• --time_unit: SECOND (default), MINUTE, HOUR, DAY, MONTH
• Note: Each category can only have one rule; category cannot be modified after creation
• Verify: hcloud WAF ListPunishmentRules --policy_id={policy_id}
• Note: Must also enable the module: hcloud WAF UpdatePolicy --policy_id={policy_id} --options.followed_action=true

5j. Anti-Leakage Rule — Prevent Sensitive Data Exposure

bash

hcloud WAF CreateAntileakageRule   --policy_id={policy_id} \
  --category={category} \
  --contents.1={content_value} \
  --url={protected_url} \
  --action.category=block \
  --description={rule_description}

Parameters (verified via --help):

• --category: code (HTTP status code) or sensitive (sensitive information)
• --contents.N:
  • For code: HTTP status codes — 400, 401, 402, 403, 404, 405, 500, 501, 502, 503, 504, 507
  • For sensitive: phone (phone number), id_card (ID card), email
• --url: URL path to apply the rule
• --action.category: block (filter) or log (record only)
• Verify: hcloud WAF ListAntileakageRules --policy_id={policy_id} --page=1 --pagesize=10
• Note: Must also enable the module: hcloud WAF UpdatePolicy --policy_id={policy_id} --options.antileakage=true

5k. Enable/Disable Built-in Protection Modules

Use UpdatePolicy with --options.* to toggle built-in protection modules:

bash

# View current module status
hcloud WAF ShowPolicy --policy_id={policy_id}

# Enable webshell detection
hcloud WAF UpdatePolicy   --policy_id={policy_id} \
  --options.webshell=true

# Enable anti-tamper module
hcloud WAF UpdatePolicy   --policy_id={policy_id} \
  --options.antitamper=true

# Enable anticrawler module
hcloud WAF UpdatePolicy   --policy_id={policy_id} \
  --options.anticrawler=true

# Enable attack punishment module
hcloud WAF UpdatePolicy   --policy_id={policy_id} \
  --options.followed_action=true

# Enable anti-leakage module
hcloud WAF UpdatePolicy   --policy_id={policy_id} \
  --options.antileakage=true

# Enable scanner detection (crawler_scanner)
hcloud WAF UpdatePolicy   --policy_id={policy_id} \
  --options.crawler_scanner=true

# Enable script crawler detection
hcloud WAF UpdatePolicy   --policy_id={policy_id} \
  --options.crawler_script=true

Full list of --options.* parameters (verified via UpdatePolicy --help):

Parameter	Description
--options.webattack	Basic web protection (sqli, xss, cmdi, lfi, rfi, vuln)
--options.webshell	Webshell detection
--options.cc	CC protection rules
--options.custom	Precise access control
--options.whiteblackip	IP blacklist/whitelist
--options.geoip	Geo access control
--options.antitamper	Anti-tamper
--options.anticrawler	Anti-crawler (JS challenge)
--options.antileakage	Anti-leakage (sensitive data)
--options.followed_action	Attack punishment
--options.privacy	Privacy masking
--options.ignore	Global whitelist (false positive bypass)
--options.crawler_scanner	Scanner detection
--options.crawler_script	Script crawler detection
--options.crawler_engine	Search engine crawler
--options.crawler_other	Other crawler detection
--options.bot_enable	BOT management master switch
--options.modulex_enabled	Intelligent CC (modulex, beta)

5l. Enable/Disable Single Rule by Status

Toggle individual rules on/off without deleting them:

bash

hcloud WAF UpdatePolicyRuleStatus   --policy_id={policy_id} \
  --rule_id={rule_id} \
  --rule_type={rule_type} \
  --status={0|1}

Parameters (verified via --help):

• --rule_type: cc, custom, whiteblackip, geoip, ip-reputation, antitamper, antileakage, ignore, privacy
• --status: 0 = disable, 1 = enable
• Note: Useful for temporary rule disabling during troubleshooting

KooCLI Parameter Pitfalls

Pitfall	❌ Wrong	✅ Correct
Nested params	--action=block	--action.category=block
Header field name	--conditions.1.field=UA	--conditions.1.index=User-Agent
Immediate effect	--status=1	--time=false
mode conflict	--mode=1 (direct)	--cli-jsonInput=file.json
Array index	--conditions.0.xxx	--conditions.1.xxx (starts from 1)
Singular/plural	ListWhiteblackipRules	ListWhiteblackipRule
Case sensitivity	ShowWhiteblackipRule	ShowWhiteBlackIpRule (capital B)

Step 6: Present Analysis Report

Output a structured report containing:

1. Summary — Total events, time range, top findings
2. Attack Type Breakdown — Counts and percentages
3. Top Attacking IPs — With geographic info
4. Most Targeted Assets — Domains and URLs
5. Time Distribution — Peak periods
6. Recommended Rules — Prioritized list with copy-paste ready hcloud commands (DO NOT execute them)

Report Delivery Format:

markdown

## 🛡️ Protection Recommendations

### Priority 1: [Rule Name]
**Purpose**: [What this rule does]
**Expected Effect**: [Impact on security posture]

**Command to execute** (copy and run in your terminal):
```bash
hcloud WAF CreateXxxRule --policy_id={policy_id} ...

Verification command (after you execute the above):

bash

hcloud WAF ListXxxRule --policy_id={policy_id}

text

**Important**: After presenting the report with all recommended commands, **STOP**. Do not ask "should I execute these?" or attempt to run them. The user will decide when and whether to execute the commands.

## Core Commands

| Command | Purpose |
|---------|---------|
| `hcloud WAF ListEvent` | Query attack event list with multi-dimensional filtering, sorting, and pagination |
| `hcloud WAF ShowEvent` | View detailed information of a single attack event |
| `hcloud WAF ListAttackActionTypes --from=<ms_timestamp> --to=<ms_timestamp>` | Aggregate event counts by protection action type (block/log/pass/etc.) within the specified time range |

### ListEvent Key Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `--recent` | string | Quick time range: `today`, `yesterday`, `3days`, `1week`, `1month` |
| `--from` / `--to` | integer | Custom time range (millisecond timestamps), max 30 days |
| `--attacks.N` | array | Filter by attack type: `sqli`, `xss`, `cc`, `botm`, `cmdi`, `rfi`, `rce`, `lfi`, `ptr`, `webshell`, `vuln`, `robot`, `iprank`, `antitamper`, `anticrawler`, `followed_action`, `antileakage`, `antiscan_high_freq_scan`, `custom_whiteblackip`, `custom_geoip`, `custom_custom`, `advanced_bot`, etc. Run `ListAttackActionTypes` for full list |
| `--actions.N` | array | Filter by action: `block`, `pass`, `log`, `captcha`, `cache`, `mask`, `js_challenge`, `advanced_captcha`, `abort_response`, `desensitize` |
| `--sip` | string | Filter by source IP (supports fuzzy match with `--query_mode=include`) |
| `--sips.N` | array | Filter by multiple source IPs |
| `--domain` | string | Filter by domain (fuzzy match) |
| `--url` | string | Filter by URL (supports fuzzy match with `--query_mode=include`) |
| `--urls.N` | array | Filter by URL list |
| `--query_mode` | string | Query mode: `equal` (exact match) or `include` (fuzzy match, default). Affects `--sip` and `--url` only |
| `--ip_countries.N` | array | Filter by client IP country |
| `--ip_regions.N` | array | Filter by client IP province (China only) |
| `--rules.N` | array | Filter by matched rule ID |
| `--sort_key` | string | Sort field: `attack_time`, `sort_ip`, `host`, `geo_str`, `component`, `rule`, `attack` |
| `--sort_direction` | string | `desc` (default) or `asc` |
| `--page` / `--pagesize` | integer | Pagination controls |
| `--payload` | string | Search by malicious payload content |
| `--nattacks.N` | array | Exclude attack type (opposite of `--attacks.N`) |
| `--enterprise_project_id` | string | Enterprise project filter |

## Parameter Confirmation

| Parameter | Required | Description | Example |
|-----------|----------|-------------|---------|
| `{time_range}` | No | Analysis time window (default: `today`) | `1week` |
| `{domain}` | No | Target domain filter | `example.com` |
| `{attack_type}` | No | Attack type filter | `sqli` |
| `{source_ip}` | No | Source IP filter | `203.0.113.1` |

## Reference Documents

- `references/iam-policies.md` — Least-privilege IAM policies for WAF log querying
- `references/cli-installation-guide.md` — hcloud CLI installation and configuration
- `references/verification-method.md` — How to verify the skill is working correctly
- `references/dataflow-diagram.md` — Mermaid data flow diagram
- `references/acceptance-criteria.md` — Acceptance criteria for analysis output quality
- `references/rule-recommendation-guide.md` — Detailed attack-to-rule mapping logic

## KooCLI Command Format Standard

```bash
hcloud <Service> <Operation> [--key=value ...]

Feature	Description	Example
Service name	Exact KooCLI service name, uppercase	WAF
Operation name	PascalCase	ListEvent, ShowEvent
Simple parameter	--key=value	--sip=203.0.113.1
Indexed parameter	--key.N=value	--attacks.1=sqli --attacks.2=xss
Region	Use default configured region; do NOT specify --cli-region	hcloud WAF ListEvent --recent=today