Build WAF Rulesets at Instance Level with ESA API - Edge Security Acceleration - Alibaba Cloud - Edge Security Acceleration

Operation description

This API operation allows you to create a WAF ruleset for a specified instance.
InstanceId is a required parameter that specifies the instance for which you want to create the ruleset.
The Phase parameter defines the phase in which the ruleset is applied, such as custom rules or rate limiting.
Name and Expression are required parameters that specify the ruleset name and the match expression.
The optional Description parameter provides a text description of the ruleset function or purpose.
Status controls whether the ruleset takes effect immediately (on) or is disabled (off).
Use the Rules parameter to configure a detailed list of rules. Each rule contains properties such as name, position, expression, and action.
A successful response returns the unique identifier Id of the newly created ruleset and the RuleIds list of all associated rule IDs.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

esa:CreateUserWafRuleset

none

*All Resource

*

None

Request syntax

POST / HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
InstanceId	string	Yes	The instance ID.	esa-site-ads11w
Phase	string	Yes	The phase to which the WAF ruleset belongs. Valid values: http_whitelist: whitelist rules http_custom: custom rules http_managed: managed rules http_anti_scan: scan protection rules http_ratelimit: rate limiting rules Note Note: The supported fields (Expression match fields, Action values, and others) vary by phase. For more information, refer to the rule configuration documentation for the corresponding phase.	http_custom
Name	string	Yes	The name of the WAF ruleset. Naming suggestion: Use a combination of letters, digits, and underscores for easy reference. The specific character set, maximum length, and uniqueness constraints are subject to the WAF ruleset service naming conventions.	example
Description	string	No	The description of the WAF ruleset.	this is a test ruleset.
Status	string	Yes	The status of the WAF ruleset. Valid values: on: Enabled. The rules in the ruleset participate in matching and blocking. off: Disabled. The ruleset is retained but does not participate in matching. Note The complete set of valid values is subject to the server-side enum.	on
Expression	string	Yes	The match expression of the WAF ruleset. Rules in this ruleset are evaluated only when a request matches this expression. Examples: `http.host eq "example.com"` — Only requests with the host example.com enter this ruleset. `starts_with(http.uri.path, "/api/")` — Only requests with the /api/ prefix enter this ruleset. Note The complete expression syntax and available field set are subject to the server-side wirefilter dialect.	ip.src == 1.1.1.1
Shared	WafBatchRuleShared	No	The shared fields across multiple rules in this ruleset, such as a unified Action or Name prefix. Note The field structure is subject to the `WafBatchRuleShared` data structure. If you do not need to share properties, you can leave this parameter empty.
Rules	array	No	The list of rule configurations in the WAF ruleset. Each element corresponds to a rule. The field structure of each rule is subject to the `WafRuleConfig` data structure, which includes Expression, Action, Name, and other fields.
	WafRuleConfig	No	The rule configuration in the WAF ruleset.

Response elements

Element	Type	Description	Example
	object	Schema of Response
RequestId	string	The request ID.	15C66C7B-671A-4297-9187-2C4477247A74
Id	integer	The ID of the WAF ruleset.	665d3af3621bccf3fe29e1a4
RuleIds	array	The list of rule IDs in the WAF ruleset.
	integer	The rule ID in the WAF ruleset.	87570

Examples

Success response

JSON format

{
  "RequestId": "15C66C7B-671A-4297-9187-2C4477247A74",
  "Id": 0,
  "RuleIds": [
    87570
  ]
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidParameter	The specified parameter is invalid.	The specified parameter is invalid.
400	InstanceNotExist	The instance does not exist. Check whether the specified instance ID is correct or whether the instance belongs to your account.	The instance does not exist. Check whether the specified instance ID is correct or whether the instance belongs to your account.
400	InternalException	Failed to call the service. Try again later or contact technical support.	Failed to call the service. Try again later or contact technical support.
403	Rule.Config.Noncompliance	The specified rule configuration does not meet the compliance requirements.Check and adjust your configurations.	The specified rule configuration does not meet the compliance requirements.Check and adjust your configurations.
403	Rule.Config.Malformed	The format of the rule configuration is invalid.Check the configuration for syntax errors or structural inconsistencies and correct them to meet the requirements.	The format of the rule configuration is invalid.Check the configuration for syntax errors or structural inconsistencies and correct them to meet the requirements.
403	%s.NotSupport	The specified resource type %s is not supported.	The specified resource type is not supported. To use this type of resource, please contact us.
403	%s.OverQuota	The quantity of %s exceeds the quota.	The amount of this resource exceeds the quota. If you need to apply for more quota, please contact us.
403	%s.WrongValueMatched	The value of specified parameter %s can not pass the matching check.	The value of the specified parameter can not pass the matching check. If you determine that you need to use this parameter value, please contact us.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.