Skip to content
Witen

Matomo

Witen for Matomo

Witen blocks attackers and unwanted bots before they reach your Matomo server. The plugin protects requests to Matomo; it does not protect the websites Matomo tracks. Local protection works without connecting. Connect to Witen for shared blocklists.

Quickstart

  1. Download the plugin from your Witen account, check its checksum, and activate it in Matomo. The full steps are below.
  2. Open Witen Security and check Overview and Diagnostics for local protection and scheduled maintenance.
  3. Add your management address to the allowed IP rules. Behind a proxy? Check the resolved client address first.
  4. Choose bot policies and login limits. Keep console access before you test new blocks.
  5. Review Activity and the local block chart as requests arrive. Test a block from a separate staging connection, and remove the test rule afterwards.

Everything above works without connecting to Witen. Connecting is optional.

Download and install

Version 0.2.19 supports Matomo On-Premise 5.13–5.x · PHP 8.1+ · Linux/Unix. You need Matomo Super User access and writable private storage outside the web root. Matomo for WordPress and Matomo 6 are not supported in this release.

  1. Sign in to Witen and download Witen-0.2.19.zip from Downloads.
  2. Check the ZIP’s SHA-256 checksum against the value on the Downloads page.
  3. Extract the ZIP into Matomo’s plugins directory so the entry file is at plugins/Witen/Witen.php. The SDK is included; you don't need Composer.
  4. Activate Witen in Matomo’s plugin administration, then open Witen Security from Administration.
  5. Review your IP rules, bot policies, and login limits. Local protection and the daily block chart start right away.

Set Matomo’s trusted proxy settings for your network. Witen uses the resolved HTTP sender address, including on tracker requests. Watch unfamiliar request patterns before you block them.

Check local protection

  1. Open Witen Security, then Overview. Review Local IP rules and the local block summary; zero blocks can be normal.
  2. Review IP rules, Bots, and Protection for the policies and login limits you want.
  3. Open Diagnostics and review the local scan and integrity results. Save a baseline only when you trust the current files, and investigate differences before changing any file.
  4. Review Activity as traffic arrives. An event or detection doesn't always mean a request was blocked.

These checks do not need a Witen token, a hosted asset, or a feed sync. Keep your management address allowed, and review tracking-endpoint policies: blocked requests never reach Matomo's tracker.

Before you connect

  • Witen is installed and activated in your Matomo instance.
  • You have Matomo Super User access to change General settings.
  • Your Witen account has a free protected-asset slot.
  • The server can reach https://collector.witenlabs.com over HTTPS.

The plugin creates a stable installation ID itself, so you don't need a tracked website URL or site ID. Name the asset in your account once it connects.

Connect to Witen (optional)

  1. In your Witen account, open Add Protection, select Add protected asset, and choose Matomo.
  2. Select Create Matomo token. The token works once and expires after 15 minutes.
  3. In Matomo, open Administration, General settings, then Witen.
  4. Turn on Connect to Witen and share security events and paste the token into Witen token. Leave Use Warden off for this direct connection.
  5. Save. Matomo trades the token for a credential that belongs to this installation and keeps it for future connections.

Check the connection

Connected installations only.

  1. In Matomo, open Witen Security, then Diagnostics.
  2. Select Refresh connections, at most once a minute. Under Connection checks, the Witen table should show a successful Heartbeat row.
  3. Open Protected Assets in your Witen account. The first successful check identifies the installation as Matomo. Give it a name you recognize.
  4. Check blocklist sync in Matomo Diagnostics, and keep Matomo scheduled tasks running so updates keep arriving.

A saved token alone doesn't prove protection is working. If checks fail, look at the failing operation, outbound HTTPS access, and your account capacity. Some blocklist profiles need a different plan. The service address is built into the plugin.

What connecting shares

Security-event sharing is required to use the Witen service. The connection also sends the server IP, installation identifier, sensor credential, and periodic status checks.

Shared events include public client IPs, event categories, timestamps, request methods and paths, and denial receipts. Usernames, query strings, cookies, and request bodies are never sent. Read the privacy policy and update your privacy notice before you connect. To stop sharing, turn off the connection: pending shared events are discarded and local rules keep working.

If you connected before without sharing events, version 0.2.10 pauses that connection until you turn on the combined connect-and-share setting. The upgrade never turns sharing on for you.

Use Warden on the same server

  1. Warden 0.1.19 and later need a credential for this Matomo installation, tied to its existing installation ID and PHP Unix user. Create it with local plugin setup.
  2. In General settings, set Warden credential file to the private file outside the web root. Web and scheduled tasks need the same Unix account and configuration.
  3. Turn on Use Warden to import Warden's cached blocklist.
  4. To send reports through the socket, also turn on Send security events through Warden. It is a separate opt-in.
  5. Select Refresh connections to check it.
  • With Send security events through Warden on, reports go through the socket even when the Witen service is connected. Pending direct-delivery reports use Warden too while service sharing stays on.
  • With it off, an enabled direct Witen connection delivers events.
  • Socket failures leave reports queued. Background jobs retry with backoff and respect rate limits; they never switch reporting to HTTPS.
  • Credential errors appear on the Witen page.
  • Malformed records are kept apart, in size-limited storage, so they don't hold up valid reports.
  • Enrollment, catalog updates, and the service status check can still use the direct connection.

Update the plugin

  1. Back up Matomo as usual and check the new ZIP’s checksum.
  2. Replace the Witen plugin files. Keep Matomo’s configuration and Witen’s private data directory; local rules and saved connection settings carry over.
  3. Confirm the version and the connection checks.
  4. Review file-baseline differences before you save a new baseline.