NGINX Documentation

Declarative Policy

policy

Field Name Type Description Allowed Values
applicationLanguage string  
  • big5
  • euc-jp
  • euc-kr
  • gb18030
  • gb2312
  • gbk
  • iso-8859-1
  • iso-8859-10
  • iso-8859-13
  • iso-8859-15
  • iso-8859-16
  • iso-8859-2
  • iso-8859-3
  • iso-8859-4
  • iso-8859-5
  • iso-8859-6
  • iso-8859-7
  • iso-8859-8
  • iso-8859-9
  • koi8-r
  • shift_jis
  • utf-8
  • windows-1250
  • windows-1251
  • windows-1252
  • windows-1253
  • windows-1255
  • windows-1256
  • windows-1257
  • windows-874
blocking-settings object    
caseInsensitive boolean    
character-sets array of objects    
cookie-settings object    
cookies array of objects    
data-guard object Data Guard feature can prevent responses from exposing sensitive information by masking the data.  
description string    
enablePassiveMode boolean    
enforcementMode string  
  • blocking
  • transparent
filetypes array of objects    
fullPath string    
general object This section includes several advanced policy configuration settings.  
header-settings object    
json-profiles array of objects    
json-validation-files array of objects    
methods array of objects    
name string    
parameters array of objects    
response-pages array of objects    
sensitive-parameters array of objects    
server-technologies array of objects    
signature-sets array of objects    
signature-settings object    
signatures array of objects    
softwareVersion string    
urls array of objects    
whitelist-ips array of objects    
xml-profiles array of objects    
xml-validation-files array of objects    

blocking-settings

Field Name Type Description Allowed Values
evasions array of objects    
http-protocols array of objects    
violations array of objects    

character-sets

Field Name Type Description Allowed Values
characterSet array of objects    
characterSetType string  
  • gwt-content
  • header
  • json-content
  • parameter-name
  • parameter-value
  • plain-text-content
  • url
  • xml-content

characterSet

Field Name Type Description Allowed Values
isAllowed boolean    
metachar string    

cookies

Field Name Type Description Allowed Values
accessibleOnlyThroughTheHttpProtocol boolean

Specifies, when true, that the system adds the HttpOnly attribute to the domain cookie’s response header. This is done to expose the cookie to only HTTP and HTTPS entities. This prevents the cookie from being modified, or intercepted even if it is not modified, by unwanted third parties that run scripts on the web page.

Notes:
  • The system does not validate that the cookie has not been modified or intercepted.
  • The feature covers all security policy cookies, both enforced and allowed, explicit and wildcard.
 
attackSignaturesCheck boolean Specifies, when true, that you want attack signatures and threat campaigns to be detected on this cookie and possibly override the security policy settings of an attack signature or threat campaign specifically for this cookie. After you enable this setting, the system displays a list of attack signatures and threat campaigns.  
enforcementType string

Specifies how the system treats this cookie.

  • enforced: Specifies that according to the security policy, this cookie may not be changed by the client.
  • allowed: Specifies that according to the security policy, this cookie may be changed by the client. The system ignores this cookie.
  • allow
  • enforce
insertSameSiteAttribute string

The introduction of the SameSite http attribute (defined in [RFC6265bis](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00)) allows you to declare if your cookie should be restricted to a first-party or same-site context. Introducing the SameSite attribute on a cookie provides three different ways of controlling same-site vs. cross-site cookie sending:

  • strict: Cookie will only be sent in a first-party context. In user terms, the cookie will only be sent if the site for the cookie matches the site currently shown in the browser’s URL bar.
  • lax: Cookies will be sent with top level navigation
  • none-value: Cookies will be sent in a third-party context.
  • lax
  • none
  • none-value
  • strict
name string

Specifies the cookie name as appearing in the http cookie header. The cookie name length is limited to 500 characters.

