Witen

Matomo

Witen for Matomo

Install local protection for your Matomo server and optionally connect to Witen for shared intelligence. The plugin protects requests to Matomo; it does not protect the websites Matomo tracks.

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 outside this release’s compatibility range.

  1. Sign in to Witen and download Witen-0.2.19.zip from Downloads.
  2. Compare the ZIP’s SHA-256 checksum with the value on the Downloads page.
  3. Extract the ZIP into Matomo’s plugins directory. The entry file must be at plugins/Witen/Witen.php. The SDK is included; Composer is not required.
  4. Activate Witen in Matomo’s plugin administration, then open Witen from Administration.
  5. Review your IP rules, bot policies, and login limits. Local protection and the daily block chart work without enrollment.

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

Before connecting to your account

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

The plugin creates a stable installation ID automatically. You do not need a tracked website URL or site ID. You can name the asset in your account after it connects.

Create and save a token

  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. Enable 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 exchanges the token for a credential belonging to this installation and saves it for future connections.

Check the connection

  1. In Matomo, open Witen, then Diagnostics.
  2. Select Refresh connections. Under Witen connection checks, look for a successful heartbeat. Refresh is limited to once per minute.
  3. Open Protected Assets in your Witen account. The first heartbeat identifies the installation as Matomo. Give it a name you recognize.
  4. Check blocklist synchronization in Matomo Diagnostics and keep Matomo scheduled tasks running for regular updates.

A saved token alone does not confirm working protection. If checks fail, review the reported operation, outbound HTTPS access, and your account capacity. A blocklist profile may require a different plan. The service address is built into the plugin.

Connecting includes security-event sharing

Security-event sharing is required to use the Witen service. The connection also sends the server IP, installation identifier, sensor credential, and periodic heartbeats. Local protection works without enrollment.

Shared events include public client IPs, event categories, timestamps, request methods and paths, and denial receipts. Usernames, query strings, cookies, and request bodies are excluded. Read the privacy policy and update your privacy notice before connecting. To stop sharing, turn off the connection; pending shared events are discarded and local rules continue to work.

If you previously connected without sharing events, version 0.2.10 pauses that connection until you enable the combined connection-and-sharing control. The upgrade does not enable sharing for you.

Connect to local Warden

Warden 0.1.19 requires a credential for this Matomo installation, bound to its existing installation ID and PHP Unix user. Follow local caller setup, then set Warden credential file in General settings to the private file outside the web root. Web and scheduled tasks need the same Unix account and configuration. Enable Send security events through Warden to route reports through the socket, even when the Witen service is connected. Pending direct-delivery reports use Warden too while service sharing remains enabled. Socket failures leave reports queued. Background jobs retry with backoff and honor rate limits; they do not switch reporting to HTTPS. Credential errors appear on the Witen page. Malformed records are retained separately in bounded storage so they do not hold up valid reports. Enrollment, catalog updates, and the service heartbeat can still use the direct connection.

Use Warden imports its cached blocklist. Send security events through Warden remains a separate opt-in. An enabled direct Witen connection continues to handle event delivery. Check Refresh connections after provisioning the credential.

Update the plugin

Back up Matomo normally, verify the new ZIP’s checksum, and replace the Witen plugin files while preserving Matomo’s configuration and Witen’s private data directory. Confirm the version and connection checks afterward. Review file-baseline differences before saving a new baseline. Local rules and saved connection settings are retained during an upgrade.