Accessible Python Modules and Functions

You can use Python scripts to expand the scope of vWAF to suit your specific requirements. For more information regarding creating and executing scripts, see Implementing Python Scripts and Script Handler.

Within your scripts you can use all basic Python operators plus the following modules and functions:

Module	Functions Available
time (standard Python module)	All functions from the standard Python time module.
re (standard Python module)	All functions from the standard Python re module.
hashlib (standard Python module)	All functions from the standard Python hashlib module. Can be used, for example, to create cryptographically secure hash values for adding additional security features to your web application, such as signed cookies.
etree (provided by lxml library)	All functions from the etree module of lxml. From a script, the module is available as lxml_etree . Example: xml = lxml_etree.parse(StringIO(xml_body))
StringIO (standard Python module)	Only accepts file descriptors. Needed for feeding the lxml library with data.
http (special interface to interact with vWAF )	All functions listed in the sections below this table.

In detection mode, only functions that are accessible during requests apply; any response functions are ignored in detection mode.

Overview: The following functions of the special http module are accessible during requests.

add_request_header(key, value)

add_response_header(key, value)

allow_request()

del_request_header(key)

del_response_header(key)

filter_response_full()

filter_response_header()

generate_blacklist_event(ip_range, timeframe)

get_client_ip()

get_request_args()

get_request_args_with_attributes()

get_request_body()

get_request_cookie(name)

get_request_cookies()

get_request_header(key)

get_request_method()

get_request_uri()

get_storage() is_request()

is_response()

log(string1, string2, string3, ..., string n)

make_random_cookie()

redirect(url)

send_response(content_type, body)

set_request_args((key1,value1,attributes1),(key2,value2,attributes2),...)

set_request_body(body)

set_request_cookie(key, value)

set_request_header(key, value)

set_request_uri(uri, arguments)

set_response_cookie(key, value)

set_response_header(key, value)

set_returncode(code)

terminate_session()

urandom(n)

Overview: The following functions of the special http module are accessible during responses.

add_response_header(key, value)

del_response_header(key)

get_request_args()

get_request_uri()

get_response_body()

get_response_cookies()

get_response_header(key)

get_returncode()

get_storage()

is_request()

is_response() log(string1, string2, string3, ..., string n)

make_random_cookie()

redirect(url)

set_response_body(body)

set_response_cookie(key, value)

set_response_header(key, value)

set_returncode(code)

terminate_session()

Functions Accessible during Requests in Detail

add_request_header(key, value)
Purpose	Adds a new header with the given data (key: value).
Input	key, value as String
Output	–

add_response_header(key, value)
Purpose	Adds a header to the response with the given values. You can also do that by enabling response filtering and then calling the function add_response_header during a response, but in this case the whole response is filtered.
Input	key, vlue as String
Output	–

allow_request()
Purpose	Aborts the current request processing and accepts the request. This can be used to bypass all handlers that are invoked after the Script Handler. The handlers that vWAF executes after the Script Handler are the handlers that are listed below the Script Handler on the Handlers tab. The sequence is determined automatically, so you can’t change it.
Input	–
Output	–

del_request_header(key)
Purpose	Deletes the header that has the given key.
Input	key as String
Output	–

del_response_header(key)
Purpose	Deletes a header from the response with the given values. You can also do that by enabling response filtering and then calling the function del_response_header during a response, but in this case the whole response is filtered.
Input	key as String
Output	–

filter_response_full()
Purpose	Tells vWAF to filter the full response, including headers and body. Be careful with potentially big response bodies. This can result in significant impact on performance.
Input	–
Output	–

filter_response_header()
Purpose	Tells vWAFto filter also the response headers belonging to the current request. There’s no access to the response body during the response cycle. If you want to filter also the body, use the function filter_response_full.
Input	–
Output	–

generate_blacklist_event(ip_range, timeframe)
Purpose	Adds the specified IP address or the specified range of IP addresses to the global IP blacklist (see Global IP Blacklisting).
Input	String, Integer value
Output	–

get_client_ip()
Purpose	Returns the IP address of the user.
Input	–
Output	String

get_request_args()
Purpose	Returns the request arguments as a list of tuples: [(key1,value1),(key2,value2),...]
Input	–
Output	list of tuples [(key1,value1),(key2,value2),...]

