diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c565e5..4655035 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ --- develop --- +* feature: Add per-account WinRM overrides, native PDH collection, poll health summaries, and bounded WMI response sizes +* issue: Configure CIM/WinRM defaults and clear stale cache values after successful empty results +* issue: Keep composite WMI cache indexes distinct, bound stalled PowerShell collectors, and document supported Windows transport requirements * dev: Run the CI poller with the shared runner group so RRD files and structured directories pass permission verification * dev: Extend the end-to-end fake wmic with --authentication-file and a stderr line, and cover host validation, the credentials file and the script-server scripts end to end * issue: Point the script-server resource and its scripts at the files that exist, load Cacti from where it is, and register the wmic path as the path_wmi setting (default /usr/bin/wmic) diff --git a/INFO b/INFO index f89d679..d045933 100644 --- a/INFO +++ b/INFO @@ -21,7 +21,7 @@ [info] name = wmi -version = 1.0 +version = 1.1 longname = WMI Information Collector author = The Cacti Group email = diff --git a/README.md b/README.md index 9b740f4..944a58b 100644 --- a/README.md +++ b/README.md @@ -77,10 +77,13 @@ Linux. ## Upgrade Replace the plugin files. Cacti does not call the plugin's -`plugin_wmi_upgrade()` function (a search of Cacti 1.2.x and develop finds no -caller), so nothing runs on upgrade. Files that a newer release no longer -ships (`functions.php` and `linux_wmi.php` in the plugin root, listed under -`tombstones` in `manifest.json`) are not removed; delete them by hand. +`plugin_wmi_upgrade()` function during ordinary page loads. Cacti runs it when +the plugin version changes during its database audit/upgrade process. This +release provisions the WinRM account and poll-health columns through the +idempotent plugin schema setup. Run the Cacti database audit/upgrade after +replacing the files. Files that a newer release no longer ships (`functions.php` +and `linux_wmi.php` in the plugin root, listed under `tombstones` in +`manifest.json`) are not removed; delete them by hand. ## Disable and uninstall @@ -98,26 +101,97 @@ server's operating system. Code that constructs `Linux_WMI` directly can pass an explicit transport instead. - **wmic** (default on a Linux server). Uses the Linux `wmic` client to reach - Windows hosts over DCOM. The client does not appear in the Debian 12 or Ubuntu - 18.04 package lists, so install it from your own package source or build - it. The Query Tool and the poller take the binary from the `path_wmi` - setting and use `/usr/bin/wmic` when it is empty; `path_wmi` has no field on - the Settings page yet. `wmi_script.php` always uses `/usr/bin/wmic`, and `script/wmi-script.php` - looks for a `wmic` inside the plugin directory, which is not shipped. The - user name and password are passed to `wmic` as `--user` and `--password` - arguments, so a local user can read them in the process list while a query - runs. This client predates current Windows hardening. Hosts that disable - NTLMv1 or enforce the DCOM packet-integrity level (KB5004442, enforced - without an opt-out since March 2023) may reject it. There is currently no - console setting to switch a Linux Cacti server to the PowerShell transport; - it is only available to code that constructs `Linux_WMI` directly and - passes an explicit transport. + Windows hosts over DCOM. Windows 11 24H2 and later no longer include the + Windows WMIC utility, but WMI itself remains supported. The utility's + removal does not remove the remote WMI service used by this Linux-side + client ([Microsoft's WMIC and WMI notes](https://learn.microsoft.com/en-us/windows/win32/wmisdk/wmic)). + Hosts that enforce current DCOM authentication hardening may still reject + this legacy transport. The client does not appear in the Debian 12 or + Ubuntu 18.04 package lists, so install it from your own package source or + build it. The Query Tool and poller use `path_wmi`, defaulting to + `/usr/bin/wmic`; there is no Settings page field for this path yet. + Credentials normally go in a private temporary authentication file. If the + plugin cannot create that file, it warns and falls back to `--user` and + `--password` arguments, which local users may see in the process list. - **PowerShell / CIM** (default on a Windows server). Runs `powershell.exe` - and uses `Get-CimInstance`, so it works when Cacti runs on Windows and - against a remote host over WinRM/CIM. Needs PowerShell on the Cacti server - and, for a remote host, WinRM enabled on the target. Credentials and every - device-supplied value are passed through the child process environment and a - fixed script on standard input, never on the command line. + and uses `Get-CimInstance`. This transport requires the Cacti server to run + Windows. Microsoft's [Get-CimInstance platform requirements](https://learn.microsoft.com/en-us/powershell/module/cimcmdlets/get-ciminstance?view=powershell-7.5) + document the CIM cmdlets as Windows-only. Remote Windows targets need WinRM + configured and reachable. Use Kerberos with domain hostnames where + available. For connections without Kerberos, configure WinRM HTTPS or a + narrowly scoped TrustedHosts entry ([PowerShell remoting guidance](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_remote_troubleshooting?view=powershell-7.5)). + The Authentication account form can override SSL, port, and authentication + per credential account, or inherit the Settings > Misc defaults. Basic is + rejected unless HTTPS is selected; certificate validation remains enabled. + Leave the port blank to use the Windows default for the selected transport. + Credentials and device-supplied values pass through the child process + environment and a fixed script on standard input, never on the command line. + +### Windows performance counter collection + +For classic performance counter WMI classes, query the +[`Win32_PerfFormattedData_*` classes](https://learn.microsoft.com/en-us/windows/win32/wmisdk/wmi-tasks--performance-monitoring) +classes for provider-formatted values (for example, `Win32_PerfFormattedData_PerfOS_Processor`). +Use a Cacti polling interval appropriate to the signal and avoid collecting +high-cardinality instance data more frequently than needed. Microsoft notes +that many raw performance counters require two timestamped samples and a +counter-specific time base; this plugin runs independent WQL queries and does +not keep PDH sample state, so it must not derive rates from raw values itself. +If collecting monotonic raw totals, configure the Cacti data source as a +`COUNTER` or `DERIVE` where appropriate so RRDtool computes a rate and handles +counter behavior. Choose `COUNTER` only when its wrap assumptions match the +counter; use `DERIVE` when negative deltas are meaningful. Neither data source +can infer Windows counter metadata from an arbitrary WMI field. Use `GAUGE` for +point-in-time and already formatted values. + +For process-level counters on Windows 11 and newer, Microsoft recommends the +Process V2 counter set because its instance names include the process ID and +avoid ambiguities when processes with the same name exit and start. Process V2 +is a PDH counter set and is not exposed by this plugin's current generic CIM +WQL transport; use a native PDH/PerfMon collector for that data. Microsoft's +Windows Server performance guidance also shows bounded `logman` counter logs +with 15-second sampling for troubleshooting, while System Insights uses +15-minute intervals for its retained server telemetry. Choose the sampling +interval based on the operational need and Cacti poller load. + +To collect a native PDH counter, create a query with `PDH` as its namespace and +one or more counter paths, one per line, in the Query field. The Windows-hosted +PowerShell collector invokes `Get-Counter` remotely over WinRM, collects two +samples one second apart, and returns the formatted value and timestamp from +the second sample. For Windows 11 process monitoring, paths from the Process V2 +counter set include the process ID in the instance name; set the query's primary +key to `Path,Instance` so the cache keeps each counter instance distinct. This mode requires +PowerShell remoting enabled on the target and is available only when Cacti runs +the collector on Windows. Do not use raw PDH counter paths with the WQL query +mode. + +Suggested starting WQL inventory and counter queries include: + +- `SELECT Caption,Version,BuildNumber,OSArchitecture,LastBootUpTime FROM Win32_OperatingSystem` +- `SELECT Name,PercentProcessorTime FROM Win32_PerfFormattedData_PerfOS_Processor` +- `SELECT AvailableMBytes,CommittedBytes,CommitLimit FROM Win32_PerfFormattedData_PerfOS_Memory` +- `SELECT Name,PercentDiskTime,AvgDiskQueueLength FROM Win32_PerfFormattedData_PerfDisk_LogicalDisk` + +These are starting points. Confirm that a class and property exists on the +target Windows version and avoid broad process or interface queries unless the +result cardinality and output size are needed. Each transport stops a query +whose response exceeds 16 MiB. + +The WMI Queries list reports the number of devices with poll history, most recent poll, +currently failing devices, and cumulative timeout count. Query failures retain +the previous cached values and record a bounded error summary. Consecutive +failure counts reset after the next successful poll. + +### Windows validation matrix + +Before releasing changes to the Windows transport, run the collector from a +Windows Server Cacti host against a current Windows 11 target and Windows +Server 2025 target. Verify WQL collection over HTTP/Negotiate and HTTPS/Kerberos, +Basic over HTTPS, a rejected Basic-over-HTTP configuration, alternate ports, +invalid credentials, denied counter paths, empty results, response-size limits, +timeouts, and Process V2 paths with `Path,Instance` as the primary key. This is +a manual lab matrix; the plugin's current CI does not run on Windows and these +target combinations are not claimed as tested here. ## Usage @@ -143,9 +217,13 @@ WMI Queries that are specific to Windows SQL Server there. The plugin registers a WMI Management realm covering account management, query definition, and the query tool. The Template Editor role is additionally granted the query-definition page only; credential management and the live query -tool stay behind the WMI Management realm. The poller needs the host password -in cleartext, so accounts are stored reversibly (base64 of a serialized array), -not hashed or encrypted; protect the database accordingly. +tool stay behind the WMI Management realm. The poller needs the host password +in cleartext, so account passwords are stored reversibly (base64 of a serialized +array), not encrypted at rest. No cross-version Cacti secret-storage API is +available to this plugin. Restrict database access to the Cacti service +accounts, keep database traffic on a protected network, encrypt database +backups, and protect `config.php` and its database credentials with filesystem +permissions. A database dump includes the reversible WMI credentials. ## Settings diff --git a/includes/database.php b/includes/database.php index a63d72c..01df346 100644 --- a/includes/database.php +++ b/includes/database.php @@ -29,7 +29,8 @@ * host_wmi_cache, wmi_processes), and registers this plugin's two Data * Input Methods ('Get WMI Data' and 'Get WMI Data (Indexed)') along with * their input/output fields, if not already present. Called from - * plugin_wmi_install() during plugin installation. + * plugin_wmi_install() during installation and plugin_wmi_upgrade() during + * upgrades. * * @return void */ @@ -50,6 +51,9 @@ function plugin_wmi_setup_tables() { `name` varchar(64) NOT NULL, `username` varchar(64) NOT NULL, `password` varchar(256) NOT NULL, + `winrm_ssl` varchar(8) NOT NULL DEFAULT 'inherit', + `winrm_port` varchar(5) NOT NULL DEFAULT '', + `winrm_auth` varchar(16) NOT NULL DEFAULT 'inherit', PRIMARY KEY (`id`)) ENGINE=InnoDB COMMENT='Holds Account Information for WMI Queries'"); @@ -75,10 +79,31 @@ function plugin_wmi_setup_tables() { `last_started` timestamp NOT NULL DEFAULT '0000-00-00', `last_runtime` double NOT NULL DEFAULT '0.00', `last_failed` timestamp NOT NULL DEFAULT '0000-00-00', + `last_success` timestamp NULL DEFAULT NULL, + `last_error` varchar(1024) NOT NULL DEFAULT '', + `consecutive_failures` int(10) unsigned NOT NULL DEFAULT '0', + `timeout_count` int(10) unsigned NOT NULL DEFAULT '0', PRIMARY KEY (`host_id`,`wmi_query_id`)) ENGINE=InnoDB COMMENT='Holds WMI Data Queries'"); + foreach ([ + ['table' => 'wmi_user_accounts', 'column' => 'winrm_ssl', 'type' => 'varchar(8)', 'default' => 'inherit'], + ['table' => 'wmi_user_accounts', 'column' => 'winrm_port', 'type' => 'varchar(5)', 'default' => ''], + ['table' => 'wmi_user_accounts', 'column' => 'winrm_auth', 'type' => 'varchar(16)', 'default' => 'inherit'], + ['table' => 'host_wmi_query', 'column' => 'last_success', 'type' => 'timestamp', 'NULL' => true, 'default' => null], + ['table' => 'host_wmi_query', 'column' => 'last_error', 'type' => 'varchar(1024)', 'default' => ''], + ['table' => 'host_wmi_query', 'column' => 'consecutive_failures', 'type' => 'int(10)', 'unsigned' => true, 'default' => '0'], + ['table' => 'host_wmi_query', 'column' => 'timeout_count', 'type' => 'int(10)', 'unsigned' => true, 'default' => '0'], + ] as $column) { + $table = $column['table']; + unset($column['table']); + $name = $column['column']; + unset($column['column']); + + api_plugin_db_add_column('wmi', $table, array_merge(['name' => $name], $column)); + } + db_execute("CREATE TABLE IF NOT EXISTS `host_template_wmi_query` ( `host_template_id` mediumint(8) unsigned NOT NULL DEFAULT '0', `wmi_query_id` mediumint(8) unsigned NOT NULL DEFAULT '0', diff --git a/includes/functions.php b/includes/functions.php index ac5fae8..28da286 100644 --- a/includes/functions.php +++ b/includes/functions.php @@ -393,9 +393,11 @@ function plugin_wmi_create_resource_xml($id) { * @global array $config Cacti global configuration array; used to load * this plugin's linux_wmi.php client. */ -function run_store_wmi_query($host_id, $wmi_query_id, $transport = null) { +function run_store_wmi_query($host_id, $wmi_query_id, $transport = null, &$error = null) { global $config; + $error = null; + $host_info = db_fetch_row_prepared('SELECT * FROM host WHERE id = ?', @@ -419,10 +421,14 @@ function run_store_wmi_query($host_id, $wmi_query_id, $transport = null) { $wmi_query = is_array($wmi_query) ? $wmi_query : []; if (!cacti_sizeof($auth_info)) { + $error = 'WMI account not found'; + return false; } if (!cacti_sizeof($wmi_query)) { + $error = 'WMI query not found'; + return false; } @@ -446,6 +452,15 @@ function run_store_wmi_query($host_id, $wmi_query_id, $transport = null) { $wmi->hostname = $host; $wmi->username = $username; $wmi->password = $wmi->decode($password); + if (in_array($auth_info['winrm_ssl'] ?? '', ['on', 'off'], true)) { + $wmi->winrm_ssl = $auth_info['winrm_ssl'] === 'on'; + } + if (($auth_info['winrm_port'] ?? '') !== '') { + $wmi->winrm_port = ctype_digit((string) $auth_info['winrm_port']) ? (int) $auth_info['winrm_port'] : 0; + } + if (in_array($auth_info['winrm_auth'] ?? '', ['Negotiate', 'Kerberos', 'Basic'], true)) { + $wmi->winrm_authentication = $auth_info['winrm_auth']; + } $wmi->querynspace = $namespace; $wmi->command = $command; $wmi->binary = read_config_option('path_wmi'); @@ -458,7 +473,9 @@ function run_store_wmi_query($host_id, $wmi_query_id, $transport = null) { $wmi->querynspace = 'root\\\\CIMV2'; } - if ($wmi->fetch() !== false) { + $fetch_result = $wmi->fetch(); + + if ($fetch_result !== false) { $indexes = $wmi->fetch_indexes(); $data = $wmi->fetch_data(); } else { @@ -468,6 +485,17 @@ function run_store_wmi_query($host_id, $wmi_query_id, $transport = null) { $indexes = is_array($indexes) ? $indexes : []; + if ($fetch_result !== false && $data === []) { + // A successful empty result is authoritative. A failed transport keeps + // the cached values intact, while an empty response removes stale data. + db_execute_prepared('DELETE FROM host_wmi_cache + WHERE host_id = ? + AND wmi_query_id = ?', + [$host_id, $wmi_query_id]); + + return true; + } + if (cacti_sizeof($data)) { $sql = []; @@ -532,6 +560,7 @@ function run_store_wmi_query($host_id, $wmi_query_id, $transport = null) { return true; } else { $reason = is_string($wmi->error) ? $wmi->error : 'WMI returned no rows'; + $error = $reason; cacti_log('WARNING: WMI Query[' . $wmi_query_id . '] for Device[' . $host_id . '] failed: ' . $reason, false, 'WMI', POLLER_VERBOSITY_MEDIUM); @@ -569,6 +598,23 @@ function wmi_account_input_valid($name, $username, $password, $confirm, $id) { return $password !== '' || $id > 0; } +/** + * Validates per-account WinRM settings before they are written to the account + * record. Basic authentication must be explicitly paired with HTTPS. + */ +function wmi_account_winrm_input_valid($ssl, $port, $authentication) { + if (!in_array($ssl, ['inherit', 'off', 'on'], true) || + !in_array($authentication, ['inherit', 'Negotiate', 'Kerberos', 'Basic'], true)) { + return false; + } + + if ($port !== '' && (!ctype_digit($port) || (int) $port < 1 || (int) $port > 65535)) { + return false; + } + + return $authentication !== 'Basic' || $ssl === 'on'; +} + /** * Checks that an encoded password fits the wmi_user_accounts.password * column (varchar(256)) instead of being truncated or rejected by the @@ -584,7 +630,8 @@ function wmi_account_password_fits($encoded) { /** * Builds the host_wmi_cache index value for one result row from the query's - * primary key. A comma separated key joins its columns' values with a comma. + * primary key. A comma separated key joins its columns' values with a comma; + * backslashes and commas inside values are escaped to keep tuples distinct. * 'None', an empty key, or a key column missing from the result header yields * 'N/A', which is the single shared index for queries that return one row. * @@ -604,7 +651,7 @@ function wmi_row_index($row, $indexes, $primary_key) { return 'N/A'; } - $values[] = $row[$position]; + $values[] = str_replace(['\\', ','], ['\\\\', '\\,'], $row[$position]); } return implode(',', $values); diff --git a/includes/linux_wmi.php b/includes/linux_wmi.php index 7ebc2e6..a455e0e 100644 --- a/includes/linux_wmi.php +++ b/includes/linux_wmi.php @@ -44,7 +44,11 @@ public function __construct( public string $namespace, public string $query, public string $separator, - public string $binary + public string $binary, + public bool $use_ssl = false, + public ?int $port = null, + public string $authentication = 'Negotiate', + public bool $counter_mode = false ) { } } @@ -65,6 +69,79 @@ public function query(Wmi_Request $request): array|false; public function error(): ?string; } +/** + * Read a started process's stdout and stderr until both close, killing it + * once it runs past the timeout or its stdout grows past the byte limit. + * stderr is capped at 2000 bytes because it only ever feeds an error message. + * + * @param resource $process + * @param array $pipes + * + * @return array{status: int, stdout: string, stderr: string, timed_out: bool, output_too_large: bool} + */ +function wmi_drain_process($process, array $pipes, int $timeout, int $max_output_bytes): array { + $open = [1 => $pipes[1], 2 => $pipes[2]]; + $buffer = [1 => '', 2 => '']; + $deadline = microtime(true) + $timeout; + $expired = false; + $too_large = false; + + foreach ($open as $stream) { + stream_set_blocking($stream, false); + } + + while ($open !== []) { + $left = $deadline - microtime(true); + + if ($left <= 0) { + $expired = true; + + break; + } + + $read = $open; + $write = null; + $except = null; + + @stream_select($read, $write, $except, 0, (int) min(200000, $left * 1000000)); + + foreach ($read as $key => $stream) { + $chunk = fread($stream, 8192); + + if ($chunk === false || ($chunk === '' && feof($stream))) { + unset($open[$key]); + } elseif ($key === 2) { + $buffer[2] .= substr($chunk, 0, max(0, 2000 - strlen($buffer[2]))); + } else { + $buffer[1] .= $chunk; + + if (strlen($buffer[1]) > $max_output_bytes) { + $too_large = true; + + break 2; + } + } + } + } + + if ($expired || $too_large) { + proc_terminate($process, 9); + } + + fclose($pipes[1]); + fclose($pipes[2]); + + $status = proc_close($process); + + return [ + 'status' => ($expired || $too_large) ? -1 : $status, + 'stdout' => $buffer[1], + 'stderr' => substr(trim($buffer[2]), 0, 2000), + 'timed_out' => $expired, + 'output_too_large' => $too_large, + ]; +} + /** * Default transport: the Linux `wmic` client. * @@ -82,12 +159,18 @@ class Wmic_Shell_Transport implements Wmi_Transport { */ public function __construct( private int $timeout = 120, - private ?string $temp_dir = null + private ?string $temp_dir = null, + private int $max_output_bytes = 16777216 ) { } public function query(Wmi_Request $request): array|false { $this->error = null; + if ($request->counter_mode) { + $this->error = 'ERROR: Performance counter queries require PowerShell on a Windows Cacti server'; + + return false; + } if (preg_match('/[\r\n\0]/', $request->username . $request->password)) { $this->error = 'ERROR: WMI credentials must not contain line breaks'; @@ -120,6 +203,12 @@ public function query(Wmi_Request $request): array|false { return false; } + if ($result['output_too_large']) { + $this->error = 'ERROR: WMI response exceeded the ' . $this->max_output_bytes . ' byte limit'; + + return false; + } + if ($result['status'] !== 0) { $this->error = $this->with_stderr('ERROR: ' . implode("\n", $result['lines']), $result['stderr']); @@ -265,7 +354,7 @@ private function auth_file_content(Wmi_Request $request): string { * Run a command with stdout and stderr read separately, stopping it when * it takes longer than the timeout. * - * @return array{status: int, lines: array, stderr: string, timed_out: bool}|null + * @return array{status: int, lines: array, stderr: string, timed_out: bool, output_too_large: bool}|null */ private function run(string $command): ?array { $process = $this->start_process($command, $pipes); @@ -274,59 +363,20 @@ private function run(string $command): ?array { return null; } - $open = [1 => $pipes[1], 2 => $pipes[2]]; - $buffer = [1 => '', 2 => '']; - $deadline = microtime(true) + $this->timeout; - $expired = false; - - foreach ($open as $stream) { - stream_set_blocking($stream, false); - } - - while ($open !== []) { - $left = $deadline - microtime(true); - - if ($left <= 0) { - $expired = true; - - break; - } - - $read = $open; - $write = null; - $except = null; - - @stream_select($read, $write, $except, 0, (int) min(200000, $left * 1000000)); - - foreach ($read as $key => $stream) { - $chunk = fread($stream, 8192); - - if ($chunk === false || ($chunk === '' && feof($stream))) { - unset($open[$key]); - } else { - $buffer[$key] .= $chunk; - } - } - } - - if ($expired) { - proc_terminate($process, 9); - } - - fclose($pipes[1]); - fclose($pipes[2]); + $result = wmi_drain_process($process, $pipes, $this->timeout, $this->max_output_bytes); - $status = proc_close($process); + $stdout = $result['stdout']; - if (substr($buffer[1], -1) === "\n") { - $buffer[1] = substr($buffer[1], 0, -1); + if (substr($stdout, -1) === "\n") { + $stdout = substr($stdout, 0, -1); } return [ - 'status' => $expired ? -1 : $status, - 'lines' => $buffer[1] === '' ? [] : array_map('rtrim', explode("\n", $buffer[1])), - 'stderr' => substr(trim($buffer[2]), 0, 2000), - 'timed_out' => $expired, + 'status' => $result['status'], + 'lines' => $stdout === '' ? [] : array_map('rtrim', explode("\n", $stdout)), + 'stderr' => $result['stderr'], + 'timed_out' => $result['timed_out'], + 'output_too_large' => $result['output_too_large'], ]; } @@ -378,7 +428,36 @@ class PowerShellCim_Transport implements Wmi_Transport { if (![string]::IsNullOrEmpty($env:WMI_HOST)) { $secure = ConvertTo-SecureString $env:WMI_PASS -AsPlainText -Force $cred = New-Object System.Management.Automation.PSCredential($env:WMI_USER, $secure) - $session = New-CimSession -ComputerName $env:WMI_HOST -Credential $cred + if ($env:WMI_COUNTER -eq '1') { + $paths = @($env:WMI_QUERY -split "`n" | ForEach-Object { $_.Trim() } | Where-Object { $_ -ne '' }) + if ($paths.Count -eq 0) { throw 'No performance counter paths were provided' } + if ($paths.Count -gt 64) { throw 'A PDH query can contain at most 64 counter paths' } + $invoke = @{ ComputerName = $env:WMI_HOST; Credential = $cred; Authentication = $env:WMI_AUTH; ErrorAction = 'Stop' } + if ($env:WMI_SSL -eq '1') { $invoke['UseSSL'] = $true } + if (![string]::IsNullOrEmpty($env:WMI_PORT)) { $invoke['Port'] = [uint32]$env:WMI_PORT } + $counterSamples = Invoke-Command @invoke -ScriptBlock { + param([string[]]$CounterPaths) + $samples = Get-Counter -Counter $CounterPaths -MaxSamples 2 -SampleInterval 1 -ErrorAction Stop + $samples[-1].CounterSamples | ForEach-Object { + [pscustomobject]@{ Path = $_.Path; Instance = $_.InstanceName; Timestamp = $_.TimeStamp; CookedValue = [string]::Format([cultureinfo]::InvariantCulture, '{0:R}', [double]$_.CookedValue) } + } + } -ArgumentList (,$paths) + Write-Output 'WindowsPerformanceCounters' + Write-Output ('Path' + $sep + 'Instance' + $sep + 'Timestamp' + $sep + 'CookedValue') + foreach ($sample in $counterSamples) { + Write-Output ([string]$sample.Path + $sep + [string]$sample.Instance + $sep + [string]$sample.Timestamp + $sep + [string]$sample.CookedValue) + } + exit 0 + } + $options = New-CimSessionOption -Protocol Wsman + if ($env:WMI_SSL -eq '1') { + $options = New-CimSessionOption -Protocol Wsman -UseSsl + } + $sessionParams = @{ ComputerName = $env:WMI_HOST; Credential = $cred; Authentication = $env:WMI_AUTH; SessionOption = $options } + if (![string]::IsNullOrEmpty($env:WMI_PORT)) { + $sessionParams['Port'] = [uint32]$env:WMI_PORT + } + $session = New-CimSession @sessionParams $params['CimSession'] = $session } try { @@ -407,13 +486,43 @@ class PowerShellCim_Transport implements Wmi_Transport { */ public function __construct( public string $binary = 'pwsh', - ?callable $runner = null + ?callable $runner = null, + private int $timeout = 120, + private int $max_output_bytes = 16777216 ) { $this->runner = $runner ?? $this->default_runner(); } public function query(Wmi_Request $request): array|false { $this->error = null; + if ($request->counter_mode && trim($request->query) === '') { + $this->error = __('ERROR: At least one performance counter path is required', 'wmi'); + + return false; + } + + if ($request->counter_mode && count(preg_split('/\R/', trim($request->query), -1, PREG_SPLIT_NO_EMPTY) ?: []) > 64) { + $this->error = __('ERROR: A PDH query can contain at most 64 counter paths', 'wmi'); + + return false; + } + if ($request->port !== null && ($request->port < 1 || $request->port > 65535)) { + $this->error = __('ERROR: Invalid WinRM port', 'wmi'); + + return false; + } + + if (!in_array($request->authentication, ['Negotiate', 'Kerberos', 'Basic'], true)) { + $this->error = __('ERROR: Invalid WinRM authentication method', 'wmi'); + + return false; + } + + if ($request->authentication === 'Basic' && !$request->use_ssl) { + $this->error = __('ERROR: Basic WinRM authentication requires HTTPS', 'wmi'); + + return false; + } $env = [ 'WMI_HOST' => trim($request->hostname), @@ -422,6 +531,10 @@ public function query(Wmi_Request $request): array|false { 'WMI_NS' => $request->namespace, 'WMI_QUERY' => $request->query, 'WMI_SEP' => $request->separator, + 'WMI_SSL' => $request->use_ssl ? '1' : '0', + 'WMI_PORT' => $request->port === null ? '' : (string) $request->port, + 'WMI_AUTH' => $request->authentication, + 'WMI_COUNTER' => $request->counter_mode ? '1' : '0', ]; $result = ($this->runner)( @@ -439,9 +552,7 @@ public function query(Wmi_Request $request): array|false { } if (count($result['stdout']) === 0) { - $this->error = __('ERROR: WMI Returned no Data', 'wmi'); - - return false; + return []; } return $result['stdout']; @@ -478,14 +589,16 @@ private function default_runner(): callable { fwrite($pipes[0], $stdin); fclose($pipes[0]); - $stdout = stream_get_contents($pipes[1]); - $stderr = stream_get_contents($pipes[2]); - fclose($pipes[1]); - fclose($pipes[2]); - - $exit = proc_close($process); + $result = wmi_drain_process($process, $pipes, $this->timeout, $this->max_output_bytes); + $exit = $result['status']; + $stdout = str_replace("\r\n", "\n", rtrim($result['stdout'], "\r\n")); + $stderr = $result['stderr']; - $stdout = str_replace("\r\n", "\n", rtrim($stdout, "\r\n")); + if ($result['timed_out']) { + $stderr = 'PowerShell did not finish within ' . $this->timeout . ' seconds' . ($stderr === '' ? '' : "\n" . $stderr); + } elseif ($result['output_too_large']) { + $stderr = 'PowerShell response exceeded the ' . $this->max_output_bytes . ' byte limit'; + } return [ 'exit' => $exit, @@ -509,6 +622,9 @@ class Linux_WMI { public string $keys = ''; // Comma separated keys public string $queryclass = ''; // Class name to pull public string $querynspace = ''; // Namespace to pull + public ?bool $winrm_ssl = null; + public ?int $winrm_port = null; + public ?string $winrm_authentication = null; /** @var array> Parsed rows from the last fetch(). */ public array $results = []; @@ -728,6 +844,15 @@ public function retrieve_account(): bool { $this->username = $info['username']; $this->password = $this->decode($info['password']); + if (in_array($info['winrm_ssl'] ?? '', ['on', 'off'], true)) { + $this->winrm_ssl = $info['winrm_ssl'] === 'on'; + } + if (($info['winrm_port'] ?? '') !== '') { + $this->winrm_port = ctype_digit((string) $info['winrm_port']) ? (int) $info['winrm_port'] : 0; + } + if (in_array($info['winrm_auth'] ?? '', ['Negotiate', 'Kerberos', 'Basic'], true)) { + $this->winrm_authentication = $info['winrm_auth']; + } return true; } @@ -758,6 +883,14 @@ public function encode(string $info): string { } private function request(): Wmi_Request { + $ssl = $this->winrm_ssl ?? (function_exists('read_config_option') && read_config_option('wmi_winrm_ssl') === 'on'); + $port = function_exists('read_config_option') ? trim((string) read_config_option('wmi_winrm_port')) : ''; + $port = $this->winrm_port ?? ($port === '' ? null : (ctype_digit($port) ? (int) $port : 0)); + $authentication = $this->winrm_authentication ?? (function_exists('read_config_option') ? (string) read_config_option('wmi_winrm_auth') : 'Negotiate'); + if (!in_array($authentication, ['Negotiate', 'Kerberos', 'Basic'], true)) { + $authentication = 'Negotiate'; + } + return new Wmi_Request( $this->hostname, $this->username, @@ -765,7 +898,12 @@ private function request(): Wmi_Request { $this->querynspace, $this->command, $this->effective_separator(), - $this->binary + $this->binary, + $ssl, + $port, + $authentication, + // PDH in the namespace field marks a list of performance counter paths. + strtoupper(trim($this->querynspace)) === 'PDH' ); } diff --git a/locales/po/cacti.pot b/locales/po/cacti.pot index 33ced2d..efc33ab 100644 --- a/locales/po/cacti.pot +++ b/locales/po/cacti.pot @@ -574,3 +574,131 @@ msgstr "" #: setup.php msgid "The path to the wmic binary used to query Windows devices from a Linux Cacti server." msgstr "" + +#: includes/linux_wmi.php +msgid "ERROR: Invalid WinRM port" +msgstr "" + +#: includes/linux_wmi.php +msgid "ERROR: Invalid WinRM authentication method" +msgstr "" + +#: includes/linux_wmi.php +msgid "ERROR: Basic WinRM authentication requires HTTPS" +msgstr "" + +#: setup.php +msgid "Use WinRM over HTTPS" +msgstr "" + +#: setup.php +msgid "Use TLS for CIM/WinRM connections. Configure and trust the target certificate; certificate checks are not disabled." +msgstr "" + +#: setup.php +msgid "WinRM Port Override" +msgstr "" + +#: setup.php +msgid "Optional port override. Leave blank for the Windows WinRM default port." +msgstr "" + +#: setup.php +msgid "Negotiate is the default. Use Kerberos for domain hosts where available. Basic authentication is accepted only when HTTPS is enabled." +msgstr "" + +#: setup.php +msgid "Negotiate" +msgstr "" + +#: setup.php +msgid "Kerberos" +msgstr "" + +#: setup.php +msgid "Basic (HTTPS only)" +msgstr "" + +#: includes/linux_wmi.php +msgid "ERROR: At least one performance counter path is required" +msgstr "" + +#: includes/linux_wmi.php +msgid "ERROR: A PDH query can contain at most 64 counter paths" +msgstr "" + +#: setup.php +msgid "Default for accounts that inherit server settings. Configure and trust the target certificate; certificate checks are not disabled." +msgstr "" + +#: setup.php +msgid "Default port override for accounts that inherit server settings. Leave blank for the Windows default." +msgstr "" + +#: setup.php +msgid "Default for accounts that inherit server settings. Use Kerberos for domain hosts where available. Basic requires HTTPS." +msgstr "" + +#: wmi_accounts.php +msgid "WinRM Authentication" +msgstr "" + +#: wmi_accounts.php +msgid "WinRM Transport" +msgstr "" + +#: wmi_accounts.php +msgid "Choose whether this account inherits the server setting or uses HTTP or HTTPS." +msgstr "" + +#: wmi_accounts.php +msgid "Use Server Default" +msgstr "" + +#: wmi_accounts.php +msgid "HTTP" +msgstr "" + +#: wmi_accounts.php +msgid "HTTPS" +msgstr "" + +#: wmi_accounts.php +msgid "Leave blank to inherit the server setting and Windows WinRM default." +msgstr "" + +#: wmi_accounts.php +msgid "Choose whether this account inherits the server setting or uses a specific authentication method. Basic requires HTTPS." +msgstr "" + +#: wmi_queries.php +msgid "Use a WMI namespace, or enter PDH for native performance counter paths." +msgstr "" + +#: wmi_queries.php +msgid "Enter WQL, or for PDH enter one Windows performance counter path per line." +msgstr "" + +#: wmi_queries.php +msgid "Enter WQL, or for PDH enter one Windows performance counter path per line. Broad queries can return many rows; responses are capped at 16 MiB." +msgstr "" + +#: wmi_queries.php +msgid "Last Poll" +msgstr "" + +#: wmi_queries.php +msgid "Failing Devices" +msgstr "" + +#: wmi_queries.php +msgid "Timeouts" +msgstr "" + +#: wmi_queries.php +msgid "Polled Devices" +msgstr "" + +#: wmi_queries.php +msgid "Most Recent Error" +msgstr "" diff --git a/poller_wmi.php b/poller_wmi.php index 619fbd8..93fab27 100644 --- a/poller_wmi.php +++ b/poller_wmi.php @@ -405,17 +405,6 @@ function process_device($host_id) { cacti_log('NOTE: Executing WMI Query[' . $q['wmi_query_id'] . "] for Device [$host_id].", false, 'WMI', POLLER_VERBOSITY_MEDIUM); - $account = db_fetch_row_prepared('SELECT * - FROM wmi_user_accounts - WHERE id = ?', - [$q['wmi_account']]); - - if (!cacti_sizeof($account)) { - cacti_log('WARNING: WMI Account ID ' . $q['wmi_account'] . " not found for WMI Device[$host_id].", false, 'WMI'); - - break; - } - $run_before = db_fetch_row_prepared('SELECT * FROM host_wmi_query WHERE host_id = ? @@ -426,27 +415,44 @@ function process_device($host_id) { if (!cacti_sizeof($run_before)) { $last_failed = '0000-00-00 00:00:00'; + $last_success = null; + $failure_count = 0; + $timeout_count = 0; } else { - $last_failed = $run_before['last_failed']; + $last_failed = $run_before['last_failed']; + $last_success = $run_before['last_success'] ?? null; + $failure_count = (int) ($run_before['consecutive_failures'] ?? 0); + $timeout_count = (int) ($run_before['timeout_count'] ?? 0); } // Run the query and store the data - $status = run_store_wmi_query($host_id, $q['wmi_query_id']) ? 0 : 1; + $query_error = null; + $status = run_store_wmi_query($host_id, $q['wmi_query_id'], null, $query_error) ? 0 : 1; $qmend = microtime(true); if ($status != 0) { - $last_failed = date('Y-m-d H:i:s'); + $last_failed = $qstart; + $failure_count++; + $wmi_errors++; + + if (preg_match('/timed? ?out|did not finish within/i', (string) $query_error)) { + $timeout_count++; + } cacti_log('WARNING: Errored WMI Query[' . $q['wmi_query_id'] . "] for Device [$host_id] in " . round($qmend - $qmstart, 2) . ' seconds.', false, 'WMI'); } else { + $last_success = $qstart; + $failure_count = 0; + $query_error = ''; + cacti_log('NOTE: Finished WMI Query[' . $q['wmi_query_id'] . "] for Device [$host_id] in " . round($qmend - $qmstart, 2) . ' seconds.', false, 'WMI', POLLER_VERBOSITY_MEDIUM); } db_execute_prepared('REPLACE INTO host_wmi_query - (host_id, wmi_query_id, sort_field, title_format, last_started, last_runtime, last_failed) - VALUES (?, ?, ?, ?, ?, ?, ?)', - [$host_id, $q['wmi_query_id'], '', '', $qstart, ($qmend - $qmstart), $last_failed] + (host_id, wmi_query_id, sort_field, title_format, last_started, last_runtime, last_failed, last_success, last_error, consecutive_failures, timeout_count) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)', + [$host_id, $q['wmi_query_id'], '', '', $qstart, ($qmend - $qmstart), $last_failed, $last_success, substr((string) $query_error, 0, 1024), $failure_count, $timeout_count] ); } } else { diff --git a/setup.php b/setup.php index eb2554d..2129e3d 100644 --- a/setup.php +++ b/setup.php @@ -51,9 +51,7 @@ function plugin_wmi_csp_nonce(): string { * @return void */ function plugin_wmi_install() { - global $config; - - require_once($config['base_path'] . '/plugins/wmi/includes/database.php'); + require_once(__DIR__ . '/includes/database.php'); api_plugin_register_hook('wmi', 'config_arrays', 'wmi_config_arrays', 'setup.php'); api_plugin_register_hook('wmi', 'config_form', 'wmi_config_form', 'setup.php'); @@ -155,13 +153,16 @@ function plugin_wmi_check_config() { /** * Performs any schema/data migrations needed when upgrading to a newer - * version of this plugin; currently a no-op placeholder. Invoked by + * version of this plugin. Invoked by * Cacti's plugin architecture when an installed plugin's version - * increases. + * increases. It provisions any new plugin schema columns before pruning + * files from earlier releases. * - * @return bool Always returns true. + * @return bool True after schema provisioning and file pruning complete. */ function plugin_wmi_upgrade() { + require_once(__DIR__ . '/includes/database.php'); + plugin_wmi_setup_tables(); wmi_prune_files(); return true; @@ -518,6 +519,30 @@ function wmi_config_settings() { 'description' => __('If selected, when running either automation, or when creating/saving a Device, all WMI Queries associated with the Device Template will be created.', 'wmi'), 'method' => 'checkbox', 'default' => 'on' + ], + 'wmi_winrm_ssl' => [ + 'friendly_name' => __('Use WinRM over HTTPS', 'wmi'), + 'description' => __('Default for accounts that inherit server settings. Configure and trust the target certificate; certificate checks are not disabled.', 'wmi'), + 'method' => 'checkbox', + 'default' => '' + ], + 'wmi_winrm_port' => [ + 'friendly_name' => __('WinRM Port Override', 'wmi'), + 'description' => __('Default port override for accounts that inherit server settings. Leave blank for the Windows default.', 'wmi'), + 'method' => 'textbox', + 'max_length' => '5', + 'default' => '' + ], + 'wmi_winrm_auth' => [ + 'friendly_name' => __('WinRM Authentication', 'wmi'), + 'description' => __('Default for accounts that inherit server settings. Use Kerberos for domain hosts where available. Basic requires HTTPS.', 'wmi'), + 'method' => 'drop_array', + 'default' => 'Negotiate', + 'array' => [ + 'Negotiate' => __('Negotiate', 'wmi'), + 'Kerberos' => __('Kerberos', 'wmi'), + 'Basic' => __('Basic (HTTPS only)', 'wmi') + ] ] ]; diff --git a/tests/E2E/CollectorFlowTest.php b/tests/E2E/CollectorFlowTest.php index 26dd9d3..4f79761 100644 --- a/tests/E2E/CollectorFlowTest.php +++ b/tests/E2E/CollectorFlowTest.php @@ -89,7 +89,16 @@ function wmi_e2e_collector(): array { expect($o['indexes'])->toBe(['A', 'B']); expect($o['rows'])->toBe(4); expect($o['present0'])->toBe(0); - })->with(['midway', 'empty_output', 'silent_failure', 'header_only']); + })->with(['midway', 'empty_output', 'silent_failure']); + + it('clears the cache after a successful header-only result', function () { + $o = wmi_e2e_collector()['header_only']; + + expect($o['result'])->toBeTrue(); + expect($o['indexes'])->toBe([]); + expect($o['rows'])->toBe(0); + expect($o['present0'])->toBe(0); + }); it('indexes rows by the primary key shape', function (string $case, array $indexes, int $rows) { $o = wmi_e2e_collector()['key_' . $case]; @@ -140,7 +149,6 @@ function wmi_e2e_collector(): array { expect($log)->toContain('WMI Query[900001] for Device[900001] failed: ERROR: WMI Returned no Data'); expect($log)->toContain('failed: ERROR: '); - expect($log)->toContain('failed: WMI returned no rows'); }); }); @@ -177,6 +185,10 @@ function wmi_e2e_collector(): array { expect($o['state']['cache']['900003'])->toBe(['svc' => [], 'prc' => $polled['prc']]); expect($o['last_failed'])->not->toBe('0000-00-00 00:00:00'); expect($o['last_failed_ok'])->toBe('0000-00-00 00:00:00'); + expect($o['last_success_failed'])->toBeNull(); + expect($o['last_success_ok'])->not->toBeNull(); + expect($o['last_error'])->not->toBe(''); + expect((int) $o['consecutive_failures'])->toBe(1); }); it('finds nothing due right after a run', function () { diff --git a/tests/E2E/collector_flow.php b/tests/E2E/collector_flow.php index cf01c07..4a46399 100644 --- a/tests/E2E/collector_flow.php +++ b/tests/E2E/collector_flow.php @@ -242,6 +242,10 @@ function refresh(int $host = HOST_A, int $query = QUERY_SVC): array { $out['stale_lock'] = $poller('-M') + ['state' => $poll_state()]; $out['stale_lock']['last_failed'] = db_fetch_cell_prepared('SELECT last_failed FROM host_wmi_query WHERE host_id = ? AND wmi_query_id = ?', [HOST_C, QUERY_SVC]); $out['stale_lock']['last_failed_ok'] = db_fetch_cell_prepared('SELECT last_failed FROM host_wmi_query WHERE host_id = ? AND wmi_query_id = ?', [HOST_A, QUERY_SVC]); +$out['stale_lock']['last_success_failed'] = db_fetch_cell_prepared('SELECT last_success FROM host_wmi_query WHERE host_id = ? AND wmi_query_id = ?', [HOST_C, QUERY_SVC]); +$out['stale_lock']['last_success_ok'] = db_fetch_cell_prepared('SELECT last_success FROM host_wmi_query WHERE host_id = ? AND wmi_query_id = ?', [HOST_A, QUERY_SVC]); +$out['stale_lock']['last_error'] = db_fetch_cell_prepared('SELECT last_error FROM host_wmi_query WHERE host_id = ? AND wmi_query_id = ?', [HOST_C, QUERY_SVC]); +$out['stale_lock']['consecutive_failures'] = db_fetch_cell_prepared('SELECT consecutive_failures FROM host_wmi_query WHERE host_id = ? AND wmi_query_id = ?', [HOST_C, QUERY_SVC]); // A second run right away finds nothing due. $out['not_due'] = $poller('-M'); diff --git a/tests/Unit/WmiAccountInputTest.php b/tests/Unit/WmiAccountInputTest.php index 1eae6ca..c99ef7e 100644 --- a/tests/Unit/WmiAccountInputTest.php +++ b/tests/Unit/WmiAccountInputTest.php @@ -36,3 +36,14 @@ expect(wmi_account_password_fits(str_repeat('x', 256)))->toBeTrue(); expect(wmi_account_password_fits(str_repeat('x', 257)))->toBeFalse(); }); + +it('validates WinRM port, authentication, and HTTPS requirements per account', function () { + expect(wmi_account_winrm_input_valid('inherit', '', 'inherit'))->toBeTrue(); + expect(wmi_account_winrm_input_valid('on', '5986', 'Basic'))->toBeTrue(); + expect(wmi_account_winrm_input_valid('off', '', 'Basic'))->toBeFalse(); + expect(wmi_account_winrm_input_valid('on', '0', 'Kerberos'))->toBeFalse(); + expect(wmi_account_winrm_input_valid('on', '65536', 'Kerberos'))->toBeFalse(); + expect(wmi_account_winrm_input_valid('on', 'not-a-port', 'Negotiate'))->toBeFalse(); + expect(wmi_account_winrm_input_valid('invalid', '', 'Negotiate'))->toBeFalse(); + expect(wmi_account_winrm_input_valid('on', '', 'CredSSP'))->toBeFalse(); +}); diff --git a/tests/Unit/WmiLifecycleTest.php b/tests/Unit/WmiLifecycleTest.php index 2866ee0..0625bcd 100644 --- a/tests/Unit/WmiLifecycleTest.php +++ b/tests/Unit/WmiLifecycleTest.php @@ -40,7 +40,7 @@ expect(plugin_wmi_check_config())->toBeTrue(); }); -it('reports the upgrade as always successful', function () { +it('runs idempotent schema provisioning during upgrade', function () { // Sandbox base_path so the upgrade-time prune (wmi_prune_files) // runs against an empty temp tree, never the real checkout. $restore = $GLOBALS['config']['base_path']; @@ -48,6 +48,7 @@ try { expect(plugin_wmi_upgrade())->toBeTrue(); + expect($GLOBALS['__test_add_column_calls'])->toHaveCount(8); } finally { $GLOBALS['config']['base_path'] = $restore; } @@ -56,7 +57,7 @@ it('adds the wmi_account column and creates every table', function () { plugin_wmi_setup_tables(); - expect($GLOBALS['__test_add_column_calls'])->toHaveCount(1); + expect($GLOBALS['__test_add_column_calls'])->toHaveCount(8); expect($GLOBALS['__test_add_column_calls'][0]['plugin'])->toBe('wmi'); expect($GLOBALS['__test_add_column_calls'][0]['table'])->toBe('host'); expect($GLOBALS['__test_add_column_calls'][0]['data']['name'])->toBe('wmi_account'); @@ -66,6 +67,10 @@ }); expect($creates)->toHaveCount(7); + $schema = implode("\n", array_column($creates, 'sql')); + expect($schema)->toContain('`winrm_ssl` varchar(8)'); + expect($schema)->toContain('`last_success` timestamp NULL'); + expect($schema)->toContain('`consecutive_failures` int(10) unsigned'); }); it('seeds both WMI data_input rows when they are not already present', function () { diff --git a/tests/Unit/WmiRunStoreQueryTest.php b/tests/Unit/WmiRunStoreQueryTest.php index c083726..2a14654 100644 --- a/tests/Unit/WmiRunStoreQueryTest.php +++ b/tests/Unit/WmiRunStoreQueryTest.php @@ -81,6 +81,80 @@ function wmi_test_cache_statements(): array { expect(wmi_test_cache_statements())->toBe(array()); }); +it('reports a missing WMI account to the poller caller', function () { + $GLOBALS['__test_fetch_row_map']['wmi_user_accounts'] = array(); + $error = null; + + $ok = run_store_wmi_query(5, 9, null, $error); + + expect($ok)->toBeFalse(); + expect($error)->toBe('WMI account not found'); + expect(wmi_test_cache_statements())->toBe(array()); +}); + +it('reports a missing WMI query to the poller caller', function () { + $GLOBALS['__test_fetch_row_map']['wmi_wql_queries'] = array(); + $error = null; + + $ok = run_store_wmi_query(5, 9, null, $error); + + expect($ok)->toBeFalse(); + expect($error)->toBe('WMI query not found'); + expect(wmi_test_cache_statements())->toBe(array()); +}); + +it('clears cached rows when the transport successfully returns no instances', function () { + $t = new Wmi_Test_Canned_Transport(array('Win32_Service', 'Name|+|State')); + + ob_start(); + $ok = run_store_wmi_query(5, 9, $t); + ob_end_clean(); + + $statements = wmi_test_cache_statements(); + + expect($ok)->toBeTrue(); + expect($statements)->toHaveCount(1); + expect($statements[0])->toContain('DELETE FROM host_wmi_cache WHERE host_id = ? AND wmi_query_id = ?'); +}); + +it('applies the selected account WinRM settings to its collector request', function () { + $GLOBALS['__test_fetch_row_map']['wmi_user_accounts']['winrm_ssl'] = 'on'; + $GLOBALS['__test_fetch_row_map']['wmi_user_accounts']['winrm_port'] = '5986'; + $GLOBALS['__test_fetch_row_map']['wmi_user_accounts']['winrm_auth'] = 'Kerberos'; + $seen = []; + $transport = new PowerShellCim_Transport('pwsh', function ($binary, $args, $script, $env) use (&$seen) { + $seen = $env; + + return ['exit' => 0, 'stdout' => ['Win32_Service', 'Name|+|State', 'Spooler|+|Running'], 'stderr' => '']; + }); + + ob_start(); + $ok = run_store_wmi_query(5, 9, $transport); + ob_end_clean(); + + expect($ok)->toBeTrue(); + expect($seen['WMI_SSL'])->toBe('1'); + expect($seen['WMI_PORT'])->toBe('5986'); + expect($seen['WMI_AUTH'])->toBe('Kerberos'); +}); + +it('loads per-account WinRM overrides when retrieving the host account', function () { + $w = new Linux_WMI(); + $w->hostid = '5'; + $GLOBALS['__test_fetch_row_map']['wmi_user_accounts'] = array( + 'username' => 'u', + 'password' => $w->encode('pw'), + 'winrm_ssl' => 'on', + 'winrm_port' => '5986', + 'winrm_auth' => 'Kerberos', + ); + + expect($w->retrieve_account())->toBeTrue(); + expect($w->winrm_ssl)->toBeTrue(); + expect($w->winrm_port)->toBe(5986); + expect($w->winrm_authentication)->toBe('Kerberos'); +}); + it('drops the cached rows of a device that no longer exists', function () { $GLOBALS['__test_fetch_row_map'] = array(); @@ -100,6 +174,17 @@ function wmi_test_cache_statements(): array { expect(wmi_row_index(array('C:', 'D1', 'x'), array('Drive', 'Disk', 'Size'), 'Drive, Disk'))->toBe('C:,D1'); }); +it('keeps composite indexes distinct when a key value contains a comma', function () { + $headers = array('First', 'Second'); + $first = wmi_row_index(array('a,b', 'c'), $headers, 'First,Second'); + $second = wmi_row_index(array('a', 'b,c'), $headers, 'First,Second'); + + expect($first)->toBe('a\\,b,c'); + expect($second)->toBe('a,b\\,c'); + expect($first)->not->toBe($second); + expect(wmi_row_index(array('a\\,b', 'c'), $headers, 'First,Second'))->toBe('a' . str_repeat('\\', 3) . ',b,c'); +}); + it('uses the shared index when the key is None or missing from the header', function () { $header = array('Name', 'State'); @@ -129,6 +214,32 @@ function wmi_test_cache_statements(): array { expect($insert)->toContain("'Spooler,Stopped'"); }); +it('stores rows with distinct composite keys when key values contain commas', function () { + $GLOBALS['__test_fetch_row_map']['wmi_wql_queries']['primary_key'] = 'Name,State'; + + $t = new Wmi_Test_Canned_Transport(array( + 'Win32_Service', + 'Name|+|State', + 'a,b|+|c', + 'a|+|b,c', + )); + + ob_start(); + run_store_wmi_query(5, 9, $t); + ob_end_clean(); + + $insert = ''; + + foreach (wmi_test_cache_statements() as $statement) { + if (strpos($statement, 'INSERT INTO') === 0) { + $insert = $statement; + } + } + + expect($insert)->toContain("'a\\\\,b,c'"); + expect($insert)->toContain("'a,b\\\\,c'"); +}); + it('logs why a query failed', function () { $t = new Wmi_Test_Canned_Transport(false, 'ERROR: access denied'); @@ -140,13 +251,15 @@ function wmi_test_cache_statements(): array { expect($GLOBALS['__test_cacti_log'][0])->toContain('WMI Query[9] for Device[5] failed: ERROR: access denied'); }); -it('logs a plain reason when a query succeeds with no rows', function () { +it('treats a successful empty result as authoritative without logging an error', function () { $t = new Wmi_Test_Canned_Transport(array('Win32_Service', 'Name|+|State')); ob_start(); $ok = run_store_wmi_query(5, 9, $t); ob_end_clean(); - expect($ok)->toBeFalse(); - expect($GLOBALS['__test_cacti_log'][0])->toContain('failed: WMI returned no rows'); + expect($ok)->toBeTrue(); + expect($GLOBALS['__test_cacti_log'])->toBe([]); + expect(wmi_test_cache_statements())->toHaveCount(1); + expect(wmi_test_cache_statements()[0])->toContain('DELETE FROM host_wmi_cache'); }); diff --git a/tests/Unit/WmiScriptServerTest.php b/tests/Unit/WmiScriptServerTest.php index 5b29846..9c18bdc 100644 --- a/tests/Unit/WmiScriptServerTest.php +++ b/tests/Unit/WmiScriptServerTest.php @@ -68,6 +68,19 @@ function cacti_escapeshellarg($string, $quote = true) { expect($settings['path']['path_wmi']['method'])->toBe('filepath'); }); +it('registers explicit CIM and WinRM transport settings', function () { + global $settings, $tabs; + + $settings = array(); + $tabs = array(); + + wmi_config_settings(); + + expect($settings['misc']['wmi_winrm_ssl']['method'])->toBe('checkbox'); + expect($settings['misc']['wmi_winrm_port']['max_length'])->toBe('5'); + expect(array_keys($settings['misc']['wmi_winrm_auth']['array']))->toBe(['Negotiate', 'Kerberos', 'Basic']); +}); + it('keeps the settings that are already on the path tab', function () { global $settings, $tabs; diff --git a/tests/Unit/WmiWmicStderrTest.php b/tests/Unit/WmiWmicStderrTest.php index 4479cac..2599fcc 100644 --- a/tests/Unit/WmiWmicStderrTest.php +++ b/tests/Unit/WmiWmicStderrTest.php @@ -104,6 +104,13 @@ function wmi_stderrtest_request(string $binary): Wmi_Request { expect(strlen($t->error()))->toBe(strlen("ERROR: x\n") + 2000); }); +it('stops wmic when its response exceeds the configured size limit', function () { + $t = new Wmic_Shell_Transport(120, null, 64); + + expect($t->query(wmi_stderrtest_request(wmi_stderrtest_wmic([str_repeat('x', 1024)]))))->toBeFalse(); + expect($t->error())->toContain('exceeded the 64 byte limit'); +}); + it('stops a wmic that does not finish within the timeout', function () { $t = new Wmic_Shell_Transport(1); $began = microtime(true); diff --git a/tests/Unit/WmiWmicTransportTest.php b/tests/Unit/WmiWmicTransportTest.php index e9d2a3c..b90dacb 100644 --- a/tests/Unit/WmiWmicTransportTest.php +++ b/tests/Unit/WmiWmicTransportTest.php @@ -99,3 +99,11 @@ function wmi_test_run_wmic(string $binary): Linux_WMI { expect($w->fetch())->toBeFalse(); expect($w->error)->toBe('ERROR: Username or Password not set!'); }); + +it('refuses native counter queries because wmic cannot collect PDH data', function () { + $request = new Wmi_Request('host', 'u', 'p', 'PDH', '\\Processor(_Total)\\% Processor Time', '|+|', '/usr/bin/wmic', false, null, 'Negotiate', true); + $transport = new Wmic_Shell_Transport(); + + expect($transport->query($request))->toBeFalse(); + expect($transport->error())->toContain('require PowerShell'); +}); diff --git a/tests/WmiPowerShellTransportTest.php b/tests/WmiPowerShellTransportTest.php index c5bc2c8..cc403a2 100644 --- a/tests/WmiPowerShellTransportTest.php +++ b/tests/WmiPowerShellTransportTest.php @@ -35,6 +35,18 @@ function wmi_test_request(string $secret): Wmi_Request { return new Wmi_Request('winsrv', 'dom\\adm', $secret, 'root\\CIMV2', 'SELECT Name,State FROM Win32_Service', '|+|', 'pwsh'); } +/** A Linux_WMI client for winsrv that sends its queries through $transport. */ +function wmi_test_client(Wmi_Transport $transport, string $secret, string $namespace, string $command): Linux_WMI { + $w = new Linux_WMI('', $transport); + $w->hostname = 'winsrv'; + $w->username = 'dom\\adm'; + $w->password = $secret; + $w->querynspace = $namespace; + $w->command = $command; + + return $w; +} + describe('PowerShellCim_Transport', function () { $secret = 'P@ss w0rd!&|'; @@ -70,16 +82,87 @@ function wmi_test_request(string $secret): Wmi_Request { expect($w->fetch_value('State', 'W32Time'))->toBe('Stopped'); }); - it('surfaces an empty result as an error', function () use ($secret) { + it('returns a successful empty result without manufacturing a transport error', function () use ($secret) { $request = wmi_test_request($secret); $seen = []; $t = new PowerShellCim_Transport('pwsh', wmi_test_recording_runner($seen, [])); - expect($t->query($request))->toBeFalse(); - expect(str_contains((string) $t->error(), 'no Data'))->toBeTrue(); + expect($t->query($request))->toBe([]); + expect($t->error())->toBeNull(); + }); + + it('passes configured WinRM settings to the CIM session', function () use ($secret) { + $seen = []; + $t = new PowerShellCim_Transport('pwsh', wmi_test_recording_runner($seen, [])); + $request = new Wmi_Request('winsrv', 'dom\\adm', $secret, 'root\\CIMV2', 'SELECT Name FROM Win32_Service', '|+|', 'pwsh', true, 5987, 'Kerberos'); + + expect($t->query($request))->toBe([]); + expect($seen['env']['WMI_SSL'])->toBe('1'); + expect($seen['env']['WMI_PORT'])->toBe('5987'); + expect($seen['env']['WMI_AUTH'])->toBe('Kerberos'); + expect($seen['stdin'])->toContain('New-CimSessionOption -Protocol Wsman -UseSsl'); + expect($seen['stdin'])->toContain("\$sessionParams['Port']"); }); + it('collects native PDH values over WinRM and returns formatted samples', function () use ($secret) { + $seen = []; + $lines = ['WindowsPerformanceCounters', 'Path|+|Instance|+|Timestamp|+|CookedValue', '\\Process V2(windows pid 42)\\% Processor Time|+|windows pid 42|+|2026-11-08T10:00:00|+|12.5']; + $t = new PowerShellCim_Transport('pwsh', wmi_test_recording_runner($seen, $lines)); + $request = new Wmi_Request('winsrv', 'dom\\adm', $secret, 'PDH', "\\Process V2(*)\\% Processor Time", '|+|', 'pwsh', true, 5986, 'Kerberos', true); + + expect($t->query($request))->toBe($lines); + expect($seen['env']['WMI_COUNTER'])->toBe('1'); + expect($seen['stdin'])->toContain('Get-Counter -Counter $CounterPaths -MaxSamples 2 -SampleInterval 1'); + expect($seen['stdin'])->toContain("[cultureinfo]::InvariantCulture"); + expect($seen['stdin'])->toContain('Invoke-Command @invoke'); + }); + + it('reads the WinRM settings when Linux_WMI builds a production request', function () use ($secret) { + $seen = []; + $GLOBALS['__test_config'] = [ + 'wmi_winrm_ssl' => 'on', + 'wmi_winrm_port' => '5987', + 'wmi_winrm_auth' => 'Kerberos', + ]; + $t = new PowerShellCim_Transport('pwsh', wmi_test_recording_runner($seen, ['Win32_Service', 'Name', 'Spooler'])); + wmi_test_client($t, $secret, 'root\\CIMV2', 'SELECT Name FROM Win32_Service')->fetch(); + $GLOBALS['__test_config'] = []; + + expect($seen['env']['WMI_SSL'])->toBe('1'); + expect($seen['env']['WMI_PORT'])->toBe('5987'); + expect($seen['env']['WMI_AUTH'])->toBe('Kerberos'); + }); + + it('switches Linux_WMI to counter mode only for the PDH namespace', function (string $namespace, string $counter) use ($secret) { + $seen = []; + $t = new PowerShellCim_Transport('pwsh', wmi_test_recording_runner($seen, ['WindowsPerformanceCounters', 'Path'])); + + wmi_test_client($t, $secret, $namespace, '\\Processor(_Total)\\% Processor Time')->fetch(); + + expect($seen['env']['WMI_COUNTER'])->toBe($counter); + })->with([ + 'PDH' => ['PDH', '1'], + 'padded lower case' => [' pdh ', '1'], + 'WMI namespace' => ['root\\CIMV2', '0'], + ]); + + it('rejects an invalid request before starting PowerShell', function (string $namespace, string $query, bool $ssl, ?int $port, string $auth, bool $counter, string $error) use ($secret) { + $seen = []; + $t = new PowerShellCim_Transport('pwsh', wmi_test_recording_runner($seen, [])); + $request = new Wmi_Request('winsrv', 'dom\\adm', $secret, $namespace, $query, '|+|', 'pwsh', $ssl, $port, $auth, $counter); + + expect($t->query($request))->toBeFalse(); + expect($t->error())->toContain($error); + expect($seen)->toBe([]); + })->with([ + 'Basic authentication without HTTPS' => ['root\\CIMV2', 'SELECT Name FROM Win32_Service', false, null, 'Basic', false, 'requires HTTPS'], + 'unsupported authentication method' => ['root\\CIMV2', 'SELECT Name FROM Win32_Service', false, null, 'NTLM', false, 'Invalid WinRM authentication method'], + 'out-of-range WinRM port' => ['root\\CIMV2', 'SELECT Name FROM Win32_Service', false, 65536, 'Negotiate', false, 'Invalid WinRM port'], + 'empty PDH query' => ['PDH', " \n ", false, null, 'Negotiate', true, 'counter path is required'], + 'more than 64 PDH paths' => ['PDH', implode("\n", array_fill(0, 65, '\\Processor(_Total)\\% Processor Time')), false, null, 'Negotiate', true, 'at most 64 counter paths'], + ]); + it('surfaces stderr on a non-zero exit', function () use ($secret) { $request = wmi_test_request($secret); @@ -90,6 +173,65 @@ function wmi_test_request(string $secret): Wmi_Request { expect(str_contains((string) $t->error(), 'Access denied'))->toBeTrue(); }); + it('returns standard output from the default process runner', function () use ($secret) { + $dir = sys_get_temp_dir() . '/wmi-powershell-' . bin2hex(random_bytes(6)); + $binary = $dir . '/powershell'; + + mkdir($dir, 0700); + file_put_contents($binary, "#!/bin/sh\nprintf 'Win32_Service\\nName|+|State\\nSpooler|+|Running\\n'\nprintf 'warning on stderr\\n' >&2\n"); + chmod($binary, 0700); + + try { + $t = new PowerShellCim_Transport($binary, null, 1); + + expect($t->query(wmi_test_request($secret)))->toBe(['Win32_Service', 'Name|+|State', 'Spooler|+|Running']); + expect($t->error())->toBeNull(); + } finally { + unlink($binary); + rmdir($dir); + } + }); + + it('drains both output streams and stops a stalled PowerShell process', function () use ($secret) { + $dir = sys_get_temp_dir() . '/wmi-powershell-' . bin2hex(random_bytes(6)); + $binary = $dir . '/powershell'; + + mkdir($dir, 0700); + file_put_contents($binary, "#!/bin/sh\nhead -c 65536 /dev/zero >&2\nexec sleep 10\n"); + chmod($binary, 0700); + + try { + $t = new PowerShellCim_Transport($binary, null, 1); + $began = microtime(true); + + expect($t->query(wmi_test_request($secret)))->toBeFalse(); + expect(microtime(true) - $began)->toBeLessThan(6.0); + expect($t->error())->toContain('did not finish within 1 seconds'); + } finally { + unlink($binary); + rmdir($dir); + } + }); + + it('stops PowerShell when its response exceeds the configured size limit', function () use ($secret) { + $dir = sys_get_temp_dir() . '/wmi-powershell-' . bin2hex(random_bytes(6)); + $binary = $dir . '/powershell'; + + mkdir($dir, 0700); + file_put_contents($binary, "#!/bin/sh\nprintf '12345678901234567890123456789012\\n'\n"); + chmod($binary, 0700); + + try { + $t = new PowerShellCim_Transport($binary, null, 1, 16); + + expect($t->query(wmi_test_request($secret)))->toBeFalse(); + expect($t->error())->toContain('exceeded the 16 byte limit'); + } finally { + unlink($binary); + rmdir($dir); + } + }); + it('follows the Cacti server OS for transport auto-selection', function () { $GLOBALS['config']['cacti_server_os'] = 'win32'; expect((new Linux_WMI())->getcommand())->toBeFalse(); diff --git a/wmi_accounts.php b/wmi_accounts.php index 60b0c27..b48f766 100644 --- a/wmi_accounts.php +++ b/wmi_accounts.php @@ -65,6 +65,39 @@ 'max_length' => '64', 'size' => '30' ], + 'winrm_ssl' => [ + 'method' => 'drop_array', + 'friendly_name' => __('WinRM Transport', 'wmi'), + 'description' => __('Choose whether this account inherits the server setting or uses HTTP or HTTPS.', 'wmi'), + 'value' => '|arg1:winrm_ssl|', + 'default' => 'inherit', + 'array' => [ + 'inherit' => __('Use Server Default', 'wmi'), + 'off' => __('HTTP', 'wmi'), + 'on' => __('HTTPS', 'wmi'), + ] + ], + 'winrm_port' => [ + 'method' => 'textbox', + 'friendly_name' => __('WinRM Port Override', 'wmi'), + 'description' => __('Leave blank to inherit the server setting and Windows WinRM default.', 'wmi'), + 'value' => '|arg1:winrm_port|', + 'max_length' => '5', + 'default' => '', + ], + 'winrm_auth' => [ + 'method' => 'drop_array', + 'friendly_name' => __('WinRM Authentication', 'wmi'), + 'description' => __('Choose whether this account inherits the server setting or uses a specific authentication method. Basic requires HTTPS.', 'wmi'), + 'value' => '|arg1:winrm_auth|', + 'default' => 'inherit', + 'array' => [ + 'inherit' => __('Use Server Default', 'wmi'), + 'Negotiate' => __('Negotiate', 'wmi'), + 'Kerberos' => __('Kerberos', 'wmi'), + 'Basic' => __('Basic (HTTPS only)', 'wmi'), + ] + ], 'id' => [ 'method' => 'hidden_zero', 'value' => '|arg1:id|' @@ -214,9 +247,13 @@ function save_accounts() { $save['id'] = get_filter_request_var('id'); $save['name'] = get_nfilter_request_var('name'); $save['username'] = get_nfilter_request_var('username'); + $save['winrm_ssl'] = isset_request_var('winrm_ssl') ? get_nfilter_request_var('winrm_ssl') : 'inherit'; + $save['winrm_port'] = isset_request_var('winrm_port') ? trim(get_nfilter_request_var('winrm_port')) : ''; + $save['winrm_auth'] = isset_request_var('winrm_auth') ? get_nfilter_request_var('winrm_auth') : 'inherit'; $password = get_nfilter_request_var('password'); - $valid = wmi_account_input_valid($save['name'], $save['username'], $password, get_nfilter_request_var('password_confirm'), (int) $save['id']); + $valid = wmi_account_input_valid($save['name'], $save['username'], $password, get_nfilter_request_var('password_confirm'), (int) $save['id']) && + wmi_account_winrm_input_valid($save['winrm_ssl'], $save['winrm_port'], $save['winrm_auth']); if ($valid && $password !== '') { $wmi = new Linux_WMI(); diff --git a/wmi_queries.php b/wmi_queries.php index baf35bd..705c5d1 100644 --- a/wmi_queries.php +++ b/wmi_queries.php @@ -68,14 +68,14 @@ 'namespace' => [ 'method' => 'textbox', 'friendly_name' => __('Namespace', 'wmi'), - 'description' => __('The Namespace for this Query.', 'wmi'), + 'description' => __('Use a WMI namespace, or enter PDH for native performance counter paths.', 'wmi'), 'value' => '|arg1:namespace|', 'max_length' => '64', ], 'query' => [ 'method' => 'textarea', 'friendly_name' => __('Query', 'wmi'), - 'description' => __('The Query to execute for gathering WMI data from the device.', 'wmi'), + 'description' => __('Enter WQL, or for PDH enter one Windows performance counter path per line. Broad queries can return many rows; responses are capped at 16 MiB.', 'wmi'), 'value' => '|arg1:query|', 'textarea_rows' => '4', 'textarea_cols' => '80', @@ -495,10 +495,30 @@ function show_queries() { query_filter(); - $queries = db_fetch_assoc("SELECT * - FROM wmi_wql_queries + $queries = db_fetch_assoc("SELECT wwq.*, + COALESCE(health.device_count, 0) AS device_count, + health.last_started, + COALESCE(health.failing_devices, 0) AS failing_devices, + COALESCE(health.timeout_count, 0) AS timeout_count, + (SELECT SUBSTRING(recent_error.last_error, 1, 160) + FROM host_wmi_query AS recent_error + WHERE recent_error.wmi_query_id = wwq.id + AND recent_error.last_error != '' + ORDER BY recent_error.last_started DESC + LIMIT 1) AS last_error + FROM wmi_wql_queries AS wwq + LEFT JOIN ( + SELECT wmi_query_id, + COUNT(DISTINCT host_id) AS device_count, + MAX(last_started) AS last_started, + SUM(CASE WHEN consecutive_failures > 0 THEN 1 ELSE 0 END) AS failing_devices, + SUM(timeout_count) AS timeout_count + FROM host_wmi_query + GROUP BY wmi_query_id + ) AS health + ON health.wmi_query_id = wwq.id $sql_where - ORDER BY name + ORDER BY wwq.name LIMIT " . ($rows * (get_request_var('page') - 1)) . ', ' . $rows); $total_rows = db_fetch_cell("SELECT COUNT(*) @@ -513,6 +533,19 @@ function show_queries() { html_start_box(__('WMI Queries', 'wmi'), '100%', false, 3, 'center', 'wmi_queries.php?action=edit'); + // The poll health columns rank the busiest or most broken queries first. + $health_columns = []; + + foreach ([ + 'device_count' => [__('Polled Devices', 'wmi'), 'right'], + 'last_started' => [__('Last Poll', 'wmi'), 'left'], + 'failing_devices' => [__('Failing Devices', 'wmi'), 'right'], + 'timeout_count' => [__('Timeouts', 'wmi'), 'right'], + 'last_error' => [__('Most Recent Error', 'wmi'), 'left'], + ] as $column => [$display, $align]) { + $health_columns[$column] = ['display' => $display, 'align' => $align, 'sort' => 'DESC']; + } + html_header_checkbox( [ 'name' => [ @@ -545,7 +578,7 @@ function show_queries() { 'align' => 'left', 'sort' => 'ASC' ] - ] + ] + $health_columns ); if (!empty($queries)) { @@ -557,6 +590,11 @@ function show_queries() { form_selectable_cell(html_escape($row['namespace']), $row['id']); form_selectable_cell(html_escape($row['query']), $row['id']); form_selectable_cell(html_escape($row['primary_key']), $row['id']); + form_selectable_cell($row['device_count'], $row['id'], '', 'right'); + form_selectable_cell(html_escape((string) ($row['last_started'] ?? 'Never')), $row['id']); + form_selectable_cell($row['failing_devices'], $row['id'], '', 'right'); + form_selectable_cell($row['timeout_count'], $row['id'], '', 'right'); + form_selectable_cell(html_escape($row['last_error'] ?? '-'), $row['id']); form_checkbox_cell($row['name'], $row['id']); form_end_row(); }