alibabacloud-cfw-ips-event

What this skill does

# IPS Alert Event Analysis

> **Skill Scope Notes:**
> - This skill is designed to use Aliyun CLI `cloudfw` commands as its primary data source.
> - It does not depend on local log files, SIEM exports, or direct host access.
> - It does not require SSH or direct connections to server IPs.
> - For IP-focused investigations, prefer `DescribeRiskEventGroup` with `--SrcIP` or `--DstIP`.

## Scenario Description

Query and analyze IPS (Intrusion Prevention System) security events and alerts detected by Alibaba Cloud Firewall, helping quickly locate threats and provide remediation recommendations.

**Architecture**: `Cloud Firewall Service → IPS Engine → Event Detection + Attack Analysis + Protection Configuration`

**Capability Level**: Query (read-only)

**Data Source**: All data is obtained **exclusively** through Aliyun CLI commands (`aliyun cloudfw ...`). No log files, no databases, no server access, no SIEM — just CLI commands. **Do NOT search the workspace for files. Do NOT ask the user for anything. Just run the commands.**

**Core Capabilities**:
1. **Alert Overview** — IPS alert statistics including attack counts, block counts, and severity distribution
2. **Alert Event Details** — Detailed list of IPS alert events with source/destination, attack type, and handling status
3. **Top Attacked Assets** — Ranking of most attacked assets
4. **Attack Type Analysis** — Distribution of attack types and applications
5. **IPS Configuration Status** — Current IPS run mode, rule switches, and rule library version
6. **Remediation Recommendations** — Prioritized security recommendations based on alert data

---

## Prerequisites

> **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` 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.

**[MUST] CLI User-Agent** — Every `aliyun` CLI command invocation must include:
`--user-agent AlibabaCloud-Agent-Skills/alibabacloud-cfw-ips-event`

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-cfw-ips-event"
```
**[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, print, cat, or display AK/SK values under any circumstances
> - **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

> **[MUST] RAM Permission Pre-check:** Before executing any commands, verify the current user has the required permissions.
> 1. Use `ram-permission-diagnose` skill to get current user's permissions
> 2. Compare against `references/ram-policies.md`
> 3. Abort and prompt user if any permission is missing

Minimum required permissions — see [references/ram-policies.md](references/ram-policies.md) for full policy JSON.

Alternatively, attach the system policy: **AliyunYundunCloudFirewallReadOnlyAccess**

---

## Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call,
> check if the user has already provided necessary parameters in their request.
> - If the user's request **explicitly mentions** a parameter value (e.g., "check IPS alerts for the last 7 days" means use 7-day time range), use that value directly **without asking for confirmation**.
> - For optional parameters with sensible defaults (PageSize, CurrentPage, time ranges), use the defaults without asking unless the user indicates otherwise.
> - Do NOT re-ask for parameters that the user has clearly stated.

| Parameter Name | Required/Optional | Description | Default Value |
|---------------|-------------------|-------------|---------------|
| RegionId | Required | Alibaba Cloud region for Cloud Firewall. Only two values: `cn-hangzhou` for mainland China, `ap-southeast-1` for Hong Kong/overseas. | `cn-hangzhou` (use directly without asking; only use `ap-southeast-1` if user explicitly mentions Hong Kong/overseas/international) |
| StartTime | Required for most APIs | Start time for alert queries (Unix timestamp in seconds) | 24 hours ago for "today", 7 days ago for "recently"/"this week" (use without asking) |
| EndTime | Required for most APIs | End time for alert queries (Unix timestamp in seconds) | Current time (use without asking) |
| PageSize | Optional | Number of items per page for paginated APIs | 50 (use without asking) |
| CurrentPage | Optional | Page number for paginated APIs | 1 (use without asking) |

## Input Validation (MUST)

Treat all Agent-provided inputs as untrusted. Validate before building CLI commands.

Validation rules:
- `RegionId`: must be exactly one of `cn-hangzhou` or `ap-southeast-1`.
- `StartTime` / `EndTime`: must be 10-digit Unix seconds (`^[0-9]{10}$`), and `StartTime < EndTime`.
- `CurrentPage`: positive integer (`>=1`).
- `PageSize`: integer in range `1-100`.
- `SrcIP` / `DstIP`: must be valid IPv4 format only (`a.b.c.d`, each octet `0-255`).

Safe command construction rules:
- Never concatenate raw user text into shell commands.
- Only pass validated values into fixed CLI flag templates.
- If any validation fails, stop execution and return a clear validation error.

---

## Error Handling and Workflow Resilience

> **CRITICAL: Continue on failure.** If any individual API call fails, do NOT stop the entire workflow.
> Log the error for that step, then proceed to the next step. Present whatever data was successfully collected.

### Retry Logic

For each API call:
1. If the call fails with a **transient error** (network timeout, throttling `Throttling.User`, `ServiceUnavailable`, HTTP 500/502/503), retry up to **2 times** with a 3-second delay between retries.
2. If the call fails with a **permanent error** (e.g., `InvalidParameter`, `Forbidden`, `InvalidAccessKeyId`), do NOT retry. Record the error and move on.
3. After all retries are exhausted, record "[Step X] Failed: {error message}" and continue to the next step.

### Timeout Policy (MUST)

Before any API call, explicitly set CLI timeouts:

```bash
export ALIBABA_CLOUD_CONNECT_TIMEOUT=10
export ALIBABA_CLOUD_READ_TIMEOUT=30
```

- `ALIBABA_CLOUD_CONNECT_TIMEOUT=10`: fast fail for connect timeout.
- `ALIBABA_CLOUD_READ_TIMEOUT=30`: prevent long-running hangs per request.
- Timeout errors are treated as transient errors and follow retry logic.

### No Alert Events