Names can be one of the following according to the type attribute:

  • explicit: Specifies that the cookie has a specific name and is not a wildcard entity. Type the name of a cookie exactly as you expect it to appear in the request.
  • wildcard: Specifies that any cookie that matches the listed wildcard expression should be treated according to the wildcard attributes. Type a wildcard expression that matches the expected cookie. For example, the wildcard expression cookie_12* of type Enforced specifies that the security policy should not allow modified domain cookies for all cookies which match cookie_12*.

The syntax for wildcard entities is based on shell-style wildcard characters. The list below describes the wildcard characters that you can use so that the entity name can match multiple objects.

  • *: Matches all characters
  • ?: Matches any single character
  • [abcde]: Matches exactly one of the characters listed
  • [!abcde]: Matches any character not listed
  • [a-e]: Matches exactly one character in the range
  • [!a-e]: Matches any character not in the range

Note: Wildcards do not match regular expressions. Do not use a regular expression as a wildcard.

 
securedOverHttpsConnection boolean

Specifies, when true, that the system adds the Secure attribute to the domain cookie’s response header. This is done to ensure that the cookies are returned to the server only over SSL (by using the HTTPS protocol). This prevents the cookie from being intercepted, but does not guarantee its integrity.

Notes:
  • The system does not validate that the cookie was received over SSL.
  • The feature covers all security policy cookies, both enforced and allowed, explicit and wildcard.
 
signatureOverrides array of objects Array of signature overrides. Specifies attack signatures whose security policy settings are overridden for this cookie, and which action the security policy takes when it discovers a request for this cookie that matches these attack signatures.  
type string Determines the type of the name attribute. Only when setting the type to wildcard will the special wildcard characters in the name interpreted as such.
  • explicit
  • wildcard

signatureOverrides

Field Name Type Description Allowed Values
enabled boolean Specifies, when true, that the overridden signature is enforced  
signatureId integer signature id  

data-guard

Field Name Type Description Allowed Values
creditCardNumbers boolean If true the system considers credit card numbers as sensitive data.  
enabled boolean If true the system protects sensitive data.  
enforcementMode string

Specifies the URLs for which the system enforces data guard protection.

  • ignore-urls-in-list: Specifies that the system enforces data guard protection for all URLs except for those URLs in the Enforcement Mode list.
  • enforce-urls-in-list: Specifies that the system enforces data guard protection only for those URLs in the Enforcement Mode list
  • enforce-urls-in-list
  • ignore-urls-in-list
enforcementUrls array of strings List of URLS to be enforced based on enforcement mode of data guard protection.  
maskData boolean If true the system intercepts the returned responses to mask sensitive data.  
usSocialSecurityNumbers boolean If true the system considers U.S Social Security numbers as sensitive data.  

filetypes

Field Name Type Description Allowed Values
allowed boolean Determines whether the file type is allowed or disallowed. In either of these cases the VIOL_FILETYPE violation is issued (if enabled) for an incoming request- 1. No allowed file type matched the file type of the request. 2. The file type of the request matched a disallowed file type.  
checkPostDataLength boolean Determines whether to enforce maximum length restriction for the body, a.k.a. “POST data” part of the requests that match the respective file type. The maximum length is determined by postDataLength attribute. Although named “POST data”, this applies to any content type and not restricted to POST requests, e.g. PUT requests are also checked. This attribute is relevant only to allowed file types.  
checkQueryStringLength boolean Determines whether to enforce maximum length restriction for the query string of the requests that match the respective file type. The maximum length is determined by queryStringLength attribute. This attribute is relevant only to allowed file types.  
checkRequestLength boolean Determines whether to enforce maximum length restriction for the total length of requests that match the respective file type. The maximum length is determined by requestLength attribute. This attribute is relevant only to allowed file types.  
checkUrlLength boolean Determines whether to enforce maximum length restriction for the URL of the requests that match the respective file type. The URL does not include the query string, past the &. The maximum length is determined by urlLength attribute. This attribute is relevant only to allowed file types.  
name string

