.. include:: Includes.txt ============== Backend module ============== The extension adds a backend module under **System** > **Firewall**. It is available to administrators only. The module has four views. Switch between them with the **View** dropdown in the module's doc-header: - **Patterns** manages the static block patterns. - **Blocked keys** lists the clients that rules have banned automatically. - **Event log** lists the recorded firewall events with their details. - **Statistics** shows how much traffic the firewall blocked over time. Patterns ======== .. figure:: /Images/backend-module-patterns.png :alt: Screenshot of the Patterns view with the pattern list and edit form The Patterns view: the active pattern list next to the add and edit form. This view manages the static block patterns. The extension always adds them to the firewall as the blocklist rule ``typo3-blocklist``, so they take effect even when no configuration file exists (see :doc:`Configuration`). Patterns are stored in the file ``config/system/phirewall.patterns.json`` (classic installation: ``typo3conf/system/phirewall.patterns.json``). The extension configuration setting ``patternsDirectory`` moves the file and its lock file to another directory, for example when ``config/system`` is read-only at runtime; the directory must lie within the TYPO3 project directory or ``BE/lockRootPath`` (see :doc:`Configuration`). Every change takes effect on the next request. No deployment and no cache flush are needed. The pattern list ---------------- The **Active Patterns** list shows one row per pattern with its kind, value, target, expiry date, creation date, and last change. A pattern that has passed its expiry date is highlighted and no longer blocks requests, until you remove it or run a prune (see below). Add and edit patterns ---------------------- The form next to the list creates a new pattern. Pick a kind, enter the value, and save. To change a pattern, open it from the list, edit the fields, and save. The form checks the value before it stores the pattern and shows a clear message when something is wrong, for example an invalid IP address or a broken regular expression. Pattern kinds ------------- A pattern's kind decides what part of the request it compares against. ``ip`` Blocks one exact client IP address, for example ``203.0.113.10``. ``cidr`` Blocks a whole IP range in CIDR notation, for example ``203.0.113.0/24``. ``path_exact`` Blocks requests whose path is exactly this value, for example ``/old-login``. ``path_prefix`` Blocks requests whose path starts with this value, for example ``/.git/``. ``path_regex`` Blocks requests whose path matches this regular expression, for example ``#^/(\.git|\.env)#``. ``header_exact`` Blocks requests where a header has exactly this value. Put the header name in the target field, for example target ``User-Agent`` and value ``BadBot/1.0``. ``header_regex`` Blocks requests where a header matches this regular expression. Put the header name in the target field, for example target ``User-Agent`` and value ``#(sqlmap|nikto)#i``. ``request_regex`` Blocks requests where the regular expression matches a combined string of the path, the query string, and the request headers, for example ``#(union\s+select|` and the :doc:`Statistics` view. .. _backend-module-event-log: Event log ========= .. figure:: /Images/backend-module-events.png :alt: Screenshot of the Event log view with type tags, key filter and search The Event log view: the type tags, the active key filter, and the search field above the event table. This view lists the latest recorded firewall events, newest first. Every entry shows the time, the event type, the rule, the key (an anonymized IP address, or a hash for sensitive keys), the request line with the user agent, and the event details. The request line contains the full request target including the query string, so GET payloads such as injection attempts are visible (and searchable) as they arrived. The details column renders everything the event carried as ``key: value`` lines. Submitted POST parameters appear as ``post.name: value`` lines. Every value is masked down to its first and last two characters (``administrator`` becomes ``ad***or``), parameter names that look like credentials (``pass``, ``token``, and similar) are masked completely, and large forms are truncated, so the log never stores passwords or other submitted data in clear text. To inspect attack payloads in POST fields, the value masking can be turned off with the ``eventLogMaskParameters`` extension setting (credential-like parameters stay masked); see :doc:`Statistics` for all event log settings. The details also include counters (``threshold``, ``count``, ``banSeconds``) and the diagnostic headers a matcher attached to its match, for example ``diagnosticHeaders.X-Phirewall-Owasp-Rule: 942100`` for an OWASP CRS match. The diagnostics land in the log independently of the ``X-Phirewall-*`` response headers, so you can inspect which rule fired without exposing that information to clients. When a client triggers many events, the list collapses them: each key shows only its three newest events, and the third row carries a hint with the number of older events. Events without a key, for example blocklist matches, are never collapsed. Click a key or the hint to filter the list to that key and see every one of its events. The rule is clickable as well and filters the list to the events of that rule; both filters combine with the tags and the search. Every active filter appears above the list and is removed again with the close button next to it. Filter the list by event type with the type tags: a click toggles a tag, and all active tags combine into one filter. The active tags and the search term are stored per backend user and restored the next time the module is opened; **Reset** clears them. The key filter is a transient drill-down and is not stored. The search field matches rule names, keys, and request paths. It also compares the search term against the stored key hash, so searching for the full IP address (for example ``203.0.113.10``) finds its events even when the list only displays the anonymized form ``203.0.113.0``. The list is paginated with 50 entries per page; the pager keeps the active filters. See :doc:`Statistics` for the retention settings of the underlying log table. Statistics ========== .. figure:: /Images/backend-module-statistics.png :alt: Screenshot of the Statistics view with the chart and top lists The Statistics view: the blocked-requests chart over time and the top lists below it. This view answers one question: how much unwanted traffic the firewall blocked. It shows the number of attackers blocked today, a chart over time, and the rules and paths that triggered most often. For the full description of the recorded data, the privacy model, and the extension settings, see :doc:`Statistics`.