diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0c545e5..b1f34ab 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -24,25 +24,25 @@ When generating code for this repository: ## Project Structure ``` -webseer/ # Repository root (install to plugins/webseer/ in Cacti) -├── classes/ # Supporting PHP classes (cURL, mxlookup) -├── includes/ # Library/helper files, require_once'd from the entry points -│ ├── database.php # Schema management: table defs + create/upgrade/drop helpers -│ ├── functions.php # Shared plugin functions -│ ├── arrays.php # Shared option/label arrays -│ └── constants.php # Shared constants -├── locales/ # Internationalization files -├── tests/ # Test suite -├── ca-bundle.crt # CA bundle for HTTPS endpoint verification -├── poller_webseer.php # Background poller entry point (CLI) -├── remote.php # Remote poller support endpoint -├── webseer.php # Main viewer/administration UI -├── webseer_process.php # Check execution logic -├── webseer_proxies.php # Proxy administration -├── webseer_servers.php # Monitored server/service administration -├── INFO # Plugin metadata (name, version, compat) +webseer/ # Repository root (install to plugins/webseer/ in Cacti) +├── classes/ # Supporting PHP classes (cURL, mxlookup) +├── includes/ # Library/helper files, require_once'd from the entry points +│ ├── database.php # Schema management: table defs + create/upgrade/drop helpers +│ ├── functions.php # Shared plugin functions +│ ├── arrays.php # Shared option/label arrays +│ └── constants.php # Shared constants +├── locales/ # Internationalization files +├── tests/ # Test suite +├── ca-bundle.crt # CA bundle for HTTPS endpoint verification +├── poller_webseer.php # Background poller entry point (CLI) +├── remote.php # Remote poller support endpoint +├── webseer.php # Main viewer/administration UI +├── webseer_process.php # Check execution logic +├── webseer_proxies.php # Proxy administration +├── webseer_servers.php # Monitored server/service administration +├── INFO # Plugin metadata (name, version, compat) ├── README.md -└── setup.php # Plugin install/uninstall/upgrade hooks +└── setup.php # Plugin install/uninstall/upgrade hooks ``` ## Naming Conventions @@ -219,3 +219,7 @@ existing code or adding new code, not just in dedicated cleanup passes: line, `@param` lines, a blank comment line, then `@return`. Infer parameter/return types from actual usage; don't change the function's real type-hints in the same pass (let static analysis flag mismatches separately). Skip vendored third-party library files. + +## File manifest & upgrade pruning + +The plugin ships a root `manifest.json` with three arrays: `tombstones` (files/directories older versions shipped that have since moved or been removed), `expected` (the top-level files and directories that ship today, directories written with a trailing `/`), and `whitelist` (paths holding user data that must never be touched). Keep `expected` current: CI runs `tests/bin/validate-manifest.php`, which fails on any drift between `expected` and the real top-level tree (it ignores `tests/`, `phpunit.xml`, `.git*`, `.md*`, and whitelisted paths). Custom customer CSS/theme files belong in `expected`, and stylesheets live in `css/` (not `themes/`). On upgrade, `webseer_prune_files()` deletes the tombstoned paths, the dev-only `tests/` tree, and the `phpunit.xml` test config, leaves `whitelist`, `.git*`, and `.md*` alone, and logs (without removing) any top-level entry the manifest does not account for. As a safety measure it refuses any tombstone that resolves outside the plugin directory (a tampered manifest.json) and logs a warning for any file or directory it cannot remove. When you move or delete a shipped file, add its old path to `tombstones` and update `expected` in the same change. diff --git a/.github/workflows/plugin-ci-workflow.yml b/.github/workflows/plugin-ci-workflow.yml index ab0d9698..430e0f1 100644 --- a/.github/workflows/plugin-ci-workflow.yml +++ b/.github/workflows/plugin-ci-workflow.yml @@ -89,6 +89,9 @@ jobs: - name: Check PHP version run: php -v + - name: Validate plugin manifest (expected-file drift) + run: php cacti/plugins/webseer/tests/bin/validate-manifest.php + - name: Run apt-get update run: sudo apt-get update diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ad9ccb..0c0e770 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ --- 3.3 --- +* compat: Lower the minimum Cacti compatibility floor from 1.2.32 to 1.2.29 +* issue: Re-introduce the `plugin_webseer_contacts` `user_id_type` UNIQUE key (on `user_id`, `type`) that Cacti 1.2.29-1.2.31's `db_update_table()` silently dropped - those releases rebuild a table's indexes only from its `keys` definition and ignore `unique_keys`. The repair runs automatically on upgrade when running one of those releases and is a no-op on 1.2.32+. WARNING: if duplicate `(user_id, type)` contact rows were inserted while the constraint was absent, re-adding the key fails; the upgrade logs the affected table and leaves the recorded version unchanged so it retries on the next request. To recover, de-duplicate `plugin_webseer_contacts` (keep a single row per `user_id`/`type`) and re-run the upgrade. Sites already upgraded to 1.2.32+ that lost the key on an earlier 1.2.29-1.2.31 run are not auto-repaired +* feature: Add a root `manifest.json` and an upgrade-time file prune that removes dev-only bundled files (e.g. `tests/`) on a version change, refuses any path resolving outside the plugin directory, and logs anything it cannot remove * refactor: Move all schema management into includes/database.php (the thold model) and manage the seven plugin_webseer_* tables through Cacti's plugin table API - create with api_plugin_db_table_create() and refresh existing tables with db_update_table() from a single shared definition, replacing the raw CREATE TABLE/version-gated ALTER TABLE migrations (the historical plugin_webseer_url_log -> plugin_webseer_urls_log rename is kept as a guarded pre-step); the upgrade path now also updates the full plugin_config row. Also switches every file inclusion from include/include_once to require/require_once * dev: Measure CI coverage with xdebug instead of pcov so the plugin's own sources are instrumented (pcov auto-scopes to the Composer root and skipped cacti/plugins/, leaving the patch-coverage gate with nothing to measure) * dev: Enforce patch coverage of changed lines in CI and remove the inert COMPOSER_ROOT_VERSION env from the Pest step diff --git a/INFO b/INFO index b21476f..5329dad 100644 --- a/INFO +++ b/INFO @@ -26,5 +26,5 @@ longname = Service Monitor author = The Cacti Group email = jimmy@sqmail.org homepage = http://cactiusers.org -compat = 1.2.32 +compat = 1.2.29 capabilities = online_view:1, online_mgmt:1, offline_view:0, offline_mgmt:0, remote_collect:1 diff --git a/README.md b/README.md index 2da0095..e0b90c3 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,16 @@ this, goto Cacti's Plugin Management page, Install and Enable the webseer. Once this is complete, you can grant users permission to create service checks for various Web Sites and Services. +## Upgrading + +`poller_webseer.php` runs as a long-lived background process, so a running copy +keeps the old code in memory across a plugin upgrade. After upgrading the plugin +files, restart the webseer background process (stop the running +`poller_webseer.php`; Cacti's poller relaunches it on the next cycle) so it +picks up the new code. On upgrade the plugin also prunes its own bundled +development-only files (for example the `tests/` directory) from the installed +tree. + ## Bugs and Feature Enhancements Bug and feature enhancements for the webseer plugin are handled in GitHub. If diff --git a/includes/database.php b/includes/database.php index 58fbdaa..47bbb58 100644 --- a/includes/database.php +++ b/includes/database.php @@ -280,9 +280,11 @@ function plugin_webseer_setup_table() { * is applied as a guarded pre-step first. Called from * plugin_webseer_upgrade() when the stored version changes. * - * @return void + * @return bool True if the refresh (including any compensating UNIQUE-key + * re-add) fully succeeded; false if a unique key could not be + * restored, so the caller can defer version bookkeeping. */ -function webseer_upgrade_tables() { +function webseer_upgrade_tables(): bool { // db_update_table() can not rename, so carry the historical URL-log // table rename (and its data) forward before the schema refresh. if (db_table_exists('plugin_webseer_url_log') && !db_table_exists('plugin_webseer_urls_log')) { @@ -296,6 +298,57 @@ function webseer_upgrade_tables() { api_plugin_db_table_create('webseer', $table, $data); } } + + return webseer_reintroduce_unique_keys(); +} + +/** + * Cacti 1.2.29 through 1.2.31 shipped a db_update_table() that silently + * dropped UNIQUE keys declared via a table definition's 'unique_keys' (it + * rebuilds indexes only from 'keys'). Re-add this plugin's unique keys when + * running on one of those releases; 1.2.32+ preserves them, so this is a + * no-op there. Uses Cacti's db_add_index() (available since 1.2.29) and + * skips any key that already exists. When a key cannot be re-added - almost + * always because duplicate rows were inserted while the constraint was + * absent - the failure is logged with remediation steps and reported to the + * caller so version bookkeeping can be deferred and the repair retried. + * + * @return bool True if every applicable unique key is present (or the gate + * does not apply); false if any key could not be re-added. + */ +function webseer_reintroduce_unique_keys(): bool { + $running = trim((string) db_fetch_cell('SELECT cacti FROM version LIMIT 1')); + + if ($running === '' || + !cacti_version_compare($running, '1.2.29', '>=') || + !cacti_version_compare($running, '1.2.32', '<')) { + return true; + } + + $unique_keys = [ + ['table' => 'plugin_webseer_contacts', 'name' => 'user_id_type', 'columns' => ['user_id', 'type']], + ]; + + $ok = true; + + foreach ($unique_keys as $uk) { + if (db_index_exists($uk['table'], $uk['name'])) { + continue; + } + + if (!db_add_index($uk['table'], 'UNIQUE', $uk['name'], $uk['columns'])) { + $ok = false; + + cacti_log(sprintf('ERROR: webseer could not re-add UNIQUE key `%s` on `%s` (%s). ' + . 'This happens only when duplicate (%s) rows were inserted while the constraint ' + . 'was absent on Cacti 1.2.29-1.2.31; de-duplicate the table, then re-run the upgrade ' + . 'to restore it.', + $uk['name'], $uk['table'], implode(', ', $uk['columns']), implode(', ', $uk['columns'])), + false, 'WEBSEER'); + } + } + + return $ok; } /** diff --git a/manifest.json b/manifest.json new file mode 100644 index 0000000..80ee0b8 --- /dev/null +++ b/manifest.json @@ -0,0 +1,24 @@ +{ + "tombstones": [], + "expected": [ + "CHANGELOG.md", + "INFO", + "LICENSE", + "README.md", + "ca-bundle.crt", + "classes/", + "images/", + "includes/", + "index.php", + "locales/", + "manifest.json", + "poller_webseer.php", + "remote.php", + "setup.php", + "webseer.php", + "webseer_process.php", + "webseer_proxies.php", + "webseer_servers.php" + ], + "whitelist": [] +} diff --git a/setup.php b/setup.php index 8bc6044..f0ad348 100644 --- a/setup.php +++ b/setup.php @@ -103,7 +103,9 @@ function plugin_webseer_check_config() { * proxies tables, renaming the URL log table, adding compression/ * notify-format/poller-id columns) and updates the recorded plugin * version/realm file list, based on comparing the installed version - * against the current INFO file version. Called from + * against the current INFO file version. If webseer_upgrade_tables() + * reports a failed compensating UNIQUE-key repair, the recorded version is + * left unchanged so the repair retries on a later request. Called from * plugin_webseer_check_config(), which is itself only invoked when the * current page is index.php, plugins.php, or webseer.php. * @@ -134,7 +136,14 @@ function plugin_webseer_upgrade() { // create any missing tables, db_update_table() diff the rest. The historical // plugin_webseer_url_log -> plugin_webseer_urls_log rename (and the column // additions that were previously hand-written ALTERs) are handled there. - webseer_upgrade_tables(); + if (!webseer_upgrade_tables()) { + // A compensating repair (re-adding a UNIQUE key that Cacti + // 1.2.29-1.2.31 dropped) failed - almost always because of + // pre-existing duplicate rows. Leave the stored version unchanged + // so the upgrade retries on the next request once the operator + // de-duplicates; the actionable details are already in the Cacti log. + return true; + } db_execute_prepared('UPDATE plugin_config SET version = ?, name = ?, author = ?, webpage = ? @@ -154,6 +163,8 @@ function plugin_webseer_upgrade() { ['webseer.php,webseer_servers.php,webseer_proxies.php']); api_plugin_register_hook('webseer', 'replicate_out', 'webseer_replicate_out', 'setup.php', '1'); + + webseer_prune_files(); } return true; @@ -350,3 +361,173 @@ function webseer_replicate_out($data) { return $data; } + +/** + * Removes files and directories that a previous version of this plugin + * shipped but that have since moved or been deleted, using the tombstone + * and whitelist lists in manifest.json. Whitelisted (user-data) paths and + * any VCS metadata (.git*) are never touched; the dev-only tests/ tree is + * removed. Any path that resolves outside the plugin directory (a tampered + * manifest.json) is refused, and any file/directory that cannot be removed + * (e.g. read-only) is reported to the Cacti log. Any top-level entry that is + * neither expected nor a tombstone nor whitelisted is logged to the Cacti + * log and left in place. Called on a plugin version change. + * + * @return void + * + * @global array $config Cacti global configuration array; used to resolve + * the plugin directory. + */ +function webseer_prune_files(): void { + global $config; + + $plugin_dir = $config['base_path'] . '/plugins/webseer'; + $manifest_path = $plugin_dir . '/manifest.json'; + + if (!is_readable($manifest_path)) { + return; + } + + $manifest = json_decode((string) file_get_contents($manifest_path), true); + + if (!is_array($manifest)) { + cacti_log('WARNING: webseer manifest.json could not be parsed; skipping file prune', false, 'WEBSEER'); + + return; + } + + $tombstones = isset($manifest['tombstones']) && is_array($manifest['tombstones']) ? $manifest['tombstones'] : []; + $expected = isset($manifest['expected']) && is_array($manifest['expected']) ? $manifest['expected'] : []; + $whitelist = isset($manifest['whitelist']) && is_array($manifest['whitelist']) ? $manifest['whitelist'] : []; + + $protected = function (string $rel) use ($whitelist): bool { + if (strncmp($rel, '.git', 4) === 0 || strncmp($rel, '.md', 3) === 0) { + return true; + } + + foreach ($whitelist as $entry) { + $entry = trim((string) $entry, '/'); + + if ($entry !== '' && ($rel === $entry + || strncmp($rel, $entry . '/', strlen($entry) + 1) === 0 + || strncmp($entry, $rel . '/', strlen($rel) + 1) === 0)) { + return true; + } + } + + return false; + }; + + // Security: resolve the plugin directory so a tampered manifest.json + // cannot steer the prune outside of it. + $plugin_real = realpath($plugin_dir); + + // Remove tombstoned (moved/deleted) paths plus the dev-only tests/ + // tree and the phpunit.xml test configuration. + $remove = $tombstones; + $remove[] = 'tests/'; + $remove[] = 'phpunit.xml'; + + foreach ($remove as $rel) { + $rel = trim((string) $rel, '/'); + + if ($rel === '' || $protected($rel)) { + continue; + } + + // A tombstone must never contain '.'/'..' segments; a tampered manifest + // could use them to escape the plugin directory or target its root. + $segments = explode('/', $rel); + + if (in_array('.', $segments, true) || in_array('..', $segments, true)) { + cacti_log(sprintf('WARNING: webseer prune refused to remove %s: path contains a traversal segment (tampered manifest.json?)', $rel), false, 'WEBSEER'); + + continue; + } + + $path = $plugin_dir . '/' . $rel; + + if (!is_link($path) && !file_exists($path)) { + continue; + } + + // Refuse any path that, after resolving symlinks and ../ segments, + // escapes the plugin directory (protects user data from a tampered + // manifest.json). + $anchor = is_link($path) ? dirname($path) : $path; + $real = realpath($anchor); + + if ($real === false || ($real !== $plugin_real && strncmp($real, $plugin_real . DIRECTORY_SEPARATOR, strlen((string) $plugin_real) + 1) !== 0)) { + cacti_log(sprintf('WARNING: webseer prune refused to remove %s: path resolves outside the plugin directory (tampered manifest.json?)', $rel), false, 'WEBSEER'); + + continue; + } + + if (is_dir($path) && !is_link($path)) { + $removed = webseer_rmtree($path); + } else { + $removed = @unlink($path); + } + + if (!$removed) { + cacti_log(sprintf('WARNING: webseer upgrade could not remove %s (check file/directory permissions)', $rel), false, 'WEBSEER'); + } + } + + // Surface any top-level entry the manifest does not account for. + $known = []; + + foreach (array_merge($expected, $tombstones) as $entry) { + $top = explode('/', trim((string) $entry, '/'))[0]; + + if ($top !== '') { + $known[$top] = true; + } + } + + $entries = scandir($plugin_dir); + + foreach (($entries !== false ? $entries : []) as $entry) { + if ($entry === '.' || $entry === '..' || $entry === 'tests' || $entry === 'phpunit.xml' || $protected($entry) || isset($known[$entry])) { + continue; + } + + cacti_log(sprintf('WARNING: webseer upgrade found a file/directory not described in manifest.json: %s (left in place)', $entry), false, 'WEBSEER'); + } +} + +/** + * Recursively deletes a directory and its contents. Symlinks are removed + * without being followed. Helper for webseer_prune_files(). + * + * @param string $dir Absolute path to the directory to remove. + * + * @return bool True if the directory and everything under it was removed; + * false if any entry could not be deleted. + */ +function webseer_rmtree(string $dir): bool { + $entries = scandir($dir); + $ok = true; + + foreach (($entries !== false ? $entries : []) as $entry) { + if ($entry === '.' || $entry === '..') { + continue; + } + + $path = $dir . '/' . $entry; + + if (is_dir($path) && !is_link($path)) { + if (!webseer_rmtree($path)) { + $ok = false; + } + } elseif (!@unlink($path)) { + $ok = false; + } + } + + if (!@rmdir($dir)) { + $ok = false; + } + + return $ok; +} diff --git a/tests/Integration/PluginLifecycleTest.php b/tests/Integration/PluginLifecycleTest.php index b3931eb..0035598 100644 --- a/tests/Integration/PluginLifecycleTest.php +++ b/tests/Integration/PluginLifecycleTest.php @@ -17,12 +17,34 @@ */ require_once dirname(__DIR__, 2) . '/setup.php'; +// Define webseer_upgrade_tables() from the real checkout so +// plugin_webseer_upgrade() runs while base_path is sandboxed below. +require_once dirname(__DIR__, 2) . '/includes/database.php'; // tests/Pest.php's beforeEach isn't reliably discovered under this plugin's CI // invocation (pest run from the cacti root via --configuration=plugins/...), // so register it here too to guarantee a clean call log between tests in this file. beforeEach(function () { webseer_test_reset_db_mocks(); + + // Sandbox base_path so the version-drift branch runs + // webseer_prune_files() against a throwaway tree with no + // manifest.json (prune no-ops), never the real checkout. The temp tree + // carries a copy of the real INFO (so plugin_webseer_version() still + // matches) and an empty includes/database.php the upgrade's top-level + // require_once can load harmlessly. + $GLOBALS['__webseer_base_restore'] = $GLOBALS['config']['base_path']; + $base = sys_get_temp_dir() . '/webseer-itest-' . uniqid(); + mkdir($base . '/plugins/webseer/includes', 0777, true); + copy(dirname(__DIR__, 2) . '/INFO', $base . '/plugins/webseer/INFO'); + file_put_contents($base . '/plugins/webseer/includes/database.php', "not->toBeEmpty(); }); + +it('leaves the recorded version unchanged when a unique-key repair fails on upgrade', function () { + // Drift plus a Cacti 1.2.29-1.2.31 run where the compensating UNIQUE-key + // re-add fails (as it would against pre-existing duplicate rows). + webseer_test_mock_db('db_fetch_cell', 'plugin_config', '1.0'); + webseer_test_mock_db('db_fetch_cell', 'SELECT cacti FROM version', '1.2.30'); + webseer_test_mock_db('db_add_index', 'plugin_webseer_contacts', false); + + plugin_webseer_upgrade(); + + $version_updates = array_filter( + $GLOBALS['__test_db_calls'], + fn ($call) => $call['fn'] === 'db_execute_prepared' && strpos($call['sql'], 'UPDATE plugin_config') !== false + ); + + expect($version_updates)->toBeEmpty(); + expect(implode("\n", $GLOBALS['__test_cacti_log'] ?? []))->toContain('could not re-add UNIQUE key'); +}); diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php new file mode 100644 index 0000000..015d6df --- /dev/null +++ b/tests/Unit/PruneFilesTest.php @@ -0,0 +1,255 @@ + ['include/', 'oldfile.php', 'userdata/', 'gone.png'], + 'expected' => ['INFO', 'setup.php', 'includes/', 'manifest.json'], + 'whitelist' => ['userdata/'], + ]; + + $base = webseer_prune_fixture($manifest); + $plugin = $base . '/plugins/webseer'; + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + try { + webseer_prune_files(); + } finally { + $GLOBALS['config']['base_path'] = $restore; + } + + // Tombstone and the dev-only tests/ tree are gone. + expect(is_dir($plugin . '/include'))->toBeFalse(); + expect(is_dir($plugin . '/tests'))->toBeFalse(); + expect(is_file($plugin . '/oldfile.php'))->toBeFalse(); + expect(is_file($plugin . '/phpunit.xml'))->toBeFalse(); + + // Whitelisted user data, VCS metadata, and expected files are untouched. + // (userdata/ is even listed as a tombstone, but the whitelist wins.) + expect(is_file($plugin . '/userdata/keep.dat'))->toBeTrue(); + expect(is_dir($plugin . '/.git'))->toBeTrue(); + expect(is_file($plugin . '/INFO'))->toBeTrue(); + expect(is_dir($plugin . '/includes'))->toBeTrue(); + expect(is_file($plugin . '/.mdlrc'))->toBeTrue(); + expect(is_file($plugin . '/.md_style.rb'))->toBeTrue(); + + // An unexpected, non-whitelisted stray is left in place but logged. + expect(is_file($plugin . '/stray.php'))->toBeTrue(); + + $logged = implode("\n", $GLOBALS['__test_cacti_log']); + expect($logged)->toContain('stray.php'); + expect($logged)->not->toContain('userdata'); + expect($logged)->not->toContain('.git'); + expect($logged)->not->toContain('.mdlrc'); + expect($logged)->not->toContain('.md_style.rb'); +}); + +it('is a safe no-op when the manifest is missing', function () { + $base = sys_get_temp_dir() . '/webseer-prune-missing-' . uniqid(); + mkdir($base . '/plugins/webseer', 0777, true); + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + try { + webseer_prune_files(); + } finally { + $GLOBALS['config']['base_path'] = $restore; + } + + expect($GLOBALS['__test_cacti_log'])->toBe([]); +}); + +it('logs and skips pruning when the manifest is malformed', function () { + $base = sys_get_temp_dir() . '/webseer-prune-bad-' . uniqid(); + $plugin = $base . '/plugins/webseer'; + mkdir($plugin, 0777, true); + file_put_contents($plugin . '/manifest.json', 'not json'); + mkdir($plugin . '/tests', 0777, true); + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + try { + webseer_prune_files(); + } finally { + $GLOBALS['config']['base_path'] = $restore; + } + + // A malformed manifest must not delete anything. + expect(is_dir($plugin . '/tests'))->toBeTrue(); + expect(implode("\n", $GLOBALS['__test_cacti_log']))->toContain('could not be parsed'); +}); + +it('refuses to remove a tombstone that resolves outside the plugin directory', function () { + $manifest = [ + 'tombstones' => ['../escapee.txt'], + 'expected' => ['manifest.json'], + 'whitelist' => [], + ]; + + $base = webseer_prune_fixture($manifest); + $plugin = $base . '/plugins/webseer'; + $outside = $base . '/plugins/escapee.txt'; + file_put_contents($outside, 'precious user data'); + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + try { + webseer_prune_files(); + } finally { + $GLOBALS['config']['base_path'] = $restore; + } + + // The out-of-tree file is untouched and the refusal is logged. + expect(is_file($outside))->toBeTrue(); + expect(implode("\n", $GLOBALS['__test_cacti_log']))->toContain('a traversal segment'); +}); + +it('warns when a tombstoned path cannot be removed', function () { + $manifest = [ + 'tombstones' => ['locked/'], + 'expected' => ['manifest.json'], + 'whitelist' => [], + ]; + + $base = webseer_prune_fixture($manifest); + $plugin = $base . '/plugins/webseer'; + mkdir($plugin . '/locked/sub', 0777, true); + file_put_contents($plugin . '/locked/sub/data', 'x'); + chmod($plugin . '/locked/sub', 0500); // read-only dir: its child cannot be unlinked + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + set_error_handler(static fn () => true); // swallow the expected unlink warning + + try { + webseer_prune_files(); + } finally { + restore_error_handler(); + $GLOBALS['config']['base_path'] = $restore; + @chmod($plugin . '/locked/sub', 0700); + } + + expect(implode("\n", $GLOBALS['__test_cacti_log']))->toContain('could not remove'); +})->skip(function () { + return function_exists('posix_getuid') && posix_getuid() === 0; +}, 'permission checks are bypassed for the root user'); + +it('refuses a tombstone that escapes through a symlinked directory', function () { + $manifest = [ + 'tombstones' => ['escdir/secret.txt'], + 'expected' => ['manifest.json'], + 'whitelist' => [], + ]; + + $base = webseer_prune_fixture($manifest); + $plugin = $base . '/plugins/webseer'; + $outside = $base . '/outside'; + mkdir($outside, 0777, true); + file_put_contents($outside . '/secret.txt', 'precious user data'); + @symlink($outside, $plugin . '/escdir'); + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + try { + webseer_prune_files(); + } finally { + $GLOBALS['config']['base_path'] = $restore; + } + + // The out-of-tree file reached through the symlink is untouched and logged. + expect(is_file($outside . '/secret.txt'))->toBeTrue(); + expect(implode("\n", $GLOBALS['__test_cacti_log']))->toContain('outside the plugin directory'); +})->skip(function () { + $probe = sys_get_temp_dir() . '/.prune-symlink-probe-' . uniqid(); + $ok = @symlink(__FILE__, $probe); + @unlink($probe); + + return $ok === false; +}, 'symlinks are not supported on this filesystem'); + +it('protects a whitelisted file from a tombstone on its parent directory', function () { + $manifest = [ + 'tombstones' => ['userdata/'], + 'expected' => ['manifest.json'], + 'whitelist' => ['userdata/keep.dat'], + ]; + + $base = webseer_prune_fixture($manifest); + $plugin = $base . '/plugins/webseer'; + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + try { + webseer_prune_files(); + } finally { + $GLOBALS['config']['base_path'] = $restore; + } + + // A whitelisted file shields its parent directory from a tombstone. + expect(is_file($plugin . '/userdata/keep.dat'))->toBeTrue(); +}); diff --git a/tests/Unit/ReintroduceUniqueKeysTest.php b/tests/Unit/ReintroduceUniqueKeysTest.php new file mode 100644 index 0000000..e160d21 --- /dev/null +++ b/tests/Unit/ReintroduceUniqueKeysTest.php @@ -0,0 +1,101 @@ + 'db_add_index', 'sql' => '.', + * 'params' => ['type' => , 'columns' => ]]. + * + * @return array The + * matching call records, re-indexed from zero. + */ +function webseer_uk_added_indexes(): array { + return array_values(array_filter($GLOBALS['__test_db_calls'], function ($call) { + return $call['fn'] === 'db_add_index'; + })); +} + +it('re-adds the contacts unique key when running Cacti 1.2.30', function () { + webseer_test_mock_db('db_fetch_cell', 'SELECT cacti FROM version', '1.2.30'); + + expect(webseer_reintroduce_unique_keys())->toBeTrue(); + + $added = webseer_uk_added_indexes(); + expect($added)->toHaveCount(1); + expect($added[0]['sql'])->toContain('plugin_webseer_contacts') + ->and($added[0]['sql'])->toContain('user_id_type') + ->and($added[0]['params']['type'])->toBe('UNIQUE') + ->and($added[0]['params']['columns'])->toBe(['user_id', 'type']); +}); + +it('does nothing on Cacti 1.2.32 and later', function () { + webseer_test_mock_db('db_fetch_cell', 'SELECT cacti FROM version', '1.2.32'); + + expect(webseer_reintroduce_unique_keys())->toBeTrue(); + expect(webseer_uk_added_indexes())->toHaveCount(0); +}); + +it('does nothing on Cacti releases before 1.2.29', function () { + webseer_test_mock_db('db_fetch_cell', 'SELECT cacti FROM version', '1.2.28'); + + expect(webseer_reintroduce_unique_keys())->toBeTrue(); + expect(webseer_uk_added_indexes())->toHaveCount(0); +}); + +it('does not re-add a unique key that already exists', function () { + webseer_test_mock_db('db_fetch_cell', 'SELECT cacti FROM version', '1.2.30'); + webseer_test_mock_db('db_index_exists', 'plugin_webseer_contacts', true); + + expect(webseer_reintroduce_unique_keys())->toBeTrue(); + expect(webseer_uk_added_indexes())->toHaveCount(0); +}); + +it('reports failure and logs remediation when the unique key cannot be re-added', function () { + webseer_test_mock_db('db_fetch_cell', 'SELECT cacti FROM version', '1.2.30'); + webseer_test_mock_db('db_add_index', 'plugin_webseer_contacts', false); + + expect(webseer_reintroduce_unique_keys())->toBeFalse(); + + $logged = implode("\n", $GLOBALS['__test_cacti_log']); + expect($logged)->toContain('could not re-add UNIQUE key') + ->and($logged)->toContain('de-duplicate'); +}); diff --git a/tests/Unit/SetupHelpersGapsTest.php b/tests/Unit/SetupHelpersGapsTest.php index 53d1d15..c9d4dbd 100644 --- a/tests/Unit/SetupHelpersGapsTest.php +++ b/tests/Unit/SetupHelpersGapsTest.php @@ -29,6 +29,25 @@ beforeEach(function () { webseer_test_reset_db_mocks(); $GLOBALS['__test_exec_calls'] = []; + + // Sandbox base_path so the version-drift branch runs + // webseer_prune_files() against a throwaway tree with no + // manifest.json (prune no-ops), never the real checkout. The temp tree + // carries a copy of the real INFO (so plugin_webseer_version() still + // matches) and an empty includes/database.php the upgrade's top-level + // require_once can load harmlessly. + $GLOBALS['__webseer_base_restore'] = $GLOBALS['config']['base_path']; + $base = sys_get_temp_dir() . '/webseer-test-' . uniqid(); + mkdir($base . '/plugins/webseer/includes', 0777, true); + copy(__DIR__ . '/../../INFO', $base . '/plugins/webseer/INFO'); + file_put_contents($base . '/plugins/webseer/includes/database.php', " $type, 'columns' => $columns], true); + } +} + +if (!function_exists('cacti_version_compare')) { + function cacti_version_compare($version1, $version2, $operator = '>') { + return version_compare($version1, $version2, $operator); } } @@ -322,6 +334,7 @@ function __esc($text, $domain = '') { if (!function_exists('cacti_log')) { function cacti_log($message, $also_print = false, $log_type = '', $level = 0) { $GLOBALS['__test_log_calls'][] = ['message' => $message, 'also_print' => $also_print, 'log_type' => $log_type, 'level' => $level]; + $GLOBALS['__test_cacti_log'][] = (string) $message; } }