Specifies the file type name as appearing in the URL extension. Names can be one of the following according to the type attribute:

  • Explicit - Specifies that the name is the liternal file extension to which the file type refers. The type attribute has to be “explicit”.
  • No Extension - Specifies the empty file type, lacking file extension. For this the reserved string no_ext should be used. The type attribute has to be “explicit”.
  • Wildcard - Specifies that any file extension that matches the wildcard expression is matched to this file type in the policy. The type attribute has to be “wildcard”.

The syntax for wildcard entities is based on shell-style wildcard characters. The list below describes the wildcard characters that you can use so that the entity name can match multiple objects.

  • *: Matches all characters
  • ?: Matches any single character
  • [abcde]: Matches exactly one of the characters listed
  • [!abcde]: Matches any character not listed
  • [a-e]: Matches exactly one character in the range
  • [!a-e]: Matches any character not in the range

Note: Wildcards do not match regular expressions. Do not use a regular expression as a wildcard.

 
postDataLength integer The maximum length in bytes of the body (POST data) of the request matching the file type. Enforced only if checkPostDataLength is set to true. If the value is exceeded then VIOL_POST_DATA_LENGTH violation is issued. This attribute is relevant only to allowed file types.  
queryStringLength integer The maximum length in bytes of the query string of the request matching the file type. Enforced only if checkQueryStringLength is set to true. If the value is exceeded then VIOL_QUERY_STRING_LENGTH violation is issued. This attribute is relevant only to allowed file types.  
requestLength integer The maximum total length in bytes of the request matching the file type. Enforced only if checkRequestLength is set to true. If the value is exceeded then VIOL_REQUEST_LENGTH violation is issued. This attribute is relevant only to allowed file types.  
responseCheck boolean Determines whether the responses to requests that match the respective file types are inspected for attack signature detection. This attribute is relevant only to allowed file types.  
type string Determines the type of the name attribute. Only when setting the type to wildcard will the special wildcard characters in the name interpreted as such.
  • explicit
  • wildcard
urlLength integer The maximum length in bytes of the URL of the request matching the file type, excluding the query string. Enforced only if checkUrlLength is set to true. If the value is exceeded then VIOL_URL_LENGTH violation is issued. This attribute is relevant only to allowed file types.  

general

Field Name Type Description Allowed Values
allowedResponseCodes array of integers You can specify which responses a security policy permits. By default, the system accepts all response codes from 100 to 399 as valid responses. Response codes from 400 to 599 are considered invalid unless added to the Allowed Response Status Codes list. By default, 400, 401, 404, 407, 417, and 503 are on the list as allowed HTTP response status codes.  
customXffHeaders array of strings If you require the system to trust a server further than one hop toward the client (the last proxy traversed), you can use the Custom XFF Headers setting to define a specific header that is inserted closer to, or at the client, that the system will trust. Additionally, if you require the system to trust a proxy server that uses a different header name than the X-Forwarded-For header name, you can add the desired header name to the Custom XFF Headers setting. When adding a custom header, the X-Forwarded-For header is not trusted anymore. In case the X-Forwarded-For header is to be trusted along with other headers, you must add it to the custom headers list.  
enforcementReadinessPeriod integer For each security policy, you can configure the number of days used as the enforcement readiness period, also called staging. Security policy entities and attack signatures remain in staging for this period of time before the system suggests that you enforce them. Staging allows you to test security policy entities and attack signatures for false positives without enforcing them. The default value of 7 days works for most situations so you typically do not need to change it.  
maskCreditCardNumbersInRequest boolean When enabled, the security policy masks credit card numbers that appear in any part of requests. The system does not mask the information in the actual requests, but rather in various logs: * Credit card numbers appearing in entity names are masked in the requests of the Requests log. * Credit card numbers appearing in entity values are masked wherever requests can be viewed: the Requests log, violation details within that log, manual learning, and reports. This setting is enabled by default, and exists in addition to masking parameters defined as containing sensitive information.  
trustXff boolean

