WAF Protection Config Backup#

Export and backup all WAF protection configurations as Excel workbooks (.xlsx) for disaster recovery, auditing, configuration migration, or compliance review. Each data module is saved as a separate sheet within the workbook.

Architecture#

text

Alibaba Cloud WAF Instance
├── WAF 3.0 (API 2021-10-01)
│   ├── Defense Resources
│   ├── Defense Resource Groups
│   ├── Defense Templates → Rules → Resource Bindings
│   │   └── 20 DefenseScene types (waf_group, cc, custom_acl, ip_blacklist, ...)
│   ├── Major Protection Black IPs
│   └── Address Books
│
└── WAF 2.0 (API 2019-09-10)
    └── Per-Domain Protection Rules
        └── 16 DefenseType types (ac_custom, whitelist, tamperproof, ...)
            ├── Rules / Status / Mode
            └── Domain Rule Group

Regions: cn-hangzhou (China) | ap-southeast-1 (International)
Output: waf3-{region}.xlsx (8 sheets) | waf2-{region}.xlsx (5 sheets)

Installation#

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 detailed 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: Python openpyxl library required

Excel (.xlsx) output requires the openpyxl Python library.

bash

pip3 install openpyxl

Environment Variables#

No environment variables are required. All parameters are provided via CLI flags or confirmed interactively.

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
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#

This skill requires read-only permissions for WAF APIs. See references/ram-policies.md for the full IAM policy JSON.

ActionWAF VersionDescriptionwaf:DescribeInstance3.0Query instance infowaf:DescribeDefenseResources3.0List defense resourceswaf:DescribeDefenseResourceGroups3.0List resource groupswaf:DescribeDefenseTemplates3.0List defense templateswaf:DescribeDefenseRules3.0List defense ruleswaf:DescribeTemplateResources3.0List template-resource bindingswaf:DescribeMajorProtectionBlackIps3.0List major protection black IPswaf:DescribeAddresses3.0List address book entrieswaf:DescribeInstanceInfo2.0Query instance infowaf:DescribeDomainNames2.0List domainswaf:DescribeProtectionModuleRules2.0List protection ruleswaf:DescribeProtectionModuleStatus2.0Query module statuswaf:DescribeProtectionModuleMode2.0Query module modewaf:DescribeDomainRuleGroup2.0Query domain rule group