get_request_args_with_attributes()
Purpose	Returns the request arguments as a list of tuples: [(key1,value1,attributes1),(key2,value2,attributes2),...] Each request can include multiple arguments, each one represented as an entry in the list as a tuple (key / value / extra attributes, in the case of a multipart form data request). The attributes dictionary allows access to all extra multipart form data header elements. The attributes dictionary is always present in the returned list for each tuple but can be empty in case that there are no extra attributes. If the attributes dictionary contains a key 'encoding' it will reflect the encoding that was used to decode the given value (e.g. 'UTF-8')
Input	–
Output	list of tuples [(key1,value1,attributes1),(key2,value2,attributes2),...]

get_request_body()
Purpose	Returns the full request body as string (empty string if there’s no body).
Input	–
Output	String

get_request_cookie(name)
Purpose	Returns a string with the value of the cookie.
Input	cookie name as String
Output	cookie value as String

get_request_cookies()
Purpose	Returns a dict with all cookies: { cookie-name1 : cookie-value1, cookie-name2 : cookie-value2 }
Input	–
Output	dict {cookie-name1 : cookie-value1, cookie-name2 : cookie-value2 }

get_request_header(key)
Purpose	Returns the value of the request header stated by the parameter key. If this header doesn’t exist, the function returns None.
Input	key as String
Output	String or None

get_request_method()
Purpose	Returns the HTTP method for the current request (GET, POST...) as string.
Input	–
Output	String

get_request_uri()
Purpose	Returns the requested URI.
Input	–
Output	String

get_storage()
Purpose	Returns a dict that can be used as data storage throughout a session. The Session Handler needs to be enabled for this to work.
Input	–
Output	dictionary

is_request()
Purpose	Returns True if the current script is executed during a request. Else the result is False. The statement not is_response() returns the same result.
Input	–
Output	Boolean

is_response()
Purpose	Returns True if the current script is executed during a response. Else the result is False. The statement not is_request() returns the same result.
Input	–
Output	Boolean

log(string1, string2, string3, ..., string n)
Purpose	Concatenates the given list of strings (at least one) and writes the result to the vWAF Log Files.
Input	list of String
Output	–

make_random_cookie()
Purpose	Generates a random string, which can be used as the name of a cookie.
Input	–
Output	String

redirect(url)
Purpose	Redirects to the given URL.
Input	URL as String
Output	–

send_response(content_type, body)
Purpose	Aborts the current request and sends a response with the given content_type (e.g. “text/html”) and body.
Input	content_type, body as String
Output	–

set_request_args ((key1,value1,attributes1),(key2,value2,attributes2),...)
Purpose	Sets the arguments of a POST request.
Input	List of tuples [(key1,value1,attributes1),(key2,value2,attributes2),...] attributesn is optional. If set, it must be a dictionary with additional attributes that will be added to a multipart form data header. If the attributes dictionary contains an 'encoding' entry it will be used to re-encode the value (e.g. 'UTF-8'). If encoding is not specified in the dictionary, the default Charset (character encoding) for the application is applied.
Output	–

set_request_body(body)
Purpose	Replaces the current request body.
Input	body: string with the replacement body
Output	–

set_request_cookie(key, value)
Purpose	Sets the cookie (from browser) that has the name key to the given value. If you want to set a cookie on the browser side, use the function set_response_cookie instead.
Input	key, value as String
Output	–

set_request_header(key, value)
Purpose	Replaces the value of the header that has the given key with a given string.
Input	key, value as String
Output	–

set_request_uri(uri, arguments)
Purpose	Replaces the request URI with the given one. Current URI arguments are also replaced with the given ones. The parameter arguments is a list of tuples. If, for example, you want to set the URI for the current request to: /index.html?a=b&c=d you would call: set_request_uri('/index.html',[(a,b),(c,d)])
Input	URI as String, arguments as list of tuples
Output	–

set_response_cookie(key, value)
Purpose	Sets the response cookie (to browser) that has the name key to the given value.
Input	key, value as String
Output	–

set_response_header(key, value)
Purpose	Unlike the function set_request_header, sets a header for the response You can also do that by enabling response filtering and then calling the function set_response_header during a response, but in this case the whole response is filtered.
Input	key, value as String
Output	–

