purplespider/kirby-monitoring-client

Kirby CMS monitoring client plugin compatible with the BiffBangPow Silverstripe monitoring server.

v1.0.0 2026-05-13 10:53 UTC

Requires

• php: >=7.4
• ext-sodium: *
• getkirby/composer-installer: ^1.2

MIT

• James Cocker

• monitoring
• kirby
• kirby-plugin
• biffbangpow

README

A monitoring plugin for Kirby CMS that provides compatibility with the BiffBangPow Silverstripe Monitoring Server.

Features

• 🔐 Secure encryption using libsodium
• 🚦 Rate limiting (1 request per minute)
• 🔑 API key authentication
• 🌐 IP whitelist support
• 📊 Modular reporting system

Requirements

• Kirby 3.x, 4.x, or 5.x
• PHP 7.4+ with sodium extension enabled
• Composer (for package version reporting)

Installation

Via Composer (recommended)

composer require purplespider/kirby-monitoring-client

This installs the plugin into site/plugins/monitoring-client/ automatically via the getkirby/composer-installer.

Manual Installation

1. Download this repository
2. Copy the files to site/plugins/monitoring-client/
3. Configure environment variables (see Configuration)

Via Git Submodule

git submodule add https://github.com/purplespider/kirby-monitoring-client site/plugins/monitoring-client

Configuration

Required Environment Variables

Add these to your .env file or server environment:

# API key for authentication (provided by monitoring server)
MONITORING_API_KEY=your-api-key-here

# Unique client identifier (provided by monitoring server)
MONITORING_UUID=unique-client-uuid

# Encryption keys (provided by monitoring server)
MONITORING_ENC_SECRET=your-encryption-secret
MONITORING_ENC_SALT=your-encryption-salt

Optional Environment Variables

# Restrict access to specific IP address or range
MONITORING_VALID_IP=192.168.1.100

# Or use CIDR notation
MONITORING_VALID_IP=192.168.1.0/24

# Or use wildcards
MONITORING_VALID_IP=192.168.*.*

Plugin Configuration

Add to your site/config/config.php:

return [
    'monitoring.client' => [
        // Endpoint path (default: 'montoro')
        'endpoint' => 'montoro',

        // Enable/disable modules
        'modules' => [
            'kirby_config' => true,  // Kirby configuration info
            'system_info' => true,   // System and server info
            'packages' => true,      // Composer package versions
        ],

        // System info module configuration
        'system_info' => [
            // Discover public IP address
            'discover_public_ip' => false,

            // Environment variables to report
            'env_variables' => [
                'SMTP_HOST',
                'SMTP_PORT',
            ]
        ],

        // Package versions configuration
        'packages' => [
            // Filter to specific packages (empty = all packages)
            'included_packages' => [
                'getkirby/cms',
            ]
        ]
    ]
];

Usage

Once configured, the monitoring endpoint will be available at:

https://yourdomain.com/montoro

The monitoring server will make POST requests to this endpoint with the API key:

curl -X POST https://yourdomain.com/montoro \
  -d "key=your-api-key"

Modules

Kirby Configuration Module

Reports:

• Site name
• Kirby version
• Base URL
• Multilang status
• Debug mode status
• Environment type

System Information Module

Reports:

• PHP version
• Host IP address
• Memory limit
• Upload max filesize
• Max execution time
• POST max size
• Database type and name (if configured)
• Environment variables (if configured)
• Public IP address (if enabled)

Package Versions Module

Reports:

• All installed Composer packages and versions
• Can be filtered to specific packages

Security

Rate Limiting

The endpoint is rate-limited to 1 request per minute per client IP address. This prevents abuse and excessive requests.

Authentication

Requests must include a valid API key via the key POST parameter. Invalid requests return a 404 error (in production) or 400 error (in debug mode).

IP Whitelisting

Optionally restrict access to specific IP addresses or ranges using the MONITORING_VALID_IP environment variable.

Supported formats:

• Exact IP: 192.168.1.100
• CIDR notation: 192.168.1.0/24
• Wildcards: 192.168.*.*

Encryption

All response data is encrypted using libsodium's sodium_crypto_secretbox with:

• Random nonce for each request
• 50-character integrity hash
• Encryption keys from environment variables

The monitoring server decrypts the response using the same keys.

Response Format

The endpoint returns encrypted data in plain text format:

[encrypted_ciphertext][nonce_hex][hash]

When decrypted and unserialized by the monitoring server, the data structure is:

[
    'clientid' => 'unique-uuid',
    'kirbyconfig' => [...],
    'systeminfo' => [...],
    'packages' => [...]
]

Troubleshooting

404 Error

• Check that environment variables are set correctly
• Verify the API key is correct
• Check IP whitelist configuration
• Enable debug mode to see detailed errors

Rate Limit Errors

Wait 1 minute between requests. The rate limit cache is stored in site/cache/monitoring/.

Encryption Errors

• Verify MONITORING_ENC_SECRET and MONITORING_ENC_SALT are set
• Ensure PHP sodium extension is enabled
• Check that keys match the monitoring server

Composer Lock Not Found

The plugin looks for composer.lock in:

1. Project root (parent of index.php)
2. index.php directory
3. Kirby root directory

Ensure composer.lock exists in one of these locations.

Debug Mode

Enable debug mode in your Kirby config to see detailed error messages:

return [
    'debug' => true,
];

Important: Never enable debug mode in production as it may expose sensitive information.

Compatibility

This plugin is designed to be compatible with the BiffBangPow Silverstripe Monitoring Server. It uses the same:

• Encryption algorithm (libsodium)
• Authentication method (API key)
• Rate limiting (1 request per minute)
• Response format (serialized + encrypted)
• Endpoint path (/montoro)

Development

Creating Custom Modules

Create a class implementing MonitoringClient\Modules\ModuleInterface:

<?php

namespace MonitoringClient\Modules;

class CustomModule implements ModuleInterface
{
    private string $name = 'custom';
    private string $title = 'Custom Module';

    public function getName(): string
    {
        return $this->name;
    }

    public function getTitle(): string
    {
        return $this->title;
    }

    public function getResult(): array
    {
        return [
            $this->getName() => [
                'custom_data' => 'value',
                'another_field' => 'another value'
            ]
        ];
    }
}

Register it in index.php:

$controller->registerModule(new CustomModule());

License

MIT License

Credits

• Based on BiffBangPow Silverstripe Monitoring Client
• Adapted for Kirby CMS

Support

For issues and questions:

• Check the troubleshooting section
• Review environment variables
• Enable debug mode for detailed errors
• Ensure all requirements are met