def add_response_header(self, key, value):
"""
Add a response header to be inspected.
With this function it is possible to feed ModSecurity with a
response header.
:param key: key of an response header
:param value: value associated to ``key``
"""
retvalue = _lib.msc_add_response_header(self._transaction_struct,
as_bytes(key), as_bytes(value))
if not retvalue:
raise FeedingError.failed_at("response header")
def add_rules_remote(self, key, uri):
"""
Fetch rules over a network and merge it with the current rules set.
:param key: key as :class:`str`
:param uri: URI address
:return: number of rules merged as :class:`int`
"""
retvalue = _lib.msc_rules_add_remote(self._rules_set,
utils.as_bytes(key),
utils.as_bytes(uri),
self._error_pointer)
if retvalue == -1:
raise InternalError(self._last_error_message())
return retvalue
def get_request_body_from_file(self, filepath):
"""
Add request body stored in a file to be inspected.
:param filepath: path to a file
"""
retvalue = _lib.msc_request_body_from_file(self._transaction_struct,
as_bytes(filepath))
if not retvalue:
raise FeedingError.failed_at("getting request body from file")
def process_uri(self, uri, method, http_version):
"""
Perform the analysis on the URI and all the query string variables.
This function should be called at very beginning of a request process,
it is expected to be executed prior to the virtual host resolution,
when the connection arrives on the server.
:param uri: URI address
:param method: an HTTP method
:param http_version: a :class:`str` defining HTTP protocol version
.. note::
* Value consistency is not checked for ``method`` and
``http_version``.
* Remember to check for a possible intervention
with :meth:`has_intervention()`.
"""
retvalue = _lib.msc_process_uri(self._transaction_struct,
as_bytes(uri), as_bytes(method),
as_bytes(http_version))
if not retvalue:
raise ProcessConnectionError.failed_at("uri")
def add_rules_file(self, filename):
"""
Add rules stored in a file and merge it with the current rules set.
:param filename: file path to rules file
:return: number of rules merged as :class:`int`
"""
retvalue = _lib.msc_rules_add_file(self._rules_set,
utils.as_bytes(filename),
self._error_pointer)
if retvalue == -1:
raise InternalError(self._last_error_message())
return retvalue
def set_connector_info(self, connector):
"""
Set information about the connector using the library.
For the purpose of log it is necessary for ModSecurity to understand
which ``connector`` is consuming the API.
It is strongly recommended to set a information in the following
pattern : *ConnectorName vX.Y.Z-tag (something else)*
:param connector: information about the connector as :class:`str`
"""
return _lib.msc_set_connector_info(self._modsecurity_struct,
utils.as_bytes(connector))
def process_connection(self, client_ip, client_port, server_ip,
server_port):
"""
Perform the analysis on the connection.
This function should be called at very beginning of a request process,
it is expected to be executed prior to the virtual host resolution,
when the connection arrives on the server.
:param client_ip: client's IP address as :class:`str`
:param client_port: client's port as :class:`int`
:param server_ip: server's IP address as :class:`str`
:param server_port: server's port as :class:`int`
.. note:: Remember to check for a possible intervention with
:meth:`has_intervention()`.
"""
retvalue = _lib.msc_process_connection(self._transaction_struct,
as_bytes(client_ip),
int(client_port),
as_bytes(server_ip),
int(server_port))
if not retvalue:
raise ProcessConnectionError.failed_at("connection")
def add_rules(self, plain_rules):
"""
Add custom rule defined by ``plain_rules`` and merge it with the
current rules set.
:param plain_rules: ModSecurity rule(s) as :class:`str`
:return: number of rules merged as :class:`int`
"""
retvalue = _lib.msc_rules_add(self._rules_set,
utils.as_bytes(plain_rules),
self._error_pointer)
if retvalue == -1:
raise InternalError(self._last_error_message())
return retvalue
def append_request_body(self, body):
"""
Add request body to be inspected.
With this function it is possible to feed ModSecurity with data for
inspection regarding the request body.
There are two possibilities here:
- Add the buffer in a row
- Add it in chunks
:param body: (chunk of the) body of a request
"""
retvalue = _lib.msc_append_request_body(self._transaction_struct,
as_bytes(body), len(body))
if not retvalue:
raise FeedingError.failed_at("request body")
def append_response_body(self, body):
"""
Add reponse body to be inspected.
With this function it is possible to feed ModSecurity with data for
inspection regarding the response body. ModSecurity can also update the
contents of the response body, this is not quite ready yet on this
version of libmodsecurity.
If the content is updated, the client cannot receive the content length
header filled, at least not with the old values. Otherwise unexpected
behavior may happens.
:param body: body of a response
"""
retvalue = _lib.msc_append_response_body(self._transaction_struct,
as_bytes(body), len(body))
if not retvalue:
raise FeedingError.failed_at("response body")
def process_response_headers(self, statuscode, protocol):
"""
Perform the analysis on the response headers.
This function perform the analysis on the response headers, notice
however that the headers should be added prior to the execution of
this function or :exc:`~exceptions.ProcessConnectionError` will be
raised.
:param statuscode: HTTP status code as :class:`int`
:param protocol: protocol name with its version (e.g "HTTP 1.1")
.. note:: Remember to check for a possible intervention
with :meth:`has_intervention()`.
"""
retvalue = _lib.msc_process_response_headers(self._transaction_struct,
int(statuscode),
as_bytes(protocol))
if not retvalue:
raise ProcessConnectionError.failed_at("response headers")
