---
title: "Statistics"
manual: "Firewall"
version: "0.10"
permalink: "https://docs.typo3.org/permalink/flowd/typo3-firewall:statistics@0.10"
source: "Statistics.rst"
rendered: "2026-11-12T21:00:51+00:00"
---

# Statistics {#statistics}

The extension records what the firewall does and shows it in the
**Statistics** view of the [backend module](https://docs.typo3.org/permalink/flowd/typo3-firewall:backend-module@0.10).
This lets you see how much unwanted traffic your website receives and which
rules and paths are hit most.

## The event log {#the-event-log}

Every firewall action is written as one row to the database table
`tx_firewall_event`. A row holds the event type, the rule name, the ban
type for ban events, the client key (see the privacy section below), the
request host, path, and method, the user agent, rule numbers such as the
threshold and the counter, for errors the exception class and message, and
the time. It never stores a page, a session, or content. The recorded event
types are:

-   **`blocklist_matched`**

    A blocklist rule answered a request with a 403 response.

-   **`throttle_exceeded`**

    A client sent more requests than a rate limit allows.

-   **`fail2ban_matched`**

    A fail2ban rule blocked a request that matched its filter, before the
    ban threshold was reached.

-   **`fail2ban_banned`**

    A fail2ban rule banned a client after repeated abuse.

-   **`fail2ban_blocked`**

    A fail2ban rule blocked a request from a client that is already banned.
    High volume, so off by default.

-   **`allow2ban_banned`**

    An allow2ban rule banned a client for too many requests.

-   **`allow2ban_blocked`**

    An allow2ban rule blocked a request from a client that is already banned.
    High volume, so off by default.

-   **`safelist_matched`**

    A safelist rule let a request through without further checks.

-   **`track_matched`**

    A track rule counted a request without blocking it. High volume, so off
    by default.

-   **`track_threshold_reached`**

    A track rule with a limit reached it: the counted requests within the
    period hit the configured threshold. The rule still does not block; the
    entry is the signal to look at the tracked traffic.

-   **`track_hit`**

    Deprecated: split into `track_matched` and `track_threshold_reached`.
    A configured `track_hit` enables both and logs a deprecation; new
    entries are never written under the old type.

-   **`firewall_error`**

    The firewall hit an internal error, for example when the store was
    unreachable.

The `blocklist_matched`, `throttle_exceeded`, `fail2ban_matched`,
`fail2ban_banned`, `fail2ban_blocked`, `allow2ban_banned`, and
`allow2ban_blocked` types count as a blocked attacker: each one rejected a
request. They feed the numbers, the chart, and the top lists in the statistics
view. The `firewall_error` type is recorded but not counted, because an
internal error makes the firewall fail open by default, so the request was not
blocked. Four types are high volume and switched off by default so they do not
fill the table quickly: `safelist_matched` and `track_matched` fire on normal
traffic, and `fail2ban_blocked` and `allow2ban_blocked` fire on every
request from an already-banned client.

## Settings {#settings}

The extension configuration controls what is logged and for how long. Open
it under **Admin Tools** \> **Settings** \>
**Extension Configuration** and select `firewall`.

-   **`eventLogEnabled` (default: on)**

    Turns the event log on or off. When off, nothing is recorded and the
    statistics view stays empty.

-   **`eventLogTypes` (default: `blocklist_matched`, `throttle_exceeded`, `fail2ban_matched`, `fail2ban_banned`, `allow2ban_banned`, `track_threshold_reached`, `firewall_error`)**

    A comma-separated list of the event types to record. Add the high-volume
    types (`fail2ban_blocked`, `allow2ban_blocked`, `safelist_matched`,
    `track_matched`) only when you need them, and expect many more rows.

-   **`eventLogRetentionDays` (default: 30)**

    How many days to keep entries. The prune command uses this value.

-   **`eventLogAnonymizeIp` (default: on)**

    Stores client IP addresses in shortened form. The last part of the
    address is dropped, so a single visitor can no longer be identified.

-   **`eventLogFullIpRules` (default: empty)**

    Comma-separated rule names whose events store the client IP
    unanonymized, as a targeted exception from `eventLogAnonymizeIp`
    while a specific attack is analyzed. Restricting the exception to the
    rules under investigation and removing it afterwards keeps the data
    minimization intact that the anonymization default provides; network
    and information security is a recognized legitimate interest (GDPR
    recital 49), and the operator should record the analysis in the
    processing documentation. While the list is not empty, the event log
    view shows a warning icon in its header and the **System > Status**
    report warns, so the exception is not forgotten.

-   **`eventLogRequestHeaders` (default: off)**

    Stores the request headers with every event, shown as their own block
    in the event details. The headers are read from the raw server
    environment (the `HTTP_*` server params) as PHP received them, so
    they show the request as it arrived even when TYPO3 or a middleware
    modified the PSR-7 request afterwards; note that the web server and
    SAPI already merge duplicate header lines into one comma-separated
    value before PHP sees them. Credential headers (`Cookie`,
    `Authorization`, `Proxy-Authorization`, `X-Api-Key`,
    `X-Auth-Token`) are redacted before storing; the remaining headers
    can still contain personal data, for example client IPs in forwarding
    headers. Enable it only while analyzing an attack and disable it
    afterwards.

## Privacy and retention {#privacy-and-retention}

The event log is built to hold as little personal data as possible.

-   The key of a client, usually its IP address, is stored only as a keyed
    hash (HMAC-SHA-256 with the installation's encryption key). The hash lets
    the view count distinct clients and find a key by its full value, and the
    keying prevents reversing the small IPv4 address space by brute force.
-   A readable address is kept in a separate field for the backend view, but
    only for real IP addresses and, with `eventLogAnonymizeIp` on, only in
    shortened form. Keys that are not IP addresses are never shown in readable
    form.
-   Submitted POST parameters are not stored. An event records only the
    metadata of the match itself (rule, counters, matched target and value);
    matchers redact credential values before they reach the log.
-   Entries are deleted after the retention period. The console command
    removes the old rows:

    ```bash
    vendor/bin/typo3 firewall:eventlog:prune
    ```

    The command deletes entries older than the configured retention. Pass
    `--days` to override it once, for example `--days 7`. Register the
    command as a scheduler task or a cron job so old entries are removed
    regularly.

## How to read the statistics view {#how-to-read-the-statistics-view}

When event logging is off, the view shows a hint and stays empty. Otherwise
it shows:

-   Two large numbers at the top: **Attackers blocked today**, the count of
    distinct clients blocked since midnight, and **Blocked requests**, the
    total for the selected time range.
-   A time range switch with three options: the last 24 hours, 7 days, or 30
    days. The 24-hour range groups the data by hour, the other two by day.
    The selected range is stored per backend user and restored the next time
    the view is opened.
-   A **Blocked requests over time** chart. Each bar is stacked and split by
    event type, so you see at a glance whether blocklists, rate limits, or bans
    caused the traffic. Every type keeps the same color across ranges, and a
    legend below the chart names each color with its count.
-   A **Recent blocked requests** table with the most recent blocking events in
    the selected range (up to 20 rows). Each row shows the time, the event type
    in the same color as the chart, the rule that fired, the request method and
    path, and the client. This answers which rule blocked a specific request. A
    client that triggers many events is collapsed to its three newest ones; a
    hint shows how many more it caused. The client links to the event log
    filtered to that key, where every one of its events is listed.
-   A **Top rules** list with the five rules that blocked the most requests,
    and a **Top blocked paths** list with the five paths that attackers
    targeted most.
-   An **Events by type** list with the count per event type in the range.

## Dashboard widgets {#dashboard-widgets}

The extension ships two widgets for the TYPO3 dashboard. They need the
`typo3/cms-dashboard` package (see [Installation](https://docs.typo3.org/permalink/flowd/typo3-firewall:installation@0.10)) and read from the
same event log.

-   ****Firewall: Blocked today****

    A single number: the distinct attackers blocked since midnight.

-   ****Firewall: Blocked requests****

    A bar chart of the blocked requests per day over the last seven days.

## Statistics, blocked keys, and patterns {#statistics-blocked-keys-and-patterns}

The backend module shows firewall data in three ways. It helps to keep them
apart:

-   **Statistics** is the history. It tells you what happened over time, even
    for events that are long over.
-   **Blocked keys** is the present. It lists the bans that are active right
    now and lets you lift them (see [Backend module](https://docs.typo3.org/permalink/flowd/typo3-firewall:backend-module@0.10)).
-   **Patterns** are the static rules you manage by hand. They do not depend on
    past traffic (see [Backend module](https://docs.typo3.org/permalink/flowd/typo3-firewall:backend-module@0.10)).