set_returncode(code)
Purpose	Aborts the current request or response and returns the given return code. (For a list of possible codes, see HTTP Error Codes.)
Input	Integer
Output	–

terminate_session()
Purpose	Ends the secure session that has been established between vWAF and the web application (see Session Handler, Cookie Jar Handler). A typical scenario is the implementation of a log out function via vWAF for a web application that doesn’t provide a manual log out option. Example: Create the path /logout. To this path, add the Script Handler and call the function http.terminate_session(). In your web application, provide the following link to log out: <a href="/ logout">Logout</a>.
Input	–
Output	–

urandom(n)
Purpose	Generates random bytes. n = specifies the number of random bytes that should be generated. The maximum value for n is 1024 (if a value greater than 1024 is entered, n is set to 1024)
Input	–
Output	a string of n random bytes

Functions Accessible during Responses in Detail

add_response_header(key, value)
Purpose	Adds a response header that has the name key to the given value. (See also add_response_header function during requests.)
Input	key, value as String
Output	–

del_response_header(key)
Purpose	Removes the response header that has the name key. (See also del_response_header function during requests.)
Input	key as String
Output	–

get_request_args()
Purpose	Returns the request arguments as a list of tuples: [(key1,value1),(key2,value2),...]
Input	–
Output	list of tuples [(key1,value1),(key2,value2),...]

get_request_uri()
Purpose	Returns the requested URI.
Input	–
Output	String

get_response_body()
Purpose	Returns the full body of the current response. This only works if a response body does actually exist and if response filtering was triggered for the full response, not only for the headers (see function filter_response_full during requests).
Input	–
Output	body as String

get_response_cookies()
Purpose	Returns a dict with all cookies: { cookie-key1 : cookie-val1, cookie-key2 : cookie- val2 }
Input	–
Output	dict { cookie-key1 : cookie-val1, cookie-key2 : cookie-val2 }

get_response_header(key)
Purpose	Returns the value of the response header stated by the parameter key. If this header doesn’t exist, the function returns None.
Input	key as String
Output	value as String

get_returncode()
Purpose	Returns the return code for the current response.
Input	–
Output	`if http.get_returncode() == "200":` return code as String Other than you might expect, the output is not an Integer value. Thus, a correct statement would be, for example: Mind the quotation marks.

get_storage()
Purpose	Returns a dict that can be used as data storage throughout a session. The Session Handler needs to be enabled for this to work.
Input	–
Output	dictionary

is_request()
Purpose	Returns True if the current script is executed during a request. Else the result is False. The statement not is_response() returns the same result.
Input	–
Output	Boolean

is_response()
Purpose	Returns True if the current script is executed during a response. Else the result is False. The statement not is_request() returns the same result.
Input	–
Output	Boolean

log(string1, string2, string3, ..., string n)
Purpose	Concatenates the given list of strings (at least one) and writes the result to the vWAF Log Files.
Input	list of String
Output	–

make_random_cookie()
Purpose	Generates a random string, which can be used as the name of a cookie.
Input	–
Output	String

redirect(url)
Purpose	Redirects to the given URL.
Input	URL as String
Output	–

set_response_body(body)
Purpose	Sets the response body to the given string.
Input	body as String
Output	–

set_response_cookie(key, value)
Purpose	Sets the response cookie (to browser) that has the given key to value. (See also set_cookie_response function during requests.)
Input	key, value as String
Output	–

set_response_header(key, value)
Purpose	Sets the response header that has the name key to the given value. (See also set_response_header function during requests.)
Input	key, value as String
Output	–

set_returncode(code)
Purpose	Aborts the current request or response and returns the given return code. (For a list of possible codes, see HTTP Error Codes.)
Input	Integer
Output	–

terminate_session()
Purpose	Ends the secure session that has been established between vWAF and the web application (see Session Handler, Cookie Jar Handler.) A typical scenario is the implementation of a log out function via vWAF for a web application that doesn’t provide a manual log out option. Example: Create the path /logout. To this path, add the Script Handler and call the function http.terminate_session(). In your web application, provide the following link to log out: <a href="/logout">Logout</a>.
Input	–
Output	–