# alibabacloud-waf-lua-extension-dev

Adopt this skill: https://proskills.md/skills/other/alibabacloud-waf-lua-extension-dev

Page: https://proskills.md/skills/other/alibabacloud-waf-lua-extension-dev
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8068

```text
WAF Extension Plugin (Lua) Development & Review

Alibaba Cloud WAF 3.0 "Extension Plugins" allow custom Lua scripts to hook into the request processing pipeline and implement security logic beyond the native rules.

Official documentation: https://help.aliyun.com/zh/waf/web-application-firewall-3-0/user-guide/extensions

This feature is supported only on the subscription Enterprise/Flagship editions and the pay-as-you-go edition, and it is a paid service. After a plugin is created, it takes effect only when it is referenced by a "Custom Rules" protection template.

Key Constraints (Read First)

ConstraintImpact
No OpenAPI / CLIExtension plugins can only be configured in the console; there is no corresponding aliyun
 command or SDK interface. Do not try to create/query plugins via CLI, and there is no capability to import local files
Block-only actionThe "plugin action parameter" in debug testing currently supports only block mode; punish()
 means blocking the request
No loggingprint
/warn
 have no effect; there is no log output mechanism inside scripts. The only feedback is the execution-result panel of "Run Debug" in the console
Association required to take effectAfter a plugin is created, it must be referenced by a "Custom Rules" protection template; the plugin logic executes only when the rule matches

Plugin Composition

An extension plugin consists of four parts in the console. This Skill uses a set of local project files to mirror them, for version control and review — but this file structure is a convention of this Skill; the platform does not consume these files, and they must ultimately be pasted into the console manually:

Console ConfigurationLocal Project FileDescription
Basic information (name/description)plugin.json
Plugin metadata
Plugin codeplugin.lua
Custom Lua script
Parameter definitionsparams.json
Predefined parameters (including type, value, KMS reference)
Debug teststests/*.json
Simulated traffic and expected action results

Workflow

1. Create

Clarify the protection goal: what kind of requests to block, and which request fields to decide on.

Create the plugin directory <plugin-name>/
 in the workspace and generate the four file types (see "Plugin Project Structure").

Write plugin.lua
: read the request → evaluate → call aliwaf.func.punish()
 on a match.

Extract hard-coded values in the script (secrets, thresholds, whitelists, etc.) into params.xxx
 and declare them in params.json
.

Write at least one tests/*.json
 case for each key scenario (one hit + one pass).

Paste the four configuration blocks into the console → enter the traffic parameters one by one → click "Run Debug", compare the results against the expectations in tests/*.json
, and associate the plugin with the custom rule only after all cases pass.

2. Edit

Read the existing plugin.lua
 and params.json
 first; understand the current logic before changing it.

When changing logic, maintain the parameter definitions and test cases at the same time, so the script never references an undeclared params.xxx
.

Re-run the review checklist after the change.

3. Review

Check item by item against the Code Review Checklist. The review output should indicate: matched items, risk level, specific line numbers/APIs, and fix suggestions.

Plugin Project Structure

text<plugin-name>/
├── plugin.json      # Basic information: name, description
├── plugin.lua       # Custom Lua script
├── params.json      # Parameter definitions (array)
└── tests/           # Debug test cases
    ├── hit.json     # Expected hit (punish)
    └── pass.json    # Expected pass

Fields of a single parameter in params.json
: name
 (corresponds to params.xxx
 in the script), type
 (string
/number
/boolean
/json_object
/json_array
), description
, and either value
 or kms_secret_name
 (one of the two).

Fields of tests/*.json
: traffic
 (method
/uri
/query
/args
/headers
/cookies
/request_body
), expect_punish
 (boolean). The console's traffic parameters are flat key-value pairs; the nested fields above are the local record format and must be mapped manually when entered.

See references/examples.md for complete templates.

Runtime Environment

The standard library whitelist and prohibition list below, as well as the static-check hints in "Common Errors", come from the platform implementation and are not fully covered in the official documentation.

Available Lua Standard Libraries

base
: core basic functions (globally available)

table
, string
, math
, utf8

cjson
: JSON encoding/decoding (safe mode)

bit32
: 32-bit bitwise operations

pb
: Protobuf encoding/decoding

Unavailable Standard Libraries

Accessing the following libraries raises an error: os
, io
, package
, debug
, coroutine

Explicitly Disabled Functions

load
 / loadstring
, dofile
, loadfile
, collectgarbage

Coding Conventions

No global variables or global functions — use local
 everywhere

No access to system-level globals — os
, io
, package
, debug

No require

Only call APIs exported by aliwaf

Avoid infinite loops and long-running operations — the execution timeout is 2ms, and a timeout at runtime forcibly skips the current execution, meaning the protection logic silently fails and the request passes through.

Make the failure strategy explicit — on parse failure or missing parameters, explicitly choose pass or block; do not leave an implicit default branch.

Business API Overview

The platform exposes APIs only under the aliwaf
 namespace; full signatures and descriptions are in references/lua-api-reference.md.

aliwaf.req.*
 — request reading (method, URI, domain, query, args, cookies, headers, body). Returns an empty string ""
 when a field does not exist.

aliwaf.util.*
 — encoding/hashing/crypto helpers (base64, hex, URI escape, md5, sha256, crc32, evp encrypt/decrypt, ES256 sign/verify, millisecond timestamp). Returns ""
 on failure (except crc32
 / get_current_ms
 / es256_verify
).

aliwaf.func.*
 — business helpers: punish()
 applies the preconfigured action (currently block only), plus the body-reception functions used in the flow below.

Body handling must follow the three-step flow — (1) if is_last_fragment_arrived()
 is false, call wait_request_body()
 and return so the framework re-executes the script after the body fully arrives; (2) if is_request_body_discarded()
 is true, the body was truncated over the size limit — give up the action; (3) only then call get_body()
. Missing any step may read an incomplete or empty body. The complete code pattern is in references/examples.md ("Standard Pattern for Request Body Handling").

params — Predefined Parameters

Scripts reference predefined parameters from the plugin configuration via params.xxx
. Strings, numbers, booleans, and JSON Object/Array are supported. An undeclared parameter is nil
 and must be validated first — see "Parameter Pitfall".

Parameter Pitfall

params.xxx
 is nil
 when it is not declared in the parameter definitions. If you write if token ~= params.token then punish() end
 directly, a missing parameter makes every request match the block condition, causing site-wide false positives. Always validate the parameter itself before use:

lualocal expected = params.token
if expected == nil then
  return                     -- Pass through when the configuration is missing, to avoid blocking the entire site
end
if aliwaf.req.get_arg("token") ~= expected then
  aliwaf.func.punish()
  return
end

Code Review Checklist

Security

 No global variable/function definitions (all local
)

 No access to os
, io
, package
, debug

 No calls to load
, loadstring
, dofile
, loadfile
, collectgarbage

 No use of require

 No hard-coded sensitive information: secrets/credentials go through params
 + KMS credentials and do not appear in comments

API Calls

 The trigger condition of punish()
 is correct and can never become constantly true due to missing parameters

 Only aliwaf.req.*
, aliwaf.util.*
, aliwaf.func.*
 are called

 The get_body()
 flow is correct

Parame
```
