Metadata-Version: 2.1
Name: request_filters
Version: 1.2.5
Summary: A firewall for your wagtail application. It allows you to filter requests based on IP, User-Agent, URL and Country.
Author: Nigel
Author-email: nigel@goodadvice.it
License: GPL-3.0-only
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: Wagtail>=5.0

# request_filters
===============

A sort of software firewall for your django application which provides advances capabilities for blocking or logging requests at runtime.
Only for use in wagtail projects - might support django-only in the future.

## Supports filtering based on:

* IP
* USER_AGENT
* PATH
* QUERY_STRING
* REFERER
* COUNTRY
* METHOD

## Matching based on:
* Absolute (== in most cases. Differs for: IP (Checks subnet if cidr provided), COUNTRY (Checks country code or name as returned by GeoIP2))
* Glob (fnmatch)
* Regex (re)
* In (IP based on cidr, splits most `filter_value`'s' by comma and checks if the request's value is in the list)


# Quick start
-----------

1. Add 'request_filters' to your INSTALLED_APPS setting like this:

   ```
   INSTALLED_APPS = [
   ...,
   'request_filters',
   ]
   ```
2. Add `request_filters.middleware.RequestFilterMiddleware` to your `MIDDLEWARE` as the **FIRST ENTRY**.

   ```
   MIDDLEWARE = [
   ...,
   'request_filters.middleware.RequestFilterMiddleware',
   ]
   ```
3. See the [options](#Options) section for more information on how to configure the app.
4. Log into your wagtail admin and configure your filters.

# Options

#### EXCLUDED_APPS

List of excluded apps, all requests to these apps will be allowed (If resolver_match is available).
Exclusions should preferably happen via IP ranges or absolute IPs.

```
    EXCLUDED_APPS:                list[str] = [
        "admin",
    ]
```

#### EXCLUDED_PATHS

Excluded paths, all requests to these paths will skip filtering

Paths should be in the format of a glob pattern.
Exclusions should preferably happen via IP ranges or absolute IPs.

```
    EXCLUDED_PATHS:               list[str] = [
        "/admin/*",
        f"{getattr(settings, 'STATIC_URL', '/static/')}*",
        f"{getattr(settings, 'MEDIA_URL', '/media/')}*",
    ]
```

#### EXCLUDED_IPS

Excluded IP addresses, all requests from these IPs will be allowed.

```
    # This is the safest way to exclude requests from being filtered.
    EXCLUDED_IPS:                 list[str] = [
        "127.0.0.0/8", "::1/128",
    ]
```

#### Caching

Caching settings and their defaults.

```
# Default cache backend to use for storing settings and filters
CACHE_BACKEND:                str                   = "default"

# Namespaces for cache keys.
SETTINGS_CACHE_KEY:           str                   = "request_filters_settings"
FILTERS_CACHE_KEY:            str                   = "request_filters_filters"

# Timeout the cache for the filter settings for 5 minutes by default
SETTINGS_CACHE_TIMEOUT:       timezone.timedelta    = timezone.timedelta(minutes=5)

# Timeout the cache for the filters for 1 hour by default
FILTERS_CACHE_TIMEOUT:        timezone.timedelta    = timezone.timedelta(hours=1)

# Clear cache when settings are saved
CLEAR_CACHE_ON_SAVE_SETTINGS: bool                  = True

# Clear cache when filters are saved
CLEAR_CACHE_ON_SAVE_FILTERS:  bool                  = True
```

#### Exception Message

**Message shown when a filter raises an exception, or blocks the request.**

```
BLOCK_MESSAGE:                str                   = _("You are not allowed to access this resource")
```

#### Filter Headers

Add headers to the response which displays minimal information about the filters.

```
ADD_FILTER_HEADERS:           bool                  = True  # Add headers to the response which displays minimal information about the filters.
```

#### Create a log entry for requests which have passed all filters.

**Not recommended for production.**

```
LOG_HAPPY_PATH:               bool                  = False # Log requests that are allowed by the filters
```

#### Default values for the check and action functions.

```
DEFAULT_CHECK_VALUE:          Union[bool, callable] = True  # Allow checks to pass by default
DEFAULT_ACTION_VALUE:         callable              = lambda self, filter, settings, request, get_response: HttpResponseForbidden(
        _("You are not allowed to access this resource")
)
```
