Advanced ACLs


Much of the Filter Engine’s functionality is configured with Access Control Lists (ACLs). Each request is assigned a number of ACL names, and then an action is chosen based on those names. For example:

acl no-web user-ip 192.168.1.25
block no-web

The first line creates an ACL named no-web, and assigns it to all requests coming from IP address 192.168.1.25. The second line causes all requests with that ACL to be blocked.

ACLs are checked at several points during the processing of a request: before sending the request to the origin server, after receiving a response, and after scanning the content for phrases. Each time, the request may match different ACLs, since more information is available. Each stage also has a different set of possible actions, although there is some overlap. (The allow, block, and block-invisible actions are always available.)


Assigning ACLs

ACLs have attributes that refer to some property of the HTTP Request / Response cycle. If there is more than one ACL with the same name and attribute, the ACL will match the Request / Response if any of the ACL patterns match (logical OR).

In addition to the tags assigned by acl lines, a request is assigned a Category ACL for its highest-scoring category (if the score is above the threshold).

The following ACL attributes are available:

connect-port

(request only) The destination port of a CONNECT request. This attribute never matches if the request method is not CONNECT.

content-type

(response only) The response’s media type, usually taken from the Content-Type header. This can also be a generic type, with an asterisk after the slash:

acl images content-type image/*

http-status

(response only) The response's HTTP status code. If this is a multiple of 100, all status codes in that block of 100 will match.

method

The HTTP request method, such as GET or POST.

referer

The request’s Referer header. (This matches the same way as regular URL matching rules.)

server-ip

The remote web server’s IP address, or a range of addresses (in CIDR format, or with a dash). This attribute only matches if the request URL contains a literal IP address; it does not do a DNS lookup.

url

The URL requested. (This matches the same way as regular URL matching rules.)

user-agent

The User-Agent header. Instead of interpreting the remainder of the line as a list of values, this attribute interprets it as a single regular expression to be matched against the User-Agent string. The matching is case insensitive.


ACL Actions

After the ACLs are assigned, Redwood goes through the ACL files looking for an action to perform. An action will be selected only if it has all the chained ACL names specified in the action line. (And none of the negated ACLs; if an ACL in an action line is preceded by an exclamation point, the Request must not match that ACL.)

The configuration files are pocessed in order, so earlier action lines take precedence over later ones. If Redwood gets to the end of the file without finding a matching rule, it will use the default action of the highest-scoring Category. If there is no Category that scores over the minimum threshold, the default action is allow.

allow

Allow the request to proceed.

block

Respond with an HTTP status code of 403, and send the standard block page.

block-invisible

Respond with HTTP 403, and send an invisible 1-pixel image instead of a block page.

disable-proxy-headers

Don't add headers that indicate that the request has passed through a proxy (X-Forwarded-For and Via).

hash-image

(response only) Calculate a hash of the image, and compare it to the hash rules. If the difference between this hash and the one in the rule is less than the number of bits specified with --dhash-threshold (or the hash's individual threshold), it matches.

This action should only be applied when the content is an image:

acl image content-type image/jpeg image/gif image/png
hash-image image

phrase-scan

(response only) Run a phrase scan on the page content. Normally this will be configured to depend on the content type:

acl text content-type text/* application/xhtml+xml
acl css content-type text/css
phrase-scan text !css

require-auth

(request only) Send an HTTP 407 response if the request doesn’t have a Proxy-Authorization header.

ssl-bump

(CONNECT requests only) Activate the SSLBump feature, to filter HTTPS connections. (Transparently intercepted HTTPS connections produce a virtual CONNECT request inside Redwood, so they can be filtered too.)