diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4987e3c..d073a12 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -4,7 +4,7 @@ When generating code for this repository: -1. **Version Compatibility**: This is a Cacti plugin (`tags`, version 0.1) targeting Cacti 1.2.32+ +1. **Version Compatibility**: This is a Cacti plugin (`tags`, version 0.1) targeting Cacti 1.2.29+ 2. **Context Files**: Prioritize patterns and standards defined in this file (`.github/copilot-instructions.md`) 3. **Codebase Patterns**: When context files don't provide specific guidance, scan the codebase for established patterns 4. **Architectural Consistency**: Maintain plugin-based architecture extending Cacti core @@ -24,15 +24,15 @@ When generating code for this repository: ## Project Structure ``` -tags/ # Repository root (install to plugins/tags/ in Cacti) -├── images/ # UI icons (including tags_example.png used in README) -├── include/ # Shared functions/database helpers -├── themes/ # CSS theme overlays -├── tags.php # Main tag administration/list UI -├── poller_tags.php # Background poller entry point (CLI) -├── INFO # Plugin metadata (name, version, compat) +tags/ # Repository root (install to plugins/tags/ in Cacti) +├── images/ # UI icons (including tags_example.png used in README) +├── include/ # Shared functions/database helpers +├── themes/ # CSS theme overlays +├── tags.php # Main tag administration/list UI +├── poller_tags.php # Background poller entry point (CLI) +├── INFO # Plugin metadata (name, version, compat) ├── README.md -└── setup.php # Plugin install/uninstall/upgrade hooks +└── setup.php # Plugin install/uninstall/upgrade hooks ``` ## Naming Conventions @@ -191,3 +191,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, `tags_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 085a0c8..cb70750 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/tags/tests/bin/validate-manifest.php + - name: Run apt-get update run: sudo apt-get update diff --git a/INFO b/INFO index 9f27d3d..e18c1c1 100644 --- a/INFO +++ b/INFO @@ -26,5 +26,5 @@ longname = Tags author = The Cacti Group, Petr Macek email = deverlopers@cacti.net, petr.macek@kostax.cz homepage = https://github.com/xmacan/plugin_tags -compat = 1.2.32 +compat = 1.2.29 capabilities = online_view:1, online_mgmt:1, offline_view:0, offline_mgmt:0, remote_collect:0 diff --git a/themes/common.css b/css/common.css similarity index 100% rename from themes/common.css rename to css/common.css diff --git a/include/database.php b/include/database.php index a56c6af..9581320 100644 --- a/include/database.php +++ b/include/database.php @@ -47,6 +47,10 @@ function plugin_tags_upgrade(): bool { plugin_tags_setup_state_table(); + if ($new != $old) { + tags_prune_files(); + } + return true; } diff --git a/manifest.json b/manifest.json new file mode 100644 index 0000000..af59c3f --- /dev/null +++ b/manifest.json @@ -0,0 +1,21 @@ +{ + "tombstones": [ + "themes/" + ], + "expected": [ + "CHANGELOG.md", + "INFO", + "LICENSE", + "README.md", + "css/", + "images/", + "include/", + "index.php", + "locales/", + "manifest.json", + "poller_tags.php", + "setup.php", + "tags.php" + ], + "whitelist": [] +} diff --git a/phpunit.xml b/phpunit.xml index 2cfb1db..894afc3 100644 --- a/phpunit.xml +++ b/phpunit.xml @@ -28,6 +28,7 @@ setup.php + include/database.php include/functions.php diff --git a/setup.php b/setup.php index 694b998..d54ddea 100644 --- a/setup.php +++ b/setup.php @@ -307,5 +307,175 @@ function plugin_tags_config_settings(): void { function plugin_tags_page_head(): void { global $config; - print get_md5_include_css('plugins/tags/themes/common.css'); + print get_md5_include_css('plugins/tags/css/common.css'); +} + +/** + * 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 tags_prune_files(): void { + global $config; + + $plugin_dir = $config['base_path'] . '/plugins/tags'; + $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: tags manifest.json could not be parsed; skipping file prune', false, 'TAGS'); + + 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: tags prune refused to remove %s: path contains a traversal segment (tampered manifest.json?)', $rel), false, 'TAGS'); + + 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: tags prune refused to remove %s: path resolves outside the plugin directory (tampered manifest.json?)', $rel), false, 'TAGS'); + + continue; + } + + if (is_dir($path) && !is_link($path)) { + $removed = tags_rmtree($path); + } else { + $removed = @unlink($path); + } + + if (!$removed) { + cacti_log(sprintf('WARNING: tags upgrade could not remove %s (check file/directory permissions)', $rel), false, 'TAGS'); + } + } + + // 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: tags upgrade found a file/directory not described in manifest.json: %s (left in place)', $entry), false, 'TAGS'); + } +} + +/** + * Recursively deletes a directory and its contents. Symlinks are removed + * without being followed. Helper for tags_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 tags_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 (!tags_rmtree($path)) { + $ok = false; + } + } elseif (!@unlink($path)) { + $ok = false; + } + } + + if (!@rmdir($dir)) { + $ok = false; + } + + return $ok; } diff --git a/tests/Unit/PruneFilesTest.php b/tests/Unit/PruneFilesTest.php new file mode 100644 index 0000000..181348b --- /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 = tags_prune_fixture($manifest); + $plugin = $base . '/plugins/tags'; + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + try { + tags_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() . '/tags-prune-missing-' . uniqid(); + mkdir($base . '/plugins/tags', 0777, true); + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + try { + tags_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() . '/tags-prune-bad-' . uniqid(); + $plugin = $base . '/plugins/tags'; + 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 { + tags_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 = tags_prune_fixture($manifest); + $plugin = $base . '/plugins/tags'; + $outside = $base . '/plugins/escapee.txt'; + file_put_contents($outside, 'precious user data'); + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + try { + tags_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 = tags_prune_fixture($manifest); + $plugin = $base . '/plugins/tags'; + 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 { + tags_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 = tags_prune_fixture($manifest); + $plugin = $base . '/plugins/tags'; + $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 { + tags_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 = tags_prune_fixture($manifest); + $plugin = $base . '/plugins/tags'; + $restore = $GLOBALS['config']['base_path']; + + $GLOBALS['config']['base_path'] = $base; + + try { + tags_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/TagsCheckConfigTest.php b/tests/Unit/TagsCheckConfigTest.php index c495ea1..a1a9d67 100644 --- a/tests/Unit/TagsCheckConfigTest.php +++ b/tests/Unit/TagsCheckConfigTest.php @@ -13,6 +13,10 @@ beforeAll(function () { require_once __DIR__ . '/../../setup.php'; + // Define plugin_tags_upgrade()/plugin_tags_setup_state_table() from the + // real checkout so check_config() runs while base_path is sandboxed below. + require_once __DIR__ . '/../../include/database.php'; + require_once __DIR__ . '/../../include/functions.php'; }); beforeEach(function () { @@ -20,6 +24,25 @@ $GLOBALS['__test_registered_hooks'] = array(); $GLOBALS['__test_db_fetch_cell_return'] = ''; $GLOBALS['__test_db_fetch_cell_prepared_return'] = ''; + + // Sandbox base_path so plugin_tags_upgrade()'s version-drift prune runs + // 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_tags_version() still matches) and empty include/ stubs the + // check_config()/upgrade() include_once()s can load harmlessly. + $GLOBALS['__tags_base_restore'] = $GLOBALS['config']['base_path']; + $base = sys_get_temp_dir() . '/tags-test-' . uniqid(); + mkdir($base . '/plugins/tags/include', 0777, true); + copy(__DIR__ . '/../../INFO', $base . '/plugins/tags/INFO'); + file_put_contents($base . '/plugins/tags/include/database.php', " array()); $GLOBALS['__test_current_page'] = 'tags.php'; - plugin_tags_config_arrays(); + // Sandbox base_path just for this drift case so tags_prune_files() + // runs against a throwaway tree with no manifest.json (prune no-ops), + // never the real checkout. Pre-load the real library so the upgrade + // functions stay defined while the temp include/ stubs are empty. + require_once __DIR__ . '/../../include/database.php'; + require_once __DIR__ . '/../../include/functions.php'; + $restore = $GLOBALS['config']['base_path']; + $base = sys_get_temp_dir() . '/tags-test-' . uniqid(); + mkdir($base . '/plugins/tags/include', 0777, true); + copy(__DIR__ . '/../../INFO', $base . '/plugins/tags/INFO'); + file_put_contents($base . '/plugins/tags/include/database.php', "