When enabled, the system has confidence in an XFF (X-Forwarded-For) header in the request. When disabled, that the system does not have confidence in an XFF header in the request. The default setting is disabled.

Select this option if the system is deployed behind an internal or other trusted proxy. Then, the system uses the IP address that initiated the connection to the proxy instead of the internal proxy’s IP address.

Leave this option disabled if you think the HTTP header may be spoofed, or crafted, by a malicious client. With this setting disabled, if the system is deployed behind an internal proxy, the system uses the internal proxy’s IP address instead of the client’s IP address.

 

header-settings

Field Name Type Description Allowed Values
maximumHttpHeaderLength
  • integer
  • string
 
  • Integer values
  • “any”

json-profiles

Field Name Type Description Allowed Values
defenseAttributes object    
description string    
hasValidationFiles boolean    
name string  
  • Default

defenseAttributes

Field Name Type Description Allowed Values
maximumArrayLength
  • integer
  • string
 
  • Integer values
  • “any”
maximumStructureDepth
  • integer
  • string
 
  • Integer values
  • “any”
maximumTotalLengthOfJSONData
  • integer
  • string
 
  • Integer values
  • “any”
maximumValueLength
  • integer
  • string
 
  • Integer values
  • “any”
tolerateJSONParsingWarnings boolean    

json-validation-files

Field Name Type Description Allowed Values
contents string    
fileName string    
isBase64 boolean    

methods

Field Name Type Description Allowed Values
name string    

parameters

Field Name Type Description Allowed Values
attackSignaturesCheck boolean Determines whether attack signatures and threat campaigns must be detected in a parameter’s value. This attribute is relevant only for parameters with alpha-numeric or binary dataType.  
checkMetachars boolean Determines whether disallowed metacharacters must be detected in a parameter’s name. This attribute is relevant only for wildcard parameters with alpha-numeric dataType.  
level string Specifies whether the parameter is associated with a URL, a flow, or neither.
  • global
metacharsOnParameterValueCheck boolean Determines whether disallowed metacharacters must be detected in a parameter’s value. This attribute is relevant only for parameters with alpha-numeric dataType.  
name string

Specifies the name of a parameter which must be permitted in requests. Format of parameter name attribute differs depending on type attribute:

  • explicit type: name of permitted parameter in request should literally match.
  • wildcard type: name of permitted parameter in request should match wildcard expression.

The syntax for wildcard entities is based on shell-style wildcard characters. The list below describes the wildcard characters that you can use so that the entity name can match multiple objects.

  • *: Matches all characters
  • ?: Matches any single character
  • [abcde]: Matches exactly one of the characters listed
  • [!abcde]: Matches any character not listed
  • [a-e]: Matches exactly one character in the range
  • [!a-e]: Matches any character not in the range
Notes:
  • Wildcards do not match regular expressions. Do not use a regular expression as a wildcard.
  • Empty parameter name is allowed for explicit type
  • *
nameMetacharOverrides array of objects Determines metacharacters whose security policy settings are overridden for this parameter, and which action the security policy takes when it discovers a request for this parameter that has these metacharacters in the name. This attribute is relevant only if checkMetachars is set to true.  
sensitiveParameter boolean Determines whether a parameter is sensitive and must be not visible in logs nor in the user interface. Instead of actual valu,e a string of asterisks is shown for this parameter. Use it to protect sensitive user input, such as a password or a credit card number, in a validated request.  
signatureOverrides array of objects Determines attack signatures whose security policy settings are overridden for this parameter, and which action the security policy takes when it discovers a request for this parameter that matches these attack signatures. This attribute is relevant only if signatureOverrides is set to true.  
valueMetacharOverrides array of objects Determines metacharacters whose security policy settings are overridden for this parameter, and which action the security policy takes when it discovers a request for this parameter that has these metacharacters in value. This attribute is relevant only if metacharsOnParameterValueCheck is set to true.  

