alibabacloud-waf-security-monitor

What this skill does

# WAF Security Product Inspection & Monitoring

This skill performs comprehensive security inspection for Alibaba Cloud WAF 3.0 instances across both business regions (cn-hangzhou and ap-southeast-1). It covers asset inventory (CNAME domains, cloud product access, SSL certificates), attack event statistics (Bot/CC via bot_manager templates), traffic analysis (QPS/bandwidth with period-over-period), HTTP status code anomaly detection (4xx/5xx), and protection status checks (alarms, DDoS, pause status). Outputs a structured inspection report following a standardized template.

**Architecture**: `waf-openapi (WAF 3.0) -> aliyun CLI plugin mode (kebab-case) -> Dual-Region Inspection -> Structured Report`

## Pre-checks

**Pre-check: Aliyun CLI >= 3.3.3 required**
> Run `aliyun version` to verify >= 3.3.3. If not installed or version too low,
> run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to install/update,
> or see [references/cli-installation-guide.md](references/cli-installation-guide.md) for installation instructions.

**Pre-check: Aliyun CLI plugin update required**
> [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation.
> [MUST] run `aliyun plugin update` to ensure that any existing plugins are always up-to-date.

**Pre-check: Script dependencies**
> Scripts in `scripts/` require Python 3 (standard library only, no third-party packages).
> See `scripts/requirements.txt` for details.

## Observability Initialization (MUST run before any command)

```bash
if [ -z "$ALICLOUD_SKILL_SESSION_ID" ]; then
  export ALICLOUD_SKILL_SESSION_ID="$(cat /proc/sys/kernel/random/uuid 2>/dev/null | tr -d '-' || uuidgen | tr -d '-' | tr 'A-F' 'a-f')"
fi
export ALICLOUD_SKILL_INVOCATION_ID="$(cat /proc/sys/kernel/random/uuid 2>/dev/null | tr -d '-' | head -c 16 || uuidgen | tr -d '-' | tr 'A-F' 'a-f' | head -c 16)"
export ALIBABA_CLOUD_USER_AGENT="AlibabaCloud-Agent-Skills/alibabacloud-waf-security-monitor/s-${ALICLOUD_SKILL_SESSION_ID}/i-${ALICLOUD_SKILL_INVOCATION_ID}"
export ALIBABA_CLOUD_OTEL_TRACEPARENT="00-${ALICLOUD_SKILL_SESSION_ID}-${ALICLOUD_SKILL_INVOCATION_ID}-01"
export ALIBABA_CLOUD_OTEL_BAGGAGE="skill=alibabacloud-waf-security-monitor,source=agent-skills"
```

Do not skip, alter formats, or place PII in baggage.

## AI-Mode Lifecycle

> At the **start** of the Core Workflow (before any CLI invocation):
> **[MUST] Enable AI-Mode** -- AI-mode is required for Agent Skill execution.
> Run the following commands before any CLI invocation:
> ```bash
> aliyun configure ai-mode enable
> aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-waf-security-monitor"
> ```
> **[MUST] Disable AI-Mode at EVERY exit point** -- Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed.
> AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.
> ```bash
> aliyun configure ai-mode disable
> ```

## Authentication

> **Pre-check: Alibaba Cloud Credentials Required**
>
> **Security Rules:**
> - **NEVER** read, echo, or print AK/SK values (e.g., `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` is FORBIDDEN)
> - **NEVER** ask the user to input AK/SK directly in the conversation or command line
> - **NEVER** use `aliyun configure set` with literal credential values
> - **ONLY** use `aliyun configure list` to check credential status
>
> ```bash
> aliyun configure list
> ```
> Check the output for a valid profile (AK, STS, or OAuth identity).
>
> **If no valid profile exists, STOP here.**
> 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak)
> 2. Configure credentials **outside of this session** (via `aliyun configure` in terminal or environment variables in shell profile)
> 3. Return and re-run after `aliyun configure list` shows a valid profile