[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

Observability (MUST follow for every aliyun command)#

Upon loading this skill, generate a random session ID (32-char lowercase hex string) once for the entire session. Use it as {session-id} below.

Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag. Local utility commands (e.g. configure, plugin, version) do not support this flag and should be excluded.

text

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-protectionconfig-backup/{session-id}

Example (assuming session-id is a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6):

bash

aliyun waf-openapi describe-instance --region cn-hangzhou --biz-region-id cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-protectionconfig-backup/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Do not skip, alter the format, or omit --user-agent on any aliyun API command invocation.

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.

ParameterRequiredDescriptionDefaultREGIONSOptionalRegions to scancn-hangzhou,ap-southeast-1``BACKUP_DIROptionalOutput directory path./waf-backup-{YYYYMMDD-HHmmss}``WAF_VERSIONOptionalTarget WAF version: 3.0, 2.0, or auto``auto

Core Workflow#

Phase 1: Initialize#

bash

BACKUP_DIR="./waf-backup-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"

Phase 2: Detect WAF Version (per region)#

For each region in [cn-hangzhou, ap-southeast-1]:

Try WAF 3.0:

bash

aliyun waf-openapi describe-instance \
  --region {region} \
  --biz-region-id {region} \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-protectionconfig-backup/{session-id}

If response contains a valid InstanceId → WAF 3.0 detected. Parse response and write to "instance" sheet of {BACKUP_DIR}/waf3-{region}.xlsx.

Try WAF 2.0:

bash

aliyun waf-openapi describe-instance-info \
  --api-version 2019-09-10 \
  --region {region} \
  --biz-region-id {region} \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-waf-protectionconfig-backup/{session-id}

If response contains valid instance info → WAF 2.0 detected. Parse response and write to "instance-info" sheet of {BACKUP_DIR}/waf2-{region}.xlsx.

If neither returns results, skip this region.

Phase 3: WAF 3.0 Backup#

For each region with WAF 3.0 detected, follow the detailed steps in references/waf3-backup-workflow.md:

All data is written to {BACKUP_DIR}/waf3-{region}.xlsx with each module as a separate sheet:

1. Backup Defense Resources — describe-defense-resources with --pager → sheet "defense-resources"

2. Backup Defense Resource Groups — describe-defense-resource-groups with --pager → sheet "defense-resource-groups"

3. Backup Defense Templates & Rules — Iterate all 20 DefenseScene values:

   • For each scene: list templates → for each template: get rules + resource bindings
   • Aggregate all templates into sheet "defense-templates", all rules into sheet "defense-rules", all bindings into sheet "template-resource-bindings"
   • See references/defense-scene-values.md for the full enum list

4. Backup Major Protection Black IPs — describe-major-protection-black-ips with --pager → sheet "major-protection-black-ips"

5. Backup Address Books — describe-addresses with --pager → sheet "addresses"

Phase 4: WAF 2.0 Backup#

For each region with WAF 2.0 detected, follow the detailed steps in references/waf2-backup-workflow.md:

All data is written to {BACKUP_DIR}/waf2-{region}.xlsx with each module as a separate sheet:

1. List Domains — describe-domain-names --api-version 2019-09-10 → sheet "domain-names"

2. Per-Domain Backup — For each domain, iterate all 16 DefenseType values:

   • describe-protection-module-rules → append to sheet "protection-rules"
   • describe-protection-module-status + describe-protection-module-mode → append to sheet "protection-status"
   • See references/defense-scene-values.md for the full enum list

3. Backup Domain Rule Group — describe-domain-rule-group per domain → append to sheet "domain-rule-groups"

CRITICAL: All WAF 2.0 commands MUST include --api-version 2019-09-10 and --region {region}. The --region flag sets the API endpoint region. Without it, non-China-mainland instances (e.g., ap-southeast-1) will not be found — the API defaults to cn-hangzhou and returns the China mainland instance instead.

Phase 5: Generate Manifest#

Create {BACKUP_DIR}/manifest.json containing:

• backupTime — ISO 8601 timestamp
• regions — object with per-region details (WAF version, instance ID, sheet counts)
• totalFiles — total number of backup Excel (.xlsx) files

Success Verification#

1. Verify manifest.json exists and is valid JSON
2. Compare Excel file count against totalFiles in manifest
3. Spot-check: open waf3-{region}.xlsx and verify "defense-resources" sheet has data rows (WAF 3.0), or open waf2-{region}.xlsx and verify "domain-names" sheet has data rows (WAF 2.0)
4. Validate all Excel files: find {BACKUP_DIR} -name "*.xlsx" -exec python3 -c "import openpyxl; openpyxl.load_workbook('{}'); print('OK: {}')" \;

See references/verification-method.md for detailed verification steps.

Cleanup#

This is a read-only backup skill. No cloud resources are created or modified.

To remove backup files:

bash

rm -rf {BACKUP_DIR}

Command Tables#

See references/related-commands.md for the complete CLI command reference.

CategoryKey CommandsVersionInstance Detectiondescribe-instance, describe-instance-info3.0 / 2.0Defense Resourcesdescribe-defense-resources, describe-defense-resource-groups3.0Defense Rulesdescribe-defense-templates, describe-defense-rules, describe-template-resources3.0Major Protectiondescribe-major-protection-black-ips3.0Address Bookdescribe-addresses3.0Domain Rulesdescribe-protection-module-rules, describe-protection-module-status, describe-protection-module-mode2.0Domain Rule Groupdescribe-domain-rule-group2.0

Best Practices#

1. Run backups on a regular schedule (daily or weekly) for disaster recovery
2. Store backup files in OSS with versioning enabled for long-term retention
3. Use auto version detection to support mixed WAF 2.0/3.0 environments
4. Always scan both cn-hangzhou and ap-southeast-1 to capture all instances
5. Validate backup integrity using manifest.json file counts after each run
6. Keep at least 7 days of backup history before pruning old backups
7. Use --pager flag to handle large datasets without manual pagination
8. Compress backup directories ( tar -czf) for archival storage

Reference Links#

ReferenceDescriptionreferences/cli-installation-guide.mdAliyun CLI installation guidereferences/ram-policies.mdComplete RAM policy JSONreferences/waf3-backup-workflow.mdWAF 3.0 detailed backup workflowreferences/waf2-backup-workflow.mdWAF 2.0 detailed backup workflowreferences/defense-scene-values.mdDefenseScene / DefenseType enum referencereferences/related-commands.mdComplete CLI command referencereferences/verification-method.mdBackup verification proceduresreferences/acceptance-criteria.mdTesting acceptance criteria