nameMetacharOverrides

Field Name Type Description Allowed Values
isAllowed boolean Specifies permission of metachar - when false, then character is prohibited.  
metachar string Specifies character in hexadecimal format with special allowance.  

signatureOverrides

Field Name Type Description Allowed Values
enabled boolean Specifies, when true, that the overridden signature is enforced  
signatureId integer signature id  

valueMetacharOverrides

Field Name Type Description Allowed Values
isAllowed boolean Specifies permission of metachar - when false, then character is prohibited.  
metachar string Specifies character in hexadecimal format with special allowance.  

response-pages

Field Name Type Description Allowed Values
ajaxActionType string  
  • alert-popup
  • custom
  • redirect
ajaxCustomContent string    
ajaxEnabled boolean    
ajaxPopupMessage string    
ajaxRedirectUrl string    
responseActionType string  
  • custom
  • default
  • erase-cookies
  • redirect
  • soap-fault
responseContent string    
responseHeader string    
responsePageType string  
  • ajax
  • ajax-login
  • captcha
  • captcha-fail
  • default
  • failed-login-honeypot
  • failed-login-honeypot-ajax
  • hijack
  • leaked-credentials
  • leaked-credentials-ajax
  • mobile
  • persistent-flow
  • xml
responseRedirectUrl string    

sensitive-parameters

Field Name Type Description Allowed Values
name string Name of a parameter whose values the system should consider sensitive.  

server-technologies

Field Name Type Description Allowed Values
serverTechnologyName string    

signature-sets

Field Name Type Description Allowed Values
alarm boolean    
block boolean    
name string    

signature-settings

Field Name Type Description Allowed Values
attackSignatureFalsePositiveMode string  
  • detect
  • detect-and-allow
  • disabled
minimumAccuracyForAutoAddedSignatures string  
  • high
  • low
  • medium

signatures

Field Name Type Description Allowed Values
enabled boolean Specifies, if true, that the signature is enabled on the security policy. When false, the signature is disable on the security policy.  
signatureId integer The signature id by which to access the signature.  

urls

Field Name Type Description Allowed Values
method string Unique ID of a URL with a protocol type and name. Select a Method for the URL to create an API endpoint: URL + Method.
  • *
name string

Specifies an HTTP URL that the security policy allows. The available types are:

  • Explicit: Specifies that the URL has a specific name and is not a wildcard entity. Type the name of a URL exactly as you expect it to appear in the request.
  • Wildcard: Specifies that any URL that matches the listed wildcard expression should be treated according to the wildcard attributes. Type a wildcard expression that matches the expected URL. For example, entering the wildcard expression * specifies that any URL is allowed by the security policy.

The syntax for wildcard entities is based on shell-style wildcard characters. The list below describes the wildcard characters that you can use so that the entity name can match multiple objects.

  • *: Matches all characters
  • ?: Matches any single character
  • [abcde]: Matches exactly one of the characters listed
  • [!abcde]: Matches any character not listed
  • [a-e]: Matches exactly one character in the range
  • [!a-e]: Matches any character not in the range

Note: Wildcards do not match regular expressions. Do not use a regular expression as a wildcard.

  • *
protocol string Specifies whether the protocol for the URL is HTTP or HTTPS.
  • http
  • https

whitelist-ips

Field Name Type Description Allowed Values
blockRequests string  
  • always
  • never
  • policy-default
description string    
ipAddress string    
ipMask string    

xml-profiles

Field Name Type Description Allowed Values
attackSignaturesCheck boolean    
defenseAttributes object    
description string    
enableWss boolean    
followSchemaLinks boolean    
name string  
  • Default

defenseAttributes

Field Name Type Description Allowed Values
allowCDATA boolean    
allowDTDs boolean    
allowExternalReferences boolean    
allowProcessingInstructions boolean    
maximumAttributeValueLength
  • integer
  • string
 
  • Integer values
  • “any”