## RAM Policy

All permissions are **read-only** (Describe/List only). See [references/ram-policies.md](references/ram-policies.md) for the full policy JSON.

| Category | API Actions | Type |
|----------|------------|------|
| Asset Management | DescribeInstance, DescribeDomains, DescribeCloudResourceList | Read-only |
| Attack Events | DescribeDefenseRuleStatistics, DescribeApisecEvents | Read-only |
| Traffic Analysis | DescribeFlowChart, DescribePeakTrend, DescribeFlowTopResource, DescribeFlowTopUrl | Read-only |
| Status Codes | DescribeResponseCodeTrendGraph | Read-only |
| Protection Status | DescribePauseProtectionStatus, DescribeAlarmList, DescribeDDoSStatus | Read-only |
| Certificates | DescribeCerts | Read-only |
| Defense | DescribeDefenseTemplates, DescribeMajorProtectionBlackIps | Read-only |

> **[MUST] Permission Failure Handling:** When any command or API call fails due to permission errors at any point during execution, follow this process:
> 1. Read `references/ram-policies.md` to get the full list of permissions required by this SKILL
> 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions
> 3. Pause and wait until the user confirms that the required permissions have been granted

## Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** -- Before executing any command or API call,
> ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks,
> passwords, domain names, resource specifications, etc.) MUST be confirmed with the
> user. Do NOT assume or use default values without explicit user approval.

| Parameter | Required/Optional | Description | Default Value |
|-----------|-------------------|-------------|---------------|
| Time range | Optional | Inspection time window | Last 24 hours |
| Comparison mode | Optional | Period-over-period baseline | Day-over-day |
| Region scope | Optional | Which WAF regions to inspect | Both cn-hangzhou and ap-southeast-1 |

## Core Inspection Workflow

> **Execution guidance**:
> - **Region rules**: WAF 3.0 has only two business regions: `cn-hangzhou` and `ap-southeast-1`. Query both independently -- each has its own InstanceId. Use `--region` flag only (`--region-id` causes "unknown flag" errors, `--biz-region-id` does not route correctly). See [API Reference](references/api-reference.md).
> - **User-Agent per command**: Every `aliyun waf-openapi` CLI call MUST include `--user-agent "$ALIBABA_CLOUD_USER_AGENT"` flag (set during Observability Initialization).
> - **Same shell session for Phase 1-2-3-4**: Variables like `REGION_INSTANCES`, `BASE_START`, `EFFECTIVE_BOT_ID` are shared across phases. Splitting into separate shells loses these values and causes undefined-variable errors.
> - Run each code block via bash. Do not just describe/plan.
> - Use `RESULT` as the variable name for API call outputs, because the verification script (`scripts/verify_output.py`) and the log aggregation pattern depend on consistent variable naming.
> - Append every `aliyun waf-openapi` output to `/tmp/waf_skill_output.log` -- the verification script in Phase 4.7 parses this single file for completeness checks.
> - On error: report to user and continue. On empty result: report "0" -- do not omit the section.

### Phase 1-2-3: Environment, Assets & Timestamps (SINGLE BLOCK)

```bash
# === Phase 1: Heartbeat ===
HEARTBEAT_CN=$(aliyun waf-openapi describe-instance \
  --region cn-hangzhou --user-agent "$ALIBABA_CLOUD_USER_AGENT" 2>&1)
echo "$HEARTBEAT_CN" > /tmp/waf_skill_output.log
HEARTBEAT_INTL=$(aliyun waf-openapi describe-instance \
  --region ap-southeast-1 --user-agent "$ALIBABA_CLOUD_USER_AGENT" 2>&1)
echo "$HEARTBEAT_INTL" >> /tmp/waf_skill_output.log

# Setup
aliyun version
aliyun configure set --auto-plugin-install true --connect-timeout 10 --read-timeout 30 2>/dev/null || true
aliyun plugin update 2>/dev/null || tr