Table of contents Index

class HttpProxy - Wrapper class for the http proxy

Declared in module Http

Inheritance hierarchy:

Http.HttpProxy
  Proxy.Proxy

Synopsis

class HttpProxy(Proxy):
    def Http.HttpProxy.__init__(self, session) # Initializes a HttpProxy instance.
    def Http.HttpProxy.config(self) # Default config event handler.
    def Http.HttpProxy.connectMethod(self)

    # Inherited from Zorp.ZorpProxy
    def Zorp.ZorpProxy.__init__(self, name, session_id, client_stream) # Initialize a low level proxy instance.

    # Inherited from Proxy.Proxy
    def Proxy.Proxy.__init__(self, name, session) # Initializes a Proxy instance.
    def Proxy.Proxy.addPolicy(self, klass) # Adds a policy to the proxy.
    def Proxy.Proxy.connectServer(self, host, port) # Callback method called when a connection established

Description

HttpProxy is a wrapper class for the built in Http proxy implemented in Zorp. It features both transparent and non-transparent modes of operation, advanced filtering and more.

Usage

Setting policy for requests:

Changing the default behaviour of requests can be done using the hash named "request". This hash is indexed by the method name (e.g: GET or POST), and each item in this hash is a tuple, whose first item is an integer value, determining the action to be done with the request, and also the interpretation of the remaining items in the tuple. All requests are denied by default in the low level proxy implementation. The most common methods (GET, POST and HEAD) are enabled from Python code.

Possible values for the first item:

HTTP_PASS
allow request without modification
HTTP_DROP
deny request (default)
HTTP_POLICY
call the given function to decide what to do this value uses an additional tuple item, which must be a callable Python function. The function must take four parameters: self, method, url, version

Example:

      class DmzHTTP(HttpProxy):
        def config(self):
          HttpProxy.config(self)
          self.request["GET"] = (HTTP_POLICY, self.filterURL)
        def self.filterURL(self, method, url, version):
          if (url == "http://www.balabit.hu")
            return Z_ACCEPT
          return Z_DENY

Changing headers in requests or responses:

Both request headers and response headers can be modified during transit. New header lines can be inserted, entries can be modified or deleted. To change headers in the request use the request_headers hash, for response headers you need the response_headers hash. Similarly to the request hash, these hashes contain a variable-length tuple, where the first item determines the interpretation of the remaining items. The hash index is the name of the header to be modified. Headers are not touched by default, except the "Host:", "Connection:" and "Proxy-Connection" headers. However the way these are modified can be changed here.

Possible values for the first item:

HTTP_PASS
pass header without change, default for all headers
HTTP_DROP
remove this header
HTTP_POLICY
call the next tuple item, which must be a Python function taking 3 parameters: self, hdr_name, hdr_value
HTTP_CHANGE_NAME
set header name to the next tuple item
HTTP_CHANGE_VALUE
set header value to the next tuple item
HTTP_CHANGE_BOTH
set header name and value to the next tuple items
HTTP_CHANGE_REGEXP
FIXME: Not yet implemented.
HTTP_INSERT
insert a new header defined by the next two tuple items (name, value)
HTTP_REPLACE
remove all existing occurences of this header and insert this one instead.

Example:

      class MyHttp(HttpProxy):
        def config(self):
          HttpProxy.config(self)
          self.request_headers["User-Agent"] = (HTTP_CHANGE_VALUE, "Lynx 2.4.1")
          self.request_headers["Cookie"] = (HTTP_POLICY, self.processCookies)
          self.response_headers["Set-Cookie"] = (HTTP_DROP,)
        def processCookies(self, name, value):
          log("http.message", 7, "cookie: value=%s" % value,)
          # you could change the current header in self.current_header_name
          # or self.current_header_value, the current request url
          # in self.request_url
          return Z_DROP

Redirecting urls:

You can choose to either reject a set of urls, or redirect them to a local mirror by changing some attributes during request processing. As a HTTP request comes in, normative policy chains are processed (self.request, self.request_headers), where you can install policy callbacks for certain events with the HTTP_POLICY directive. Any of these callbacks may change the request_url attribute which may result in a completely different url to be fetched.

Example:

      class MyHttp(HttpProxy):
        def config(self):
          HttpProxy.config(self)
          self.request["GET"] = (HTTP_POLICY, self.filterURL)
        def filterURL(self, method, url, version):
          self.request_url = "http://www.balabit.hu/"

Using parent proxies:

There are two things to checked to use parent proxies. First you have to pick a chainer which makes the proxy connect to the parent proxy. The two possibilities are InbandChainer(), or DirectedChainer(). The second thing to set is the parent_proxy and parent_proxy_port attribute in the HttpProxy instance. Setting these attributes results in proxy requests to be emitted to the target server in either transparent or non-transparent mode. The parent proxy attributes can be set in both the configuration phase (e.g. config() event), and later on a per-request basis.

Example:

      class MyHttp(HttpProxy):
        def config(self):
          HttpProxy.config(self)
          self.parent_proxy = "proxy.balabit.hu"
          self.parent_proxy_port = 3128

Attributes:

transparent_mode
(logical) TRUE for transparent proxy, FALSE otherwise (default: TRUE)
transparent_server_requests
(logical) allow server requests in transparent mode (default: TRUE)
transparent_proxy_requests
(logical) allow proxy requests in transparent mode (default: FALSE)
connection_mode
HTTP_CONNECTION_CLOSE or HTTP_CONNECTION_KEEPALIVE can be used to forcibly close a keepalive connection.
parent_proxy
(string) address or hostname of the parent proxy to connect to. You have to use DirectedChainer or InbandChainer for this option to take effect.
parent_proxy_port
(integer) the port of the parent proxy to connect to. (default: 3128)
default_port
(integer) if the port number is not specified in the URL use this port. (default: 80)
rewrite_host_header
(logical) rewrite Host header when redirecting an url (default: TRUE)
max_line_length
(integer) maximum length of non-transfer mode lines (default: 4096)
max_header_lines
(integer) maximum number of header lines in requests or responses (default: 50)
max_keepalive_requests
(integer) maximum number of requests in a single session
timeout
(integer) I/O timeout in milliseconds (default: 30000)
request
(hash) normative policy hash, directing the proxy to do something with requests, without the need to call Python. indexed by the method (e.g. "GET", "PUT" etc) (default: empty) See below for more information.
request_headers
(hash) normative policy hash, directing the proxy to do something with request headers (drop, insert, rewrite etc) It is indexed by the header name (e.g. "Set-cookie") (default: empty) See below for more information.
response
(hash) normative policy hash directing the proxy to do something with responses. FIXME: not yet used
response_headers
(hash) similar to request_headers for response headers.
request_url
(string) request url string, can be changed to redirect the current request.
current_header_name
(string) defined during header processing functions, and can be changed to actually change a header in the request or response.
current_header_value
(string) similar to current_header_name but contains the header value
error_response
(integer) if the request is denied use this HTTP response code (default: 500)
error_info
(string) a string included in error message.


Http.HttpProxy.__init__(self, session)

Initializes a HttpProxy instance.

self
this instance
session
the session this instance participates in
Creates and initializes a HttpProxy instance.

Http.HttpProxy.config(self)

Default config event handler.

self
this instance
Enables the most common HTTP methods so we have a useful default configuration.

Http.HttpProxy.connectMethod(self)

None


Copyright © 2000 BalaBit IT Ltd.
Written by: Balázs Scheidler