maximumAttributesPerElement
  • integer
  • string
 
  • Integer values
  • “any”
maximumChildrenPerElement
  • integer
  • string
 
  • Integer values
  • “any”
maximumDocumentDepth
  • integer
  • string
 
  • Integer values
  • “any”
maximumDocumentSize
  • integer
  • string
 
  • Integer values
  • “any”
maximumElements
  • integer
  • string
 
  • Integer values
  • “any”
maximumNSDeclarations
  • integer
  • string
 
  • Integer values
  • “any”
maximumNameLength
  • integer
  • string
 
  • Integer values
  • “any”
maximumNamespaceLength
  • integer
  • string
 
  • Integer values
  • “any”
tolerateCloseTagShorthand boolean    
tolerateLeadingWhiteSpace boolean    
tolerateNumericNames boolean    

xml-validation-files

Field Name Type Description Allowed Values
contents string    
fileName string    
isBase64 boolean    

evasions

Field Name Type Description Allowed Values
description string Human-readable name of sub-violation.
  • %u decoding
  • Apache whitespace
  • Bad unescape
  • Bare byte decoding
  • Directory traversals
  • IIS Unicode codepoints
  • IIS backslashes
  • Multiple decoding
enabled boolean Defines if sub-violation is enforced - alarmed or blocked, according to the ‘Evasion technique detected’ (VIOL_EVASION) violation blocking settings.  
maxDecodingPasses integer Defines how many times the system decodes URI and parameter values before the request is considered an evasion. Relevant only for the ‘Multiple decoding’ sub-violation.  

http-protocols

Field Name Type Description Allowed Values
description string Human-readable name of sub-violation
  • Bad host header value
  • Bad HTTP version
  • Content length should be a positive number
  • No Host header in HTTP/1.1 request
  • Null in request
  • Several Content-Length headers
  • Unparsable request content
enabled boolean Defines if sub-violation is enforced - alarmed or blocked, according to the ‘HTTP protocol compliance failed’ (VIOL_HTTP_PROTOCOL) violation blocking settings  
maxHeaders integer Defines maximum allowed number of headers in request. Relevant only for the ‘Check maximum number of headers’ sub-violation  
maxParams integer Defines maximum allowed number of paramters in request. Relevant only for the ‘Check maximum number of parameters’ sub-violation  

violations

Field Name Type Description Allowed Values
alarm boolean    
block boolean    
description string    
name string  
  • VIOL_ASM_COOKIE_MODIFIED
  • VIOL_BLACKLISTED_IP
  • VIOL_COOKIE_EXPIRED
  • VIOL_COOKIE_LENGTH
  • VIOL_COOKIE_MALFORMED
  • VIOL_COOKIE_MODIFIED
  • VIOL_DATA_GUARD
  • VIOL_ENCODING
  • VIOL_EVASION
  • VIOL_FILETYPE
  • VIOL_HEADER_LENGTH
  • VIOL_HEADER_METACHAR
  • VIOL_HTTP_PROTOCOL
  • VIOL_HTTP_RESPONSE_STATUS
  • VIOL_JSON_FORMAT
  • VIOL_JSON_MALFORMED
  • VIOL_METHOD
  • VIOL_POST_DATA_LENGTH
  • VIOL_QUERY_STRING_LENGTH
  • VIOL_REQUEST_MAX_LENGTH
  • VIOL_REQUEST_LENGTH
  • VIOL_URL_LENGTH
  • VIOL_URL_METACHAR
  • VIOL_XML_FORMAT
  • VIOL_XML_MALFORMED
  • VIOL_RATING_THREAT
  • VIOL_RATING_NEED_EXAMINATION
  • VIOL_PARAMETER_MULTIPART_NULL_VALUE
  • VIOL_PARAMETER_NAME_METACHAR
  • VIOL_PARAMETER_VALUE_METACHAR